Crosswalks

The map behind every conversion, and the registry of exact ones.

scale_map

scale_map(
    x: NestedScale,
    source: str,
    target: str,
    weight: str | None = None,
    by: Sequence[str] = (),
    **kwargs: object,
) -> pa.Table

Crosswalk between two frames of a scale.

One row per pair of overlapping units with n_from (atoms in the source unit), n_overlap (atoms shared), w (weight of the overlap) and w_from (full weight of the source unit); w / w_from is the split share of sum disaggregation. The label columns are named by the frames; a null target marks atoms target does not cover. A registered map is returned as-is.

scale_map_between

scale_map_between(
    source: NestedScale,
    target: NestedScale,
    weight: str | None = None,
) -> pa.Table

Crosswalk between two scales through their shared atom keys.

Label columns are named after the scales. Atoms of source absent from target get a null target (with a warning).

register_scale_map

register_scale_map(
    x: NestedScale | str,
    source: str,
    target: str,
    map: object,
) -> str

Register a direct crosswalk between two frames of one scale.

Scoped to the scale (object or name). map=None removes the entry. Returns the registry key.

register_scale_map_between

register_scale_map_between(
    source: NestedScale | str,
    target: NestedScale | str,
    map: object,
) -> str

Register a direct crosswalk between two scales (objects or names).

get_scale_map

get_scale_map(
    x: NestedScale | str, source: str, target: str
) -> pa.Table | None

The map registered for two frames of x, or None.

get_scale_map_between

get_scale_map_between(
    source: NestedScale | str, target: NestedScale | str
) -> pa.Table | None

The map registered between two scales, or None.

list_scale_maps

list_scale_maps() -> pa.Table

Registry keys, one row each (column key).

clear_scale_maps

clear_scale_maps(
    name: str | Sequence[str] | None = None,
) -> None

Remove registered crosswalks: the named registry keys (as list_scale_maps() reports them), or, with name=None, all of them.