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.

  • ClimateRecord Typed record with canonical to_dict and from_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.v1 record. Call climate_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: ValueError

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

One validated femic.climate.v1 record.

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:

ClimateRecord

Raises:

ClimateContractError – If the record violates femic.climate.v1.

to_dict()[source]

Return the canonical dict form, including null optional fields.

Return type:

dict[str, object]

femic.contracts.climate.climate_schema()[source]

Return a defensive copy of the femic.climate.v1 JSON 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) – .csv file with one record per row, or .json file containing a list of records or an object with a records list.

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 .csv or .json path.

  • 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