# ipl-uv/climx architecture

> Architecture diagram of the GitHub repository ipl-uv/climx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ipl-uv/climx
- Repository: https://github.com/ipl-uv/climx

## Overview

ClimX is a climate-model emulation benchmark: users prepare forcing and target data, train an emulator, predict daily climate fields, derive climate indices, and submit those indices for regional extreme-aware scoring. The README documents an end-to-end notebook, baseline training, Hugging Face data, Kaggle formatting, and an optional probabilistic track. Source excerpts confirm the training, preprocessing, model, index, and submission components; unsampled integrations are shown only where documented, and the optional uncertainty track has no implementation path established by the tree.

Main entry points: [`train.py`](https://github.com/ipl-uv/climx/blob/main/train.py) (Baseline training), [`src/models/emulator.py`](https://github.com/ipl-uv/climx/blob/main/src/models/emulator.py) (Emulator interface), [`src/data_preprocessing/preprocessing.py`](https://github.com/ipl-uv/climx/blob/main/src/data_preprocessing/preprocessing.py) (Climate preprocessing), [`src/models/climatology_model.py`](https://github.com/ipl-uv/climx/blob/main/src/models/climatology_model.py) (Climatology baseline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Benchmark workflow"]
  node_training["Baseline training<br/>[train.py]"]
  node_dataset_access["Dataset access"]
  node_preprocessing["Climate preprocessing<br/>[preprocessing.py]"]
  node_preprocessing_utils["Transform utilities"]
end

subgraph group_models["Emulator baselines"]
  node_emulator["Emulator interface<br/>[emulator.py]"]
  node_climatology["Climatology baseline"]
  node_neural["Neural baseline<br/>[nn_model.py]"]
  node_graph["Graph baseline<br/>[gnn_model.py]"]
  node_lps["LPS baseline<br/>[lps_model.py]"]
end

subgraph group_indices["Indices and scoring"]
  node_index_calc["Climate indices<br/>[indices_xclim.py]"]
  node_index_metadata["Index metadata<br/>[index_metadata.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_main_score["Regional nNSE<br/>[rnNSE.py]"]
end

subgraph group_submission["Submission and inspection"]
  node_submission_format["Kaggle formatting"]
  node_visualization["Climate visualization<br/>[visualize_data.py]"]
  node_probabilistic["Probabilistic track"]
end

node_participant(("Benchmark participant"))
node_hf_dataset[("Hugging Face dataset")]
node_kaggle{{"Kaggle tracks"}}

node_participant -->|"trains baselines"| node_training
node_hf_dataset -->|"provides data"| node_dataset_access
node_training -->|"opens dataset"| node_dataset_access
node_training -->|"prepares data"| node_preprocessing
node_preprocessing -->|"applies transforms"| node_preprocessing_utils
node_training -->|"selects baseline"| node_climatology
node_training -->|"selects baseline"| node_neural
node_training -->|"selects baseline"| node_graph
node_training -.->|"selects baseline"| node_lps
node_climatology -->|"implements"| node_emulator
node_neural -->|"implements"| node_emulator
node_graph -->|"implements"| node_emulator
node_lps -->|"implements"| node_emulator
node_participant -->|"derives indices"| node_index_calc
node_index_calc -->|"uses definitions"| node_index_metadata
node_participant -->|"formats predictions"| node_submission_format
node_submission_format -->|"prepares submission"| node_kaggle
node_kaggle -->|"scores main track"| node_main_score
node_participant -->|"inspects climate data"| node_visualization
node_kaggle -.->|"offers UQ track"| node_probabilistic
node_probabilistic -.->|"evaluates CRPS"| node_kaggle

click node_training "https://github.com/ipl-uv/climx/blob/main/train.py"
click node_dataset_access "https://github.com/ipl-uv/climx/blob/main/src/utils/hugging_face_utils.py"
click node_preprocessing "https://github.com/ipl-uv/climx/blob/main/src/data_preprocessing/preprocessing.py"
click node_preprocessing_utils "https://github.com/ipl-uv/climx/blob/main/src/data_preprocessing/preprocessing_utils.py"
click node_emulator "https://github.com/ipl-uv/climx/blob/main/src/models/emulator.py"
click node_climatology "https://github.com/ipl-uv/climx/blob/main/src/models/climatology_model.py"
click node_neural "https://github.com/ipl-uv/climx/blob/main/src/models/nn_model.py"
click node_graph "https://github.com/ipl-uv/climx/blob/main/src/models/gnn_model.py"
click node_lps "https://github.com/ipl-uv/climx/blob/main/src/models/lps_model.py"
click node_index_calc "https://github.com/ipl-uv/climx/blob/main/src/indices_xclim.py"
click node_index_metadata "https://github.com/ipl-uv/climx/blob/main/src/index_metadata.py"
click node_metrics "https://github.com/ipl-uv/climx/blob/main/src/metrics.py"
click node_main_score "https://github.com/ipl-uv/climx/blob/main/rnNSE.py"
click node_submission_format "https://github.com/ipl-uv/climx/blob/main/src/utils/kaggle_submission.py"
click node_visualization "https://github.com/ipl-uv/climx/blob/main/src/visualization/visualize_data.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_training,node_dataset_access,node_preprocessing,node_preprocessing_utils toneBlue
class node_emulator,node_climatology,node_neural,node_graph,node_lps,node_hf_dataset toneAmber
class node_index_calc,node_index_metadata,node_metrics,node_main_score toneMint
class node_submission_format,node_visualization,node_probabilistic toneRose
class node_participant,node_kaggle toneIndigo
```

## Components

### Benchmark workflow

- [Baseline training](https://github.com/ipl-uv/climx/blob/main/train.py): `train.py`
- [Dataset access](https://github.com/ipl-uv/climx/blob/main/src/utils/hugging_face_utils.py): `src/utils/hugging_face_utils.py`
- [Climate preprocessing](https://github.com/ipl-uv/climx/blob/main/src/data_preprocessing/preprocessing.py): `src/data_preprocessing/preprocessing.py`
- [Transform utilities](https://github.com/ipl-uv/climx/blob/main/src/data_preprocessing/preprocessing_utils.py): `src/data_preprocessing/preprocessing_utils.py`

### Emulator baselines

- [Emulator interface](https://github.com/ipl-uv/climx/blob/main/src/models/emulator.py): `src/models/emulator.py`
- [Climatology baseline](https://github.com/ipl-uv/climx/blob/main/src/models/climatology_model.py): `src/models/climatology_model.py`
- [Neural baseline](https://github.com/ipl-uv/climx/blob/main/src/models/nn_model.py): `src/models/nn_model.py`
- [Graph baseline](https://github.com/ipl-uv/climx/blob/main/src/models/gnn_model.py): `src/models/gnn_model.py`
- [LPS baseline](https://github.com/ipl-uv/climx/blob/main/src/models/lps_model.py): `src/models/lps_model.py`

### Indices and scoring

- [Climate indices](https://github.com/ipl-uv/climx/blob/main/src/indices_xclim.py): `src/indices_xclim.py`
- [Index metadata](https://github.com/ipl-uv/climx/blob/main/src/index_metadata.py): `src/index_metadata.py`
- [Evaluation metrics](https://github.com/ipl-uv/climx/blob/main/src/metrics.py): `src/metrics.py`
- [Regional nNSE](https://github.com/ipl-uv/climx/blob/main/rnNSE.py): `rnNSE.py`

### Submission and inspection

- [Kaggle formatting](https://github.com/ipl-uv/climx/blob/main/src/utils/kaggle_submission.py): `src/utils/kaggle_submission.py`
- [Climate visualization](https://github.com/ipl-uv/climx/blob/main/src/visualization/visualize_data.py): `src/visualization/visualize_data.py`
- **Probabilistic track**

### Other components

- **Benchmark participant**
- **Hugging Face dataset**
- **Kaggle tracks**

## Connections

- Benchmark participant → Baseline training: trains baselines
- Hugging Face dataset → Dataset access: provides data
- Baseline training → Dataset access: opens dataset
- Baseline training → Climate preprocessing: prepares data
- Climate preprocessing → Transform utilities: applies transforms
- Baseline training → Climatology baseline: selects baseline
- Baseline training → Neural baseline: selects baseline
- Baseline training → Graph baseline: selects baseline
- Baseline training → LPS baseline: selects baseline
- Climatology baseline → Emulator interface: implements
- Neural baseline → Emulator interface: implements
- Graph baseline → Emulator interface: implements
- LPS baseline → Emulator interface: implements
- Benchmark participant → Climate indices: derives indices
- Climate indices → Index metadata: uses definitions
- Benchmark participant → Kaggle formatting: formats predictions
- Kaggle formatting → Kaggle tracks: prepares submission
- Kaggle tracks → Regional nNSE: scores main track
- Benchmark participant → Climate visualization: inspects climate data
- Kaggle tracks → Probabilistic track: offers UQ track
- Probabilistic track → Kaggle tracks: evaluates CRPS