Publish ML-MODIS engineering reproduction

.gitattributes

@@ -1,35 +1,2 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,141 @@
+---
+license: apache-2.0
+language:
+- en
+tags:
+- OneScience
+- Earth Science
+- Climate Diagnostics
+- Random Forest
+frameworks: PyTorch
+---
+
+<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
+
+| Use Case | Description |
+| :---: | :--- |
+| Counterfactual cloud prediction | Estimate unperturbed `Nd`, `reff`, `LWP`, and `CF` from ERA5 meteorology and compare them with 2014 observations. |
+| OOB interpretation and radiative diagnostics | Calculate OOB skill and permutation importance, then diagnose relative Twomey, LWP, and CF shortwave radiative contributions. |
+| Local workflow validation | Validate data generation, training, checkpoint restoration, inference, evaluation, and visualization with structured synthetic data. |
+| ModelScope/OneCode execution | Validate structured data, training, inference, counterfactual and radiative-diagnostic 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/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**
+
+```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
+```
+
+**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
+```
+
+### 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.
+
+```bash
+python scripts/fake_data.py
+```
+
+### Training
+
+For single-GPU 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
+```
+
+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:
+
+```text
+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
+
+```bash
+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
+
+```bash
+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
+
+| 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 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.

README_zh.md

@@ -0,0 +1,142 @@
+---
+license: apache-2.0
+language:
+- en
+- zh
+tags:
+- OneScience
+- 地球科学
+- 气候诊断
+- Random Forest
+frameworks: PyTorch
+---
+
+<p align="center">
+  <strong><span style="font-size: 30px;">ML-MODIS</span></strong>
+</p>
+
+# 模型介绍
+
+ML-MODIS 复现 Chen 等（2022）提出的卫星机器学习流程，依据气象状态估计未受 2014 年火山气溶胶扰动的云属性反事实，并据此诊断气溶胶云效应及其短波辐射贡献。
+
+论文：Machine learning reveals climate forcing from aerosols is dominated by increased cloud cover  
+https://doi.org/10.1038/s41561-022-00991-6
+
+# 模型描述
+
+该方法由 University of Exeter、Met Office、ETH Zurich、University of Cambridge、NASA Goddard Space Flight Center、University of Leeds 和 Ludwig Maximilian University of Munich 等机构组成的研究团队提出。论文将 MODIS Collection 6.1 云产品与 ERA5 气象数据配对，使用非 2014 年样本训练月份与云属性目标相互独立的随机森林。模型根据气象条件生成反事实云属性，再将 2014 年 MODIS 观测与反事实比较，以诊断火山气溶胶引起的云响应和短波辐射强迫贡献。
+
+# 适用场景
+
+| 场景 | 说明 |
+| :---: | :--- |
+| 云属性反事实预测 | 从 ERA5 气象状态估计无火山扰动条件下的 `Nd`、`reff`、`LWP` 和 `CF`，并与 2014 年观测比较。 |
+| OOB 解释与辐射诊断 | 计算 OOB 技能和置换重要性，并诊断 Twomey、LWP 与 CF 的相对短波辐射贡献。 |
+| 本地流程验证 | 使用结构化虚拟数据验证数据生成、训练、checkpoint 恢复、推理、评估和可视化。 |
+| ModelScope/OneCode 运行 | 在 ModelScope 或 OneCode 环境中验证结构化数据、训练、推理、反事实与辐射诊断指标和可视化流程。 |
+| 多卡训练 | 通过 `torchrun` 验证分布式训练和 checkpoint 流程。 |
+
+# 使用说明
+
+## 1.OneCode
+
+可通过 OneCode 在线环境体验智能化一键式 AI4S 编程：
+
+[点击体验智能化一键式 AI4S 编程](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)
+
+## 2.下载安装
+
+```bash
+modelscope download --model OneScience/ML-MODIS --local_dir ./ML-MODIS
+cd ML-MODIS
+```
+
+### 环境依赖
+
+**硬件要求**
+
+- 推荐使用 GPU 或 DCU 运行。
+- CPU 可用于默认小样本配置的连通性验证。
+- DCU 用户需预先安装 DTK，建议使用 DTK 25.04.2 以上版本或与当前集群匹配的 OneScience 推荐版本。
+
+**DCU环境**
+
+```bash
+# 请首先激活DTK及CONDA
+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环境**
+
+```bash
+# 请首先激活CONDA
+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
+```
+
+### 训练数据介绍
+
+论文使用 MODIS Collection 6.1 云产品和 ERA5 气象数据，按年月、Terra/Aqua 平台及经纬度对齐，并排除 2014 年样本进行训练。每个样本包含 114 个输入特征，即 9 个廓线变量在 10 个压力层上的 90 个字段和 24 个单层字段，目标为 `Nd`、`reff`、`LWP` 和 `CF`。虚拟数据包含合理的气象、时空和云属性关系，仅用于验证工程流程，不代表 MODIS 或 ERA5 的真实数据分布、训练规模或论文性能。
+
+```bash
+python scripts/fake_data.py
+```
+
+### 训练
+
+单卡训练可使用：
+
+```bash
+python scripts/train.py
+```
+
+多卡训练可使用：
+
+```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
+```
+
+训练为 September/October 的四个云属性分别构建随机森林；默认配置将每个森林由论文的 100 棵树缩为 12 棵，但不缩小 114 维输入、月份、目标和多模态对齐协议。正式实验需要真实 MODIS、ERA5 数据并核验补充材料中的字段定义，训练产物保存到：
+
+```text
+result/checkpoints/ml_modis.pt
+result/training/metrics.json
+```
+
+### 训练权重
+
+本仓库不在 `weight/` 中内置权重，也未发现论文作者公开的模型权重或可直接下载的 checkpoint。论文仅说明代码可向通讯作者合理申请，当前本地 checkpoint 是工程训练产物，不声明与作者未公开的权重兼容。
+
+### 推理
+
+```bash
+python scripts/inference.py
+```
+
+推理加载训练 checkpoint，根据 ERA5 气象条件生成四种云属性的反事实预测，并保存逐树预测、森林均值、观测和对齐信息。完整数值结果保存到 `result/output/predictions.npz`。
+
+### 评估和可视化
+
+```bash
+python scripts/result.py
+```
+
+评估计算 OOB MSE、R²、Pearson 相关系数、置换重要性、2014 年面积加��响应、susceptibility 和相对短波辐射贡献。结果保存到 `result/evaluation/metrics.json` 和 `result/evaluation/comparison.png`；虚拟数据结果仅用于工程验证，不代表论文正式性能或气候归因结论。
+
+# OneScience官方信息
+
+| 平台 | OneScience 主仓库 | Skills 仓库 |
+| --- | --- | --- |
+| 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 |
+
+# 引用与许可证
+
+本仓库为 ML-MODIS 公开规格的独立工程复现版本。
+
+本仓库代码采用 Apache-2.0 许可证；原论文和作者代码仍受其各自版权及使用条款约束。
+
+MODIS Collection 6.1 和 ERA5 数据的使用应分别遵循 NASA Earthdata/LAADS DAAC 和 Copernicus Climate Data Store/ECMWF 的现行条款。

conf/config.yaml

@@ -0,0 +1,55 @@
+format_version: ml_modis_npz_v1
+data:
+  path: data/ml_modis_fake.npz
+  samples: 1400
+  years: [2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020]
+  months: [9, 10]
+  platforms: [Terra, Aqua]
+  dimensions:
+    predictors: 114
+    targets: 4
+  variables:
+    profile:
+      names: [temperature, specific_humidity, relative_humidity, u_wind, v_wind, omega, geopotential, cloud_liquid, cloud_fraction]
+      pressure_levels_hpa: [1000, 950, 900, 850, 800, 750, 700, 650, 600, 550]
+      count: 90
+    single_level:
+      names: [sst, surface_pressure, mslp, skin_temperature, t2m, d2m, u10, v10, surface_solar_radiation, surface_thermal_radiation, latent_heat_flux, sensible_heat_flux, boundary_layer_height, total_column_water_vapour, total_column_cloud_liquid, cape, cin, low_cloud_cover, sea_ice_fraction, precipitation, cos_sza, latitude, longitude, platform_hour]
+      count: 24
+    targets:
+      names: [Nd, reff, LWP, CF]
+      units: [cm-3, um, g-m-2, fraction]
+    coordinates:
+      latitude_degrees_north: [45, 75]
+      longitude_degrees_east: [-60, 30]
+model:
+  trees: 12
+  max_depth: 9
+  min_leaf: 7
+  max_features: 38
+  bootstrap_fraction: 0.6
+  split_candidates: 12
+paper_model:
+  trees: 100
+  max_depth: null
+  min_leaf: 7
+  max_features: 38
+  bootstrap_fraction: 0.6
+  split_candidates: 12
+train:
+  excluded_year: 2014
+  independent_models: 8
+runtime:
+  seed: 20220908
+  device: cpu
+  distributed_backend: gloo
+paths:
+  checkpoint: result/checkpoints/ml_modis.pt
+  training_metrics: result/training/metrics.json
+  predictions: result/output/predictions.npz
+  evaluation_dir: result/evaluation
+evaluation:
+  cloud_albedo: 0.38
+  clear_sky_ocean_albedo: 0.07
+  importance_top_k: 10
+  figure_dpi: 150

config.json

@@ -0,0 +1,39 @@
+{
+  "model_name": "ML-MODIS",
+  "model_type": "bootstrap-random-forest-regressor",
+  "architectures": ["BootstrapRandomForestRegressor"],
+  "framework": "PyTorch",
+  "domain": "earth-science",
+  "task": "counterfactual-cloud-property-regression",
+  "implementation": {
+    "entry_point": "model/ml_modis.py",
+    "scope": "independent paper-method engineering reproduction",
+    "train_script": "scripts/train.py",
+    "inference_script": "scripts/inference.py",
+    "evaluation_script": "scripts/result.py",
+    "synthetic_data_script": "scripts/fake_data.py"
+  },
+  "architecture": {
+    "family": "bootstrap random regression forest",
+    "input_features": 114,
+    "output_targets": 4,
+    "independent_models": 8,
+    "months": [9, 10],
+    "targets": ["Nd", "reff", "LWP", "CF"]
+  },
+  "data": {
+    "format": "NPZ",
+    "protocol": "ml_modis_npz_v1",
+    "input_shape": ["N", 114],
+    "target_shape": ["N", 4],
+    "alignment_key": ["year", "month", "platform", "latitude", "longitude"]
+  },
+  "configuration_sources": [
+    "conf/config.yaml",
+    "model/ml_modis.py",
+    "scripts/fake_data.py",
+    "scripts/train.py",
+    "scripts/inference.py",
+    "scripts/result.py"
+  ]
+}

configuration.json

@@ -0,0 +1,12 @@
+{
+  "framework": "PyTorch",
+  "task": "counterfactual-cloud-property-regression",
+  "model": "ML-MODIS",
+  "input_format": "NPZ arrays with X[N,114], Y[N,4], and aligned spatiotemporal metadata",
+  "protocol": "independent bootstrap random forests by month and cloud-property target",
+  "default_config": "conf/config.yaml",
+  "training": "scripts/train.py",
+  "inference": "scripts/inference.py",
+  "evaluation": "scripts/result.py",
+  "visualization": "scripts/result.py"
+}

model/ml_modis.py

@@ -0,0 +1,247 @@
+"""Pure NumPy bootstrap random-forest regression used by ML-MODIS."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+
+TARGETS = ("Nd", "reff", "LWP", "CF")
+PRESSURE_VARIABLES = ("temperature", "specific_humidity", "relative_humidity", "u_wind", "v_wind", "omega", "geopotential", "cloud_liquid", "cloud_fraction")
+PRESSURE_LEVELS = (1000, 950, 900, 850, 800, 750, 700, 650, 600, 550)
+SINGLE_FEATURES = (
+    "sst", "surface_pressure", "mslp", "skin_temperature", "t2m", "d2m",
+    "u10", "v10", "surface_solar_radiation", "surface_thermal_radiation",
+    "latent_heat_flux", "sensible_heat_flux", "boundary_layer_height",
+    "total_column_water_vapour", "total_column_cloud_liquid", "cape", "cin",
+    "low_cloud_cover", "sea_ice_fraction", "precipitation", "cos_sza",
+    "latitude", "longitude", "platform_hour",
+)
+
+
+def feature_names() -> List[str]:
+    names = [f"{variable}_{level}hPa" for variable in PRESSURE_VARIABLES for level in PRESSURE_LEVELS]
+    names.extend(SINGLE_FEATURES)
+    if len(names) != 114:
+        raise RuntimeError("The ERA5 predictor ledger must contain exactly 114 features")
+    return names
+
+
+def regression_metrics(y_true: np.ndarray, y_pred: np.ndarray) -> Dict[str, float]:
+    mask = np.isfinite(y_true) & np.isfinite(y_pred)
+    if mask.sum() < 2:
+        return {"n": int(mask.sum()), "mse": float("nan"), "r2": float("nan"), "pearson": float("nan")}
+    y = np.asarray(y_true[mask], dtype=np.float64)
+    p = np.asarray(y_pred[mask], dtype=np.float64)
+    mse = float(np.mean((y - p) ** 2))
+    variance = float(np.sum((y - y.mean()) ** 2))
+    r2 = float(1.0 - np.sum((y - p) ** 2) / variance) if variance > 0 else float("nan")
+    pearson = float(np.corrcoef(y, p)[0, 1]) if np.std(y) > 0 and np.std(p) > 0 else float("nan")
+    return {"n": int(mask.sum()), "mse": mse, "r2": r2, "pearson": pearson}
+
+
+@dataclass
+class TreeConfig:
+    min_leaf: int = 7
+    max_features: int = 38
+    max_depth: Optional[int] = None
+    split_candidates: int = 12
+
+
+class RandomRegressionTree:
+    """CART regressor with random feature subsets and compact array state."""
+
+    def __init__(self, config: TreeConfig, seed: int):
+        self.config = config
+        self.seed = int(seed)
+        self.feature: List[int] = []
+        self.threshold: List[float] = []
+        self.left: List[int] = []
+        self.right: List[int] = []
+        self.value: List[float] = []
+
+    def fit(self, x: np.ndarray, y: np.ndarray) -> "RandomRegressionTree":
+        x = np.asarray(x, dtype=np.float32)
+        y = np.asarray(y, dtype=np.float64)
+        rng = np.random.default_rng(self.seed)
+
+        def build(indices: np.ndarray, depth: int) -> int:
+            node = len(self.value)
+            self.feature.append(-1)
+            self.threshold.append(np.nan)
+            self.left.append(-1)
+            self.right.append(-1)
+            self.value.append(float(y[indices].mean()))
+            if indices.size < 2 * self.config.min_leaf:
+                return node
+            if self.config.max_depth is not None and depth >= self.config.max_depth:
+                return node
+            parent_sse = float(np.sum((y[indices] - y[indices].mean()) ** 2))
+            if parent_sse <= 1e-12:
+                return node
+            n_features = min(self.config.max_features, x.shape[1])
+            candidates = rng.choice(x.shape[1], size=n_features, replace=False)
+            best: Optional[Tuple[float, int, float, np.ndarray]] = None
+            quantiles = np.linspace(0.05, 0.95, self.config.split_candidates)
+            for feature in candidates:
+                values = x[indices, feature]
+                thresholds = np.unique(np.quantile(values, quantiles))
+                for threshold in thresholds:
+                    is_left = values <= threshold
+                    nl = int(is_left.sum())
+                    nr = indices.size - nl
+                    if nl < self.config.min_leaf or nr < self.config.min_leaf:
+                        continue
+                    yl, yr = y[indices[is_left]], y[indices[~is_left]]
+                    score = float(np.sum((yl - yl.mean()) ** 2) + np.sum((yr - yr.mean()) ** 2))
+                    if best is None or score < best[0]:
+                        best = (score, int(feature), float(threshold), is_left.copy())
+            if best is None or best[0] >= parent_sse - 1e-12:
+                return node
+            _, split_feature, split_threshold, is_left = best
+            self.feature[node] = split_feature
+            self.threshold[node] = split_threshold
+            self.left[node] = build(indices[is_left], depth + 1)
+            self.right[node] = build(indices[~is_left], depth + 1)
+            return node
+
+        build(np.arange(y.size, dtype=np.int64), 0)
+        return self
+
+    def predict(self, x: np.ndarray) -> np.ndarray:
+        x = np.asarray(x, dtype=np.float32)
+        output = np.empty(x.shape[0], dtype=np.float32)
+        for row in range(x.shape[0]):
+            node = 0
+            while self.feature[node] >= 0:
+                node = self.left[node] if x[row, self.feature[node]] <= self.threshold[node] else self.right[node]
+            output[row] = self.value[node]
+        return output
+
+    def state_dict(self) -> Dict[str, Any]:
+        return {
+            "seed": self.seed,
+            "config": self.config.__dict__.copy(),
+            "feature": np.asarray(self.feature, dtype=np.int32),
+            "threshold": np.asarray(self.threshold, dtype=np.float32),
+            "left": np.asarray(self.left, dtype=np.int32),
+            "right": np.asarray(self.right, dtype=np.int32),
+            "value": np.asarray(self.value, dtype=np.float32),
+        }
+
+    @classmethod
+    def from_state_dict(cls, state: Dict[str, Any]) -> "RandomRegressionTree":
+        tree = cls(TreeConfig(**state["config"]), int(state["seed"]))
+        for name in ("feature", "threshold", "left", "right", "value"):
+            setattr(tree, name, np.asarray(state[name]).tolist())
+        return tree
+
+
+class BootstrapRandomForestRegressor:
+    """Regression forest with explicit approximately 60% bootstrap and OOB state."""
+
+    def __init__(self, n_trees: int = 100, min_leaf: int = 7, max_features: int = 38,
+                 bootstrap_fraction: float = 0.6, max_depth: Optional[int] = None,
+                 split_candidates: int = 12, seed: int = 0):
+        if n_trees < 1 or min_leaf < 1 or not 0 < bootstrap_fraction <= 1:
+            raise ValueError("Invalid forest configuration")
+        self.n_trees = int(n_trees)
+        self.bootstrap_fraction = float(bootstrap_fraction)
+        self.seed = int(seed)
+        self.tree_config = TreeConfig(int(min_leaf), int(max_features), max_depth, int(split_candidates))
+        self.trees: List[RandomRegressionTree] = []
+        self.oob_indices: List[np.ndarray] = []
+
+    def fit(self, x: np.ndarray, y: np.ndarray) -> "BootstrapRandomForestRegressor":
+        x = np.asarray(x, dtype=np.float32)
+        y = np.asarray(y, dtype=np.float32)
+        if x.ndim != 2 or x.shape[1] != 114 or y.shape != (x.shape[0],):
+            raise ValueError(f"Expected X [N,114] and y [N], got {x.shape} and {y.shape}")
+        rng = np.random.default_rng(self.seed)
+        draw_size = max(2 * self.tree_config.min_leaf, int(round(self.bootstrap_fraction * x.shape[0])))
+        self.trees, self.oob_indices = [], []
+        for _ in range(self.n_trees):
+            bootstrap = rng.integers(0, x.shape[0], size=draw_size)
+            used = np.zeros(x.shape[0], dtype=bool)
+            used[np.unique(bootstrap)] = True
+            oob = np.flatnonzero(~used)
+            tree_seed = int(rng.integers(0, 2**31 - 1))
+            self.trees.append(RandomRegressionTree(self.tree_config, tree_seed).fit(x[bootstrap], y[bootstrap]))
+            self.oob_indices.append(oob.astype(np.int32))
+        return self
+
+    def predict_trees(self, x: np.ndarray) -> np.ndarray:
+        if not self.trees:
+            raise RuntimeError("Forest is not fitted")
+        return np.stack([tree.predict(x) for tree in self.trees], axis=1)
+
+    def predict(self, x: np.ndarray) -> np.ndarray:
+        return self.predict_trees(x).mean(axis=1)
+
+    def oob_predict(self, x: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        sums = np.zeros(x.shape[0], dtype=np.float64)
+        counts = np.zeros(x.shape[0], dtype=np.int32)
+        for tree, indices in zip(self.trees, self.oob_indices):
+            if indices.size:
+                sums[indices] += tree.predict(x[indices])
+                counts[indices] += 1
+        prediction = np.full(x.shape[0], np.nan, dtype=np.float32)
+        valid = counts > 0
+        prediction[valid] = (sums[valid] / counts[valid]).astype(np.float32)
+        return prediction, counts
+
+    def permutation_importance(self, x: np.ndarray, y: np.ndarray, seed: int = 0) -> np.ndarray:
+        """Breiman OOB permuted-predictor delta MSE, averaged over eligible trees."""
+        rng = np.random.default_rng(seed)
+        deltas = np.zeros(x.shape[1], dtype=np.float64)
+        counts = np.zeros(x.shape[1], dtype=np.int32)
+        for tree, indices in zip(self.trees, self.oob_indices):
+            if indices.size < 2:
+                continue
+            xo = np.asarray(x[indices], dtype=np.float32)
+            yo = np.asarray(y[indices], dtype=np.float32)
+            baseline = float(np.mean((yo - tree.predict(xo)) ** 2))
+            for feature in range(x.shape[1]):
+                changed = xo.copy()
+                changed[:, feature] = changed[rng.permutation(indices.size), feature]
+                deltas[feature] += float(np.mean((yo - tree.predict(changed)) ** 2)) - baseline
+                counts[feature] += 1
+        return np.divide(deltas, counts, out=np.zeros_like(deltas), where=counts > 0).astype(np.float32)
+
+    def state_dict(self) -> Dict[str, Any]:
+        return {
+            "n_trees": self.n_trees,
+            "bootstrap_fraction": self.bootstrap_fraction,
+            "seed": self.seed,
+            "tree_config": self.tree_config.__dict__.copy(),
+            "trees": [tree.state_dict() for tree in self.trees],
+            "oob_indices": self.oob_indices,
+        }
+
+    @classmethod
+    def from_state_dict(cls, state: Dict[str, Any]) -> "BootstrapRandomForestRegressor":
+        config = state["tree_config"]
+        forest = cls(state["n_trees"], config["min_leaf"], config["max_features"],
+                     state["bootstrap_fraction"], config["max_depth"],
+                     config["split_candidates"], state["seed"])
+        forest.trees = [RandomRegressionTree.from_state_dict(item) for item in state["trees"]]
+        forest.oob_indices = [np.asarray(item, dtype=np.int32) for item in state["oob_indices"]]
+        return forest
+
+
+def validate_multimodal_keys(data: Dict[str, np.ndarray]) -> None:
+    required = ("year", "month", "platform", "latitude", "longitude", "X", "Y")
+    missing = [key for key in required if key not in data]
+    if missing:
+        raise ValueError(f"Missing aligned arrays: {missing}")
+    n = data["X"].shape[0]
+    if data["X"].shape[1] != 114 or data["Y"].shape != (n, 4):
+        raise ValueError("Predictors must be [N,114] and targets [N,4]")
+    if any(np.asarray(data[key]).shape[0] != n for key in required[:-2]):
+        raise ValueError("Year/month/platform/coordinates are not row-aligned")
+    keys = list(zip(data["year"].tolist(), data["month"].tolist(), data["platform"].tolist(),
+                    np.round(data["latitude"], 4).tolist(), np.round(data["longitude"], 4).tolist()))
+    if len(set(keys)) != n:
+        raise ValueError("Multimodal year-month-platform-latitude-longitude keys are not unique")

scripts/fake_data.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Generate structured synthetic ERA5-MODIS monthly pairs for an executable demo."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "model"))
+from ml_modis import PRESSURE_LEVELS, PRESSURE_VARIABLES, SINGLE_FEATURES, feature_names, validate_multimodal_keys
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", default=str(ROOT / "conf/config.yaml"))
+    parser.add_argument("--samples", type=int, default=None)
+    parser.add_argument("--output", default=None)
+    return parser.parse_args()
+
+
+def ocean_mask(lat: np.ndarray, lon: np.ndarray) -> np.ndarray:
+    """Analytic North Atlantic mask excluding coarse Greenland/Europe land shapes."""
+    greenland = (lat > 59) & (lon > -53) & (lon < -20 + 0.55 * (lat - 59))
+    europe = (lat > 50) & (lon > -10 + 0.35 * (lat - 50))
+    iceland = (lat > 63) & (lat < 67) & (lon > -25) & (lon < -13)
+    north_america = (lon < -52 + 0.3 * (lat - 45))
+    return ~(greenland | europe | iceland | north_america)
+
+
+def main() -> None:
+    args = parse_args()
+    config = yaml.safe_load(Path(args.config).read_text())
+    n = int(args.samples or config["data"]["samples"])
+    rng = np.random.default_rng(config["runtime"]["seed"])
+    years = np.asarray(config["data"]["years"], dtype=np.int16)
+    months = np.asarray(config["data"]["months"], dtype=np.int8)
+    platforms = np.asarray(config["data"]["platforms"], dtype="U5")
+
+    records = []
+    used = set()
+    while len(records) < n:
+        year = int(rng.choice(years))
+        month = int(rng.choice(months))
+        platform = str(rng.choice(platforms))
+        lat = int(rng.integers(45, 76))
+        lon = int(rng.integers(-60, 31))
+        key = (year, month, platform, lat, lon)
+        if key in used or not ocean_mask(np.array([lat]), np.array([lon]))[0]:
+            continue
+        used.add(key)
+        records.append(key)
+    year = np.asarray([r[0] for r in records], dtype=np.int16)
+    month = np.asarray([r[1] for r in records], dtype=np.int8)
+    platform = np.asarray([r[2] for r in records], dtype="U5")
+    lat = np.asarray([r[3] for r in records], dtype=np.float32)
+    lon = np.asarray([r[4] for r in records], dtype=np.float32)
+    hour = np.where(platform == "Terra", 11.0, 13.0).astype(np.float32)
+
+    phase = np.deg2rad(lon + 25) + (month - 9) * 0.35
+    maritime = np.cos(np.deg2rad(lat - 58)) * np.cos(np.deg2rad(lon + 25))
+    synoptic = np.sin(phase * 1.7 + (year - 2001) * 0.43) + 0.45 * np.cos(np.deg2rad(lat * 3))
+    sst = 286.0 - 0.42 * (lat - 45) + 1.1 * np.cos(phase) - 0.35 * (month - 9) + 0.025 * (year - 2001)
+    surface_pressure = 101300 + 900 * synoptic - 8 * (lat - 55) + rng.normal(0, 160, n)
+    humidity_base = np.clip(0.82 - 0.008 * (lat - 45) + 0.08 * maritime + 0.04 * synoptic, 0.35, 0.98)
+    stability = 0.7 * (lat - 55) - 1.8 * synoptic + rng.normal(0, 0.7, n)
+    x = np.empty((n, 114), dtype=np.float32)
+    column = 0
+    for variable in PRESSURE_VARIABLES:
+        for level in PRESSURE_LEVELS:
+            z = (1000 - level) / 50.0
+            if variable == "temperature": value = sst - 1.7 - 3.15 * z + 0.15 * stability
+            elif variable == "specific_humidity": value = 0.010 * humidity_base * np.exp(-0.23 * z)
+            elif variable == "relative_humidity": value = np.clip(humidity_base - 0.025 * z + 0.04 * np.sin(phase + z), 0.05, 1.0)
+            elif variable == "u_wind": value = 5 + 0.8 * z + 2.2 * np.sin(phase) + 0.12 * (lat - 55)
+            elif variable == "v_wind": value = 1.5 + 1.6 * np.cos(phase * 1.3) - 0.25 * z
+            elif variable == "omega": value = -0.025 * synoptic * np.exp(-0.08 * z)
+            elif variable == "geopotential": value = z * 50 * 9.81 + 4 * synoptic
+            elif variable == "cloud_liquid": value = np.maximum(0, 2.2e-4 * (humidity_base - 0.55) * np.exp(-0.18 * z))
+            else: value = np.clip((humidity_base - 0.55) * 1.8 * np.exp(-0.12 * z), 0, 1)
+            x[:, column] = value + rng.normal(0, max(float(np.std(value)) * 0.035, 1e-6), n)
+            column += 1
+    cos_sza = np.clip(np.cos(np.deg2rad(lat - 20)) * (0.97 - 0.01 * (hour - 11)), 0, 1)
+    singles = np.column_stack([
+        sst, surface_pressure, surface_pressure + 35, sst - 0.4, sst - 1.1,
+        sst - (1 - humidity_base) * 12, x[:, 30], x[:, 40], 190 * cos_sza,
+        315 - 2.5 * (sst - 278), 65 + 18 * synoptic, 18 + 8 * stability,
+        650 + 120 * humidity_base + 20 * synoptic, 16 + 30 * humidity_base,
+        0.08 + 0.18 * np.maximum(synoptic, 0), 80 * np.maximum(synoptic, 0),
+        -25 * np.maximum(-synoptic, 0), np.clip(0.25 + 0.45 * humidity_base + 0.05 * synoptic, 0, 1),
+        np.clip((lat - 68) / 8, 0, 1), np.maximum(0, 1.8 + 1.5 * synoptic),
+        cos_sza, lat, lon, hour,
+    ]).astype(np.float32)
+    x[:, 90:] = singles
+
+    platform_term = np.where(platform == "Aqua", 1.0, -1.0)
+    low_cloud = np.clip(0.22 + 0.55 * humidity_base + 0.035 * stability + 0.025 * synoptic, 0.05, 0.9)
+    nd = 62 + 48 * humidity_base + 5 * synoptic + 0.32 * (lat - 55) + 1.8 * platform_term
+    reff = 18.5 - 0.035 * nd + 0.055 * (sst - 278) - 0.10 * stability
+    lwp = 58 + 115 * low_cloud + 10 * synoptic - 2.0 * stability
+    cf = np.clip(low_cloud + 0.018 * platform_term, 0.03, 0.95)
+
+    plume = np.exp(-((lat - 60) / 10) ** 2 - ((lon + 20) / 25) ** 2)
+    eruption = (year == 2014).astype(np.float32) * (0.72 + 0.28 * (month == 10)) * plume
+    nd *= 1 + 0.28 * eruption
+    reff *= 1 - 0.08 * eruption
+    lwp *= 1 + 0.008 * eruption
+    cf = np.clip(cf * (1 + 0.11 * eruption), 0.01, 0.99)
+    y = np.column_stack([
+        nd + rng.normal(0, 3.0, n), reff + rng.normal(0, 0.28, n),
+        lwp + rng.normal(0, 5.0, n), cf + rng.normal(0, 0.018, n),
+    ]).astype(np.float32)
+    y[:, 0:3] = np.maximum(y[:, 0:3], 1e-3)
+    y[:, 3] = np.clip(y[:, 3], 0.001, 0.999)
+
+    payload = {"X": x, "Y": y, "year": year, "month": month, "platform": platform,
+               "platform_hour": hour, "latitude": lat, "longitude": lon,
+               "feature_names": np.asarray(feature_names()), "target_names": np.asarray(config["data"]["variables"]["targets"]["names"]),
+               "format_version": np.array(config["format_version"]),
+               "is_ocean": np.ones(n, dtype=bool), "eruption_strength": eruption.astype(np.float32)}
+    validate_multimodal_keys(payload)
+    output = ROOT / (args.output or config["data"]["path"])
+    output.parent.mkdir(parents=True, exist_ok=True)
+    np.savez_compressed(output, **payload)
+    print(f"output={output.relative_to(ROOT)} samples={n} shape={list(x.shape)} "
+          f"eruption_samples={int((year == 2014).sum())}")
+
+
+if __name__ == "__main__":
+    main()

scripts/inference.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Run all serialized trees and retain ensemble and per-tree predictions."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+import torch
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "model"))
+from ml_modis import BootstrapRandomForestRegressor, validate_multimodal_keys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", default=str(ROOT / "conf/config.yaml"))
+    parser.add_argument("--data", default=None)
+    parser.add_argument("--checkpoint", default=None)
+    parser.add_argument("--output", default=None)
+    args = parser.parse_args()
+    config = yaml.safe_load(Path(args.config).read_text())
+    with np.load(ROOT / (args.data or config["data"]["path"])) as archive:
+        data = {key: archive[key] for key in archive.files}
+    validate_multimodal_keys(data)
+    checkpoint = torch.load(ROOT / (args.checkpoint or config["paths"]["checkpoint"]), map_location="cpu", weights_only=False)
+    if checkpoint.get("format_version") != config["format_version"]:
+        raise ValueError("Checkpoint format_version does not match configuration")
+    targets = list(checkpoint["model_config"]["targets"])
+    tree_count = len(next(iter(checkpoint["model"].values()))["state"]["trees"])
+    tree_predictions = np.full((data["X"].shape[0], len(targets), tree_count), np.nan, dtype=np.float32)
+    for month in checkpoint["model_config"]["months"]:
+        mask = data["month"] == month
+        for target_index, target in enumerate(targets):
+            model = BootstrapRandomForestRegressor.from_state_dict(checkpoint["model"][f"{month}:{target}"]["state"])
+            tree_predictions[mask, target_index, :] = model.predict_trees(data["X"][mask])
+    prediction = tree_predictions.mean(axis=2)
+    safe_prediction = np.where(np.abs(prediction) > 1e-8, prediction, np.nan)
+    ratio = data["Y"] / safe_prediction
+    if not np.isfinite(prediction).all() or not np.isfinite(ratio).all():
+        raise FloatingPointError("Inference produced non-finite values")
+    output = ROOT / (args.output or config["paths"]["predictions"])
+    output.parent.mkdir(parents=True, exist_ok=True)
+    np.savez_compressed(output, pred=prediction, pred_trees=tree_predictions, obs=data["Y"],
+                        obs_over_pred=ratio, relative_response=ratio - 1.0,
+                        year=data["year"], month=data["month"], platform=data["platform"],
+                        latitude=data["latitude"], longitude=data["longitude"],
+                        target_names=np.asarray(targets))
+    print(f"output={output.relative_to(ROOT)} samples={prediction.shape[0]} "
+          f"targets={targets} trees_per_prediction={tree_count}")
+
+
+if __name__ == "__main__":
+    main()

scripts/result.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Evaluate OOB skill, 2014 cloud responses, importance and radiative contributions."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+from pathlib import Path
+
+import numpy as np
+import torch
+import yaml
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "model"))
+from ml_modis import BootstrapRandomForestRegressor, feature_names, regression_metrics
+
+
+def finite(value: float):
+    return float(value) if math.isfinite(float(value)) else None
+
+
+def weighted_mean(values: np.ndarray, latitude: np.ndarray) -> float:
+    valid = np.isfinite(values)
+    weights = np.cos(np.deg2rad(latitude[valid]))
+    return float(np.sum(values[valid] * weights) / np.sum(weights))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", default=str(ROOT / "conf/config.yaml"))
+    parser.add_argument("--data", default=None)
+    parser.add_argument("--checkpoint", default=None)
+    parser.add_argument("--predictions", default=None)
+    parser.add_argument("--output", default=None)
+    parser.add_argument("--skip-importance", action="store_true")
+    args = parser.parse_args()
+    config = yaml.safe_load(Path(args.config).read_text())
+    with np.load(ROOT / (args.data or config["data"]["path"])) as archive:
+        data = {key: archive[key] for key in archive.files}
+    with np.load(ROOT / (args.predictions or config["paths"]["predictions"])) as archive:
+        predictions = {key: archive[key] for key in archive.files}
+    checkpoint = torch.load(ROOT / (args.checkpoint or config["paths"]["checkpoint"]), map_location="cpu", weights_only=False)
+    targets = list(checkpoint["model_config"]["targets"])
+    report = {"format_version": config["format_version"],
+              "evidence_scope": "Synthetic structured data smoke reproduction; not paper numerical results.",
+              "oob": {}, "all_sample_skill": {}, "response_2014": {}, "susceptibility": {},
+              "radiative_relative_contribution_percent": {}, "permutation_importance_top10": {}}
+    names = feature_names()
+    for month in checkpoint["model_config"]["months"]:
+        for target_index, target in enumerate(targets):
+            key = f"{month}:{target}"
+            model_info = checkpoint["model"][key]
+            report["oob"][key] = {metric: finite(value) if metric != "n" else int(value)
+                                  for metric, value in model_info["oob_metrics"].items()}
+            month_mask = data["month"] == month
+            metrics = regression_metrics(predictions["obs"][month_mask, target_index], predictions["pred"][month_mask, target_index])
+            report["all_sample_skill"][key] = {metric: finite(value) if metric != "n" else int(value) for metric, value in metrics.items()}
+            if not args.skip_importance:
+                train_mask = month_mask & (data["year"] != 2014)
+                forest = BootstrapRandomForestRegressor.from_state_dict(model_info["state"])
+                importance = forest.permutation_importance(data["X"][train_mask], data["Y"][train_mask, target_index], config["runtime"]["seed"] + target_index)
+                order = np.argsort(importance)[::-1][:config["evaluation"]["importance_top_k"]]
+                report["permutation_importance_top10"][key] = [
+                    {"feature": names[index], "delta_oob_mse": float(importance[index])} for index in order
+                ]
+    eruption = predictions["year"] == 2014
+    monthly_log_response = {target: [] for target in targets}
+    for month in checkpoint["model_config"]["months"]:
+        mask = eruption & (predictions["month"] == month)
+        for target_index, target in enumerate(targets):
+            ratio = predictions["obs_over_pred"][mask, target_index]
+            mean_ratio = weighted_mean(ratio, predictions["latitude"][mask])
+            response = mean_ratio - 1.0
+            report["response_2014"][f"{month}:{target}"] = {
+                "area_weighted_obs_over_pred": mean_ratio,
+                "area_weighted_relative_percent": 100.0 * response,
+                "samples": int(mask.sum()),
+            }
+            monthly_log_response[target].append(math.log(max(mean_ratio, 1e-8)))
+    nd_change = float(np.mean(monthly_log_response["Nd"]))
+    for target in ("reff", "LWP", "CF"):
+        report["susceptibility"][f"dln{target}_dlnNd"] = finite(float(np.mean(monthly_log_response[target])) / nd_change)
+
+    alpha_cloud = float(config["evaluation"]["cloud_albedo"])
+    alpha_clear = float(config["evaluation"]["clear_sky_ocean_albedo"])
+    s_lwp = report["susceptibility"]["dlnLWP_dlnNd"] or 0.0
+    s_cf = report["susceptibility"]["dlnCF_dlnNd"] or 0.0
+    terms = {
+        "Twomey": alpha_cloud * (1 - alpha_cloud) / 3.0,
+        "LWP": alpha_cloud * (1 - alpha_cloud) * (5.0 / 6.0) * s_lwp,
+        "CF": (alpha_cloud - alpha_clear) * s_cf,
+    }
+    denominator = sum(terms.values())
+    report["radiative_relative_contribution_percent"] = {
+        key: finite(100.0 * value / denominator) for key, value in terms.items()
+    }
+    report["radiative_assumptions"] = {
+        "cloud_albedo": alpha_cloud, "clear_sky_ocean_albedo": alpha_clear,
+        "method": "Paper equations 1-3; common SWdown, CF and dlnNd/dlnAOD factors cancel in relative terms.",
+        "twomey_note": "The 1/3 term follows the paper equation; observed dlnreff/dlnNd is reported separately."
+    }
+    output_dir = ROOT / config["paths"]["evaluation_dir"]
+    output = ROOT / args.output if args.output else output_dir / "metrics.json"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    serialized = json.dumps(report, indent=2, allow_nan=False) + "\n"
+    output.write_text(serialized)
+    figure, axes = plt.subplots(1, 2, figsize=(12, 4.5))
+    labels = [f"{month}-{target}" for month in checkpoint["model_config"]["months"] for target in targets]
+    pearson = [report["all_sample_skill"][label.replace("-", ":")]["pearson"] for label in labels]
+    axes[0].bar(labels, pearson, color=["#275d6c", "#d98b3a", "#6b8e23", "#8b5a83"] * 2)
+    axes[0].set(ylabel="Pearson correlation", title="All-sample model skill")
+    axes[0].tick_params(axis="x", rotation=45, labelsize=8)
+    response_labels = [f"{month}-{target}" for month in checkpoint["model_config"]["months"] for target in targets]
+    responses = [report["response_2014"][label.replace("-", ":")]["area_weighted_relative_percent"] for label in response_labels]
+    axes[1].bar(response_labels, responses, color=["#275d6c", "#d98b3a", "#6b8e23", "#8b5a83"] * 2)
+    axes[1].axhline(0, color="black", linewidth=0.7)
+    axes[1].set(ylabel="Area-weighted response (%)", title="Observed / counterfactual in 2014")
+    axes[1].tick_params(axis="x", rotation=45, labelsize=8)
+    figure.tight_layout()
+    figure.savefig(output_dir / "comparison.png", dpi=int(config["evaluation"]["figure_dpi"]))
+    plt.close(figure)
+    print(json.dumps({"output": str(output), "response_2014": report["response_2014"],
+                      "susceptibility": report["susceptibility"],
+                      "radiative_percent": report["radiative_relative_contribution_percent"]}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

scripts/train.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Train month-by-target ML-MODIS forests, optionally task-parallel under torchrun."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+import torch
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "model"))
+from ml_modis import BootstrapRandomForestRegressor, feature_names, regression_metrics, validate_multimodal_keys
+
+
+def args_parser() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", default=str(ROOT / "conf/config.yaml"))
+    parser.add_argument("--data", default=None)
+    parser.add_argument("--checkpoint", default=None)
+    parser.add_argument("--paper-model", action="store_true")
+    parser.add_argument("--trees", type=int, default=None)
+    return parser.parse_args()
+
+
+def distributed_context() -> tuple[int, int]:
+    world = int(os.environ.get("WORLD_SIZE", "1"))
+    rank = int(os.environ.get("RANK", "0"))
+    if world > 1:
+        torch.distributed.init_process_group(backend="gloo")
+    return rank, world
+
+
+def main() -> None:
+    args = args_parser()
+    config = yaml.safe_load(Path(args.config).read_text())
+    settings = dict(config["model"])
+    if args.paper_model:
+        settings.update(config["paper_model"])
+    if args.trees is not None:
+        settings["trees"] = args.trees
+    data_path = ROOT / (args.data or config["data"]["path"])
+    with np.load(data_path) as archive:
+        data = {key: archive[key] for key in archive.files}
+    validate_multimodal_keys(data)
+    rank, world = distributed_context()
+    months = config["data"]["months"]
+    targets = config["data"]["variables"]["targets"]["names"]
+    tasks = [(int(month), target_index, target) for month in months
+              for target_index, target in enumerate(targets)]
+    local_models = {}
+    for task_index, (month, target_index, target) in enumerate(tasks):
+        if task_index % world != rank:
+            continue
+        mask = (data["month"] == month) & (data["year"] != config["train"]["excluded_year"])
+        x, y = data["X"][mask], data["Y"][mask, target_index]
+        model = BootstrapRandomForestRegressor(
+            n_trees=int(settings["trees"]), min_leaf=int(settings["min_leaf"]),
+            max_features=int(settings["max_features"]), bootstrap_fraction=float(settings["bootstrap_fraction"]),
+            max_depth=settings["max_depth"], split_candidates=int(settings["split_candidates"]),
+            seed=int(config["runtime"]["seed"] + task_index * 1009),
+        ).fit(x, y)
+        oob, counts = model.oob_predict(x)
+        local_models[f"{month}:{target}"] = {
+            "state": model.state_dict(), "oob_metrics": regression_metrics(y[counts > 0], oob[counts > 0]),
+            "train_samples": int(mask.sum()), "excluded_year": int(config["train"]["excluded_year"]),
+        }
+        print(f"rank={rank} trained month={month} target={target} samples={mask.sum()}", flush=True)
+    if world > 1:
+        gathered = [None] * world if rank == 0 else None
+        torch.distributed.gather_object(local_models, gathered, dst=0)
+        if rank == 0:
+            local_models = {key: value for shard in gathered for key, value in shard.items()}
+    if rank == 0:
+        checkpoint = ROOT / (args.checkpoint or config["paths"]["checkpoint"])
+        checkpoint.parent.mkdir(parents=True, exist_ok=True)
+        model_config = {
+            "architecture": "BootstrapRandomForestRegressor", "settings": settings,
+            "targets": targets, "months": months, "input_features": 114,
+            "feature_names": feature_names(), "excluded_year": int(config["train"]["excluded_year"]),
+        }
+        torch.save({"model": local_models, "model_config": model_config,
+                    "format_version": config["format_version"],
+                    "training": {"paper_model": args.paper_model, "distributed_world_size": world}}, checkpoint)
+        summary = {key: value["oob_metrics"] for key, value in sorted(local_models.items())}
+        metrics_path = ROOT / config["paths"]["training_metrics"]
+        metrics_path.parent.mkdir(parents=True, exist_ok=True)
+        metrics_path.write_text(json.dumps({"format_version": config["format_version"],
+                                            "models": summary}, indent=2, allow_nan=False) + "\n")
+        print(json.dumps({"checkpoint": str(checkpoint), "models": len(local_models), "oob": summary}, indent=2))
+    if world > 1:
+        torch.distributed.destroy_process_group()
+
+
+if __name__ == "__main__":
+    main()