Skip to content

Scales

Build a scale and read its structure.

scale_from_leaftable 

scale_from_leaftable(
    leaftable: Any,
    frames: str | Sequence[str],
    key: str | None = None,
    weights: str | Sequence[str] | None = None,
    default_weight: str | None = None,
    members: Mapping[str, Sequence[str]] | None = None,
    name: str = "",
    desc: str = "",
    attributes: Any = None,
    aliases: Any = None,
    **meta: Any,
) -> NestedScale

Build a NestedScale from a flat table of atoms.

leaftable has one row per atom, one column per name in frames (coarsest first) and optionally numeric weight columns. Blank strings in frame columns become null: that atom has no code at that frame.

key defaults to "unit" when that column exists, else the finest frame. weights defaults to every numeric column that is neither a frame, the key, nor a reserved name. members defaults to first-appearance order. Extra keyword arguments are merged into meta (e.g. source, labels).

scale_example 

scale_example() -> NestedScale

A small example scale with three awkward real-world features.

  • a code ("G1") reused at two frames, so lookups must name the frame;
  • a non-nesting pair -- group "GB" draws units from two classes;
  • a unit ("OTH") with no code at any coarser frame.

scale_example2 

scale_example2() -> NestedScale

A second small, well-behaved example scale (frames era/period).

NestedScale dataclass

A nested discrete partition: a table of atoms plus the frames grouping them.

Construct with scale_from_leaftable(). Treat as immutable: every verb returns a new object.

__getitem__ 

__getitem__(idx: tuple) -> NestedScale

x[frame, unit] is filter_scale(x, frame, unit), as in R.

scale_class

NestedScale -- the dimension-agnostic core type (port of R/scale-class.R).

A NestedScale is a nested partition of a set of atoms, in any dimension:

  • leaftable -- one row per atom: a column per frame, a unique key column (named by key) and zero or more numeric weight columns
  • frames -- frame names, COARSEST first
  • members -- frame -> the ordered code vocabulary at that frame
  • key -- name of the atom key column (default "unit")
  • meta -- name, desc, weights, default_weight, residuals, labels, source, and the sample bookkeeping (coverage, parent_totals, parent_name)

Frames are partitions of the atoms, not necessarily a tree; conversion always routes through the atoms. Anything derivable is computed on demand.

SCALE_ATTRIBUTE_KINDS module-attribute 

SCALE_ATTRIBUTE_KINDS = ('property', 'factor')

property = an invertible ratio (lhv, density); factor = one-way (an emission factor, a loss factor).

NestedScale dataclass

A nested discrete partition: a table of atoms plus the frames grouping them.

Construct with scale_from_leaftable(). Treat as immutable: every verb returns a new object.

__getitem__ 

__getitem__(idx: tuple) -> NestedScale

x[frame, unit] is filter_scale(x, frame, unit), as in R.

ScaleSummary dataclass

The quantitative view of a scale (R: summary() -> summary_Scale).

scale_alias_property 

scale_alias_property(name: str) -> property

A read-only property exposing an inherited field under another name.

How a Calendar keeps timeframes and a Geoscale keeps geoframes over the inherited frames.

scale_atom_level 

scale_atom_level(x: NestedScale) -> str

The finest frame when it has one code per atom, otherwise the key.

scale_class 

scale_class() -> type[NestedScale]

The NestedScale class, for subclassing and dispatch.

scale_frames 

scale_frames(
    x: NestedScale, finest: bool = False
) -> list[str] | str

Frame names, coarsest first; only the finest when finest=True.

scale_is 

scale_is(x: object) -> bool

Is x a NestedScale (or a subclass)?

scale_key 

scale_key(x: NestedScale) -> str

The atom key column name.

scale_leaftable 

scale_leaftable(x: NestedScale) -> pa.Table

The one-row-per-atom table the scale is built on.

scale_payload_slice 

scale_payload_slice(
    x: NestedScale, i: Sequence[int]
) -> NestedScale

Subset a subclass's per-atom payload to the kept leaftable rows i.

The NestedScale default has no payload and returns x unchanged.

scale_rank 

scale_rank(
    x: NestedScale, frame: str | Sequence[str]
) -> int | None | list

Position of a frame in the hierarchy; 1 is the coarsest.

The key ranks one past the last frame when it is not itself a frame. Names that are not frames give None.

scale_residuals 

scale_residuals(
    x: NestedScale, frame: str | None = None
) -> dict | list[str]

Residual units: the frame -> codes mapping, or one frame's codes.

scale_summary 

scale_summary(x: NestedScale) -> ScaleSummary

Per-weight totals, coverage and the adjacent-frame nesting table.

scale_units 

scale_units(
    x: NestedScale, frame: str | None = None
) -> list[str]

The code vocabulary at one frame, in canonical order (default: atoms).

scale_vocab 

scale_vocab(x: NestedScale) -> dict[str, str]

The words engine messages use for this scale's dimension.

Subclasses register their own implementation with scale_vocab.register(Subclass).

scale_weights 

scale_weights(x: NestedScale) -> list[str]

Weight column names (possibly empty).

scale_product_class 

scale_product_class() -> type[ScaleProduct]

scale_is 

scale_is(x: object) -> bool

Is x a NestedScale (or a subclass)?

scale_is_product 

scale_is_product(x: object) -> bool

scale_frames 

scale_frames(
    x: NestedScale, finest: bool = False
) -> list[str] | str

Frame names, coarsest first; only the finest when finest=True.

scale_units 

scale_units(
    x: NestedScale, frame: str | None = None
) -> list[str]

The code vocabulary at one frame, in canonical order (default: atoms).

scale_key 

scale_key(x: NestedScale) -> str

The atom key column name.

scale_leaftable 

scale_leaftable(x: NestedScale) -> pa.Table

The one-row-per-atom table the scale is built on.

scale_weights 

scale_weights(x: NestedScale) -> list[str]

Weight column names (possibly empty).

scale_rank 

scale_rank(
    x: NestedScale, frame: str | Sequence[str]
) -> int | None | list

Position of a frame in the hierarchy; 1 is the coarsest.

The key ranks one past the last frame when it is not itself a frame. Names that are not frames give None.

scale_atom_level 

scale_atom_level(x: NestedScale) -> str

The finest frame when it has one code per atom, otherwise the key.

scale_residuals 

scale_residuals(
    x: NestedScale, frame: str | None = None
) -> dict | list[str]

Residual units: the frame -> codes mapping, or one frame's codes.

is_valid_frame 

is_valid_frame(
    x: str | Iterable[object],
) -> bool | list[bool]

Validate frame names.

Returns a bool for a single string, a list of bools for a sequence.

scale_summary 

scale_summary(x: NestedScale) -> ScaleSummary

Per-weight totals, coverage and the adjacent-frame nesting table.