HDP: Heatwave Diagnostics Package

The Heatwave Diagnostics Package (HDP) is an open-source Python project that equips researchers with computationally-efficient tools to quantify heatwave metrics across multiple parameters for daily, gridded data produced by climate model large ensembles.

The HDP offers functions that leverage Xarray, Dask, and Numba to take full advantage of the available hardware capabilities. These functions have been optimized to both run quickly in serial execution and scale effectively in parallel and distributed computing systems. In addition to computing heatwave datasets, the HDP also contains several plotting functions that generate summary figures for quickly evaluating changes in heatwave patterns spatially, temporally, and across the heatwave parameter space. The user can choose to use the resulting matplotlib figures as base templates for creating their own custom figures or opt to create a standardized deck of figures that broadly summarizes the different metric trends. All graphical plots can then be stored in a Jupyter notebook for easy viewing and consolidated storage.

Why create the HDP?

Existing tools used to quantify heatwave metrics (such as ehfheatwaves, heatwave3, nctoolkit) were not designed to sample large sections of the heatwave parameter space. Many of these tools struggle to handle the computational burden of analyzing terabyte-scale datasets and do not offer a complete workflow for generating heatwave diagnostics from daily, gridded climate model output. The HDP expands upon this work to empower the user to conduct parameter-sampling analysis and reduce the computational burden of calculating heatwave metrics from increasingly large model output.

Installation

To install the HDP, activate your preferred Python environment (conda, venv, uv, etc.) and use the Python Package Index (PyPI) pip install command:

pip install hdp-python

Documentation

To learn more about the HDP and how to use it, check out the full ReadTheDocs documentation at https://hdp.readthedocs.io/en/latest/overview.html

Quick-Start

The code block below showcases an example HDP workflow using generated sample data:

from hdp.graphics.notebook import create_notebook
import hdp.utils
import hdp.measure
import hdp.threshold
import hdp.metric
import numpy as np

output_dir = "."

sample_control_temp = hdp.utils.generate_test_control_dataarray(add_noise=True)
sample_warming_temp = hdp.utils.generate_test_warming_dataarray(add_noise=True)

baseline_measures = hdp.measure.format_standard_measures(
    temp_datasets=[sample_control_temp]
)
test_measures = hdp.measure.format_standard_measures(
    temp_datasets=[sample_warming_temp]
)

percentiles = np.arange(0.9, 1.0, 0.01)

thresholds_dataset = hdp.threshold.compute_thresholds(
    baseline_measures,
    percentiles
)

definitions = [[3,0,0], [3,1,1], [4,0,0], [4,1,1], [5,0,0], [5,1,1]]

metrics_dataset = hdp.metric.compute_group_metrics(test_measures, thresholds_dataset, definitions, include_threshold=True)
metrics_dataset.to_netcdf(f"{output_dir}/sample_hw_metrics.nc", mode='w')

figure_notebook = create_notebook(metrics_dataset)
figure_notebook.save_notebook(f"{output_dir}/sample_hw_summary_figures.ipynb")

sample_control_temp = sample_control_temp.to_dataset()
sample_control_temp.attrs["description"] = "Mock control temperature dataset generated by HDP for unit testing."
sample_control_temp.to_netcdf(f"{output_dir}/sample_control_temp.nc", mode='w')

sample_warming_temp = sample_warming_temp.to_dataset()
sample_warming_temp.attrs["description"] = "Mock temperature dataset with warming trend generated by HDP for unit testing."
sample_warming_temp.to_netcdf(f"{output_dir}/sample_warming_temp.nc", mode='w')

LLM Support

The HDP is designed to support LLM-assisted development workflows.

If you are using Claude, ChatGPT, Gemini, or any other LLM service, point the coding assistant to the llms.txt file or drop in the following URL if you are using a web interface:

https://raw.githubusercontent.com/AgentOxygen/HDP/refs/heads/main/llms.txt

This text file serves as a entry point for LLMs to learn how to accurately use the HDP via markdown skills, isolated examples, and code snippets.

Unit Tests

The testing suite can be run by cloning the repository, building the docker image, and then running the container:

git clone git@github.com:AgentOxygen/HDP.git
cd HDP
docker build --rm -t hdp .
docker run -v .:/project -it hdp

Tests are also run automatically in the GitHub Actions to verify that commits pushed to the repository do not break existing functionality.

All tests are written using pytest and are described in the hdp/tests/ directory.

Contributing

Please report any bugs, ask questions, and make suggestions through the GitHub Issues form of this repository.

See the Contributing Guidelines for how to set up a development environment, run the tests, and submit changes. The Developer's Guide contains additional detail.

Acknowledgements

I would like to acknowledge the following people for their contributions to this project:

1. Dr. Geeta Persad for her guidance, mentorship, and encouragement throughout the development of this package.
2. Dr. Jane Baldwin for sharing her initial heatwave analysis code that inspired the HDP and providing her expertise on the science of extreme heat.
3. Dr. Tammas Loughran for developing ehfheatwaves which served as a comparable project and informed the software design of the HDP.
4. Dr. Ifeanyi Nduka for his design input and expertise in quantifying extreme heat.
5. (Soon to be Dr.) Sebastian Utama for helping me debug my code and brainstorm ideas.

Citation

If our software package helps you with your research, please consider citing it. GitHub also generates a citation from the repository's CITATION.cff via the Cite this repository button.

• Cummins, C., & Persad, G. (2026). Heatwave Diagnostics Package: Efficiently Compute Heatwave Metrics Across Parameter Spaces. Journal of Open Source Software, 11(118), 8111, https://doi.org/10.21105/joss.08111

@article{
    Cummins2026,
    doi = {10.21105/joss.08111},
    url = {https://doi.org/10.21105/joss.08111},
    year = {2026},
    publisher = {The Open Journal},
    volume = {11},
    number = {118},
    pages = {8111},
    author = {Cummins, Cameron and Persad, Geeta},
    title = {Heatwave Diagnostics Package: Efficiently Compute Heatwave Metrics Across Parameter Spaces},
    journal = {Journal of Open Source Software}
}