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: ``.csv`` with one record per row, or ``.json`` with a
list of records (or an object with a ``records`` list).
- 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
-------------
.. list-table::
:header-rows: 1
:widths: 22 14 64
* - Field
- Type
- Meaning
* - ``schema_version``
- string
- Must be ``femic.climate.v1``.
* - ``aoi_id``
- string
- Area-of-interest identifier the value applies to.
* - ``variable``
- string
- Canonical variable, one of the table below.
* - ``unit``
- string
- Canonical unit for the variable.
* - ``year``
- integer
- Calendar year, 1900-2300.
* - ``scenario``
- string
- Scenario label from the canonical list.
* - ``gcm``
- string
- GCM, ensemble, or ``observed`` label.
* - ``value``
- number
- Finite climate value in ``unit``.
* - ``variance``
- number or null
- Optional variance. Must be finite and non-negative.
* - ``source_id``
- string
- Upstream source identifier.
* - ``source_version``
- string
- Source release or version.
* - ``downscaling_method``
- string
- Downscaling or processing method, or ``none``.
* - ``retrieved_utc``
- string
- ISO-8601 retrieval timestamp with a timezone.
* - ``notes``
- string or null
- Optional free-text note.
Variables and Units
-------------------
.. list-table::
:header-rows: 1
:widths: 25 25 50
* - Variable
- Unit
- Meaning
* - ``tavg``
- ``degC``
- Mean temperature.
* - ``tmax``
- ``degC``
- Maximum temperature.
* - ``tmin``
- ``degC``
- Minimum temperature.
* - ``mat``
- ``degC``
- Mean annual temperature.
* - ``ppt``
- ``mm``
- Total precipitation.
* - ``prcp``
- ``mm``
- Precipitation (source-compatible alias).
* - ``map``
- ``mm``
- Mean annual precipitation.
* - ``snow``
- ``mm``
- Snowfall or snow water equivalent.
* - ``cwd``
- ``mm``
- Climatic water deficit.
* - ``pet``
- ``mm``
- Potential evapotranspiration.
* - ``rh``
- ``percent``
- Relative humidity.
* - ``vpd``
- ``kPa``
- Vapour pressure deficit.
* - ``gdd``
- ``degree_days``
- 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
-------------------------
:func:`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
``:``; with one row it is the base id. The source column name is
appended to ``notes`` for provenance.
.. code-block:: python
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_version`` is exact; a new shape needs a new version.
- ``variable`` must be in the canonical set, and ``unit`` must match it.
- ``year`` must be an integer in 1900-2300; booleans are not integers here.
- ``value`` and ``variance`` must be finite; ``variance`` is non-negative.
- ``retrieved_utc`` must be ISO-8601 and timezone-aware.
- The table must contain at least one record.
Provenance Summary
------------------
:func:`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
-------
.. code-block:: python
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.
Cross-References
----------------
- :doc:`../api/femic-contracts-climate`
- :doc:`../api/femic-contracts-climate-na`
- :doc:`index`
.. toctree::
:hidden:
../api/femic-contracts-climate