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_COLUMNS The 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 is aoi_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 to DEFAULT_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.