Climate Contract (femic.climate.v1)
Purpose
This page is the source-of-truth contract for the climate table that FEMIC, ws3, ws4, and Nemora exchange. It defines one validated record, the canonical units and scenario labels, the table formats, and the provenance a consumer can report.
The contract does not download ClimateNA data, choose a GCM ensemble, or model climate. An adapter is responsible for converting a source to this table.
Quick Contract
Record schema:
femic.climate.v1.Canonical table files:
.csvwith one record per row, or.jsonwith a list of records (or an object with arecordslist).Required timezone: ISO-8601 with an explicit offset.
Canonical scenarios:
historical,rcp26,rcp45,rcp60,rcp85,ssp126,ssp245,ssp370,ssp585.Canonical units are fixed per variable; adapters convert before writing.
The validator rejects unknown fields, missing fields, unsupported variables, mismatched units, out-of-range years, non-finite values, negative variance, and timestamps without a timezone.
Record Fields
Field |
Type |
Meaning |
|---|---|---|
|
string |
Must be |
|
string |
Area-of-interest identifier the value applies to. |
|
string |
Canonical variable, one of the table below. |
|
string |
Canonical unit for the variable. |
|
integer |
Calendar year, 1900-2300. |
|
string |
Scenario label from the canonical list. |
|
string |
GCM, ensemble, or |
|
number |
Finite climate value in |
|
number or null |
Optional variance. Must be finite and non-negative. |
|
string |
Upstream source identifier. |
|
string |
Source release or version. |
|
string |
Downscaling or processing method, or |
|
string |
ISO-8601 retrieval timestamp with a timezone. |
|
string or null |
Optional free-text note. |
Variables and Units
Variable |
Unit |
Meaning |
|---|---|---|
|
|
Mean temperature. |
|
|
Maximum temperature. |
|
|
Minimum temperature. |
|
|
Mean annual temperature. |
|
|
Total precipitation. |
|
|
Precipitation (source-compatible alias). |
|
|
Mean annual precipitation. |
|
|
Snowfall or snow water equivalent. |
|
|
Climatic water deficit. |
|
|
Potential evapotranspiration. |
|
|
Relative humidity. |
|
|
Vapour pressure deficit. |
|
|
Growing degree days. |
Scenarios
historical is the observed or baseline lane. rcp* labels are retained
for ClimateNA v6/v7 outputs; ssp* labels are the CMIP6 generation. A single
GCM is not a scenario: record the ensemble or model label in gcm and the
selection rule in the adapter documentation.
Table Formats
CSV files carry one record per row with the header fields in this order:
schema_version,aoi_id,variable,unit,year,scenario,gcm,value,variance,
source_id,source_version,downscaling_method,retrieved_utc,notes
JSON files carry a list of record objects, or an object with a records
list. Empty tables are rejected: a consumer should fail on an empty table
rather than silently report zero records.
ClimateNA/SilvR21 Adapter
femic.contracts.climate_na.read_climate_na_csv() reads an annual
ClimateNA-style CSV and emits femic.climate.v1 records. The default map
covers MAT/Tave, MAP/PPT, MWMT, MCMT, DD5, NFFD,
PAS, CMD, Eref, RH, and VPD. A caller can supply an explicit
column_map for a release with different names.
The adapter does not download data, choose an ensemble, or convert between
non-canonical units. It skips missing tokens such as NA and rejects a
non-numeric mapped value. With multiple rows, the record aoi_id is
<base>:<ID>; with one row it is the base id. The source column name is
appended to notes for provenance.
from pathlib import Path
from femic.contracts.climate_na import read_climate_na_csv
records = read_climate_na_csv(
Path("data/climate/climate-na-2050.csv"),
aoi_id="north-island",
year=2050,
scenario="ssp245",
gcm="ensemble",
source_version="ClimateNA v7.40",
retrieved_utc="2026-10-25T00:00:00+00:00",
)
Validation Rules
Unknown fields and missing required fields are errors.
schema_versionis exact; a new shape needs a new version.variablemust be in the canonical set, andunitmust match it.yearmust be an integer in 1900-2300; booleans are not integers here.valueandvariancemust be finite;varianceis non-negative.retrieved_utcmust be ISO-8601 and timezone-aware.The table must contain at least one record.
Provenance Summary
femic.contracts.climate.summarize_climate_table() returns counts, AOIs,
variables, units, scenarios, the year range, deduplicated source tuples, and
the retrieval-time range. A consumer should report this summary with any
derived product so a reader can see which source and downscaling method were
used.
Example
from pathlib import Path
from femic.contracts.climate import (
read_climate_table,
summarize_climate_table,
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)
Out of Scope
A ClimateNA/SilvR21 adapter or a GCM ensemble selector.
A climate model, downscaling algorithm, or gap-filling method.
A climate-growth response function or yield modifier.
A database or data portal.