terraflow-agro 0.4.0

TerraFlow: a reproducible workflow for geospatial agricultural modeling.

TerraFlow: Reproducible Geospatial Agricultural Modeling

TerraFlow is a reproducible, config-driven geospatial workflow for agricultural suitability modeling. Give it a land-cover raster, a climate CSV, and a YAML config — it returns a scored, location-stamped results table with full provenance.

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)"]
    PIPE --> GEO["Geospatial<br/>(ROI clipping)"]
    PIPE --> MOD["Model<br/>(suitability scoring)"]
    PIPE --> OUT["Outputs<br/>(Parquet, CSV,<br/>manifest, report)"]
    ING --> GEO
    ING --> MOD
    GEO --> MOD

Property	What TerraFlow guarantees
Deterministic outputs	Same config + same inputs → bit-identical results, addressed by run fingerprint
Provenance	Every run writes a manifest.json capturing config, input hashes, software versions, and fingerprint
Spatial validation	Spatial-block CV with Cohen's κ + Moran's I on residuals (terraflow validate)
Sensitivity analysis	Sobol' / Morris indices for model weights (terraflow sensitivity)
Uncertainty quantification	Kriging Monte Carlo → score CIs (score_ci_low / score_ci_high)
Interop	H3-indexed export for downstream tools (terraflow export --format h3)
GeoAI engines (optional)	terraflow geoai {fields,landcover,canopy} runners with deterministic fingerprinted caching (pip install terraflow-agro[geoai])
Distribution	PyPI (terraflow-agro) + Homebrew (gmarupilla/terraflow) + Docker
Citation	Citable via CITATION.cff; JOSS paper in preparation

---

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

For the optional GeoAI engines (field-boundary detection, landcover classification, canopy regression):

pip install "terraflow-agro[geoai]"

This installs geoai-py and torch; the GeoAI runners auto-detect CUDA or Apple Silicon MPS at runtime.

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

Subcommand	Purpose
terraflow run -c config.yml	Run the full pipeline
terraflow sensitivity -c config.yml	Sobol' / Morris sensitivity indices for model weights
terraflow validate -c config.yml	Spatial block CV, Cohen's kappa, Moran's I on residuals
terraflow export --format h3 -c config.yml	H3-indexed export for interop with H3-native visualization tools (pip install terraflow-agro[h3])
terraflow geoai fields -c config.yml	Field-boundary detection via the optional GeoAI engine (pip install terraflow-agro[geoai])
terraflow geoai landcover -c config.yml	Landcover classification (GeoAI extra)
terraflow geoai canopy -c config.yml	Canopy-height regression (GeoAI extra)

See CLI docs and the GeoAI guide for full reference.

Climate interpolation

Three spatial algorithms are available via interpolation_method:

Method	Notes
linear (default)	scipy.griddata — fast, no extra deps
kriging	Ordinary Kriging via pykrige; adds {var}_krig_std uncertainty columns
idw	Inverse Distance Weighting (power=2) — faster than kriging, no uncertainty

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, climate, core/run_identity, exceptions, export, geo, ingest, model, pipeline, sensitivity, stats, utils, validation, 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 our JOSS paper (manuscript in preparation).

License

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