OneScience-Group/ML-MODIS

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

Model Introduction

ML-MODIS reproduces the satellite-based machine-learning workflow proposed by Chen et al. (2022), estimating cloud-property counterfactuals without the 2014 volcanic aerosol perturbation and using them to diagnose aerosol-cloud effects and their shortwave radiative contributions.

Paper: Machine learning reveals climate forcing from aerosols is dominated by increased cloud cover https://doi.org/10.1038/s41561-022-00991-6

Model Description

The method was proposed by a research team from the University of Exeter, the Met Office, ETH Zurich, the University of Cambridge, NASA Goddard Space Flight Center, the University of Leeds, Ludwig Maximilian University of Munich, and collaborating institutions. The paper pairs MODIS Collection 6.1 cloud products with ERA5 meteorological data and trains independent random forests by month and cloud-property target using samples from years other than 2014. The model generates counterfactual cloud properties from meteorological conditions and compares them with 2014 MODIS observations to diagnose volcanic-aerosol cloud responses and their shortwave radiative-forcing contributions.

Use Cases

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/ML-MODIS --local-dir ./ML-MODIS
cd ML-MODIS

Environment Dependencies

Hardware Requirements

• —A GPU or DCU is recommended.
• —A CPU can be used for connectivity validation with the default small-sample configuration.
• —DCU users must install DTK in advance. DTK 25.04.2 or later, or the OneScience-recommended version matching the current 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

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

Training Data

The paper uses MODIS Collection 6.1 cloud products and ERA5 meteorological data aligned by year, month, Terra/Aqua platform, and coordinates, excluding 2014 samples from training. Each sample contains 114 predictors, comprising 90 fields from nine profile variables at ten pressure levels and 24 single-level fields, with Nd, reff, LWP, and CF as targets. The synthetic data contain structured meteorological, spatiotemporal, and cloud-property relationships for engineering validation only and do not represent the real MODIS or ERA5 distributions, training scale, or paper performance.

python scripts/fake_data.py

Training

For single-GPU 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

Training builds separate random forests for four cloud properties in September and October; the default reduces each forest from the paper's 100 trees to 12 without reducing the 114 predictors, months, targets, or multimodal alignment protocol. Formal experiments require real MODIS and ERA5 data and field-level verification against the supplementary material, with training artifacts saved to:

result/checkpoints/ml_modis.pt
result/training/metrics.json

Trained Weights

No official weights are bundled under weight/, and no public model weights or directly downloadable checkpoint from the paper authors were identified. The paper states only that code is available from the corresponding author upon reasonable request; the local checkpoint is an engineering artifact and makes no compatibility claim with unreleased author weights.

Inference

python scripts/inference.py

Inference loads the training checkpoint and generates counterfactual predictions for all four cloud properties from ERA5 meteorological conditions, saving per-tree predictions, forest means, observations, and alignment metadata. Complete numerical results are saved to result/output/predictions.npz.

Evaluation and Visualization

python scripts/result.py

Evaluation computes OOB MSE, R², Pearson correlation, permutation importance, area-weighted 2014 responses, susceptibilities, and relative shortwave radiative contributions. Results are saved to result/evaluation/metrics.json and result/evaluation/comparison.png; synthetic-data results validate engineering only and do not represent paper performance or climate-attribution evidence.

Official OneScience Information

Citation and License

This repository is an independent engineering reproduction of the public ML-MODIS specifications.

Its code is licensed under Apache-2.0; the paper and author code remain subject to their respective copyright and usage terms.

Use of MODIS Collection 6.1 and ERA5 remains subject to the current NASA Earthdata/LAADS DAAC and Copernicus Climate Data Store/ECMWF terms, respectively.