formatters

Curation steps for structural, non-semantic output formatting.

Formatters change dtypes or column layout only; they do not fill, infer, or reconcile any values.

Functions

cast_categoricals(→ openplaces.io.curator.CurateState)	Cast registry-defined categoricals and provenance sidecars to Categorical.
cast_integers(→ openplaces.io.curator.CurateState)	Cast numeric columns to a nullable integer dtype.
order_columns(→ openplaces.io.curator.CurateState)	Order columns: canonical -> sources -> linked evidence -> flags/viz.

Module Contents

openplaces.io.curator.formatters.cast_categoricals(state: openplaces.io.curator.CurateState) → openplaces.io.curator.CurateState

Cast registry-defined categoricals and provenance sidecars to Categorical.

openplaces.io.curator.formatters.cast_integers(state: openplaces.io.curator.CurateState, columns: list[str]) → openplaces.io.curator.CurateState

Cast numeric columns to a nullable integer dtype.

Unlike fill_missing_numeric, this does not fill missing values with a placeholder — a row with no evidence stays missing (pd.NA), not a misleading 0 (e.g. year 0). Values are rounded before casting, since a reconciled column can legitimately be non-integer (e.g. a fallback median across several buildings) even though the canonical attribute is a whole number.

Parameters:

columns (list of str) – Numeric columns to cast to pandas’ nullable Int64. Missing columns are skipped.

openplaces.io.curator.formatters.order_columns(state: openplaces.io.curator.CurateState, overrides: list[str] | None = None, drop: list[str] | None = None) → openplaces.io.curator.CurateState

Order columns: canonical -> sources -> linked evidence -> flags/viz.

Four bands: (0) canonical/final variables (incl. m2), ordered by the attribute-registry sort rank, with priority_on_parcel ending the band; (0.5) every {col}_source provenance sidecar, grouped together and ordered by their base column’s rank; (1) source variables inherited from other entities (relational counts first, then each source’s evidence group led by its bare id columns — parcel_id/parcel_id_all/ parcel_id_local head the _parcel group); (2) flag and visualization-only columns (occupancy_type_conflict/_review, *_per_area). An {col}_all variant always directly follows its base column. geometry is always kept last. Computed from each column’s name and the registry, so the recipe needs no explicit column list.

Parameters:

• overrides (list of str, optional) – Columns to force to the front, in the given order (escape hatch for any bespoke placement the rule does not capture). Defaults to none.

• drop (list of str, optional) – Transient columns to remove from the output (e.g. an intermediate used only during inference). Defaults to none.