Building a dimension package

Hooks and helpers for packages that subclass NestedScale.

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_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_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_write_payload

scale_write_payload(
    x: NestedScale, dir: Path | None, header: dict
) -> dict

Write a subclass's payload next to the header; returns the header.

scale_read_payload

scale_read_payload(
    x: NestedScale, dir: Path | None, header: Mapping
) -> NestedScale

Rebuild a subclass from the core scale and its payload files.

register_scale_class

register_scale_class(cls: type) -> str

Register a NestedScale subclass under its pkg::Name so read_scale() can give it back.

list_scale_classes

list_scale_classes() -> list[str]

scale_atom_pairs

scale_atom_pairs(
    x: NestedScale,
    source: str,
    target: str,
    weight: str | None = None,
    **kwargs: object,
) -> pa.Table

Atom-level correspondence between two frames: columns source, target, w.

The seam a dimension package overrides (scale_atom_pairs.register) when its atom layer is generated; extra identifier columns must be named in the caller's by.

backend_bind_rows

backend_bind_rows(parts: Sequence[Table]) -> pa.Table

Row-bind tables, unifying their schemas. R: .ms_bind_rows().

backend_distinct

backend_distinct(
    table: Table, columns: Sequence[str]
) -> pa.Table

Distinct combinations of columns in first-appearance order.

Python only: R gets this from dplyr::distinct().

backend_is_lazy

backend_is_lazy(backend: Backend) -> bool

Is this a lazy backend (pyarrow Dataset, polars LazyFrame)?

R: .ms_is_lazy().

backend_of

backend_of(data: Any, arg: str = 'data') -> Backend

Classify a data argument; error when it is not a supported table.

R: .ms_backend() / .ms_require_backend().

backend_pull

backend_pull(data: Any) -> pa.Table

Any supported table, collected into a pyarrow.Table.

R: .ms_pull().

backend_restore

backend_restore(
    table: Table,
    backend: Backend,
    collect: bool | None = None,
) -> Any

A result in the caller's type: pandas, polars, a LazyFrame (unless collect), or a pyarrow.Table.

R: .ms_restore().

backend_scan

backend_scan(
    data: Any,
    backend: Backend | None = None,
    columns: Sequence[str] | None = None,
    filter: Expression | None = None,
) -> pa.Table

Materialise the needed columns (and rows) of a data argument, pushing the projection and filter into the scan of a lazy input.

R: .ms_lazy() followed by .ms_pull().

backend_schema

backend_schema(
    data: Any, backend: Backend | None = None
) -> pa.Schema

Column names and types, without scanning a lazy input.

R: .ms_schema().