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.

  • ClimateContext Typed context with a JSON-serializable to_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: ValueError

Raised 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: object

A 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

to_dict()[source]

Return a JSON-serializable context.

Return type:

dict[str, object]

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:

ClimateContext

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.