extremeweatherbench 1.0.0__tar.gz

extremeweatherbench-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+*.egg-info
+.DS_Store
+build/
+dist/
+__pycache__/
+.pytest_cache
+*.py[oc]
+wheels/
+.python-version
+.venv
+.ipynb_checkpoints/
+.coverage*
+.mypy_cache
+.vscode/
+docs/source/_build/

extremeweatherbench-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brightband
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

extremeweatherbench-1.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: extremeweatherbench
+Version: 1.0.0
+Summary: Benchmarking weather and weather AI models using extreme events
+Project-URL: Documentation, https://extremeweatherbench.readthedocs.io/
+Project-URL: Repository, https://github.com/brightbandtech/extremeweatherbench
+License: MIT License
+        
+        Copyright (c) 2025 Brightband
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: benchmarking,climate,extreme events,forecasting,weather
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: <3.14,>=3.11
+Requires-Dist: cartopy==0.24.1
+Requires-Dist: click>=8.1.8
+Requires-Dist: dacite>=1.8.1
+Requires-Dist: eccodes==2.42.0
+Requires-Dist: flox>=0.10.0
+Requires-Dist: frozenlist==1.5.0
+Requires-Dist: gcsfs>=2024.12.0
+Requires-Dist: geopandas>=1.0.1
+Requires-Dist: joblib>=1.4.2
+Requires-Dist: kerchunk[dev]
+Requires-Dist: numba>=0.63.1
+Requires-Dist: numpy>=2.2.0
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: polars>=1.32.1
+Requires-Dist: pyarrow>=19.0.1
+Requires-Dist: pyogrio==0.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: regionmask>=0.13.0
+Requires-Dist: s3fs>=2024.12.0
+Requires-Dist: scikit-image>=0.25.2
+Requires-Dist: scores>=2.4.0
+Requires-Dist: sparse>=0.17.0
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: xarray[io]>=2025.7.1
+Requires-Dist: zarr<4,>=3.0.9
+Provides-Extra: data-prep
+Requires-Dist: fsspec>=2024.12.0; extra == 'data-prep'
+Requires-Dist: icechunk>=1.1.14; extra == 'data-prep'
+Requires-Dist: matplotlib>=3.10.0; extra == 'data-prep'
+Requires-Dist: obstore>=0.8.2; extra == 'data-prep'
+Requires-Dist: scipy>=1.13; extra == 'data-prep'
+Requires-Dist: seaborn>=0.13.2; extra == 'data-prep'
+Requires-Dist: ujson>=5.10.0; extra == 'data-prep'
+Requires-Dist: virtualizarr==2.1.2; extra == 'data-prep'
+Provides-Extra: multiprocessing
+Requires-Dist: dask[complete]>=2025.1.0; extra == 'multiprocessing'
+Requires-Dist: distributed>=2025.1.0; extra == 'multiprocessing'
+Description-Content-Type: text/markdown
+
+# Extreme Weather Bench (EWB)
+
+[![Documentation Status](https://readthedocs.org/projects/extremeweatherbench/badge/?version=latest)](https://extremeweatherbench.readthedocs.io/en/latest/?badge=latest)
+
+**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](https://www.brightband.com/blog/extreme-weather-bench)
+
+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](docs/events/AllCaseStudies.md).  
+
+## 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 hello@brightband.com 
+
+# Installing EWB
+
+Currently, the easiest way to install EWB is using the ```pip``` command:
+
+```shell
+$ pip install git+https://github.com/brightbandtech/ExtremeWeatherBench.git
+```
+
+It is highly recommend to use [uv](https://docs.astral.sh/uv/) if possible:
+
+```shell
+$ 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:
+
+```shell
+$ 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:
+ 
+```python
+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')
+```

extremeweatherbench-1.0.0/README.md

@@ -0,0 +1,105 @@
+# Extreme Weather Bench (EWB)
+
+[![Documentation Status](https://readthedocs.org/projects/extremeweatherbench/badge/?version=latest)](https://extremeweatherbench.readthedocs.io/en/latest/?badge=latest)
+
+**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](https://www.brightband.com/blog/extreme-weather-bench)
+
+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](docs/events/AllCaseStudies.md).  
+
+## 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 hello@brightband.com 
+
+# Installing EWB
+
+Currently, the easiest way to install EWB is using the ```pip``` command:
+
+```shell
+$ pip install git+https://github.com/brightbandtech/ExtremeWeatherBench.git
+```
+
+It is highly recommend to use [uv](https://docs.astral.sh/uv/) if possible:
+
+```shell
+$ 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:
+
+```shell
+$ 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:
+ 
+```python
+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')
+```

extremeweatherbench-1.0.0/pyproject.toml

@@ -0,0 +1,181 @@
+[project]
+name = "extremeweatherbench"
+version = "1.0.0"
+description = "Benchmarking weather and weather AI models using extreme events"
+keywords = [
+    "weather",
+    "extreme events",
+    "benchmarking",
+    "forecasting",
+    "climate",
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "dacite>=1.8.1",
+    "gcsfs>=2024.12.0",
+    "geopandas>=1.0.1",
+    "joblib>=1.4.2",
+    "numpy>=2.2.0",
+    "pandas>=2.2.3",
+    "pyarrow>=19.0.1",
+    "pyyaml>=6.0.2",
+    "regionmask>=0.13.0",
+    "s3fs>=2024.12.0",
+    "scores>=2.4.0",
+    "tqdm>=4.67.1",
+    "xarray[io]>=2025.7.1",
+    "zarr>=3.0.9,<4",
+    "kerchunk[dev]",
+    "flox>=0.10.0",
+    "click>=8.1.8",
+    "polars>=1.32.1",
+    "eccodes==2.42.0",
+    "frozenlist==1.5.0",
+    "pyogrio==0.10.0",
+    "scikit-image>=0.25.2",
+    "cartopy==0.24.1",
+    "numba>=0.63.1",
+    "sparse>=0.17.0",
+]
+
+[project.optional-dependencies]
+data-prep = [
+    "fsspec>=2024.12.0",
+    "icechunk>=1.1.14",
+    "matplotlib>=3.10.0",
+    "obstore>=0.8.2",
+    "scipy>=1.13",
+    "seaborn>=0.13.2",
+    "ujson>=5.10.0",
+    "virtualizarr==2.1.2",
+]
+multiprocessing = ["dask[complete]>=2025.1.0", "distributed>=2025.1.0"]
+
+[dependency-groups]
+dev = [
+    "deptry>=0.23.0",
+    "ipykernel>=6.29.5",
+    "ipywidgets>=8.1.5",
+    "isort>=6.0.1",
+    "jupyterlab>=4.4.5",
+    "lxml-stubs>=0.5.1",
+    "mypy>=1.14.1",
+    "pandas-stubs>=2.3.0.250703",
+    "pre-commit>=4.1.0",
+    "pytest>=8.3.4",
+    "pytest-cov>=6.0.0",
+    "pytest-mock>=3.14.0",
+    "ruff>=0.9.4",
+    "types-pytz>=2025.2.0.20250809",
+    "types-pyyaml>=6.0.12.20241230",
+    "types-tqdm>=4.67.0.20250809",
+    "python-semantic-release>=10.3.0",
+    "twine>=5.1.1",
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-autoapi[python]>=0.4.1",
+    "mkdocs-material>=9.7.0",
+    "mkdocstrings[python]>=1.0.0",
+    "pymdown-extensions>=10.19.1",
+]
+
+complete = ["extremeweatherbench[data-prep,multiprocessing]"]
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/extremeweatherbench"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/extremeweatherbench/**/*"]
+
+[project.urls]
+Documentation = "https://extremeweatherbench.readthedocs.io/"
+Repository = "https://github.com/brightbandtech/extremeweatherbench"
+
+
+[project.scripts]
+ewb = "extremeweatherbench.evaluate_cli:cli_runner"
+
+[tool.uv.sources]
+extremeweatherbench = { workspace = true }
+kerchunk = { git = "https://github.com/fsspec/kerchunk" }
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+lint.ignore = []
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+
+# Enable auto-formatting of code examples in docstrings. Markdown,
+# reStructuredText code/literal blocks and doctests are all supported.
+#
+# This is currently disabled by default, but it is planned for this
+# to be opt-out in the future.
+docstring-code-format = true
+
+# Set the line length limit used when formatting code snippets in
+# docstrings.
+#
+# This only has an effect when the `docstring-code-format` setting is
+# enabled.
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint.isort]
+case-sensitive = true
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+dist_path = "dist/"
+upload_to_pypi = false
+remote = { type = "github" }
+commit_author = "semantic-release <semantic-release@python>"
+commit_parser = "conventional"
+commit_parser_options = { parse_squash_commits = "false", parse_merge_commits = "true" }
+minor_tag = "[minor]"
+patch_tag = "[patch]"
+major_tag = "[major]"
+build_command = """
+  uv lock --offline
+  git add uv.lock
+  uv build
+"""
+# Only create GitHub releases for the current version, not historical ones
+github_release_mode = "latest"
+# Ensure assets are only uploaded for the current release, not past ones
+upload_assets_for_all_releases = false
+
+[tool.pytest]
+addopts = ["--ignore=tests/test_golden.py", "--cov=extremeweatherbench"]
+markers = [
+    "integration: marks tests as integration tests (may be slow)",
+    "slow: marks tests as slow (may take longer to complete)",
+]