extremeweatherbench 1.0.0

Benchmarking weather and weather AI models using extreme events

Extreme Weather Bench (EWB)

EWB is currently in limited pre-release. Bugs are likely to occur for now.

v1.0 to be published alongside EWB preprint.

Read our blog post here

As AI weather models are growing in popularity, we need a standardized set of community driven tests that evaluate the models across a wide variety of high-impact hazards. Extreme Weather Bench (EWB) builds on the successful work of WeatherBench and introduces a set of high-impact weather events, spanning across multiple spatial and temporal scales and different parts of the weather spectrum. We provide data to use for testing, standard metrics for evaluation by forecasters worldwide for each of the phenomena, as well as impact-based metrics. EWB is a community system and will be adding additional phenomena, test cases and metrics in collaboration with the worldwide weather and forecast verification community.

Events

EWB has cases broken down by multiple event types within src/extremeweatherbench/data/events.yaml between 2020 and 2024. EWB case studies are documented here.

Available:

Event Type	Number of Cases
🌇 Heat Waves	46
🧊 Freezes	14
🌀 Tropical Cyclones	106
☔️ Atmospheric Rivers	56
🌪️ Severe Convection	115
Total Cases	337

EWB paper and talks

• AMS 2025 talk: https://ams.confex.com/ams/105ANNUAL/meetingapp.cgi/Paper/451220
• EWB paper is in preparation and will be submitted in late 2025

How do I suggest new data, metrics, or otherwise get involved?

We welcome your involvement! The success of a benchmark suite rests on community involvement and feedback. There are several ways to get involved:

• Get involved in community discussion using the discussion board
• Submit new code requests using the issues
• Send us email at [e-mail]

Installing EWB

Currently, the easiest way to install EWB is using the pip command:

$ pip install git+https://github.com/brightbandtech/ExtremeWeatherBench.git

It is highly recommend to use uv if possible:

$ git clone https://github.com/brightbandtech/ExtremeWeatherBench.git
$ cd ExtremeWeatherBench
$ uv sync

How to Run EWB

Running EWB on sample data (included) is straightforward.

Using command line initialization:

$ ewb --default

Note: this will run every event type, case, target source, and metric for the individual event type as they become available for GFS initialized FourCastNetv2. It is expected a full evaluation will take some time, even on a large VM.

Using Jupyter Notebook or a Script:

from extremeweatherbench import cases, inputs, metrics, evaluate, utils

# Load in a forecast; here, we load in GFS initialized FCNv2 from the CIRA MLWP archive with a default variable built-in for convenience
fcnv2_heatwave_forecast = defaults.cira_fcnv2_heatwave_forecast

# Load in ERA5 with another default convenience variable 
era5_heatwave_target = defaults.era5_heatwave_target

# EvaluationObjects are used to evaluate a single forecast source against a single target source with a defined event type. Event types are declared with each case. One or more metrics can be evaluated with each EvaluationObject.
heatwave_evaluation_list = [
    inputs.EvaluationObject(
        event_type="heat_wave",
        metric_list=[
            metrics.MaximumMeanAbsoluteError(),
            metrics.RootMeanSquaredError(),
            metrics.MaximumLowestMeanAbsoluteError(),
        ],
        target=era5_heatwave_target,
        forecast=fcnv2_heatwave_forecast,
    ),
]
# Load in the EWB default list of event cases
case_metadata = cases.load_ewb_events_yaml_into_case_list()

# Create the evaluation class, with cases and evaluation objects declared
ewb_instance = evaluate.ExtremeWeatherBench(
    case_metadata=case_metadata,
    evaluation_objects=heatwave_evaluation_list,
)

# Execute a parallel run and return the evaluation results as a pandas DataFrame
heatwave_outputs = ewb_instance.run(
    parallel_config={'n_jobs':16} # Uses 16 jobs with the loky backend as default
)

# Save the results
heatwave_outputs.to_csv('heatwave_evaluation_results.csv')