Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

Climate_Indices

Contains Python implementations of various climate index algorithms which provide a geographical and temporal picture of the severity of precipitation and temperature anomalies useful for climate monitoring and research.
https://github.com/monocongo/climate_indices

Category: Climate Change
Sub Category: Climate Data Processing and Analysis

Keywords from Contributors

gtk qt tk wx

Last synced: about 18 hours ago
JSON representation

Repository metadata

Climate indices for drought monitoring

README.md

Banner Image

climate_indices

Actions Status
License
PyPI - Python Version

Python library of indices useful for climate monitoring

This project contains Python implementations of various climate index algorithms which provide
a geographical and temporal picture of the severity and duration of precipitation and temperature
anomalies useful for climate monitoring and research.

The following indices are provided:

  • SPI,
    Standardized Precipitation Index, utilizing both gamma and Pearson Type III distributions
  • SPEI,
    Standardized Precipitation Evapotranspiration Index, utilizing both gamma and Pearson Type III distributions
  • PET, Potential Evapotranspiration, utilizing either Thornthwaite
    or Hargreaves equations
  • PNP,
    Percentage of Normal Precipitation
  • PCI, Precipitation Concentration Index

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.

Supported Python Versions

Python Version Status Notes
3.10 Supported Minimum supported version
3.11 Supported
3.12 Supported
3.13 Supported Latest supported version

All versions are tested on Linux (ubuntu-latest). Python 3.10 and 3.13 are additionally
tested on macOS. 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

API Surface Status Guarantee
NumPy array functions (indices.spi, indices.spei, indices.pet) Stable No breaking changes in minor versions
xarray DataArray functions (spi(), spei(), pet_thornthwaite(), pet_hargreaves()) Beta No breaking changes in patch versions

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 are identical
to the stable NumPy API — only the interface surface (parameter names, metadata attributes,
coordinate handling) may evolve. Beta features are tagged with BetaFeatureWarning and
marked in docstrings.

Migration Guide for v2.2.0

Breaking Change: Exception-Based Error Handling

Version 2.2.0 introduces a significant architectural improvement in error handling. The library now uses exception-based error handling instead of returning None tuples for error conditions.

What Changed

Before (v2.1.x and earlier):

# Old behavior - functions returned None tuples on failure
result = some_internal_function(data)
if result == (None, None, None, None):
    # Handle error case
    pass

After (v2.2.0+):

# New behavior - functions raise specific exceptions
try:
    result = some_internal_function(data)
except climate_indices.compute.InsufficientDataError as e:
    # Handle insufficient data case
    print(f"Not enough data: {e.non_zero_count} values found, {e.required_count} required")
except climate_indices.compute.PearsonFittingError as e:
    # Handle fitting failure case
    print(f"Fitting failed: {e}")

New Exception Hierarchy

  • DistributionFittingError (base class)
    • InsufficientDataError - raised when there are too few non-zero values for statistical fitting
    • PearsonFittingError - raised when L-moments calculation fails for Pearson Type III distribution

Impact on Users

  • Direct API users: No changes needed - the public SPI/SPEI functions handle exceptions internally
  • Library integrators: If you were checking for None return values from internal functions, update to use try/catch blocks
  • Benefits: More informative error messages, better debugging, and automatic fallback from Pearson to Gamma distribution when appropriate

Code Quality Improvements

Version 2.2.0 also addresses floating point comparison issues (python:S1244) throughout the codebase:

Floating Point Comparisons:

# ❌ OLD: Direct equality checks (unreliable)
if values == 0.0:
    handle_zero_case()

# ✅ NEW: Safe comparison using numpy.isclose()
if np.isclose(values, 0.0, atol=1e-8):
    handle_zero_case()

Benefits:

  • Eliminates floating point precision issues in statistical parameter validation
  • Improves test reliability and numerical robustness
  • Follows scientific computing best practices for floating point arithmetic
  • See docs/floating_point_best_practices.md for comprehensive guidelines

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--"
}

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 4 days ago

Total Commits: 1,175
Total Committers: 20
Avg Commits per committer: 58.75
Development Distribution Score (DDS): 0.309

Commits in past year: 195
Committers in past year: 3
Avg Commits per committer in past year: 65.0
Development Distribution Score (DDS) in past year: 0.169

Name Email Commits
James Adams m****o@g****m 812
James.Adams J****s@C****l 213
james.adams j****s@o****m 60
james.a j****a@c****m 25
dependabot[bot] 4****] 13
James Adams j****s@v****m 11
Benjamin Root b****t@g****m 10
Arnab Paul Choudhury a****4@g****m 9
Nathan Nayda n****a@s****m 6
kikocorreoso k****o@g****m 4
AGericke g****e@i****n 3
Ben Lewis b****n 1
David de Klerk d****k@e****k 1
DeepSource Bot b****t@d****o 1
haysengithub d****e@g****m 1
Scott Wales s****s@u****u 1
Laura Guillory l****y@g****m 1
deepsource-autofix[bot] 6****] 1
kikocorreoso y****u@e****m 1
snyk-bot s****t@s****o 1

Committer domains:

Issue and Pull Request metadata

Last synced: 4 days ago

Total issues: 325
Total pull requests: 267
Average time to close issues: 3 months
Average time to close pull requests: 15 days
Total issue authors: 111
Total pull request authors: 17
Average comments per issue: 2.59
Average comments per pull request: 1.03
Merged pull request: 229
Bot issues: 0
Bot pull requests: 10

Past year issues: 9
Past year pull requests: 18
Past year average time to close issues: 44 minutes
Past year average time to close pull requests: 1 day
Past year issue authors: 6
Past year pull request authors: 2
Past year average comments per issue: 1.11
Past year average comments per pull request: 2.28
Past year merged pull request: 7
Past year bot issues: 0
Past year bot pull requests: 7

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/monocongo/climate_indices

Top Issue Authors

  • monocongo (166)
  • crestedcaracaryn (6)
  • kikocorreoso (5)
  • bennyistanto (5)
  • WeatherGod (5)
  • aleccourt (4)
  • SouhailAB (4)
  • s-m-t-c (3)
  • itati01 (3)
  • wsor330 (3)
  • Lixia0911 (3)
  • tommylees112 (3)
  • helena434 (2)
  • yheng0821 (2)
  • fipoucat (2)

Top Pull Request Authors

  • monocongo (224)
  • WeatherGod (10)
  • dependabot[bot] (10)
  • Seven-milk (7)
  • kikocorreoso (3)
  • nnayda (2)
  • go1me (1)
  • oshin94 (1)
  • cshields143 (1)
  • dawiedotcom (1)
  • ScottWales (1)
  • Emmadd (1)
  • itati01 (1)
  • Daafip (1)
  • Laura-Guillory (1)

Top Issue Labels

  • enhancement (28)
  • help wanted (19)
  • bug (11)
  • question (3)
  • documentation (2)

Top Pull Request Labels

  • dependencies (11)
  • python:uv (7)
  • enhancement (1)

Package metadata

proxy.golang.org: github.com/monocongo/climate_indices

pypi.org: climate-indices

Reference implementations of various climate indices typically used for drought monitoring

  • Homepage: https://github.com/monocongo/climate_indices
  • Documentation: https://climate-indices.readthedocs.io/en/latest/
  • Licenses: BSD-3-Clause License ======================================================================================================================== Copyright 2017, James Adams Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ======================================================================================================================== ======================================================================================================================== Previous Public Domain License (from code originally downloaded from drought.gov): ======================================================================================================================== NOAA's National Centers for Environmental Information NOAA/NESDIS/NCEI 151 Patton Ave, Asheville, NC 28801 THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY, EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL SUPPORT TO USERS.
  • Latest release: 2.4.0 (published 14 days ago)
  • Last Synced: 2026-04-17T04:01:45.413Z (4 days ago)
  • Versions: 17
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 2,349 Last month
  • Docker Downloads: 100
  • Rankings:
    • Dependent packages count: 8.74%
    • Average: 28.994%
    • Dependent repos count: 49.249%
  • Maintainers (1)

Dependencies

uv.lock pypi
  • 208 dependencies
Dockerfile docker
  • python 3.11-slim build
.github/workflows/benchmarks.yml actions
  • actions/checkout 34e114876b0b11c390a56381ad16ebd13914f8d5 composite
  • actions/setup-python a26af69be951a213d495a4c3e4e4022e16d87065 composite
  • actions/upload-artifact ea165f8d65b6e75b540449e92b4886f43607fa02 composite
  • astral-sh/setup-uv e58605a9b6da7c637471fab8847a5e5a6b8df081 composite
.github/workflows/release.yml actions
  • actions/checkout 34e114876b0b11c390a56381ad16ebd13914f8d5 composite
  • actions/setup-python a26af69be951a213d495a4c3e4e4022e16d87065 composite
  • actions/upload-artifact ea165f8d65b6e75b540449e92b4886f43607fa02 composite
  • astral-sh/setup-uv e58605a9b6da7c637471fab8847a5e5a6b8df081 composite
  • pypa/gh-action-pypi-publish ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e composite
.github/workflows/unit-tests-workflow.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v2 composite
pyproject.toml pypi
  • pytest * develop
  • toml 0.10.2 develop
  • cftime 1.6.2
  • dask 2022.2.0
  • h5netcdf 1.1.0
  • python >=3.8,<3.12
  • scipy 1.9.3
  • xarray 2023.1.0
docs/requirements.txt pypi
  • toml >=0.10.2

Score: 16.99029906293525