README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Seasonal Precipitation Forecasting
- Interpretable Machine Learning
frameworks: PyTorch
---

<p align="center">
  <strong><span style="font-size: 30px;">CESM-SeasonalML</span></strong>
</p>

# Model Introduction

CESM-SeasonalML trains interpretable machine-learning models on a large climate-model ensemble to predict four large-scale patterns of standardized western-US seasonal precipitation anomalies separately for NDJ and JFM.

Paper: Training machine learning models on climate model output yields skillful interpretable seasonal precipitation forecasts  
https://doi.org/10.1038/s43247-021-00225-4

# Model Description

The method was proposed by teams at the Center for Western Weather and Water Extremes, Scripps Institution of Oceanography, University of California San Diego, and NASA's Jet Propulsion Laboratory at the California Institute of Technology. The paper trains on CESM-LENS and tests with ERSSTv5, ERA5, and the CPC Unified Gauge-Based Analysis of Global Daily Precipitation. The models predict four western-US precipitation patterns separately for NDJ and JFM and use random forests to explain the contributions of key oceanic and atmospheric predictors.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Seasonal classification | Predict four large-scale western-US precipitation patterns separately for NDJ and JFM. |
| KMeans target construction | Cluster standardized seasonal precipitation fields into stable four-class training targets. |
| RF interpretation | Analyze key predictors with permutation importance, mean minimum depth, and root frequency. |
| Local workflow validation | Validate data generation, training, inference, evaluation, and visualization with structured synthetic data. |
| ModelScope/OneCode execution | Validate structured data, training, inference, seasonal-classification metrics, and visualization in ModelScope or OneCode environments. |
| Multi-GPU training | Validate distributed training and the checkpoint workflow through `torchrun`. |

# Usage Instructions

## 1.OneCode

Experience intelligent, one-click AI4S programming through the OneCode online environment:

[Try intelligent, one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Download and Installation

```bash
hf download OneScience-Group/CESM-SeasonalML --local-dir ./CESM-SeasonalML
cd CESM-SeasonalML
```

### Environment Dependencies

**Hardware Requirements**

- A GPU or DCU is recommended for neural-network training.
- A CPU can generate synthetic data and validate the default small-sample workflow.
- DCU users must install DTK first. DTK 25.04.2 or later, or the OneScience-recommended version matching the cluster, is recommended.

**DCU Environment**

```bash
# Activate DTK and Conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
pip install onescience[earth-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
pip install numpy pyyaml matplotlib
```

**GPU Environment**

```bash
# Activate Conda first
conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
conda activate onescience311
pip install onescience[earth-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
pip install numpy pyyaml matplotlib
```

### Training Data

The paper trains on CESM-LENS and tests with ERSSTv5, ERA5, and CPC data.
RF/XGB, NN, and LSTM use `103`, `416`, and `28` input dimensions, respectively, to predict four seasonal precipitation-pattern target classes.
Because the paper does not provide a complete feature manifest or the final preprocessed grid dimensions, this repository's structured placeholder features and `20×24` grid are engineering assumptions.
Synthetic data are for engineering validation only and do not represent real data distributions, dataset scale, or paper performance.

```bash
python scripts/fake_data.py
```

### Training

For single-device training, use:

```bash
python scripts/train.py
```

For multi-GPU training, use:

```bash
torchrun --nproc_per_node=8 --nnodes=1 --rdzv_id=1000 --rdzv_backend=c10d --max_restarts=0 --master_addr="localhost" --master_port=29500 scripts/train.py --models nn lstm
```

The default engineering configuration trains RF, XGB, and LSTM with reduced tree counts, training rounds, and epochs, but does not reduce the `103/416/28` input dimensions or four target classes.
Formal experiments should use CESM-LENS training data and ERSSTv5, ERA5, and CPC test data and restore the paper-scale configuration under `paper_model` in `conf/config.yaml`; training artifacts are saved to:

```text
result/checkpoints/cesm_seasonal_ml.pt
result/training/metrics.json
```

### Trained Weights

This repository does not bundle paper weights, and no confirmed public official checkpoint is available; the paper states that its original code can be requested from the corresponding author. Training creates a local engineering checkpoint at `result/checkpoints/cesm_seasonal_ml.pt` containing models, KMeans state, data specifications, and training records, but it is neither an official pretrained weight nor a claim of the paper's numerical results.

### Inference

```bash
python scripts/inference.py
```

Inference loads the locally trained checkpoint and validates versions, season, manifests, and data shapes. Four-class probabilities and predictions from every enabled model, targets, centroids, years, coordinates, and target precipitation fields are saved to:

```text
result/output/predictions.npz
```

### Evaluation and Visualization

```bash
python scripts/result.py
```

Evaluation computes seasonal classification metrics and baselines and generates comparison plots for the models, baselines, and precipitation patterns.
Synthetic-data results are for engineering validation only and do not represent paper performance.

```text
result/evaluation/metrics.json
result/evaluation/comparison.png
result/evaluation/precipitation_clusters.png
result/evaluation/seasonal_predictions.png
```

# Official OneScience Information

| Platform | OneScience Main Repository | Skills Repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |

# Citation and License

This repository is an independent engineering reproduction of the public CESM-SeasonalML specifications.

Use of this repository's code, official model weights, and data remains subject to the licenses and terms of their respective projects.