TerraFlow: A Reproducible Geospatial Suitability Framework

TerraFlow is a reproducible, config-driven framework for climate-impact assessment of agricultural suitability. Give it a land-cover raster, a climate CSV (weather-station observations), and a YAML config — it returns a scored, location-stamped per-cell results table with full provenance and per-cell uncertainty intervals. As of v0.5.0 the framework also fans out climate-induced crop hazards (growing-degree days, frost days, heat-stress days, precipitation percentiles, simplified Thornthwaite SPEI) across arbitrary CMIP6 SSP scenario windows, writing a sibling climate_features.parquet artifact alongside the historical suitability score. The same workflow methodology extends to habitat suitability, land-use planning, and conservation siting.

Documentation: terraflow.marupilla.dev — see the Reproducibility page for what the run fingerprint covers and known sources of non-determinism.

At a Glance

flowchart LR
    CFG["Config<br/>(YAML + Pydantic)"] --> PIPE["Pipeline<br/>(orchestration)"]
    PIPE --> ING["Ingest<br/>(raster, climate CSV,<br/>timeseries CSV / CMIP6)"]
    PIPE --> GEO["Geospatial<br/>(ROI clip, CRS)"]
    PIPE --> CIM["Climate impact<br/>(temporal, hazard,<br/>CMIP6)"]
    PIPE --> MOD["Model<br/>(suitability scoring)"]
    PIPE --> OUT["Outputs<br/>(features.parquet,<br/>climate_features.parquet,<br/>manifest, report)"]
    ING --> GEO
    ING --> CIM
    ING --> MOD
    GEO --> MOD
    CIM --> OUT
    MOD --> OUT

Drought-impact prediction benchmark

terraflow drought builds and evaluates an impact-labeled drought benchmark — predicting insured drought loss (USDA RMA Cause of Loss) from within-season climate/vegetation anomalies. It is a decision-relevant impact target, distinct from drought severity (USDM D2+) and crop yield benchmarks (CY-Bench, SustainBench).

terraflow drought fetch    --rma-dir data/drought/rma --year-min 2000 --year-max 2023
terraflow drought build    -c examples/drought_v0_corn_6state.yml
terraflow drought evaluate -c examples/drought_v0_corn_6state.yml

Dataset on Zenodo: 10.5281/zenodo.21208651 (CC-BY-4.0). See the drought benchmark guide.

Installation

macOS (Homebrew) — handles GDAL and PROJ automatically:

brew tap gmarupilla/terraflow
brew install terraflow

pip / uv:

uv pip install terraflow-agro
# or
pip install terraflow-agro

For kriging-based interpolation:

pip install terraflow-agro pykrige

See Homebrew install docs for update/uninstall instructions and troubleshooting.

Quickstart

terraflow run --config config.yml

A minimal config:

raster_path: "data/land_cover.tif"
climate_csv: "data/climate.csv"
output_dir: "outputs"
roi:
  type: bbox
  xmin: -120.5
  ymin: 34.0
  xmax: -118.0
  ymax: 35.5
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

Results are written to outputs/runs/<fingerprint>/:

features.parquet   — scored cells (lat, lon, score, label, …)
results.csv        — same data in CSV
manifest.json      — full provenance record
report.json        — QA stats and timings

CLI subcommands

See CLI docs for full reference. End-to-end climate-impact example: examples/demo_config_climate_impact.yml + the demo notebook.

Climate interpolation

Three spatial algorithms are available via interpolation_method:

Combine interpolation_method: kriging with uncertainty_samples: N in model_params to get Monte Carlo score confidence intervals (score_ci_low / score_ci_high). For kriging, variogram_mode: extended evaluates additional nested variogram candidates and records all LOOCV candidate scores in report.json; use the default standard mode for large station networks unless nested structures are needed. See the extended variogram notebook in the docs for a worked synthetic example.

See Config Schema for the full reference.

Python API

from terraflow.pipeline import run_pipeline

results_df = run_pipeline("config.yml")

Development

git clone https://github.com/gmarupilla/AgroTerraFlow.git
cd AgroTerraFlow
make dev       # create .venv and install dev deps
make test      # run test suite
make lint      # ruff + black
make docs-build

Architecture

Core modules: cli, config, pipeline, model, ingest, geo, climate, climate_impact, temporal, hazard, cmip6, sensitivity, validation, core/run_identity, stats, exceptions, utils, viz.

Run artifacts under <output_dir>/runs/<fingerprint>/ include features.parquet, manifest.json, report.json, and results.csv. When kriging is configured, report.json also carries kriging_diagnostics (model, nugget, sill, range), kriging_loocv RMSE per variable, uncertainty coverage, and an interpolation_fallback block with per-variable fallback-to-mean counts. Multi-band rasters are supported via the top-level raster_band field (1-based; default 1).

Key design decisions are documented in Architecture Decision Records under docs/architecture/. See docs/reproducibility.md for the run fingerprint contract and known sources of non-determinism.

Project Scope

TerraFlow is a reproducible pipeline for geospatial agricultural modeling. It handles raster ingestion, ROI clipping, climate interpolation, suitability scoring, and deterministic artifact generation.

In scope:

• Configuration-driven pipeline execution (YAML → Parquet + provenance artifacts)
• Spatial interpolation of point climate observations (linear, kriging, IDW)
• Per-cell suitability scoring with uncertainty quantification (Monte Carlo)
• Deterministic run fingerprinting and artifact caching

Out of scope:

• Real-time data ingestion or streaming workflows
• General-purpose raster analysis (use rioxarray or rasterstats instead)
• Cloud-scale distributed processing (no Dask/Spark integration planned)
• Web application or GUI layer

Maintenance & Support

TerraFlow is actively maintained. Bug fixes are prioritized; the test suite and CI pipeline are kept green on every commit.

Feature requests are evaluated against project scope — open an issue to discuss before building. Not all requests will be accepted.

Support is provided on a best-effort basis via GitHub Issues. Response time is typically within a week. There is no paid support tier.

Contributing

See CONTRIBUTING.md.

Citation

If you use TerraFlow in your research, please cite the archived Zenodo release:

Marupilla, G. (2026). TerraFlow: A Reproducible Framework for Climate-Impact Assessment of Agricultural Suitability (v0.5.0). Zenodo. https://doi.org/10.5281/zenodo.21070362

CITATION.cff carries the canonical metadata. A companion JOSS paper is drafted and will be resubmitted once external adoption signal materialises; see the postmortem at https://github.com/openjournals/joss-reviews/issues/10686.

License

MIT License — free for academic, commercial, and open-source use.