Banner Image

climate_indices

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