OneScience-Group/CESM-SeasonalML

CESM-SeasonalML

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

2. Download and Installation

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

# 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

# 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.

python scripts/fake_data.py

Training

For single-device training, use:

python scripts/train.py

For multi-GPU training, use:

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:

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

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:

result/output/predictions.npz

Evaluation and Visualization

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.

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.