femic.contracts.climate_na Module
The femic.contracts.climate_na module adapts an annual ClimateNA-style
CSV to the femic.climate.v1 contract. It maps source columns to canonical
variables, converts nothing silently, and preserves the source column in the
record notes.
Use this page when you have a ClimateNA or SilvR21 annual export and need a validated climate table for FEMIC, ws4, or Nemora.
Start Here If…
Use this page first if you are trying to:
load an annual ClimateNA CSV without hand-building a table;
map a release with non-standard column names;
preserve scenario, GCM, source version, and retrieval provenance; or
debug a non-numeric value or a missing mapped column.
Typical Usage
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",
)
Key Entry Surfaces
read_climate_na_csv()Read an annual ClimateNA-style CSV and emit validated records.climate_na_columns()Return a defensive copy of the default annual column map.DEFAULT_CLIMATE_NA_COLUMNSThe default source column to(variable, unit)map.
Cross-References
ClimateNA/SilvR21 CSV adapter for the femic.climate.v1 contract.
The adapter reads an annual ClimateNA-style CSV, maps its columns to canonical
climate variables, and emits validated ClimateRecord
rows. It does not download data, choose a GCM ensemble, or model climate.
ClimateNA files are wide and their column sets vary by version. The default map covers the annual columns used most often; a caller can supply an explicit map when a release uses different names.
- femic.contracts.climate_na.DEFAULT_CLIMATE_NA_COLUMNS: dict[str, tuple[str, str]] = {'CMD': ('cwd', 'mm'), 'DD5': ('gdd', 'degree_days'), 'Eref': ('pet', 'mm'), 'MAP': ('ppt', 'mm'), 'MAT': ('tavg', 'degC'), 'MCMT': ('mcmt', 'degC'), 'MWMT': ('mwmt', 'degC'), 'NFFD': ('nffd', 'days'), 'PAS': ('snow', 'mm'), 'PPT': ('ppt', 'mm'), 'RH': ('rh', 'percent'), 'Tave': ('tavg', 'degC'), 'VPD': ('vpd', 'kPa')}
Annual ClimateNA columns and their canonical
(variable, unit)pairs.
- femic.contracts.climate_na.climate_na_columns()[source]
Return a defensive copy of the default ClimateNA column map.
- Return type:
dict[str, tuple[str, str]]
- femic.contracts.climate_na.read_climate_na_csv(path, *, aoi_id, year, scenario, gcm, source_version, retrieved_utc, source_id='climate-na', downscaling_method='climate-na', column_map=None, row_id_column='ID', variance=None, notes=None, require_all_columns=False)[source]
Read a ClimateNA-style annual CSV and emit climate records.
- Parameters:
path (pathlib.Path) – CSV file with one row per location and ClimateNA annual columns.
aoi_id (str) – Base area-of-interest id. With multiple rows, the record id is
f"{aoi_id}:{row_id}"; with one row it isaoi_id.year (int) – Calendar year or period label for every record in the file.
scenario (str) – Scenario label from the canonical climate vocabulary.
gcm (str) – GCM or ensemble label.
source_version (str) – ClimateNA/SilvR21 release or version.
retrieved_utc (str) – Timezone-aware ISO-8601 retrieval timestamp.
source_id (str, optional) – Upstream source id. Defaults to
"climate-na".downscaling_method (str, optional) – Downscaling method. Defaults to
"climate-na".column_map (mapping[str, tuple[str, str]] | None, optional) – Source column to
(variable, unit)mapping. Defaults toDEFAULT_CLIMATE_NA_COLUMNS.row_id_column (str, optional) – Column used to distinguish locations. Defaults to
"ID".variance (float | None, optional) – Optional variance applied to every emitted record.
notes (str | None, optional) – Optional note; the source column name is appended for provenance.
require_all_columns (bool, optional) – If true, every mapped column must exist in the CSV. Defaults to false so a release with a smaller annual column set still loads.
- Returns:
Validated records in CSV row and column-map order.
- Return type:
tuple[ClimateRecord, …]
- Raises:
ClimateContractError – If the file is not a CSV, has no header or rows, a mapped column is missing when required, a mapped value is not numeric, no records are produced, or a record violates
femic.climate.v1.