Technical Documentation

Methodology, Implementation, and API Reference

Overview

Technical documentation for the precip-index package, including detailed methodology, implementation details, and complete API reference. If you’re validating inputs/outputs (rather than the math), start with Data Model & Outputs before Methodology.

Contents

Methodology

Scientific background and mathematical foundations:

  • SPI Calculation
    • Gamma distribution fitting
    • Standardization process
    • Calibration period selection
  • SPEI Calculation
    • Water balance approach
    • PET estimation methods
    • Distribution fitting
  • Run Theory Framework
    • Threshold theory
    • Event identification
    • Magnitude types (cumulative vs instantaneous)

Implementation

Technical details and design decisions:

  • Architecture
    • Module structure
    • Data flow
    • Performance optimizations
  • Core Components
    • Distribution fitting with SciPy
    • Numba acceleration
    • CF Convention compliance
  • Quality Assurance
    • Input validation
    • Error handling
    • Test coverage

API Reference

Complete function documentation:

  • indices.py - SPI and SPEI calculation
  • runtheory.py - Event analysis
  • visualization.py - Plotting functions
  • utils.py - Utility functions

Probability Distributions

Distribution selection and fitting:

  • Supported Distributions - Gamma, Pearson III, Log-Logistic, GEV, Generalized Logistic
  • Selection Guide - When to use each distribution
  • Mathematical Background - PDFs, CDFs, parameter estimation
  • Zero-Inflation Handling - Mixed distribution approach

Validation & Test Results

Quality assurance and verification:

  • Distribution Comparison - SPI/SPEI across distributions
  • Spatial Validation - Maps and difference analysis
  • Event Analysis Tests - Run theory verification
  • Test Suite Results - Comprehensive test coverage

For Developers

If you’re contributing to the package or want to understand the internals:

  1. Start with Methodology - Understand the science
  2. Review Implementation - Learn the architecture
  3. Explore Distributions - Distribution fitting details
  4. Reference API docs - Function signatures and parameters
  5. Check Validation - Test results and quality verification

For Researchers

If you’re citing the package or validating results:

Key References

SPI

  • McKee, T.B., Doesken, N.J., Kleist, J. (1993). The relationship of drought frequency and duration to time scales. Proceedings of the 8th Conference on Applied Climatology, 17(22), 179-183.

SPEI

  • Vicente-Serrano, S.M., Beguería, S., López-Moreno, J.I. (2010). A multiscalar drought index sensitive to global warming: the standardized precipitation evapotranspiration index. Journal of Climate, 23(7), 1696-1718.

Run Theory

  • Yevjevich, V. (1967). An objective approach to definitions and investigations of continental hydrologic droughts. Hydrology Papers 23, Colorado State University.

Support

For technical questions:

Back to top