climate_indices

Python library of climate indices for drought, wildfire, and flood monitoring

climate_indices provides reference implementations of climate index algorithms that give a geographical and temporal picture of the severity and duration of precipitation, temperature, evaporative-demand, fire-weather, and wet-extreme anomalies for climate monitoring and research. It began as a drought library; it now covers drought, wildfire, and flood potential, and an energy family is in development.

Indices

Drought and moisture balance

• SPI, Standardized Precipitation Index, utilizing gamma and Pearson Type III distributions, with selectable placement of zero accumulations (zero_handling)
• SPEI, Standardized Precipitation Evapotranspiration Index, utilizing gamma, Pearson Type III, and generalized-logistic (log-logistic) distributions
• Standardized index (indices.standardized_index()), the SPI fitting pipeline for any non-negative series, such as runoff or streamflow for SRI/SSI work
• PNP, Percentage of Normal Precipitation
• PCI, Precipitation Concentration Index
• EDDI, Evaporative Demand Drought Index
• Palmer indices, including PDSI, PHDI, PMDI, Z-Index, and scPDSI

Evapotranspiration

• PET, Potential Evapotranspiration, utilizing the Thornthwaite, Hargreaves, or FAO-56 Penman-Monteith equations

Wildfire (climate_indices.fire)

• KBDI, the Keetch-Byram Drought Index
• CFFWIS, the Canadian Forest Fire Weather Index System: the FFMC, DMC, and DC moisture codes (with Drought Code overwintering) and the ISI, BUI, FWI, and DSR behavior indices
• Fosberg Fire Weather Index (FFWI)
• Hot-Dry-Windy Index (HDW)
• Haines Index

Flood potential (climate_indices.flood)

• Effective Precipitation (PE) and its derived Effective Drought Index (EDI, distinct from EDDI), the Flood Index (I_F), and the Antecedent Precipitation Index (API): daily accumulated-wetness measures that indicate flood potential, not flooding
• flood_events(), which extracts events with onset, duration, peak, and severity from a daily flood index

Energy (in development, #1157)

Planned, none shipped yet in the package:

• Heating, cooling, and energy degree days (HDD / CDD / EDD)
• Hub-height wind-speed profile, and wind and temperature-derated PV capacity factors
• Standardized energy production and demand indices: SREPI and a standardized demand index, plus SRLI for signed residual-load series, following Allen and Otero (2023)
• Run-theory energy-drought events (onset, duration, severity), and a capacity-weighted precipitation proxy for hydropower
• These indices describe the climate-driven component of energy supply and demand, not actual generation or load

Supporting tools

• Run theory (climate_indices.runs): runs above or below a threshold with duration, magnitude, intensity, and peak, per series or per grid cell
• Distribution fit diagnostics (fit_diagnostics()): the fitted parameters, probability of zero, and Kolmogorov-Smirnov statistic per calendar step and cell
• Probability-scale output (output_scale): standardized indices as normal scores, fitted cumulative probabilities, or a bounded [-1, 1] scale

Highlights

• Rust backend. An optional compiled extension (climate_indices._native) runs Rust ports of the numerical kernels behind SPI, SPEI, the standardized index, EDDI, PET, PNP, PCI, the Palmer family, the KBDI and CFFWIS moisture-code recurrences, and the flood family. It preserves the public API; a cross-backend parity registry checks every ported kernel against the Python reference at rtol = atol = 1e-10 with matching NaN positions, not bit-for-bit equality; see the parity contract. Speedups vary by kernel: the flood family measured 1.2x to 6.7x faster than its Python path and Thornthwaite PET 1.4x, while Hargreaves measured at parity and Penman-Monteith slightly slower (0.89x) at the benchmark size; see the measurements.
• Vectorized gridded computation. SPI, SPEI, EDDI, PNP, PET, and PDSI fit or rank a whole (time, *cells) block in one call instead of looping over cells. On a 38x87-cell, 40-year reference grid that is 4.4x faster for SPI, 3.6x for SPEI, 53x for Thornthwaite PET, 342x for EDDI, and 111x for gridded PDSI. On fully populated monthly grids, gamma SPI/SPEI, EDDI, and PNP are bit-identical to per-cell computation; Thornthwaite PET and successful Pearson fits agree within 1e-12. Pearson SPI's block-wide gamma fallback is not per-cell equivalent and can depend on chunk layout; daily and missing-data bounds are documented separately.
• xarray, Dask, and Zarr. Supported xarray entry points accept xarray.DataArray input, preserve coordinates, attach CF metadata, and stay lazy on Dask-backed arrays for chunk-by-chunk Zarr output. Temporal inference and core-dimension chunk requirements vary by function; indices.standardized_index() and scPDSI remain NumPy-only. See the compatibility matrix, writing NetCDF and Zarr outputs, the Zarr/Dask notebook, and chunking and scheduler guidance.
• Validation. Documented evidence distinguishes external checks against NOAA, NRCan, SPEIbase, and literature reference data from regression-only coverage; see Validation.
• Command-line interface. climate_indices --index {spi,spei,pnp,scaled,pet,palmers,kbdi,pe,edi,flood_index,api,all} computes indices from NetCDF inputs.

Project goals

This Python implementation of the above climate index algorithms is being developed with the following goals in mind:

• to provide an open source software package to compute a suite of climate indices commonly used for climate monitoring, with well documented code that is faithful to the relevant literature and which produces scientifically verifiable results
• to provide a central, open location for participation and collaboration for researchers, developers, and users of climate indices
• to facilitate standardization and consensus on best-of-breed climate index algorithms and corresponding compliant implementations in Python
• to provide transparency into the operational code used for climate monitoring activities at NCEI/NOAA, and consequent reproducibility of published datasets computed from this package
• to incorporate modern software engineering principles and scientific programming best practices

This is a developmental/forked version of code that was originally developed by NIDIS/NCEI/NOAA. See drought.gov.

• Documentation
• Climate Indices for Wildfire Applications
• Climate Indices for Flood and Wet-Extreme Applications
• Validation status
• Changelog
• License
• Disclaimer

Installation

This README describes 3.0.0, which is not yet published on PyPI. The released 2.x package does not include the fire, flood, or runs modules or the Rust backend. For 3.0.0 features, install from a development checkout.

Install the released 2.x package from PyPI:

pip install "climate-indices>=2.3"

uv users can run uv pip install "climate-indices>=2.3". The 2.3.0 floor matches the quickstart, which uses the xarray API added in 2.3.0; see Supported Python Versions for interpreter support.

Starting with 3.0.0, wheels for Linux (x86-64 and aarch64, manylinux_2_28, so glibc 2.28 or newer), macOS (Apple silicon and Intel), and Windows (x86-64) include the optional Rust acceleration backend; every other platform, including a Linux system with older glibc, installs the pure-Python wheel. Both carry the same version and the same public API; results agree within the cross-backend parity tolerance, not necessarily bit for bit. Calling code need not depend on which one pip selected. To see which one you have:

python -c "import climate_indices._native"   # succeeds when the extension is installed

A missing extension is not an error: climate_indices imports, and every computation runs the Python implementation. Installing from source needs no Rust toolchain either — pip install --no-binary climate_indices climate_indices installs from the sdist, which builds the pure-Python wheel. Developers who want the extension from a checkout build it with uv run maturin develop --release; see the Rust backend section of the architecture notes.

Developer Workflow

This project uses trunk-based development. main is the trunk and should always be releasable.

1. Start from current trunk: git switch main && git pull --ff-only origin main
2. Create a short-lived branch: git switch -c feature/<short-topic>
3. Make focused changes with tests.
4. Run validation: uv run ruff check src/ tests/ uv run ruff format --check src/ tests/ uv run mypy src/ tests/test_type_checking.py uv run pytest
5. Open a PR into main.
6. The maintainer merges the PR after review and passing CI; agents never merge.

Use feature/<topic>, fix/<topic>, docs/<topic>, chore/<topic>, perf/<topic>, refactor/<topic>, test/<topic>, ci/<topic>, or hotfix/<topic> branch names. Release branches are avoided; use maintenance branches only for approved older-version support.

The methodology behind this workflow — parallel agent sessions, worktree isolation, and the evidence each change must carry — is documented in AI-assisted development.

Release Recipe

Releases are tag-based. The Git tag, package version, GitHub Release, and PyPI version must match.

• Git tag: v1.2.3
• Package version: 1.2.3
• GitHub Release: v1.2.3
• PyPI release: 1.2.3

1. Prepare a release PR that updates pyproject.toml, CHANGELOG.md, and release notes/docs; the maintainer merges it after review and passing CI.
2. Confirm main is green.
3. Create an annotated tag from main.
4. Push the tag. The release workflow builds, validates, publishes to PyPI, and creates the GitHub Release.

Tag creation and publishing require maintainer approval. See docs/release-process.md for the full checklist.

Maintainer Quick Commands

Read-only preflight:

git status --short
git branch --show-current
git log --oneline --decorate -5
uv run pytest tests/test_release_integrity.py

Safe PR branch setup:

git switch main
git pull --ff-only origin main
git switch -c chore/issue-667-release-docs

Approval-required release tag commands:

git switch main
git pull --ff-only origin main
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

Supported Python Versions

Supports Python 3.10–3.14.

All supported versions are tested on Linux (ubuntu-latest) for every pull request and push to main. Python 3.14 is additionally tested on macOS on every event, and 3.10 on macOS on pushes to main, merge groups, the weekly schedule, and manual dispatch. Both latest and minimum declared dependency versions are tested in CI.

Version Support Policy

This project provides 12 months notice before dropping support for a Python version. When a version approaches end-of-life, removal will be announced via the CHANGELOG and a GitHub issue, and implemented no sooner than 12 months after announcement with a version bump.

Python 3.9 support was dropped in v2.2.0 (August 2025) due to scipy>=1.15.3 requiring 3.10+.

API Stability

Stable API: The NumPy-based computation functions follow strict semantic versioning.

Beta API: The xarray adapter layer provides automatic parameter inference, coordinate preservation, CF metadata, and Dask support. While beta, computation results follow the stable NumPy API's documented numerical-equivalence bounds — only the interface surface (parameter names, metadata attributes, coordinate handling) may evolve. Beta features are marked in docstrings, with BetaFeatureWarning as their public warning category. The adapter stays Beta in 3.0.0 and is promoted no earlier than 3.1.0, once the 3.0.0 calendar alignment has a release of soak time (ADR-0012).

See docs/xarray_compatibility.md for the 3.0.0 compatibility matrix, including Dask chunking constraints, metadata behavior, and the Palmer xarray adapter. See docs/performance.md for a runnable parallel SPI/SPEI example and the measured speedups behind the chunk and scheduler guidance.

Validation

VALIDATION.md classifies the evidence for the indices in its per-index inventory, separating independent external validation from regression coverage and recording their known gaps. Fosberg Fire Weather Index and Haines Index are not yet classified there. uv run pytest -m validation runs the marked reference-fixture and specification checks. FAO-56 worked-example checks run in the core suite via uv run pytest tests/test_pm_eto.py. The evidence includes:

• EDDI: NOAA PSL monthly reference ET/EDDI for 1-, 3-, and 6-month timescales (1979–2023); maximum observed error 2.43e-6.
• SPI: characterized against NOAA NCEI's operational climate-divisional SPI for all 344 divisions and 7 timescales; zero placement compared with the R SEI and SCI packages.
• SPEI: reproduces SPEIbase v2.11 from its own CRU TS inputs (correlation 0.9996–0.99999) and matches the R SPEI package's log-logistic fit within 1e-6.
• Standard Palmer (PDSI, PHDI, PMDI, Z-Index): qualified external validation against NOAA NCEI nClimDiv for all 344 divisions, 1895–2022 (median absolute difference 0.0127).
• scPDSI: cross-validated against Wells-lineage reference fixtures (atol=5e-5).
• CFFWIS: all seven components match the NRCan cffdrs reference within 1e-9.
• KBDI: reproduces the Keetch & Byram (1968) worked example.
• HDW: reproduces event timing and tracks the daily series in the Srock et al. (2018) Cedar Fire case; published magnitudes are characterization only, not numerical validation.
• PET: selected FAO-56 helper examples and the daily end-to-end Example 18, plus Thornthwaite and Hargreaves literature examples; monthly Example 17 is not encoded.
• Flood family: specification-level and regression coverage only; no external numeric oracle has been adopted yet.

The Rust backend has its own gate: the parity registry in tests/parity_registry.py runs each ported entry point through the extension and through the Python implementation on property-generated inputs, and fails if a kernel is added without an entry.

Upgrading to 3.0.0

3.0.0 changes some computed values and exception types without a deprecation period, most notably corrected daily calendar alignment in the xarray adapter, the PCI February fix, and the gamma probability of zero now taken from the Calibration Period. It also removes the spi console script in favor of climate_indices --index spi. Each change, how to detect it, and what to change is in docs/deprecations/api-changes.md; the full list is in the CHANGELOG. Upgrading from 2.1.x or earlier also crosses the 2.2.0 switch from None return tuples to exceptions.

Citation

You can cite climate_indices in your projects and research papers via the BibTeX entry below.

@misc {climate_indices,
    author = "James Adams",
    title  = "climate_indices, an open source Python library providing reference implementations of commonly used climate indices",
    url    = "https://github.com/monocongo/climate_indices",
    month  = "may",
    year   = "2017--"
}