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: 23 minutes 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.

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: 1 day ago

Total Commits: 1,004
Total Committers: 20
Avg Commits per committer: 50.2
Development Distribution Score (DDS): 0.352

Commits in past year: 24
Committers in past year: 2
Avg Commits per committer in past year: 12.0
Development Distribution Score (DDS) in past year: 0.042

Name Email Commits
James Adams m****o@g****m 651
James.Adams J****s@C****l 213
james.adams j****s@o****m 60
james.a j****a@c****m 25
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
dependabot[bot] 4****] 3
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: 1 day ago

Total issues: 322
Total pull requests: 252
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: 0.94
Merged pull request: 224
Bot issues: 0
Bot pull requests: 3

Past year issues: 11
Past year pull requests: 3
Past year average time to close issues: about 8 hours
Past year average time to close pull requests: 27 minutes
Past year issue authors: 10
Past year pull request authors: 1
Past year average comments per issue: 0.73
Past year average comments per pull request: 1.0
Past year merged pull request: 2
Past year bot issues: 0
Past year bot pull requests: 0

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

Top Issue Authors

  • monocongo (164)
  • crestedcaracaryn (6)
  • kikocorreoso (5)
  • bennyistanto (5)
  • aleccourt (4)
  • SouhailAB (4)
  • WeatherGod (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 (216)
  • WeatherGod (10)
  • Seven-milk (7)
  • kikocorreoso (3)
  • dependabot[bot] (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 (4)
  • 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/
  • Licenses: BSD License
  • Latest release: 2.2.0 (published 5 months ago)
  • Last Synced: 2025-12-18T18:06:32.803Z (7 days ago)
  • Versions: 16
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 3,531 Last month
  • Docker Downloads: 100
  • Rankings:
    • Dependent packages count: 8.74%
    • Average: 28.994%
    • Dependent repos count: 49.249%
  • Maintainers (1)

Dependencies

.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: 17.396081822963115