femic.contracts.climate Module
The femic.contracts.climate module owns the femic.climate.v1 record
contract. It validates climate tables and reports their provenance without
importing FEMIC’s modelling or runtime stack.
Use this page when you are producing, reading, or validating a climate table for a FEMIC instance, a ws4 scenario, or a Nemora workflow.
Start Here If…
Use this page first if you are trying to:
define a canonical climate table for a new AOI;
check a ClimateNA/SilvR21 adapter’s output before a model consumes it;
debug a unit, scenario, year, or timestamp failure; or
report which source and downscaling method produced a climate value.
Typical Usage
from pathlib import Path
from femic.contracts.climate import (
read_climate_table,
summarize_climate_table,
validate_climate_record,
write_climate_table,
)
table = read_climate_table(Path("data/climate/north-island.csv"))
summary = summarize_climate_table(table)
write_climate_table(Path("data/climate/north-island.json"), table)
Key Entry Surfaces
validate_climate_record()Validate one record against the schema and the variable/unit rules.ClimateRecordTyped record with canonicalto_dictandfrom_dict.read_climate_table()Read and validate a CSV or JSON table in file order.write_climate_table()Write a validated table to CSV or JSON.summarize_climate_table()Return the provenance-bearing summary a consumer can report.climate_schema()Return a defensive copy of the JSON Schema document.femic.contracts.climate_na.read_climate_na_csv()Adapt an annual ClimateNA-style CSV to validated records.
Cross-References
Versioned climate-table contract for the FRESH modelling ecosystem.
This module owns the femic.climate.v1 record contract: the canonical
climate table that FEMIC, ws3, ws4, and Nemora exchange. It validates units,
scenarios, timestamps, and provenance before a consumer can use a value.
The contract is deliberately narrow. It does not download ClimateNA data, select a GCM ensemble, or model climate. The adapter that produces a table is a separate concern; this module defines what a valid table is.
- femic.contracts.climate.CLIMATE_SCENARIOS: frozenset[str] = frozenset({'historical', 'rcp26', 'rcp45', 'rcp60', 'rcp85', 'ssp126', 'ssp245', 'ssp370', 'ssp585'})
Accepted scenario labels.
rcp*labels are retained for ClimateNA v6/v7 outputs;ssp*labels are the CMIP6 generation.
- femic.contracts.climate.CLIMATE_SCHEMA: dict[str, object] = {'$id': 'https://femic.ubc.ca/schemas/climate.v1.json', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'additionalProperties': False, 'properties': {'aoi_id': {'minLength': 1, 'type': 'string'}, 'downscaling_method': {'minLength': 1, 'type': 'string'}, 'gcm': {'minLength': 1, 'type': 'string'}, 'notes': {'type': ['string', 'null']}, 'retrieved_utc': {'format': 'date-time', 'type': 'string'}, 'scenario': {'enum': ['historical', 'rcp26', 'rcp45', 'rcp60', 'rcp85', 'ssp126', 'ssp245', 'ssp370', 'ssp585'], 'type': 'string'}, 'schema_version': {'const': 'femic.climate.v1'}, 'source_id': {'minLength': 1, 'type': 'string'}, 'source_version': {'minLength': 1, 'type': 'string'}, 'unit': {'enum': ['days', 'degC', 'degree_days', 'kPa', 'mm', 'percent'], 'type': 'string'}, 'value': {'type': 'number'}, 'variable': {'enum': ['cwd', 'gdd', 'map', 'mat', 'mcmt', 'mwmt', 'nffd', 'pet', 'ppt', 'prcp', 'rh', 'snow', 'tavg', 'tmax', 'tmin', 'vpd'], 'type': 'string'}, 'variance': {'minimum': 0, 'type': ['number', 'null']}, 'year': {'maximum': 2300, 'minimum': 1900, 'type': 'integer'}}, 'required': ['schema_version', 'aoi_id', 'variable', 'unit', 'year', 'scenario', 'gcm', 'value', 'source_id', 'source_version', 'downscaling_method', 'retrieved_utc'], 'title': 'FEMIC climate.v1 record', 'type': 'object'}
JSON Schema for one
femic.climate.v1record. Callclimate_schema()for a defensive copy.
- femic.contracts.climate.CLIMATE_VARIABLES: dict[str, str] = {'cwd': 'mm', 'gdd': 'degree_days', 'map': 'mm', 'mat': 'degC', 'mcmt': 'degC', 'mwmt': 'degC', 'nffd': 'days', 'pet': 'mm', 'ppt': 'mm', 'prcp': 'mm', 'rh': 'percent', 'snow': 'mm', 'tavg': 'degC', 'tmax': 'degC', 'tmin': 'degC', 'vpd': 'kPa'}
Canonical variable names and their required units. Adapters convert source units to these before writing a table.
- exception femic.contracts.climate.ClimateContractError[source]
Bases:
ValueErrorRaised when a climate record or table violates
femic.climate.v1.
- class femic.contracts.climate.ClimateRecord(aoi_id, variable, unit, year, scenario, gcm, value, source_id, source_version, downscaling_method, retrieved_utc, variance=None, notes=None, schema_version='femic.climate.v1')[source]
Bases:
objectOne validated
femic.climate.v1record.- Parameters:
aoi_id (str)
variable (str)
unit (str)
year (int)
scenario (str)
gcm (str)
value (float)
source_id (str)
source_version (str)
downscaling_method (str)
retrieved_utc (str)
variance (float | None)
notes (str | None)
schema_version (str)
- aoi_id
Identifier of the area of interest the value applies to.
- Type:
str
- variable
Canonical climate variable, one of
CLIMATE_VARIABLES.- Type:
str
- unit
Canonical unit for the variable.
- Type:
str
- year
Calendar year of the value.
- Type:
int
- scenario
Scenario label, one of
CLIMATE_SCENARIOS.- Type:
str
- gcm
General circulation model or ensemble label.
- Type:
str
- value
Climate value in
unit.- Type:
float
- source_id
Identifier of the upstream data source.
- Type:
str
- source_version
Version of the upstream source or release.
- Type:
str
- downscaling_method
Downscaling or processing method applied to the source.
- Type:
str
- retrieved_utc
Timezone-aware ISO-8601 retrieval timestamp.
- Type:
str
- variance
Optional variance for the value. Must be non-negative when present.
- Type:
float | None, optional
- notes
Optional free-text note.
- Type:
str | None, optional
- schema_version
Contract version. Defaults to
CLIMATE_SCHEMA_VERSION.- Type:
str, optional
- classmethod from_dict(record)[source]
Validate and construct a record from a mapping.
- Parameters:
record (mapping[str, object]) – Candidate record.
- Returns:
The validated record.
- Return type:
- Raises:
ClimateContractError – If the record violates
femic.climate.v1.
- femic.contracts.climate.climate_schema()[source]
Return a defensive copy of the
femic.climate.v1JSON Schema.- Returns:
A copy of the schema document, safe for a caller to mutate.
- Return type:
dict[str, object]
- femic.contracts.climate.read_climate_table(path)[source]
Read and validate a climate table from CSV or JSON.
- Parameters:
path (pathlib.Path) –
.csvfile with one record per row, or.jsonfile containing a list of records or an object with arecordslist.- Returns:
The validated records in file order.
- Return type:
tuple[ClimateRecord, …]
- Raises:
ClimateContractError – If the suffix is unsupported, the file is empty, or any record is invalid.
- femic.contracts.climate.summarize_climate_table(records)[source]
Return a provenance-bearing summary of a climate table.
- Parameters:
records (sequence[ClimateRecord]) – Validated records.
- Returns:
Counts, AOIs, variables, units, scenarios, year range, source tuples, and the retrieval-time range. This is the shape a consumer can report without copying the whole table.
- Return type:
dict[str, object]
- Raises:
ClimateContractError – If the table is empty.
- femic.contracts.climate.validate_climate_record(record)[source]
Validate one climate record against
femic.climate.v1.- Parameters:
record (mapping[str, object]) – Candidate record.
- Raises:
ClimateContractError – If the record is not a mapping, has unknown or missing fields, carries an unsupported variable or scenario, has a unit that does not match the variable, has an out-of-range year, or has an invalid value, variance, or timestamp.
- Return type:
None
- femic.contracts.climate.write_climate_table(path, records)[source]
Write a validated climate table to CSV or JSON.
- Parameters:
path (pathlib.Path) – Destination
.csvor.jsonpath.records (sequence[ClimateRecord]) – Records to write. Each is validated before writing.
- Raises:
ClimateContractError – If the suffix is unsupported or a record is invalid.
- Return type:
None