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.
~0.1 km² each
~86 km² each
per cell, baseline
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
/suitabilityPre-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 = yellow → 1.0 = green (ideal)
Scored crops: Wheat · Barley · Sugar Beet · Sunflower · Maize · Chickpea · Lentil · Cotton
Yield & Profit
/yield-profitPre-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: loss → break-even → profit (breakpoints at −500 / 0 / +500 USD/ha)
What-If
/scenariosDraw 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
| Layer | Technology |
|---|---|
| Spatial indexing | H3 hexagonal grid (Uber) — res-6 to res-9 |
| Database | PostgreSQL 16 + PostGIS 3 + TimescaleDB |
| ETL pipeline | Python 3.11, pandas, xarray, h3-py, Alembic |
| Web backend | Flask 3.x, SQLAlchemy 2.x, GeoAlchemy2 |
| Async scoring | Celery + Redis |
| Frontend | MapLibre GL JS, Chart.js, vanilla JS (no build step) |
| Containerization | Docker 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 Zoom | H3 Resolution | Cell area | Data shown |
|---|---|---|---|
| < 7 | Cluster | — | Centroid clusters (MapLibre native) |
| 7–8 | res-6 | ~86 km² | ERA5 weather only |
| 9–10 | res-7 | ~12 km² | All features (aggregated) |
| 11 | res-8 | ~1.8 km² | All features (aggregated) |
| ≥ 12 | res-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.