# davidsamah/jordan-agricultural-water-stress-v0 architecture

> Architecture diagram of the GitHub repository davidsamah/jordan-agricultural-water-stress-v0, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davidsamah/jordan-agricultural-water-stress-v0
- Repository: https://github.com/davidsamah/jordan-agricultural-water-stress-v0

## Overview

This is a research prototype for forecasting next-month shallow-soil-moisture stress in the Northern Jordan Valley, not an operational alerting service. Its main workflow turns processed climate observations into a leakage-safe target and lagged feature table, trains and evaluates a Random Forest against persistence and seasonal-climatology baselines, then produces uncertainty, sensitivity, visualization, and reporting outputs. The README also describes literature review, data acquisition, and verification, but those implementations were not sampled; their relationships are therefore not asserted.

Main entry points: [`scripts/train_v0.py`](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/train_v0.py) (Train and compare), [`scripts/plot_results.py`](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/plot_results.py) (Result plots), [`data/processed_v0/model_dataset_lagged.csv`](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/model_dataset_lagged.csv) (Lagged model dataset), [`results/test_predictions_2024.csv`](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/test_predictions_2024.csv) (2024 predictions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Environmental data"]
  node_chirps[("CHIRPS precipitation")]
  node_era5[("ERA5-Land variables")]
end

subgraph group_prep["Target and features"]
  node_climate[("Climate feature table")]
  node_complete[("Complete features")]
  node_target["Stress target builder<br/>[build_target.py]"]
  node_modeldata[("Target dataset<br/>[model_dataset.csv]")]
  node_featurebuilder["Lag and season features<br/>[build_features.py]"]
  node_lagged[("Lagged model dataset")]
  node_leakage["Leakage checks<br/>[leakage_check.py]"]
end

subgraph group_eval["Forecast evaluation"]
  node_trainer["Train and compare<br/>[train_v0.py]"]
  node_model["Random Forest model"]
  node_metrics["Evaluation metrics<br/>[metrics_v0.json]"]
  node_predictions["2024 predictions"]
  node_importance["Feature importance"]
  node_bootstrap["Bootstrap uncertainty<br/>[bootstrap_test.py]"]
  node_sensitivity["Threshold sensitivity"]
  node_sensitivityout["Sensitivity results"]
end

subgraph group_research["Research outputs"]
  node_plotter["Result plots<br/>[plot_results.py]"]
  node_figures["Research figures"]
  node_reporter["Report generator<br/>[make_report.py]"]
  node_report["Experiment report"]
  node_evidence["Research evidence"]
  node_notes["Study notes"]
end

node_complete -->|"provides input"| node_target
node_target -->|"writes target"| node_modeldata
node_modeldata -->|"provides input"| node_featurebuilder
node_featurebuilder -->|"writes features"| node_lagged
node_lagged -->|"provides input"| node_trainer
node_lagged -->|"checks ordering"| node_leakage
node_trainer -->|"saves model"| node_model
node_trainer -->|"writes metrics"| node_metrics
node_trainer -->|"writes predictions"| node_predictions
node_trainer -->|"writes importance"| node_importance
node_predictions -->|"reads predictions"| node_sensitivity
node_sensitivity -->|"writes results"| node_sensitivityout
node_complete -->|"reads features"| node_plotter
node_predictions -->|"reads predictions"| node_plotter
node_importance -->|"reads importance"| node_plotter
node_plotter -->|"writes figures"| node_figures
node_metrics -->|"reads metrics"| node_reporter
node_importance -->|"reads importance"| node_reporter
node_reporter -->|"writes report"| node_report
node_chirps -.->|"contributes precipitation"| node_climate
node_era5 -.->|"contributes variables"| node_climate

click node_chirps "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/data/chirps/processed"
click node_era5 "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/data/era5land/processed"
click node_climate "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/climate_features_2018_2024_monthly.csv"
click node_complete "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/features_complete.csv"
click node_target "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/build_target.py"
click node_modeldata "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/model_dataset.csv"
click node_featurebuilder "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/build_features.py"
click node_lagged "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/model_dataset_lagged.csv"
click node_leakage "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/leakage_check.py"
click node_trainer "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/train_v0.py"
click node_model "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/models/random_forest_v0.joblib"
click node_metrics "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/metrics_v0.json"
click node_predictions "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/test_predictions_2024.csv"
click node_importance "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/feature_importance.csv"
click node_bootstrap "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/bootstrap_test.py"
click node_sensitivity "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/threshold_sensitivity.py"
click node_sensitivityout "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/threshold_sensitivity.csv"
click node_plotter "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/plot_results.py"
click node_figures "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/figures"
click node_reporter "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/make_report.py"
click node_report "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/reports/v0_experiment_report.md"
click node_evidence "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/evidence"
click node_notes "https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/notes"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chirps,node_era5 toneBlue
class node_climate,node_complete,node_target,node_modeldata,node_featurebuilder,node_lagged,node_leakage toneAmber
class node_trainer,node_model,node_metrics,node_predictions,node_importance,node_bootstrap,node_sensitivity,node_sensitivityout toneMint
class node_plotter,node_figures,node_reporter,node_report,node_evidence,node_notes toneRose
```

## Components

### Environmental data

- [CHIRPS precipitation](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/data/chirps/processed): `data/chirps/processed`
- [ERA5-Land variables](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/data/era5land/processed): `data/era5land/processed`

### Target and features

- [Climate feature table](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/climate_features_2018_2024_monthly.csv): `data/processed_v0/climate_features_2018_2024_monthly.csv`
- [Complete features](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/features_complete.csv): `data/processed_v0/features_complete.csv`
- [Stress target builder](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/build_target.py): `scripts/build_target.py`
- [Target dataset](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/model_dataset.csv): `data/processed_v0/model_dataset.csv`
- [Lag and season features](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/build_features.py): `scripts/build_features.py`
- [Lagged model dataset](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/data/processed_v0/model_dataset_lagged.csv): `data/processed_v0/model_dataset_lagged.csv`
- [Leakage checks](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/leakage_check.py): `scripts/leakage_check.py`

### Forecast evaluation

- [Train and compare](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/train_v0.py): `scripts/train_v0.py`
- [Random Forest model](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/models/random_forest_v0.joblib): `models/random_forest_v0.joblib`
- [Evaluation metrics](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/metrics_v0.json): `results/metrics_v0.json`
- [2024 predictions](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/test_predictions_2024.csv): `results/test_predictions_2024.csv`
- [Feature importance](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/feature_importance.csv): `results/feature_importance.csv`
- [Bootstrap uncertainty](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/bootstrap_test.py): `scripts/bootstrap_test.py`
- [Threshold sensitivity](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/threshold_sensitivity.py): `scripts/threshold_sensitivity.py`
- [Sensitivity results](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/results/threshold_sensitivity.csv): `results/threshold_sensitivity.csv`

### Research outputs

- [Result plots](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/plot_results.py): `scripts/plot_results.py`
- [Research figures](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/figures): `figures`
- [Report generator](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/scripts/make_report.py): `scripts/make_report.py`
- [Experiment report](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/blob/main/reports/v0_experiment_report.md): `reports/v0_experiment_report.md`
- [Research evidence](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/evidence): `evidence`
- [Study notes](https://github.com/davidsamah/jordan-agricultural-water-stress-v0/tree/main/notes): `notes`

## Connections

- Complete features → Stress target builder: provides input (evidence: `scripts/build_target.py`)
- Stress target builder → Target dataset: writes target (evidence: `scripts/build_target.py`)
- Target dataset → Lag and season features: provides input (evidence: `scripts/build_features.py`)
- Lag and season features → Lagged model dataset: writes features (evidence: `scripts/build_features.py`)
- Lagged model dataset → Train and compare: provides input (evidence: `scripts/train_v0.py`)
- Lagged model dataset → Leakage checks: checks ordering (evidence: `scripts/leakage_check.py`)
- Train and compare → Random Forest model: saves model (evidence: `scripts/train_v0.py`)
- Train and compare → Evaluation metrics: writes metrics (evidence: `scripts/train_v0.py`)
- Train and compare → 2024 predictions: writes predictions (evidence: `scripts/train_v0.py`)
- Train and compare → Feature importance: writes importance (evidence: `scripts/train_v0.py`)
- 2024 predictions → Threshold sensitivity: reads predictions (evidence: `scripts/threshold_sensitivity.py`)
- Threshold sensitivity → Sensitivity results: writes results (evidence: `scripts/threshold_sensitivity.py`)
- Complete features → Result plots: reads features (evidence: `scripts/plot_results.py`)
- 2024 predictions → Result plots: reads predictions (evidence: `scripts/plot_results.py`)
- Feature importance → Result plots: reads importance (evidence: `scripts/plot_results.py`)
- Result plots → Research figures: writes figures (evidence: `scripts/plot_results.py`)
- Evaluation metrics → Report generator: reads metrics (evidence: `scripts/make_report.py`)
- Feature importance → Report generator: reads importance (evidence: `scripts/make_report.py`)
- Report generator → Experiment report: writes report (evidence: `scripts/make_report.py`)
- CHIRPS precipitation → Climate feature table: contributes precipitation (evidence: `README.md`)
- ERA5-Land variables → Climate feature table: contributes variables (evidence: `README.md`)
