occupancy

Shared occupancy-classification helpers for the curate stage.

Vocabulary-neutral: all class names, evidence columns, thresholds, and the raw-label -> class mapping come from the recipe occupancy config block and the class-map ruleset CSV, never from this module. Used by the inferer, reconciler, and diagnostics steps.

Functions

get_occupancy_config(→ dict)	Return the recipe's occupancy config block (or an empty dict).
load_ruleset(→ list[dict])	Load an ordered label-mapping ruleset CSV stored beside the curate recipe.
coerce_to_class(→ pandas.Series)	Map raw occupancy labels to coarse classes via rules; unmatched pass through.
bucket_classes(→ pandas.Series)	Collapse already-coerced occupancy classes to residential granularity.
bucket_to_residential(→ pandas.Series)	Coerce series to occupancy classes, collapsing non-residential to a bucket.

Module Contents

openplaces.io.curator.occupancy.get_occupancy_config(state: openplaces.io.curator.CurateState) → dict

Return the recipe’s occupancy config block (or an empty dict).

openplaces.io.curator.occupancy.load_ruleset(state: openplaces.io.curator.CurateState, ruleset: str) → list[dict]

Load an ordered label-mapping ruleset CSV stored beside the curate recipe.

Columns: pattern, match_type (contains | regex; default contains), occupancy_type (the output class), and an optional reviewed (true | false; default false). Rows apply top to bottom, first match wins, so more specific terms must precede general ones. Matching is case-insensitive.

Parameters:

ruleset (str) – Filename (or recipe-id stem) of the CSV beside the curate recipe; a .csv extension is added when missing.

openplaces.io.curator.occupancy.coerce_to_class(series: pandas.Series, rules: list[dict]) → pandas.Series

Map raw occupancy labels to coarse classes via rules; unmatched pass through.

First matching rule wins (case-insensitive contains/regex). Values matching no rule are returned unchanged (e.g. non-residential categories); missing values stay missing.

openplaces.io.curator.occupancy.bucket_classes(coerced: pandas.Series, config: dict) → pandas.Series

Collapse already-coerced occupancy classes to residential granularity.

Every class outside residential_classes plus the secondary_class is replaced with a single conflict_other_label (default Non-Residential), so two differing non-residential categories (e.g. Retail vs Hotel) do not register as a disagreement while residential subtypes (Single-Family vs Multi-Family) do. Missing values stay missing.

openplaces.io.curator.occupancy.bucket_to_residential(series: pandas.Series, config: dict, rules: list[dict]) → pandas.Series

Coerce series to occupancy classes, collapsing non-residential to a bucket.

Used to compare occupancy evidence sources at residential granularity; see bucket_classes() for the bucketing semantics.