femic.climate.consumer Module
The femic.climate.consumer module resolves a validated climate table into
an AOI/scenario/year context and attaches the values and provenance to
attribute rows.
Use this page when you are wiring climate values into a curve or attribute stage for the first time.
Start Here If…
Use this page first if you are trying to:
select one climate context for an AOI, scenario, and year;
detect an ambiguous GCM or mixed-source selection;
attach climate values to fragment or attribute rows; or
carry climate provenance into a downstream report.
Typical Usage
from pathlib import Path
from femic.climate.consumer import attach_climate_to_rows
from femic.contracts.climate import read_climate_table
table = read_climate_table(Path("data/climate/north-island.csv"))
rows = [
{"fragment_id": 1, "aoi_id": "north-island"},
{"fragment_id": 2, "aoi_id": "south-island"},
]
attached = attach_climate_to_rows(
rows,
table,
scenario="ssp245",
year=2050,
variables=["tavg", "ppt"],
)
Key Entry Surfaces
select_climate_context()Resolve values, units, and provenance for one AOI/scenario/year.ClimateContextTyped context with a JSON-serializableto_dict.attach_climate_context()Attach one context to copies of rows.attach_climate_to_rows()Resolve a context per row and attach it, with a default-AOI fallback.
Cross-References
Join validated climate records to FEMIC attribute rows.
This is the first consumer of the femic.climate.v1 contract. It selects a
climate context for an AOI, scenario, year, and variable set, then attaches the
values and their provenance to attribute rows. It does not implement a
climate-growth response; that is a later model layer.
- exception femic.climate.consumer.ClimateConsumerError[source]
Bases:
ValueErrorRaised when a climate table cannot be resolved or attached.
- class femic.climate.consumer.ClimateContext(aoi_id, scenario, year, gcm, values, units, source_id, source_version, downscaling_method, retrieved_utc)[source]
Bases:
objectA resolved climate context for one AOI, scenario, and year.
- Parameters:
aoi_id (str)
scenario (str)
year (int)
gcm (str)
values (dict[str, float])
units (dict[str, str])
source_id (str)
source_version (str)
downscaling_method (str)
retrieved_utc (str)
- aoi_id
Area-of-interest identifier.
- Type:
str
- scenario
Scenario label.
- Type:
str
- year
Calendar year or period label.
- Type:
int
- gcm
GCM or ensemble label.
- Type:
str
- values
Variable to value.
- Type:
dict[str, float]
- units
Variable to canonical unit.
- Type:
dict[str, str]
- source_id
Upstream source identifier.
- Type:
str
- source_version
Source release or version.
- Type:
str
- downscaling_method
Downscaling or processing method.
- Type:
str
- retrieved_utc
Latest retrieval timestamp in the context.
- Type:
str
- femic.climate.consumer.attach_climate_context(rows, context, *, prefix='climate_')[source]
Attach a climate context to copies of attribute rows.
- Parameters:
rows (sequence[mapping[str, object]]) – Attribute rows. They are copied, not mutated.
context (ClimateContext) – Resolved climate context.
prefix (str, optional) – Field prefix. Defaults to
"climate_".
- Returns:
Copies with
<prefix><variable>,<prefix><variable>_unit, and context provenance fields.- Return type:
list[dict[str, object]]
- Raises:
ClimateConsumerError – If the prefix is empty or a row is not a mapping.
- femic.climate.consumer.attach_climate_to_rows(rows, records, *, scenario, year, variables, gcm=None, aoi_field='aoi_id', default_aoi_id=None, prefix='climate_')[source]
Resolve a context per row and attach its climate values.
- Parameters:
rows (sequence[mapping[str, object]]) – Attribute rows with an AOI field, or a default AOI id.
records (sequence[ClimateRecord]) – Validated climate records.
scenario (str) – Scenario to select.
year (int) – Year to select.
variables (sequence[str]) – Variables to include.
gcm (str | None, optional) – GCM to select when the table is ambiguous.
aoi_field (str, optional) – Row field naming the AOI. Defaults to
"aoi_id".default_aoi_id (str | None, optional) – AOI to use when a row omits the field.
prefix (str, optional) – Field prefix. Defaults to
"climate_".
- Returns:
Copies of the rows with climate values and provenance.
- Return type:
list[dict[str, object]]
- Raises:
ClimateConsumerError – If a row has no AOI and no default, or a context cannot be resolved.
- femic.climate.consumer.select_climate_context(records, *, aoi_id, scenario, year, variables, gcm=None)[source]
Select one climate context from a validated table.
- Parameters:
records (sequence[ClimateRecord]) – Validated climate records.
aoi_id (str) – AOI to select.
scenario (str) – Scenario to select.
year (int) – Year to select.
variables (sequence[str]) – Variables to include. Duplicates are collapsed in order.
gcm (str | None, optional) – GCM to select. Required when the table has more than one GCM for the same AOI, scenario, year, and variable.
- Returns:
The resolved values, units, and provenance.
- Return type:
- Raises:
ClimateConsumerError – If the selection is empty, a variable is missing, multiple GCMs or sources are ambiguous, or a variable has more than one record.