hsilvosa/climate-spatiotemporal-forecaster

Global Extreme Climate and Heatwave Forecaster

A deep spatiotemporal probabilistic neural forecasting model designed to predict multi-horizon (1 to 14 days) extreme climate events, including dangerous heatwaves, record frosts, and precipitation anomalies ($T_{max}, T_{min}, PRCP$).

Trained on curated global weather stations from the NOAA Global Historical Climatology Network Daily (GHCN-Daily) dataset spanning all continents and major Koppen climate zones.

Model Architecture

The ClimateSpatiotemporalNet combines geometric spatial modeling with multi-horizon sequence attention:

1. Spherical Harmonic Embedding: Continuous latitude, longitude, and elevation are mapped onto a multi-scale Fourier manifold using spherical harmonic frequency bands ($2^0, 2^1, \dots, 2^7$).
2. Dilated Residual TCN Backbone: Extracts causal temporal dependencies across historical 30-day continuous observations without information leakage.
3. Temporal Multi-Head Self-Attention: Captures atmospheric memory, persistent pressure blocking patterns, and long-range seasonal transitions.
4. Direct Multi-Step Quantile Decoder: Predicts calibrated probabilistic trajectories for $P_{10}, P_{50}, P_{90}$ quantiles for $T_{max}$, $T_{min}$, and $PRCP$ across horizons $t+1 \dots t+14$, with structural monotonicity guarantees ($P_{10} \le P_{50} \le P_{90}$).
5. Extreme Hazard Classification Heads: Predicts calibrated event probabilities for extreme heatwaves ($T_{max} \ge \text{P95}$ for $\ge 3$ days), frost freezes ($T_{min} \le 0^\circ\text{C}$), and deluge anomalies ($PRCP \ge 50\text{mm/day}$).

Benchmark Performance

Evaluated on held-out out-of-sample global station observations:

Target / Hazard Metric	Horizon / Metric	Model Value	Baseline Skill
TMAX (Max Temperature)	1-Day MAE	2.397 °C	+28.4% vs Persistence
TMAX (Max Temperature)	7-Day MAE	2.734 °C	+21.2% vs Persistence
TMAX (Max Temperature)	Overall 14-Day MAE	2.694 °C	+18.6% vs Persistence
TMAX Interval Coverage	80% CI (P10 - P90)	80.2%	Calibrated (Nominal: 80%)
TMIN (Min Temperature)	Overall 14-Day MAE	2.475 °C	+19.4% vs Persistence
Heatwave Alert (EHF)	F1-Score	0.4099	ROC-AUC: 0.7701
Frost / Freeze Alert	F1-Score	0.8539	ROC-AUC: 0.9638
Deluge Hazard Alert	F1-Score	0.626	ROC-AUC: 0.8689

Installation & Quickstart

pip install torch safetensors numpy pandas pyarrow

Python Inference Example

import torch
from safetensors.torch import load_file
from climate_forecast.models.spatiotemporal_net import ClimateSpatiotemporalNet
from climate_forecast.config import ModelConfig

# 1. Initialize architecture and load weights
config = ModelConfig()
model = ClimateSpatiotemporalNet(config)
state_dict = load_file("model.safetensors")
model.load_state_dict(state_dict)
model.eval()

# 2. Prepare sample input tensors
# x_seq: [Batch, 30 days, 7 features] -> [tmax, tmin, prcp, sin_doy, cos_doy, tmax_anom, tmin_anom]
# x_spatial: [Batch, 3] -> [lat / 90.0, lon / 180.0, normalized_elevation]
# x_future_time: [Batch, 14 days, 2] -> [sin_doy, cos_doy]
x_seq = torch.randn(1, 30, 7)
x_spatial = torch.tensor([[40.7128 / 90.0, -74.0060 / 180.0, 0.1]])
x_future_time = torch.randn(1, 14, 2)

# 3. Predict 14-day probabilistic forecast and extreme hazard alerts
with torch.no_grad():
    outputs = model(x_seq, x_spatial, x_future_time)
    # quantiles: [1, 14, 3 targets (TMAX, TMIN, PRCP), 3 quantiles (P10, P50, P90)]
    quantiles = outputs["quantiles"]
    # hazard_probs: [1, 14, 3 hazards (Heatwave, Frost, Deluge)]
    hazard_probs = outputs["hazard_probs"]

print("14-Day TMAX P50:", quantiles[0, :, 0, 1].numpy())
print("14-Day Heatwave Probability:", hazard_probs[0, :, 0].numpy())

Dataset & Provenance

• Source: NOAA National Climatic Data Center, Global Historical Climatology Network - Daily (GHCN-Daily).
• Spatial Coverage: 120 representative global weather stations across 6 continents and all elevation profiles.
• Reference Climatology: 30-Year WMO Standard Normal period (1991-2020).

Citation

@article{menne2012ghcnd,
  title={An overview of the Global Historical Climatology Network-Daily Database},
  author={Menne, Matthew J and Durre, Imke and Vose, Russell S and Gleason, Byron E and Houston, Tamara G},
  journal={Journal of Atmospheric and Oceanic Technology},
  volume={29},
  number={7},
  pages={897--910},
  year={2012}
}