Navigation and shares

Move between frames and report what a unit holds.

scale_children

scale_children(
    x: NestedScale,
    frame: str,
    unit: str | Sequence[str],
    target: str | None = None,
) -> list[str]

Codes one frame down (or at target) sharing an atom with unit.

scale_parents(
    x: NestedScale,
    frame: str,
    unit: str | Sequence[str],
    target: str | None = None,
) -> list[str]

Codes one frame up (or at target) sharing an atom with unit.

scale_descendants(
    x: NestedScale,
    frame: str,
    unit: str | Sequence[str],
    target: str | None = None,
) -> pa.Table

Related codes at every finer frame (or target): columns frame, unit.

scale_ancestors(
    x: NestedScale,
    frame: str,
    unit: str | Sequence[str],
    target: str | None = None,
) -> pa.Table

Related codes at every coarser frame (or target): columns frame, unit.

scale_family(
    x: NestedScale,
    parent: str | None = None,
    child: str | None = None,
) -> pa.Table

Immediate parent-child table between two frames.

Defaults to every adjacent pair. Columns parent_frame, parent, child_frame, child; atoms unassigned at either frame are omitted.

scale_ancestry(x: NestedScale) -> pa.Table

Every (coarser, finer) code pair sharing at least one atom, all frame pairs.

Atom-mediated, not a transitive closure of scale_family(): closing a cross-cutting hierarchy manufactures false relationships.

scale_nests(
    x: NestedScale, parent: str, child: str
) -> Verdict

Does every code at child fall within a single code at parent?

A diagnostic: nesting is not required. When not, offenders holds the child codes with more than one parent.

scale_crosses(x: NestedScale, a: str, b: str) -> Verdict

Does every unit of a combine with the same set of units of b?

True for overlaying frames such as MONTH x HOUR. When not, offenders names the units of a whose set differs from the first one's.

scale_is_uniform(
    x: NestedScale,
    frame: str,
    weight: str | None = None,
    tolerance: float = 1e-09,
) -> Verdict

Do all units of frame hold the same number of atoms (or weight total)?

Atoms with no code at frame are ignored. When not, sizes holds the per-unit counts or totals.

scale_share(
    x: NestedScale,
    frame: str,
    weight: str | None = None,
    within: str | None = None,
) -> pa.Table

Weight shares of the units of frame, over the whole scale or within each unit of the coarser frame within.

scale_coverage(
    x: NestedScale, weight: str | None = None
) -> dict[str, float] | float

Fraction of the root parent's weight surviving in a sampled scale.

A scale never subset covers all of itself: every weight reports 1.