# wur-ai/agml-cy-bench architecture

> Architecture diagram of the GitHub repository wur-ai/agml-cy-bench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wur-ai/agml-cy-bench
- Repository: https://github.com/wur-ai/agml-cy-bench

## Overview

CY-Bench is a Python library and benchmark for subnational, in-season maize and wheat yield forecasting. The principal workflow is to load a configured crop dataset, align predictors to crop seasons and forecast cutoffs, train models on training years, predict held-out years, and evaluate forecasts. The repository also provides feature engineering, multiple model families, result processing and visualizations, plus data-preparation utilities. Relationships are limited to calls or references shown in excerpts, the source index, or README; several result and preparation details are only documented or indexed, not inspected in full.

Main entry points: [`cybench/runs/run_benchmark.py`](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/run_benchmark.py) (Benchmark runner), [`cybench/datasets/torch_dataset.py`](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/torch_dataset.py) (Torch dataset), [`cybench/datasets/alignment.py`](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/alignment.py) (Season alignment), [`cybench/datasets/configured.py`](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/configured.py) (Configured datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and features"]
  node_config["Benchmark config<br/>[config.py]"]
  node_configured["Configured datasets<br/>[configured.py]"]
  node_alignment["Season alignment<br/>[alignment.py]"]
  node_dataset["Dataset samples<br/>[dataset.py]"]
  node_torch_dataset["Torch dataset<br/>[torch_dataset.py]"]
  node_features["Feature engineering<br/>[features.py]"]
  node_data_util["Data utilities<br/>[data.py]"]
  node_torch_util["Torch utilities<br/>[torch.py]"]
end

subgraph group_models["Modeling"]
  node_base_model["Model interface<br/>[model.py]"]
  node_naive["Naive models<br/>[naive_models.py]"]
  node_trend["Trend models<br/>[trend_models.py]"]
  node_sklearn["Scikit-learn models<br/>[sklearn_models.py]"]
  node_xgboost["XGBoost model<br/>[xgboost_model.py]"]
  node_neural["Neural models<br/>[nn_models.py]"]
  node_residual["Residual models<br/>[residual_models.py]"]
end

subgraph group_benchmark["Benchmark and evaluation"]
  node_runner["Benchmark runner<br/>[run_benchmark.py]"]
  node_evaluation["Forecast metrics<br/>[eval.py]"]
  node_comet["Experiment logging<br/>[log_experiments.py]"]
end

subgraph group_results["Results and reporting"]
  node_process["Result processing<br/>[process_results.py]"]
  node_plots["Result plots<br/>[results_plots.py]"]
  node_maps["Forecast maps"]
  node_aggregate_maps["Aggregated maps"]
  node_geo["Boundary utilities<br/>[geo.py]"]
end

subgraph group_prep["Data preparation"]
  node_prep_predictors["Predictor preparation"]
  node_prep_filter["Predictor filtering"]
  node_prep_yield["Yield filtering"]
  node_coverage["Coverage views"]
end

node_user(("Benchmark user"))
node_external_comet["Comet ML"]

node_user -->|"starts benchmark"| node_runner
node_runner -->|"loads dataset"| node_configured
node_configured -->|"aligns inputs"| node_alignment
node_configured -->|"reads settings"| node_config
node_dataset -->|"uses loader"| node_configured
node_alignment -->|"uses date features"| node_features
node_alignment -->|"converts data"| node_data_util
node_alignment -->|"reads settings"| node_config
node_torch_dataset -->|"wraps samples"| node_dataset
node_torch_dataset -->|"uses utilities"| node_torch_util
node_torch_dataset -->|"uses utilities"| node_data_util
node_torch_dataset -->|"uses alignment"| node_alignment
node_base_model -->|"fits and predicts"| node_dataset
node_runner -->|"constructs models"| node_base_model
node_runner -->|"dispatches model"| node_naive
node_runner -->|"dispatches model"| node_trend
node_runner -->|"dispatches model"| node_sklearn
node_runner -->|"dispatches model"| node_xgboost
node_runner -->|"dispatches model"| node_neural
node_runner -->|"dispatches model"| node_residual
node_neural -->|"uses batches"| node_torch_dataset
node_runner -->|"computes metrics"| node_evaluation
node_evaluation -->|"requests predictions"| node_base_model
node_evaluation -->|"reads targets"| node_dataset
node_process -->|"reads run results"| node_runner
node_process -->|"uses metrics"| node_evaluation
node_plots -->|"uses processed results"| node_process
node_plots -->|"reads run results"| node_runner
node_maps -->|"loads boundaries"| node_geo
node_aggregate_maps -->|"loads boundaries"| node_geo
node_comet -->|"logs experiments"| node_external_comet
node_prep_filter -->|"uses settings"| node_config
node_prep_predictors -->|"uses settings"| node_config
node_coverage -->|"uses boundaries"| node_geo
node_runner -.->|"logs benchmark"| node_comet

click node_config "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/config.py"
click node_configured "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/configured.py"
click node_alignment "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/alignment.py"
click node_dataset "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/dataset.py"
click node_torch_dataset "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/torch_dataset.py"
click node_features "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/util/features.py"
click node_data_util "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/util/data.py"
click node_torch_util "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/util/torch.py"
click node_base_model "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/model.py"
click node_naive "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/naive_models.py"
click node_trend "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/trend_models.py"
click node_sklearn "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/sklearn_models.py"
click node_xgboost "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/xgboost_model.py"
click node_neural "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/nn_models.py"
click node_residual "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/residual_models.py"
click node_runner "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/run_benchmark.py"
click node_evaluation "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/evaluation/eval.py"
click node_comet "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/evaluation/log_experiments.py"
click node_process "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/process_results.py"
click node_plots "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/results_plots.py"
click node_maps "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/visualize_results.py"
click node_aggregate_maps "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/visualize_results_aggregated.py"
click node_geo "https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/util/geo.py"
click node_prep_predictors "https://github.com/wur-ai/agml-cy-bench/blob/main/data_preparation/predictor_data_prep.py"
click node_prep_filter "https://github.com/wur-ai/agml-cy-bench/blob/main/data_preparation/filter_predictor_data.py"
click node_prep_yield "https://github.com/wur-ai/agml-cy-bench/blob/main/data_preparation/filter_yield_data.py"
click node_coverage "https://github.com/wur-ai/agml-cy-bench/blob/main/data_preparation/visualize_coverage.py"

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_config,node_configured,node_alignment,node_dataset,node_torch_dataset,node_features,node_data_util,node_torch_util,node_user toneBlue
class node_base_model,node_naive,node_trend,node_sklearn,node_xgboost,node_neural,node_residual toneAmber
class node_runner,node_evaluation,node_comet toneMint
class node_process,node_plots,node_maps,node_aggregate_maps,node_geo toneRose
class node_prep_predictors,node_prep_filter,node_prep_yield,node_coverage,node_external_comet toneIndigo
```

## Components

### Data and features

- [Benchmark config](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/config.py): `cybench/config.py`
- [Configured datasets](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/configured.py): `cybench/datasets/configured.py`
- [Season alignment](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/alignment.py): `cybench/datasets/alignment.py`
- [Dataset samples](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/dataset.py): `cybench/datasets/dataset.py`
- [Torch dataset](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/datasets/torch_dataset.py): `cybench/datasets/torch_dataset.py`
- [Feature engineering](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/util/features.py): `cybench/util/features.py`
- [Data utilities](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/util/data.py): `cybench/util/data.py`
- [Torch utilities](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/util/torch.py): `cybench/util/torch.py`

### Modeling

- [Model interface](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/model.py): `cybench/models/model.py`
- [Naive models](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/naive_models.py): `cybench/models/naive_models.py`
- [Trend models](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/trend_models.py): `cybench/models/trend_models.py`
- [Scikit-learn models](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/sklearn_models.py): `cybench/models/sklearn_models.py`
- [XGBoost model](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/xgboost_model.py): `cybench/models/xgboost_model.py`
- [Neural models](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/nn_models.py): `cybench/models/nn_models.py`
- [Residual models](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/models/residual_models.py): `cybench/models/residual_models.py`

### Benchmark and evaluation

- [Benchmark runner](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/run_benchmark.py): `cybench/runs/run_benchmark.py`
- [Forecast metrics](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/evaluation/eval.py): `cybench/evaluation/eval.py`
- [Experiment logging](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/evaluation/log_experiments.py): `cybench/evaluation/log_experiments.py`

### Results and reporting

- [Result processing](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/process_results.py): `cybench/runs/process_results.py`
- [Result plots](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/results_plots.py): `cybench/runs/results_plots.py`
- [Forecast maps](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/visualize_results.py): `cybench/runs/visualize_results.py`
- [Aggregated maps](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/runs/visualize_results_aggregated.py): `cybench/runs/visualize_results_aggregated.py`
- [Boundary utilities](https://github.com/wur-ai/agml-cy-bench/blob/main/cybench/util/geo.py): `cybench/util/geo.py`

### Data preparation

- [Predictor preparation](https://github.com/wur-ai/agml-cy-bench/blob/main/data_preparation/predictor_data_prep.py): `data_preparation/predictor_data_prep.py`
- [Predictor filtering](https://github.com/wur-ai/agml-cy-bench/blob/main/data_preparation/filter_predictor_data.py): `data_preparation/filter_predictor_data.py`
- [Yield filtering](https://github.com/wur-ai/agml-cy-bench/blob/main/data_preparation/filter_yield_data.py): `data_preparation/filter_yield_data.py`
- [Coverage views](https://github.com/wur-ai/agml-cy-bench/blob/main/data_preparation/visualize_coverage.py): `data_preparation/visualize_coverage.py`

### Other components

- **Benchmark user**
- **Comet ML**

## Connections

- Benchmark user → Benchmark runner: starts benchmark (evidence: `README.md`)
- Benchmark runner → Configured datasets: loads dataset (evidence: `cybench/runs/run_benchmark.py`)
- Configured datasets → Season alignment: aligns inputs (evidence: `cybench/datasets/configured.py`)
- Configured datasets → Benchmark config: reads settings (evidence: `cybench/datasets/configured.py`)
- Dataset samples → Configured datasets: uses loader (evidence: `cybench/datasets/dataset.py`)
- Season alignment → Feature engineering: uses date features (evidence: `cybench/datasets/alignment.py`)
- Season alignment → Data utilities: converts data (evidence: `cybench/datasets/alignment.py`)
- Season alignment → Benchmark config: reads settings (evidence: `cybench/datasets/alignment.py`)
- Torch dataset → Dataset samples: wraps samples (evidence: `cybench/datasets/torch_dataset.py`)
- Torch dataset → Torch utilities: uses utilities (evidence: `cybench/datasets/torch_dataset.py`)
- Torch dataset → Data utilities: uses utilities (evidence: `cybench/datasets/torch_dataset.py`)
- Torch dataset → Season alignment: uses alignment (evidence: `cybench/datasets/torch_dataset.py`)
- Model interface → Dataset samples: fits and predicts (evidence: `cybench/models/model.py`)
- Benchmark runner → Model interface: constructs models (evidence: `cybench/runs/run_benchmark.py`)
- Benchmark runner → Naive models: dispatches model (evidence: `cybench/runs/run_benchmark.py`)
- Benchmark runner → Trend models: dispatches model (evidence: `cybench/runs/run_benchmark.py`)
- Benchmark runner → Scikit-learn models: dispatches model (evidence: `cybench/runs/run_benchmark.py`)
- Benchmark runner → XGBoost model: dispatches model (evidence: `cybench/runs/run_benchmark.py`)
- Benchmark runner → Neural models: dispatches model (evidence: `cybench/runs/run_benchmark.py`)
- Benchmark runner → Residual models: dispatches model (evidence: `cybench/runs/run_benchmark.py`)
- Neural models → Torch dataset: uses batches (evidence: `cybench/models/nn_models.py`)
- Benchmark runner → Forecast metrics: computes metrics (evidence: `cybench/runs/run_benchmark.py`)
- Forecast metrics → Model interface: requests predictions (evidence: `cybench/evaluation/eval.py`)
- Forecast metrics → Dataset samples: reads targets (evidence: `cybench/evaluation/eval.py`)
- Result processing → Benchmark runner: reads run results (evidence: `cybench/runs/process_results.py`)
- Result processing → Forecast metrics: uses metrics (evidence: `cybench/runs/process_results.py`)
- Result plots → Result processing: uses processed results (evidence: `cybench/runs/results_plots.py`)
- Result plots → Benchmark runner: reads run results (evidence: `cybench/runs/results_plots.py`)
- Forecast maps → Boundary utilities: loads boundaries (evidence: `cybench/runs/visualize_results.py`)
- Aggregated maps → Boundary utilities: loads boundaries (evidence: `cybench/runs/visualize_results_aggregated.py`)
- Experiment logging → Comet ML: logs experiments (evidence: `cybench/evaluation/log_experiments.py`)
- Predictor filtering → Benchmark config: uses settings (evidence: `data_preparation/filter_predictor_data.py`)
- Predictor preparation → Benchmark config: uses settings (evidence: `data_preparation/predictor_data_prep.py`)
- Coverage views → Boundary utilities: uses boundaries (evidence: `data_preparation/visualize_coverage.py`)
- Benchmark runner → Experiment logging: logs benchmark (evidence: `cybench/evaluation/log_experiments.py`)
