Skip to content

Configuration Schema

TerraFlow uses a single YAML configuration file that maps to the PipelineConfig model. It is validated with Pydantic v2 and rejects unknown fields. Geographic coordinates are validated with custom pydantic field validators.

Top-level fields

Field Type Description
raster_path string Path to the input raster (GeoTIFF).
raster_band integer 1-based rasterio band index for multi-band inputs (default: 1). Out-of-range values raise ValueError at start-up; the selected band is captured in manifest.json.
climate_csv string Path to the climate CSV (must have lat, lon, and climate variable columns).
output_dir string Directory to write run outputs.
roi object Region of interest definition (bbox supported).
model_params object Parameters for suitability scoring.
climate object Climate data handling configuration (optional, defaults to spatial interpolation).
sensitivity object Optional Sobol' / Morris sensitivity analysis block (consumed by terraflow sensitivity).
validation object Optional spatial-block CV block (consumed by terraflow validate).
max_cells integer Maximum cells sampled from the ROI (default: 500).

ROI (bbox)

Field Type Default Description
type string "bbox" Must be "bbox" (only supported type).
xmin float — West boundary.
ymin float — South boundary.
xmax float — East boundary.
ymax float — North boundary.
roi_crs string "EPSG:4326" CRS of the bbox coordinates. Use any EPSG code or WKT string accepted by pyproj. Set to the raster's native CRS (e.g. "EPSG:5070") when coordinates are in projected metres.

ROI Examples

Most common case — specifying your region in latitude/longitude degrees.

config.yml
roi:
  type: bbox
  xmin: -120.5   # West longitude
  ymin: 34.0     # South latitude
  xmax: -118.0   # East longitude
  ymax: 35.5     # North latitude
  # roi_crs defaults to EPSG:4326 — no change needed

Your raster is in a projected CRS (e.g., UTM, Albers), but you specify ROI in WGS84 degrees. TerraFlow reprojects automatically.

config.yml
roi:
  type: bbox
  xmin: -120.5   # WGS84 degrees
  ymin: 34.0
  xmax: -118.0
  ymax: 35.5
  roi_crs: "EPSG:4326"   # Pipeline reprojects to raster CRS

Your raster is in UTM/Albers and you want to specify ROI in meters directly.

config.yml
roi:
  type: bbox
  xmin: 500000    # UTM easting (meters)
  ymin: 4200000   # UTM northing (meters)
  xmax: 600000
  ymax: 4300000
  roi_crs: "EPSG:32614"  # UTM Zone 14N — no reprojection

Output Always in WGS84

Regardless of input CRS, the pipeline always writes lat / lon output columns in WGS 84 geographic degrees so downstream tools receive consistent coordinates.

Model parameters

Field Type Default Description
v_min / v_max float — Vegetation index suitability range
t_min / t_max float — Temperature (°C) suitability range
r_min / r_max float — Rainfall (mm) suitability range
w_v / w_t / w_r float — Weights (must sum to 1.0)
uncertainty_samples int 0 Monte Carlo draws per cell for score confidence intervals. Requires interpolation_method: kriging. 0 disables. 
model_params:
  v_min: 0.0
  v_max: 1.0
  t_min: 10.0
  t_max: 35.0
  r_min: 100.0
  r_max: 800.0
  w_v: 0.4
  w_t: 0.3
  w_r: 0.3
  uncertainty_samples: 0  # set >0 with kriging to get score_ci_low/score_ci_high

Climate configuration

Climate data is applied per-cell using configurable interpolation strategies and algorithms.

climate fields

Field Type Default Description
strategy string "spatial" "spatial" or "index" — how cells are matched to climate observations
interpolation_method string "linear" "linear", "kriging", or "idw" — spatial algorithm (ignored when strategy: index)
variogram_mode string "standard" "standard" tries spherical/exponential/Gaussian; "extended" also evaluates nested kriging candidates (kriging only)
fallback_to_mean bool true Use global mean for cells outside interpolation range
cell_id_column string null Column for explicit cell ID matching (index strategy only)
temporal_aggregations list [] Optional list of climate aggregation rules computed per cell per scenario (climate-impact flagship, #138).
scenarios list [] Optional list of named climate scenarios (historical / SSP variants). Required when temporal_aggregations is non-empty.

Climate-impact aggregations and scenarios (flagship #138)

Why: Climate-impact assessment needs the same suitability calculation across multiple time slices — historical baseline plus projected CMIP6 scenarios — combined with crop-specific climate indicators. TerraFlow expresses this as a (temporal_aggregations × scenarios) outer product: each rule is computed for each scenario, producing scenario-tagged derived columns on features.parquet.

Defaults: Both lists default to empty, which preserves the historical single-period behaviour. The pipeline only enters the multi-scenario code path when both lists are non-empty.

Supported temporal_aggregations[].kind values and their required fields:

kind Required fields Description
annual_mean — Yearly mean of the climate variable
seasonal_mean months: [1..12] Mean over the selected calendar months
growing_degree_days base_temp_c: float GDD accumulation above the base temperature
frost_days threshold_c: float Count of days at or below the threshold
heat_stress_days threshold_c: float Count of days at or above the threshold
precip_percentile percentile: 0..100 Nth percentile of daily precipitation
spei timescale_months: int > 0 Standardised Precipitation-Evapotranspiration Index

scenarios[] entries take a free-form name (typically historical, ssp245, ssp585) and a closed period: [year_min, year_max] pair (e.g. [1991, 2020]). Scenario names must be unique within a config.

Example (full flagship block):

config.yml
climate:
  strategy: spatial
  interpolation_method: kriging
  temporal_aggregations:
    - kind: annual_mean
    - kind: seasonal_mean
      months: [4, 5, 6, 7, 8, 9]   # growing season
    - kind: growing_degree_days
      base_temp_c: 10.0
    - kind: frost_days
      threshold_c: 0.0
    - kind: heat_stress_days
      threshold_c: 35.0
    - kind: precip_percentile
      percentile: 95.0
    - kind: spei
      timescale_months: 3
  scenarios:
    - { name: historical, period: [1991, 2020] }
    - { name: ssp245, period: [2041, 2070] }
    - { name: ssp585, period: [2041, 2070] }

Interpolation methods

Fast triangular interpolation via scipy.interpolate.griddata. No extra dependencies.

config.yml
climate:
  strategy: spatial
  interpolation_method: linear
  fallback_to_mean: true

Ordinary Kriging via pykrige. Geostatistically optimal; selects variogram model automatically via LOOCV. Adds {var}_krig_std columns to output. Combine with uncertainty_samples for score confidence intervals.

config.yml
climate:
  strategy: spatial
  interpolation_method: kriging
  variogram_mode: standard
  fallback_to_mean: true
model_params:
  # ... other params ...
  uncertainty_samples: 500  # produces score_ci_low / score_ci_high

Set variogram_mode: extended to evaluate additional nested candidates and record their LOOCV scores in report.json. Extended mode fits custom nested variograms before LOOCV, so it is slower than standard mode on large station networks.

Requires pykrige

Install with pip install terraflow-agro[kriging] or pip install pykrige.

Inverse Distance Weighting (power=2). Faster than kriging, no uncertainty output.

config.yml
climate:
  strategy: spatial
  interpolation_method: idw
  fallback_to_mean: true

Match climate CSV rows to cells by row order or explicit cell ID. No interpolation.

config.yml
climate:
  strategy: index
  cell_id_column: null    # optional: column for explicit ID matching
  fallback_to_mean: true

Climate CSV format

Must include lat and lon columns with valid coordinates:

lat,lon,mean_temp,total_rain
40.005,-100.005,22.5,650
40.015,-99.995,23.1,680
40.025,-99.985,21.8,620
  • lat: Latitude in [-90, 90]
  • lon: Longitude in [-180, 180]
  • Climate variables: One or more numeric columns (mean_temp, total_rain, etc.)

If climate is omitted entirely, defaults to strategy: spatial, interpolation_method: linear, variogram_mode: standard, fallback_to_mean: true.