README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Severe Weather
- Probability Calibration
frameworks: PyTorch
---

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

# Model Introduction

WoFS-StormCal addresses calibration of short-term, storm-scale severe-weather probabilities by combining storm state, surrounding environment, and object morphology from ensemble storm tracks to estimate the likelihood of tornadoes, severe hail, and severe wind. It is primarily intended to improve the reliability of ensemble guidance and support nowcasting, severe-weather risk assessment, and forecaster decision-making.

Paper: Using Machine Learning to Calibrate Storm-Scale Probabilistic Guidance of Severe Weather Hazards in the Warn-on-Forecast System  
https://arxiv.org/abs/2012.00679

# Model Description

WoFS-StormCal was proposed by research teams from the University of Oklahoma, the Cooperative Institute for Mesoscale Meteorological Studies, and the NOAA National Severe Storms Laboratory. The paper trained and validated the models with WoFS ensemble forecasts and local storm reports from the 2017-2019 NOAA Hazardous Weather Testbed Spring Forecasting Experiments. The model supports short-term storm-scale probabilistic forecasting and calibration for tornadoes, severe hail, and severe wind.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Storm-scale probabilistic guidance | Predict tornado, severe-hail, and severe-wind probabilities for ensemble storm-track objects. |
| Probability calibration | Fit monotone isotonic mappings from cross-validated probabilities. |
| Lead-group modeling | Process first-hour and second-hour 30-minute storm-track windows separately. |
| ModelScope/OneCode execution | Validate training, inference, probabilistic evaluation, visualization, and checkpoint workflows. |
| Multi-GPU training | Launch distributed data-parallel training with `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/WoFS-StormCal --local-dir ./WoFS-StormCal
cd WoFS-StormCal
```

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

Synthetic features use storm organization, rotation, instability, shear, cold-pool, and ensemble-spread latent drivers to create within-group and cross-group correlation while preserving all 113 dimensions. The data validates feature loading, probabilistic training, calibration, inference, and evaluation only; it does not represent the real severe-weather sample distribution or paper performance.

```bash
python scripts/fake_data.py
```

### 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 outputs are saved to:

```text
result/checkpoints/wofsstormcal.pt
result/training/metrics.json
```

### Trained Weights

No weights are bundled under `weight/`. The paper provides no confirmed official checkpoint, and the engineering checkpoint is not claimed to be compatible with external weights.

### Inference

```bash
python scripts/inference.py
```

Inference loads the training checkpoint, produces calibrated probabilities for three hazards from 113-dimensional object features, and saves them to `result/output/predictions.npz`.

### Evaluation and Visualization

```bash
python scripts/result.py
```

Evaluation reports probabilistic skill, classification skill, and reliability metrics for each hazard and lead group in `result/evaluation/metrics.json`. It also generates performance and reliability diagrams. 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 WoFS-StormCal paper specifications.

Use of this repository's code, official model weights, and data remains subject to the licenses and terms of their respective projects.