Documentation

AgriTwin — Agricultural digital twin for Konya Province, Turkey

About the Project

AgriTwin is an open agricultural digital twin for Konya Province, Turkey — the country's single largest and most productive agricultural region, covering roughly 40,000 km². It integrates satellite imagery, climate reanalysis, and soil survey data into a unified PostgreSQL database indexed on the H3 hexagonal grid at five resolution levels (res-6 through res-9).

The platform lets agronomists, planners, and researchers explore field-level environmental conditions, score crop suitability, model what-if scenarios, and evaluate economic outcomes — directly in a browser, with no software to install.

346,787 H3 res-9 cells
~0.1 km² each
1,007 ERA5 res-6 cells
~86 km² each
8 Crops scored
per cell, baseline
2018–2023 Temporal range
ERA5 / MODIS monthly

Features

Field Explorer

/

Browse the full H3 grid across five zoom levels — from 86 km² ERA5 weather cells down to 0.1 km² field-level cells. Click any cell to open the detail sidebar with two tabs:

  • Latest — terrain (elevation, slope, aspect), weather snapshot, vegetation indices, and soil properties. Each row is also a radio button that recolors the map by that feature.
  • Historic — multi-year timeseries charts: NDVI history, temperature & precipitation, temperature range (mean vs min), solar radiation, and actual evapotranspiration.

The map recolors on every pan and zoom, fetching only cells in the current viewport via a ?bbox= API. Panel width is drag-resizable and persists in localStorage.

Crop Fit

/suitability

Pre-computed suitability scores (0–1) for 8 crops per res-9 cell, using a trapezoidal fuzzy membership function against monthly ERA5 climate data and SoilGrids soil properties. Scores are computed by the ETL pipeline and stored in the database; the app is read-only.

  • Tab 1 — Crop Scores: 8 crop rows with radio buttons, CSS progress bars, and numeric scores (0.00–1.00). Selecting a crop radio recolors the map immediately.
  • Tab 2 — Monthly Detail: Chart.js band chart overlaying the actual monthly climate value for this cell against the crop's ideal min/max requirement band — one feature at a time. Growing-season months only; off-season months show no band.

Color ramp: 0.0 = red (poor)0.5 = yellow1.0 = green (ideal)

Scored crops: Wheat · Barley · Sugar Beet · Sunflower · Maize · Chickpea · Lentil · Cotton

Yield & Profit

/yield-profit

Pre-computed economic projections per cell per crop, built from suitability scores, FAOSTAT commodity prices, and TAGEM production costs.

  • Yield estimate: ref_yield × (0.2 + 0.8 × score) — the 20% floor prevents unrealistic zero-yield cells.
  • Net profit: yield × price − total_cost, where costs are TAGEM 2022 figures CPI-adjusted to 2024 (factor 1.40).
  • Confidence bands: High ±20% (Wheat, Barley) · Medium ±40% (most crops) · Low ±60% (Cotton).
  • ⓘ notes for Sugar Beet, Chickpea, Sunflower, Maize flag irrigation requirements, rotation constraints, and regional processing capacity limits.

Map color ramp: lossbreak-evenprofit (breakpoints at −500 / 0 / +500 USD/ha)

What-If

/scenarios

Draw a polygon over any area on the map and apply environmental override deltas — then watch cells re-scored in the background by a Celery worker.

  • Overrides: precipitation (±mm/month), temperature (±°C), soil pH (±units). Deltas are additive on top of the observed ERA5 / SoilGrids values.
  • Result page: side-by-side dual map (baseline left, scenario right) synced on pan and zoom. Right sidebar shows baseline vs scenario score per crop, plus a monthly chart overlaying baseline and override climate lines against the ideal requirement band.
  • Demo scenarios: four pre-seeded examples cover drought, irrigation boost, warming, and soil acidification — available immediately without drawing a polygon.

Technical Overview

LayerTechnology
Spatial indexingH3 hexagonal grid (Uber) — res-6 to res-9
DatabasePostgreSQL 16 + PostGIS 3 + TimescaleDB
ETL pipelinePython 3.11, pandas, xarray, h3-py, Alembic
Web backendFlask 3.x, SQLAlchemy 2.x, GeoAlchemy2
Async scoringCelery + Redis
FrontendMapLibre GL JS, Chart.js, vanilla JS (no build step)
ContainerizationDocker Compose — db, redis, migrate, web, celery_worker, loader

H3 Zoom Ladder

The monitoring map uses five zoom modes to balance data volume with spatial fidelity:

Map ZoomH3 ResolutionCell areaData shown
< 7ClusterCentroid clusters (MapLibre native)
7–8res-6~86 km²ERA5 weather only
9–10res-7~12 km²All features (aggregated)
11res-8~1.8 km²All features (aggregated)
≥ 12res-9~0.1 km²All features (raw observations)

ERA5 weather observations are stored only at res-6. For higher-resolution cells the API maps each cell to its res-6 parent at query time — no duplication.