Publish CausalModelEvaluation engineering reproduction

.gitattributes

@@ -1,35 +1,12 @@
-*.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
+weight/* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,139 @@
+---
+license: cc-by-4.0
+language:
+- en
+tags:
+- OneScience
+- Earth Science
+- Causal Networks
+- Climate Model Evaluation
+frameworks: PyTorch
+---
+
+<p align="center">
+  <strong><span style="font-size: 30px;">CausalModelEvaluation</span></strong>
+</p>
+
+# Model Introduction
+
+CausalModelEvaluation (CME) addresses the limitations of climate-model evaluations that rely mainly on mean-state errors and do not determine whether key process relationships are represented correctly. It is primarily intended to construct causal climate fingerprints, identify dependencies among models with shared development backgrounds, evaluate precipitation simulation skill, and use historical process skill to constrain uncertainty in future precipitation change.
+
+Paper: Causal networks for climate model evaluation and constrained projections  
+https://doi.org/10.1038/s41467-020-15195-y
+
+# Model Description
+
+Causal Model Evaluation was proposed by research teams from Imperial College London, the German Aerospace Center, the University of Bremen, and the University of East Anglia. The paper evaluates CMIP5 sea-level-pressure and precipitation simulations with NCEP-NCAR and ERA-Interim reanalyses and CRU TS v4.02 precipitation observations. The model supports causal climate-fingerprint reconstruction, process-oriented climate-model evaluation, and constrained precipitation-change projection.
+
+# Use Cases
+
+| Use Case | Description |
+| :---: | :--- |
+| Causal fingerprinting | Estimate a directed, signed, lagged network from seasonal 50-node time series. |
+| Climate model evaluation | Compute reference-oriented asymmetric F1 with direction, sign, and lag tolerance. |
+| Precipitation skill | Compute latitude-area-weighted Taylor S-score and pattern correlation. |
+| Constrained projection | Fit an RBF plus white-noise GP between CME F1 and precipitation change. |
+| ModelScope/OneCode | Validate data, fitting, checkpoint, inference, evaluation, and task-figure workflows. |
+
+# 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/CausalModelEvaluation --local-dir ./CausalModelEvaluation
+cd CausalModelEvaluation
+```
+
+### 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
+
+```bash
+python scripts/fake_data.py
+```
+
+This repository uses a small number of structured synthetic samples to validate the engineering workflow. The data contains seasonal sea-level-pressure mode time series, distinct lagged causal relationships across models, and precipitation fields and changes related to model process skill. It preserves the paper's node, time, lag, and spatial dimensions and validates causal-network construction, model comparison, and constrained projection only; it does not represent the real climate-data distribution or paper performance.
+
+### 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
+```
+
+Training results include reference and model causal networks, model-comparison scores, and the precipitation-constraint relationship, with a checkpoint and training metrics saved for subsequent inference.
+
+```text
+result/checkpoints/causalmodelevaluation.pt
+result/training/metrics.json
+```
+
+### Trained Weights
+
+No weights are bundled under `weight/`. The paper method produces no conventional neural-network weights; the engineering checkpoint stores statistical networks and GP state and is not claimed to be compatible with external weights.
+
+### Inference
+
+```bash
+python scripts/inference.py
+```
+
+Inference reloads the checkpoint and exports complete model and four-season `edges/pvalues/mci`, complete reference networks, reference/model precipitation fields, CME F1, precipitation changes, GP means and 95% intervals, and network/projection metadata to `result/output/inference.npz`.
+
+### Evaluation and Visualization
+
+```bash
+python scripts/result.py
+```
+
+Evaluation generates structured results for climate-model causal-network comparison, precipitation simulation skill, and constrained projection, and saves them to `result/evaluation/metrics.json`. It also creates the model-skill and precipitation-change comparison figure `result/evaluation/cme_task.png`. Synthetic-data results are only for engineering-workflow validation and do not represent paper performance on the real test set.
+
+# 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 Causal Model Evaluation paper specifications.
+
+Use of this repository's code, official model weights, and data remains subject to the licenses and terms of their respective projects.

README_zh.md

@@ -0,0 +1,140 @@
+---
+license: cc-by-4.0
+language:
+- en
+- zh
+tags:
+- OneScience
+- 地球科学
+- 因果网络
+- 气候模型评估
+frameworks: PyTorch
+---
+
+<p align="center">
+  <strong><span style="font-size: 30px;">CausalModelEvaluation</span></strong>
+</p>
+
+# 模型介绍
+
+CausalModelEvaluation（CME）用于解决传统气候模型评价过度依赖平均状态误差、难以衡量过程关系是否正确的问题，通过比较气候模型与再分析资料中的因果联系评价模型对关键气候过程的表示能力。该方法主要用于构建气候因果指纹、识别具有共同开发背景的模型依赖性、评价降水模拟能力，并利用历史过程技能约束未来降水变化的不确定性。
+
+论文：Causal networks for climate model evaluation and constrained projections  
+https://doi.org/10.1038/s41467-020-15195-y
+
+# 模型描述
+
+Causal Model Evaluation 由 Imperial College London、German Aerospace Center、University of Bremen 和 University of East Anglia 的研究团队提出。论文使用 CMIP5 海平面气压与降水模拟、NCEP-NCAR 和 ERA-Interim 再分析以及 CRU TS v4.02 降水观测开展评价。模型适用于气候因果指纹重建、过程导向的气候模型评价和降水变化约束投影。
+
+# 适用场景
+
+| 场景 | 说明 |
+| :---: | :--- |
+| 因果指纹重建 | 从 50 节点季节时间序列估计有向、有符号、时滞网络。 |
+| 气候模型评估 | 以参考网络为基准计算方向、符号和时滞容忍的非对称 F1。 |
+| 降水技能评估 | 计算带纬度面积权重的 Taylor S-score 和空间型相关。 |
+| 约束投影 | 拟合 CME F1 与降水变化之间的 RBF 加白噪声 GP。 |
+| ModelScope/OneCode | 验证数据、拟合、checkpoint、推理、评估和任务图流程。 |
+
+# 使用说明
+
+## 1.OneCode
+
+可通过 OneCode 在线环境体验智能化一键式 AI4S 编程：
+
+[点击体验智能化一键式 AI4S 编程](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)
+
+## 2.下载安装
+
+```bash
+modelscope download --model OneScience/CausalModelEvaluation --local_dir ./CausalModelEvaluation
+cd CausalModelEvaluation
+```
+
+### 环境依赖
+
+**硬件要求**
+
+- 推荐使用 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
+```
+
+### 训练数据介绍
+
+```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
+```
+
+训练结果包含参考与模型因果网络、模型比较分数和降水约束关系，并保存 checkpoint 与训练指标供后续推理使用。
+
+```text
+result/checkpoints/causalmodelevaluation.pt
+result/training/metrics.json
+```
+
+### 训练权重
+
+本仓库不在 `weight/` 中内置权重。论文方法不产生传统神经网络权重，工程 checkpoint 保存统计网络与 GP 状态，不声明兼容外部权重。
+
+### 推理
+
+```bash
+python scripts/inference.py
+```
+
+推理重新加载 checkpoint，输出所有模型与四季的完整 `edges/pvalues/mci`、完整参考网络、参考及模型降水场、CME F1、降水变化、GP 均值与 95% 区间，以及网络和投影元数据到 `result/output/inference.npz`。
+
+### 评估和可视化
+
+```bash
+python scripts/result.py
+```
+
+评估生成气候模型因果网络比较、降水模拟能力和约束投影的结构化结果，并保存到 `result/evaluation/metrics.json`。脚本同时生成模型技能与降水变化关系的对比图 `result/evaluation/cme_task.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 |
+
+# 引用与许可证
+
+本仓库为 Causal Model Evaluation 论文公开规格的独立工程复现版本。
+
+本仓库代码、官方模型权重和数据的使用仍应以各自项目中的许可证及使用条款为准。

conf/config.yaml

@@ -0,0 +1,34 @@
+seed: 42
+data:
+  root: data
+  format_version: cme_structured_var_seasonal_v1
+  samples: 1
+  time_steps: 2100
+  nodes: 50
+  seasons: [DJF, MAM, JJA, SON]
+  model_count: 4
+  grid_shape: [73, 144]
+  years_per_segment: 70
+  time_step_days: 3
+model:
+  max_lag: 10
+  alpha: 0.02
+  ridge: 1.0e-6
+  exclude_self_links: true
+paper_model:
+  nodes: 50
+  time_step_days: 3
+  max_lag: 10
+  maximum_delay_days: 30
+  alpha: 1.0e-4
+  method: PCMCI with partial correlation
+  engineering_approximation: target-history conditional regression with partial correlation
+evaluation:
+  lag_tolerance: 2
+  reference_f1_for_projection: 0.64
+paths:
+  dataset: data/cme_fake.npz
+  checkpoint: result/checkpoints/causalmodelevaluation.pt
+  training_metrics: result/training/metrics.json
+  inference: result/output/inference.npz
+  evaluation_dir: result/evaluation

config.json

@@ -0,0 +1,38 @@
+{
+  "model_name": "CausalModelEvaluation",
+  "model_type": "causalmodelevaluation",
+  "architectures": ["LaggedPartialCorrelationCME", "PrecipitationConstraintGP"],
+  "framework": "PyTorch/NumPy/scikit-learn",
+  "domain": "climate-science",
+  "task": "causal-network-model-evaluation-and-constrained-precipitation-projection",
+  "implementation": {
+    "entry_point": "model/causalmodelevaluation.py",
+    "scope": "linear PCMCI-ParCorr engineering approximation at the paper node and lag dimensions",
+    "train_script": "scripts/train.py",
+    "inference_script": "scripts/inference.py",
+    "evaluation_script": "scripts/result.py",
+    "synthetic_data_script": "scripts/fake_data.py"
+  },
+  "architecture": {
+    "family": "lagged partial correlation conditional regression and Gaussian process",
+    "nodes": 50,
+    "maximum_lag_steps": 10,
+    "time_step_days": 3,
+    "paper_significance_threshold": 0.0001,
+    "engineering_fake_data_threshold": 0.02,
+    "network_layout": ["source", "target", "lag"],
+    "network_shape": [50, 50, 10]
+  },
+  "data": {
+    "protocol": "cme_structured_var_seasonal_v1",
+    "node_series_layout": ["member", "three_day_step", "node"],
+    "node_series_shape": ["B", 2100, 50],
+    "years_per_segment": 70,
+    "seasons": ["DJF", "MAM", "JJA", "SON"],
+    "precipitation_grid_shape": [73, 144],
+    "precipitation_grid_degrees": 2.5,
+    "network_output_shape": [50, 50, 10],
+    "model_count": 4
+  },
+  "configuration_sources": ["conf/config.yaml", "model/causalmodelevaluation.py", "scripts/fake_data.py", "scripts/train.py", "scripts/inference.py", "scripts/result.py"]
+}

configuration.json

@@ -0,0 +1,13 @@
+{
+  "framework": "PyTorch/NumPy/scikit-learn",
+  "task": "causal-network-evaluation-and-precipitation-constraint",
+  "model": "CausalModelEvaluation",
+  "input_format": "T50 or BT50",
+  "output_format": "source-target-lag tensors [50,50,10]",
+  "protocol": "lagged conditional regression approximation to linear PCMCI plus asymmetric signed F1, Taylor S-score, and RBF+white GP",
+  "default_config": "conf/config.yaml",
+  "training": "scripts/train.py",
+  "inference": "scripts/inference.py",
+  "evaluation": "scripts/result.py",
+  "visualization": "scripts/result.py"
+}

model/causalmodelevaluation.py

@@ -0,0 +1,182 @@
+"""Core statistical models and metrics for causal model evaluation (CME)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import torch
+from scipy import stats
+from sklearn.gaussian_process import GaussianProcessRegressor
+from sklearn.gaussian_process.kernels import ConstantKernel, RBF, WhiteKernel
+
+
+FORMAT_VERSION = "cme_lagged_parcorr_v1"
+
+
+def _as_series(data: np.ndarray | torch.Tensor, nodes: int) -> np.ndarray:
+    """Normalize [T,N] or [B,T,N] input without joining sample boundaries."""
+    array = data.detach().cpu().numpy() if isinstance(data, torch.Tensor) else np.asarray(data)
+    if array.ndim == 2:
+        array = array[None, ...]
+    if array.ndim != 3 or array.shape[-1] != nodes:
+        raise ValueError(f"expected [T,{nodes}] or [B,T,{nodes}], got {array.shape}")
+    if not np.isfinite(array).all():
+        raise ValueError("node time series contains NaN or Inf")
+    return array.astype(np.float64, copy=False)
+
+
+@dataclass
+class CausalNetwork:
+    """A directed signed lagged network with source-target-lag tensor layout."""
+
+    edges: torch.Tensor
+    pvalues: torch.Tensor
+    mci: torch.Tensor
+
+    def state_dict(self) -> dict[str, torch.Tensor]:
+        return {"edges": self.edges.cpu(), "pvalues": self.pvalues.cpu(), "mci": self.mci.cpu()}
+
+    @classmethod
+    def from_state_dict(cls, state: dict[str, torch.Tensor]) -> "CausalNetwork":
+        return cls(state["edges"].bool(), state["pvalues"].float(), state["mci"].float())
+
+
+class LaggedPartialCorrelationCME:
+    """Linear conditional-regression approximation to PCMCI's ParCorr MCI step.
+
+    Each target is conditioned on its own history through ``max_lag``. All
+    source-lag candidates are then residualized against that common condition
+    set and tested with a two-sided t test. This captures directed lagged
+    conditional dependence, but does not implement PCMCI's iterative PC stage.
+    """
+
+    def __init__(self, nodes: int = 50, max_lag: int = 10, alpha: float = 0.02,
+                 ridge: float = 1e-6, exclude_self_links: bool = True):
+        self.nodes = int(nodes)
+        self.max_lag = int(max_lag)
+        self.alpha = float(alpha)
+        self.ridge = float(ridge)
+        self.exclude_self_links = bool(exclude_self_links)
+        if self.nodes <= 1 or self.max_lag < 1 or not 0 < self.alpha < 1:
+            raise ValueError("nodes, max_lag, and alpha must define a valid test")
+
+    def fit(self, data: np.ndarray | torch.Tensor) -> CausalNetwork:
+        samples = _as_series(data, self.nodes)
+        if samples.shape[1] <= self.max_lag + 2:
+            raise ValueError("time dimension is too short for requested maximum lag")
+        current = np.concatenate([x[self.max_lag:] for x in samples], axis=0)
+        lagged = np.concatenate([
+            np.stack([x[self.max_lag - lag:-lag] for lag in range(1, self.max_lag + 1)], axis=2)
+            for x in samples
+        ], axis=0)  # [observations, source, lag]
+        candidates = lagged.reshape(len(current), -1)
+        candidates -= candidates.mean(axis=0, keepdims=True)
+        pvalues = np.ones((self.nodes, self.nodes, self.max_lag), dtype=np.float32)
+        mci = np.zeros_like(pvalues)
+        for target in range(self.nodes):
+            controls = lagged[:, target, :]
+            controls = np.column_stack([np.ones(len(controls)), controls])
+            gram = controls.T @ controls + self.ridge * np.eye(controls.shape[1])
+            projection = np.linalg.solve(gram, controls.T)
+            residual_x = candidates - controls @ (projection @ candidates)
+            y = current[:, target]
+            residual_y = y - controls @ (projection @ y)
+            numerator = residual_x.T @ residual_y
+            denominator = np.sqrt(np.sum(residual_x ** 2, axis=0) * np.sum(residual_y ** 2))
+            correlation = np.divide(numerator, denominator, out=np.zeros_like(numerator), where=denominator > 1e-12)
+            correlation = np.clip(correlation, -0.999999, 0.999999)
+            dof = max(len(y) - controls.shape[1] - 1, 1)
+            statistic = np.abs(correlation) * np.sqrt(dof / np.maximum(1.0 - correlation ** 2, 1e-12))
+            probability = 2.0 * stats.t.sf(statistic, dof)
+            mci[:, target, :] = correlation.reshape(self.nodes, self.max_lag)
+            pvalues[:, target, :] = probability.reshape(self.nodes, self.max_lag)
+        if self.exclude_self_links:
+            diagonal = np.arange(self.nodes)
+            pvalues[diagonal, diagonal, :] = 1.0
+            mci[diagonal, diagonal, :] = 0.0
+        edges = pvalues < self.alpha
+        return CausalNetwork(torch.from_numpy(edges), torch.from_numpy(pvalues), torch.from_numpy(mci))
+
+    def config(self) -> dict:
+        return {"nodes": self.nodes, "max_lag": self.max_lag, "alpha": self.alpha,
+                "ridge": self.ridge, "exclude_self_links": self.exclude_self_links}
+
+
+def asymmetric_f1(reference: CausalNetwork, candidate: CausalNetwork, lag_tolerance: int = 2) -> dict[str, float | int]:
+    """Compare direction and sign while allowing candidate lag error of +/- tolerance."""
+    ref_edges, pred_edges = reference.edges.numpy(), candidate.edges.numpy()
+    ref_sign, pred_sign = np.sign(reference.mci.numpy()), np.sign(candidate.mci.numpy())
+
+    def matched(edges_a, sign_a, edges_b, sign_b):
+        hits = 0
+        for source, target, lag in np.argwhere(edges_a):
+            lo, hi = max(0, lag - lag_tolerance), min(edges_b.shape[2], lag + lag_tolerance + 1)
+            hits += int(np.any(edges_b[source, target, lo:hi] &
+                               (sign_b[source, target, lo:hi] == sign_a[source, target, lag])))
+        return hits
+
+    ref_count, pred_count = int(ref_edges.sum()), int(pred_edges.sum())
+    recall_hits = matched(ref_edges, ref_sign, pred_edges, pred_sign)
+    precision_hits = matched(pred_edges, pred_sign, ref_edges, ref_sign)
+    recall = recall_hits / ref_count if ref_count else float(pred_count == 0)
+    precision = precision_hits / pred_count if pred_count else float(ref_count == 0)
+    f1 = 2 * precision * recall / (precision + recall) if precision + recall else 0.0
+    return {"f1": float(f1), "precision": float(precision), "recall": float(recall),
+            "reference_edges": ref_count, "candidate_edges": pred_count,
+            "precision_matches": precision_hits, "recall_matches": recall_hits,
+            "lag_tolerance": int(lag_tolerance)}
+
+
+def pattern_correlation(reference: np.ndarray, model: np.ndarray, weights: np.ndarray | None = None) -> float:
+    reference, model = np.asarray(reference, float).ravel(), np.asarray(model, float).ravel()
+    weights = np.ones_like(reference) if weights is None else np.asarray(weights, float).ravel()
+    weights = weights / weights.sum()
+    ref_centered = reference - np.sum(weights * reference)
+    model_centered = model - np.sum(weights * model)
+    denominator = np.sqrt(np.sum(weights * ref_centered ** 2) * np.sum(weights * model_centered ** 2))
+    return float(np.sum(weights * ref_centered * model_centered) / denominator) if denominator > 0 else 0.0
+
+
+def taylor_s_score(reference: np.ndarray, model: np.ndarray, weights: np.ndarray | None = None) -> dict[str, float]:
+    """Paper Eq. 5: (1+R)^4 / (4*(SDR + 1/SDR)^2)."""
+    reference, model = np.asarray(reference, float).ravel(), np.asarray(model, float).ravel()
+    weights = np.ones_like(reference) if weights is None else np.asarray(weights, float).ravel()
+    weights = weights / weights.sum()
+    correlation = pattern_correlation(reference, model, weights)
+    ref_std = np.sqrt(np.sum(weights * (reference - np.sum(weights * reference)) ** 2))
+    model_std = np.sqrt(np.sum(weights * (model - np.sum(weights * model)) ** 2))
+    ratio = model_std / max(ref_std, 1e-12)
+    score = (1.0 + correlation) ** 4 / (4.0 * (ratio + 1.0 / max(ratio, 1e-12)) ** 2)
+    return {"s_score": float(score), "pattern_correlation": correlation, "standard_deviation_ratio": float(ratio)}
+
+
+class PrecipitationConstraintGP:
+    """RBF plus white-noise GP for F1-to-delta-precipitation constraints."""
+
+    def __init__(self, random_state: int = 42, restarts: int = 2):
+        kernel = ConstantKernel(1.0, (1e-3, 1e3)) * RBF(0.15, (1e-2, 10.0)) + WhiteKernel(0.01, (1e-6, 1.0))
+        self.model = GaussianProcessRegressor(kernel=kernel, normalize_y=True,
+                                              n_restarts_optimizer=int(restarts), random_state=random_state)
+
+    def fit(self, f1_scores: np.ndarray, delta_precipitation: np.ndarray) -> "PrecipitationConstraintGP":
+        self.x_train = np.asarray(f1_scores, float).reshape(-1, 1)
+        self.y_train = np.asarray(delta_precipitation, float)
+        self.model.fit(self.x_train, self.y_train)
+        return self
+
+    def predict(self, f1_scores: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        mean, std = self.model.predict(np.asarray(f1_scores, float).reshape(-1, 1), return_std=True)
+        return mean, mean - 1.96 * std, mean + 1.96 * std
+
+    def state_dict(self) -> dict:
+        return {"x_train": self.x_train.astype(np.float64), "y_train": self.y_train.astype(np.float64),
+                "kernel_theta": self.model.kernel_.theta.astype(np.float64)}
+
+    @classmethod
+    def from_state_dict(cls, state: dict, random_state: int = 42) -> "PrecipitationConstraintGP":
+        instance = cls(random_state=random_state, restarts=0)
+        instance.model.kernel.theta = np.asarray(state["kernel_theta"])
+        instance.model.optimizer = None
+        instance.model.fit(np.asarray(state["x_train"]), np.asarray(state["y_train"]))
+        return instance

scripts/fake_data.py

@@ -0,0 +1,91 @@
+"""Generate seasonal directed VAR networks and precipitation fields for CME."""
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def stable_network(rng, nodes, season_index):
+    coefficients = np.zeros((nodes, nodes, 10), dtype=np.float32)
+    coefficients[np.arange(nodes), np.arange(nodes), 0] = 0.48 + 0.04 * season_index
+    for source in range(nodes):
+        target = (source + 3 + season_index) % nodes
+        lag = (source + 2 * season_index) % 4
+        coefficients[source, target, lag] = (0.13 + 0.03 * (source % 3)) * (-1 if source % 5 == 0 else 1)
+        if source % 4 == 0:
+            coefficients[source, (source + 11) % nodes, (lag + 1) % 6] = -0.11
+    return coefficients
+
+
+def simulate(rng, coefficients, samples, time_steps):
+    nodes, max_lag = coefficients.shape[0], coefficients.shape[2]
+    output = np.zeros((samples, time_steps, nodes), dtype=np.float32)
+    for sample in range(samples):
+        series = rng.normal(0, 0.35, (time_steps + max_lag, nodes)).astype(np.float32)
+        for time in range(max_lag, time_steps + max_lag):
+            forcing = np.zeros(nodes, dtype=np.float32)
+            for lag in range(1, max_lag + 1):
+                forcing += series[time - lag] @ coefficients[:, :, lag - 1]
+            series[time] = forcing + rng.normal(0, 0.38, nodes)
+        output[sample] = series[max_lag:]
+    return output
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+    config = yaml.safe_load((ROOT / "conf/config.yaml").read_text())
+    data, seed = config["data"], int(config["seed"])
+    path = ROOT / config["paths"]["dataset"]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and not args.force:
+        print(f"exists={path.relative_to(ROOT)} use --force to regenerate")
+        return
+    rng = np.random.default_rng(seed)
+    seasons, models = len(data["seasons"]), int(data["model_count"])
+    nodes, samples, steps = int(data["nodes"]), int(data["samples"]), int(data["time_steps"])
+    reference_coefficients = np.stack([stable_network(rng, nodes, season) for season in range(seasons)])
+    reference_series = np.stack([simulate(rng, reference_coefficients[s], samples, steps) for s in range(seasons)])
+    model_series = np.empty((models, seasons, samples, steps, nodes), dtype=np.float32)
+    model_coefficients = np.empty((models, seasons, nodes, nodes, 10), dtype=np.float32)
+    quality = np.linspace(0.92, 0.35, models).astype(np.float32)
+    for model in range(models):
+        for season in range(seasons):
+            coefficients = reference_coefficients[season].copy()
+            cross = ~np.eye(nodes, dtype=bool)
+            coefficients[cross] *= quality[model]
+            mutation_count = 3 + 3 * model
+            for _ in range(mutation_count):
+                source, target = rng.integers(0, nodes, 2)
+                if source != target:
+                    coefficients[source, target, rng.integers(0, 7)] = rng.choice([-1, 1]) * rng.uniform(0.08, 0.16)
+            model_coefficients[model, season] = coefficients
+            model_series[model, season] = simulate(rng, coefficients, samples, steps)
+    lat_count, lon_count = map(int, data["grid_shape"])
+    latitude = np.linspace(-90.0, 90.0, lat_count, dtype=np.float32)
+    longitude = np.linspace(0, 360, lon_count, endpoint=False, dtype=np.float32)
+    lat2d, lon2d = np.meshgrid(latitude, longitude, indexing="ij")
+    reference_precip = (3.0 + 2.1 * np.cos(np.deg2rad(lat2d)) ** 2 +
+                        0.45 * np.sin(np.deg2rad(2 * lon2d))).astype(np.float32)
+    precip_fields, delta = [], []
+    for model, q in enumerate(quality):
+        bias = (1 - q) * (0.8 * np.sin(np.deg2rad(lat2d)) + 0.35 * np.cos(np.deg2rad(lon2d)))
+        precip_fields.append(reference_precip * (0.88 + 0.12 * q) + bias + rng.normal(0, 0.06 + 0.08 * (1 - q), reference_precip.shape))
+        delta.append(0.18 + 0.95 * (q - 0.62) ** 2 + rng.normal(0, 0.025))
+    np.savez_compressed(path, format_version=np.asarray(data["format_version"]), seasons=np.asarray(data["seasons"]),
+                        reference_series=reference_series, model_series=model_series,
+                        reference_coefficients=reference_coefficients, model_coefficients=model_coefficients,
+                        reference_precipitation=reference_precip, model_precipitation=np.asarray(precip_fields, np.float32),
+                        delta_precipitation=np.asarray(delta, np.float32), latitude_degrees=latitude,
+                        longitude_degrees=longitude, model_quality=quality, time_step_days=np.asarray(data["time_step_days"]))
+    print(f"generated={path.relative_to(ROOT)} reference={reference_series.shape} models={model_series.shape}")
+
+
+if __name__ == "__main__":
+    main()

scripts/inference.py

@@ -0,0 +1,52 @@
+"""Reload the CME checkpoint and export complete network and projection outputs."""
+
+import json
+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))
+from model.causalmodelevaluation import CausalNetwork, FORMAT_VERSION, PrecipitationConstraintGP
+
+
+def stack_networks(states, field):
+    return np.stack([[getattr(CausalNetwork.from_state_dict(state), field).numpy() for state in group] for group in states])
+
+
+def main():
+    config = yaml.safe_load((ROOT / "conf/config.yaml").read_text())
+    checkpoint = torch.load(ROOT / config["paths"]["checkpoint"], map_location="cpu", weights_only=False)
+    if checkpoint["version"] != FORMAT_VERSION:
+        raise ValueError("unsupported checkpoint version")
+    reference_states = [checkpoint["reference_networks"]]
+    model_states = checkpoint["model_networks"]
+    f1 = checkpoint["model_f1"].numpy()
+    gp = PrecipitationConstraintGP.from_state_dict(checkpoint["gp"], int(config["seed"]))
+    query = np.sort(np.unique(np.append(f1, float(config["evaluation"]["reference_f1_for_projection"]))))
+    mean, lower, upper = gp.predict(query)
+    source = np.load(ROOT / config["paths"]["dataset"])
+    output = ROOT / config["paths"]["inference"]
+    output.parent.mkdir(parents=True, exist_ok=True)
+    np.savez_compressed(
+        output, edges=stack_networks(model_states, "edges"), pvalues=stack_networks(model_states, "pvalues"),
+        mci=stack_networks(model_states, "mci"), reference_edges=stack_networks(reference_states, "edges")[0],
+        reference_pvalues=stack_networks(reference_states, "pvalues")[0],
+        reference_mci=stack_networks(reference_states, "mci")[0], model_f1=f1,
+        reference_precipitation=source["reference_precipitation"], model_precipitation=source["model_precipitation"],
+        delta_precipitation=source["delta_precipitation"], latitude_degrees=source["latitude_degrees"],
+        longitude_degrees=source["longitude_degrees"], gp_query_f1=query, gp_mean_delta_precipitation=mean,
+        gp_lower_95=lower, gp_upper_95=upper, seasons=source["seasons"],
+        network_metadata=np.asarray(json.dumps(checkpoint["metadata"])),
+        projection_metadata=np.asarray(json.dumps({"kernel": str(gp.model.kernel_), "confidence": 0.95,
+                                                   "input": "CME asymmetric F1", "output": "delta precipitation"})),
+        format_version=np.asarray(FORMAT_VERSION))
+    print(f"inference={output.relative_to(ROOT)} edges={stack_networks(model_states, 'edges').shape} reference={stack_networks(reference_states, 'edges')[0].shape}")
+
+
+if __name__ == "__main__":
+    main()

scripts/result.py

@@ -0,0 +1,83 @@
+"""Compute CME, precipitation metrics, GP intervals, and the task figure."""
+
+import json
+import sys
+from pathlib import Path
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+import torch
+import yaml
+from scipy import stats
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from model.causalmodelevaluation import CausalNetwork, asymmetric_f1, taylor_s_score
+
+
+def network(edges, pvalues, mci):
+    return CausalNetwork(torch.from_numpy(edges), torch.from_numpy(pvalues), torch.from_numpy(mci))
+
+
+def main():
+    config = yaml.safe_load((ROOT / "conf/config.yaml").read_text())
+    data = np.load(ROOT / config["paths"]["inference"])
+    tolerance = int(config["evaluation"]["lag_tolerance"])
+    by_model, model_s = [], []
+    weights = np.cos(np.deg2rad(data["latitude_degrees"]))[:, None] * np.ones((1, len(data["longitude_degrees"])))
+    for model_index in range(data["edges"].shape[0]):
+        seasonal = []
+        for season in range(data["edges"].shape[1]):
+            seasonal.append(asymmetric_f1(
+                network(data["reference_edges"][season], data["reference_pvalues"][season], data["reference_mci"][season]),
+                network(data["edges"][model_index, season], data["pvalues"][model_index, season], data["mci"][model_index, season]), tolerance))
+        taylor = taylor_s_score(data["reference_precipitation"], data["model_precipitation"][model_index], weights)
+        model_s.append(taylor["s_score"])
+        edge_count = int(data["edges"][model_index].sum())
+        possible = int(np.prod(data["edges"][model_index].shape))
+        by_model.append({"model": model_index, "cme_f1": float(np.mean([x["f1"] for x in seasonal])),
+                         "seasonal_cme": seasonal, "edge_count": edge_count, "edge_density": edge_count / possible,
+                         "taylor": taylor, "delta_precipitation": float(data["delta_precipitation"][model_index])})
+    f1 = np.asarray([item["cme_f1"] for item in by_model])
+    s_scores = np.asarray(model_s)
+    delta = data["delta_precipitation"]
+    f1_delta = stats.pearsonr(f1, delta)
+    f1_s = stats.pearsonr(f1, s_scores)
+    report = {
+        "models": by_model,
+        "reference": {"edge_count": int(data["reference_edges"].sum()),
+                      "edge_density": float(data["reference_edges"].mean())},
+        "correlations": {"f1_vs_delta_precipitation": {"r": float(f1_delta.statistic), "pvalue": float(f1_delta.pvalue)},
+                         "f1_vs_taylor_s": {"r": float(f1_s.statistic), "pvalue": float(f1_s.pvalue)}},
+        "gp_projection": {"query_f1": data["gp_query_f1"].tolist(), "mean": data["gp_mean_delta_precipitation"].tolist(),
+                          "lower_95": data["gp_lower_95"].tolist(), "upper_95": data["gp_upper_95"].tolist(),
+                          "metadata": json.loads(str(data["projection_metadata"]))},
+        "protocol": {"direction_sign_required": True, "lag_tolerance_steps": tolerance,
+                     "lag_tolerance_days": tolerance * int(config["data"]["time_step_days"]),
+                     "paper_alpha": config["paper_model"]["alpha"], "engineering_alpha": config["model"]["alpha"]}
+    }
+    output = ROOT / config["paths"]["evaluation_dir"]
+    output.mkdir(parents=True, exist_ok=True)
+    (output / "metrics.json").write_text(json.dumps(report, indent=2) + "\n")
+    order = np.argsort(data["gp_query_f1"])
+    figure, axes = plt.subplots(1, 2, figsize=(11, 4.3))
+    axes[0].scatter(f1, s_scores, c=np.arange(len(f1)), cmap="viridis", s=55)
+    axes[0].set(xlabel="CME asymmetric F1", ylabel="Precipitation Taylor S-score", title=f"Network and precipitation skill (R={f1_s.statistic:.2f})")
+    axes[1].scatter(f1, delta, color="#9b3a2e", label="Synthetic models")
+    axes[1].plot(data["gp_query_f1"][order], data["gp_mean_delta_precipitation"][order], color="#173f5f", label="RBF + white GP")
+    axes[1].fill_between(data["gp_query_f1"][order], data["gp_lower_95"][order], data["gp_upper_95"][order], color="#4f8fba", alpha=0.25, label="95% interval")
+    axes[1].set(xlabel="CME asymmetric F1", ylabel="Delta precipitation", title="Constrained precipitation relationship")
+    axes[1].legend(fontsize=8)
+    figure.tight_layout()
+    figure.savefig(output / "cme_task.png", dpi=160)
+    plt.close(figure)
+    if not np.isfinite([f1_delta.statistic, f1_s.statistic, *data["gp_mean_delta_precipitation"]]).all():
+        raise FloatingPointError("evaluation contains non-finite values")
+    print(f"evaluation={output.relative_to(ROOT)} models={len(by_model)} figure=cme_task.png")
+
+
+if __name__ == "__main__":
+    main()

scripts/train.py

@@ -0,0 +1,53 @@
+"""Fit statistical CME networks and the precipitation-constraint GP."""
+
+import json
+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))
+from model.causalmodelevaluation import (FORMAT_VERSION, LaggedPartialCorrelationCME,
+                                         PrecipitationConstraintGP, asymmetric_f1)
+
+
+def main():
+    config = yaml.safe_load((ROOT / "conf/config.yaml").read_text())
+    np.random.seed(int(config["seed"]))
+    data = np.load(ROOT / config["paths"]["dataset"])
+    if str(data["format_version"]) != config["data"]["format_version"]:
+        raise ValueError("incompatible synthetic data format")
+    estimator = LaggedPartialCorrelationCME(**config["model"])
+    references = [estimator.fit(series) for series in data["reference_series"]]
+    model_networks, scores = [], []
+    for model_series in data["model_series"]:
+        networks = [estimator.fit(series) for series in model_series]
+        model_networks.append(networks)
+        scores.append(float(np.mean([asymmetric_f1(ref, net, int(config["evaluation"]["lag_tolerance"]))["f1"]
+                                     for ref, net in zip(references, networks)])))
+    gp = PrecipitationConstraintGP(int(config["seed"])).fit(np.asarray(scores), data["delta_precipitation"])
+    checkpoint = {
+        "version": FORMAT_VERSION, "config": config, "network_config": estimator.config(),
+        "reference_networks": [network.state_dict() for network in references],
+        "model_networks": [[network.state_dict() for network in networks] for networks in model_networks],
+        "model_f1": torch.tensor(scores), "gp": gp.state_dict(),
+        "metadata": {"method": "lagged target-history conditional regression ParCorr approximation",
+                     "gradient_training": False, "tensor_layout": "source,target,lag", "time_step_days": 3}
+    }
+    checkpoint_path = ROOT / config["paths"]["checkpoint"]
+    metrics_path = ROOT / config["paths"]["training_metrics"]
+    checkpoint_path.parent.mkdir(parents=True, exist_ok=True)
+    metrics_path.parent.mkdir(parents=True, exist_ok=True)
+    torch.save(checkpoint, checkpoint_path)
+    metrics_path.write_text(json.dumps({"model_f1": scores, "gp_kernel": str(gp.model.kernel_),
+                                        "paper_alpha": config["paper_model"]["alpha"],
+                                        "engineering_alpha": config["model"]["alpha"]}, indent=2) + "\n")
+    print(f"checkpoint={checkpoint_path.relative_to(ROOT)} networks={len(references) * (1 + len(model_networks))} gp_samples={len(scores)}")
+
+
+if __name__ == "__main__":
+    main()