Update docs

bennyistanto · bennyistanto · commit c5bbfaf73f5b · 2026-01-28T13:42:32.000+07:00
diff --git a/README.md b/README.md
@@ -1,167 +1,25 @@
 # Precipitation Index - SPI & SPEI for Climate Extremes Monitoring
 
-> **⚠️ Active Development:** This package is under active development. Some features may not work as expected and bugs may be present. Please report issues on GitHub.
+**precip-index** is a lightweight set of Python scripts for calculating precipitation-based climate indices (SPI and SPEI) and analyzing **dry and wet extremes** using **run theory**, designed for gridded `xarray` workflows.  
 
-A minimal, efficient Python implementation of **Standardized Precipitation Index (SPI)** and **Standardized Precipitation Evapotranspiration Index (SPEI)** for monitoring **both drought and wet conditions** using run theory.
+📚 Documentation: https://bennyistanto.github.io/precip-index/
 
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
-[![License: BSD-3](https://img.shields.io/badge/License-BSD%203--Clause-green.svg)](https://opensource.org/licenses/BSD-3-Clause)
+## Key features
 
-## Features
+- **SPI / SPEI** at 1, 3, 6, 12, 24-month scales (xarray + CF-style NetCDF outputs)
+- **Bidirectional extremes**: drought (dry) and flood-prone (wet) conditions in one framework
+- **Multi-distribution fitting**: Gamma, Pearson Type III, Log-Logistic
+- **Run theory events**: duration, magnitude, intensity, peak, interarrival + gridded summaries
+- **Scalable processing**: chunked tiling, memory estimation, streaming I/O for global datasets
+- **Visualization**: event-highlighted time series, 11-category classification, maps, comparisons
 
-**Climate Indices:**
+## What makes precip-index different?
 
-- SPI (Standardized Precipitation Index) - precipitation-based
-- SPEI (Standardized Precipitation Evapotranspiration Index) - temperature-inclusive
-- Multiple time scales (1, 3, 6, 12, 24 months)
-- CF-compliant NetCDF output
-- **Monitor both dry (drought) and wet (flood/excess) conditions**
-
-**Climate Extremes Analysis (Run Theory):**
-
-- Event identification for **both drought and wet conditions**
-- Duration, magnitude, intensity, peak for any extreme
-- Time-series monitoring with varying characteristics
-- Period aggregation (gridded statistics for decision-making)
-- Comprehensive visualization suite
-- Works with negative thresholds (dry) or positive thresholds (wet)
-
-**Optimized for:**
-
-- Global-scale gridded data
-- CF Convention (time, lat, lon)
-- Operational climate monitoring (drought, flooding, extremes)
-
-## Getting Started
-
-**📖 See [QUICK_START.md](QUICK_START.md) for detailed installation and usage examples.**
-
-The Quick Start guide covers:
-
-- Installation and setup
-- Calculating SPI and SPEI
-- Analyzing climate extremes (both dry and wet)
-- Visualization examples
-- Working with your own data
-
-## Installation
-
-```bash
-# Install dependencies
-pip install numpy scipy xarray netCDF4 numba matplotlib
-
-# Clone repository
-git clone https://github.com/bennyistanto/precip-index.git
-cd precip-index
-```
-
-## Documentation
-
-**User Guides:**
-
-- [SPI Guide](docs/user-guide/spi.md) - Calculation, parameters, examples
-- [SPEI Guide](docs/user-guide/spei.md) - Temperature-inclusive index
-- [Climate Extremes Analysis](docs/user-guide/runtheory.md) - Event analysis (dry & wet)
-- [Magnitude Explained](docs/user-guide/magnitude.md) - Cumulative vs instantaneous
-- [Visualization Guide](docs/user-guide/visualization.md) - Plotting functions
-
-**Tutorials (Jupyter Notebooks):**
-
-- `notebooks/01_calculate_spi.ipynb` - SPI calculation
-- `notebooks/02_calculate_spei.ipynb` - SPEI with PET
-- `notebooks/03_event_characteristics.ipynb` - Climate extremes event analysis
-- `notebooks/04_visualization_gallery.ipynb` - All plot types
-
-**Technical Documentation:**
-
-- [Implementation Details](docs/technical/implementation.md) - Architecture and design
-- [CHANGELOG.md](CHANGELOG.md) - Version history
-
-## Key Capabilities
-
-### Neutral Climate Extremes Analysis
-
-All event analysis functions work for **both dry and wet conditions**:
-
-| Function | Dry Events (Drought) | Wet Events (Flooding) |
-| ---------- | ---------------------- | ---------------------- |
-| `identify_events()` | `threshold=-1.2` | `threshold=+1.2` |
-| `calculate_timeseries()` | Monitors dry periods | Monitors wet periods |
-| `calculate_period_statistics()` | SPI/SPEI < 0 | SPI/SPEI > 0 |
-| `plot_index()` | Full range with WMO colors | Both extremes |
-
-**The threshold direction determines which extreme to analyze** - the same tools work for both ends of the precipitation spectrum!
-
-![Run Theory Concept](./docs/images/runtheory.svg)
-
-**Run Theory Framework:** Events are identified when an index crosses a threshold. This example shows **dry events** (below threshold), but the identical analysis applies to **wet events** (above threshold). Key metrics—Duration (D), Magnitude (M), Intensity (I), and Inter-arrival Time (T)—are calculated the same way for both extremes.
-
-*See [Climate Extremes Analysis Guide](docs/user-guide/runtheory.md) for detailed explanation.*
-
-### Three Analysis Modes
-
-**1. Event-Based** - Identify complete extreme events
-
-```python
-events = identify_events(spi_ts, threshold=-1.2)
-# Returns: DataFrame with event_id, duration, magnitude, intensity, peak
-```
-
-**2. Time-Series** - Month-by-month monitoring
-
-```python
-ts = calculate_timeseries(spi_ts, threshold=-1.2)
-# Returns: DataFrame with varying characteristics over time
-```
-
-**3. Period Statistics** - Gridded decision support
-
-```python
-stats = calculate_period_statistics(spi, threshold=-1.2,
-                                    start_year=2020, end_year=2024)
-# Returns: xarray Dataset (lat, lon) with 9 variables
-```
-
-### Dual Magnitude Approach
-
-Provides **both** magnitude types for comprehensive analysis:
-
-- **Cumulative** - Total water deficit (standard run theory)
-- **Instantaneous** - Current severity (NDVI-like pattern)
-
-See [Magnitude Explained](docs/user-guide/magnitude.md) for details.
+- **Dry + wet symmetry**: same API and methodology for negative (drought) and positive (wet) thresholds
+- **Distribution-aware SPI/SPEI**: choose the best-fit distribution per workflow (Gamma / P-III / Log-Logistic)
+- **Event analytics included**: run theory metrics beyond simple threshold exceedance
+- **Designed for large grids**: practical for CHIRPS / ERA5-Land / TerraClimate via chunked processing
 
 ## Credits
 
-**Modified/adapted from:** [climate-indices](https://github.com/monocongo/climate_indices) by James Adams (monocongo)
-
-**Author:** Benny Istanto    
-**Organization:** GOST/DEC Data Group, The World Bank    
-**Email:** bistanto@worldbank.org    
-
-## References
-
-- McKee, T.B., Doesken, N.J., Kleist, J. (1993). The relationship of drought frequency and duration to time scales. 8th Conference on Applied Climatology.
-
-- 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.
-
-- Yevjevich, V. (1967). An objective approach to definitions and investigations of continental hydrologic droughts. Hydrology Papers 23, Colorado State University.
-
-## License
-
-BSD 3-Clause License - See [LICENSE](LICENSE) for details.
-
-## Contributing
-
-Contributions welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Submit a pull request
-
-For bugs or feature requests, open an issue on GitHub.
-
----
-
-**Version:** 2026.1
-**Last Updated:** 2026-01-21
+SPI/SPEI components are modified/adapted from `climate-indices` by James Adams ([monocongo](https://github.com/monocongo/climate_indices)).
diff --git a/docs/get-started/quick-start.qmd b/docs/get-started/quick-start.qmd
@@ -290,19 +290,22 @@ The same functions work for both drought (negative threshold) and wet events (po
 
 ### SPI/SPEI Classification
 
-| Value Range | Category | Probability | Interpretation |
-|-------------|----------|-------------|----------------|
-| ≤ -2.00 | Exceptionally Dry | Bottom 2.3% | Exceptional drought |
-| -2.00 to -1.50 | Extremely Dry | Bottom 6.7% | Severe drought |
-| -1.50 to -1.20 | Severely Dry | Bottom 9.7% | Severe drought |
-| -1.20 to -0.70 | Moderately Dry | Bottom 24.2% | Moderate drought |
-| -0.70 to -0.50 | Abnormally Dry | Bottom 30.9% | Below normal |
-| -0.50 to +0.50 | Near Normal | Middle 38.2% | Normal conditions |
-| +0.50 to +0.70 | Abnormally Moist | Top 30.9% | Above normal |
-| +0.70 to +1.20 | Moderately Moist | Top 24.2% | Moderately wet |
-| +1.20 to +1.50 | Very Moist | Top 9.7% | Very wet conditions |
-| +1.50 to +2.00 | Extremely Moist | Top 6.7% | Extremely wet conditions |
-| ≥ +2.00 | Exceptionally Moist | Top 2.3% | Extreme flooding risk |
+| Value Range | Category | Percentile band (approx.) | Interpretation |
+|-------------|----------|---------------------------|----------------|
+| ≤ -2.00 | Exceptionally Dry | 0–2.3% | Exceptional drought |
+| -2.00 to -1.50 | Extremely Dry | 2.3–6.7% | Severe drought |
+| -1.50 to -1.20 | Severely Dry | 6.7–11.5% | Severe drought |
+| -1.20 to -0.70 | Moderately Dry | 11.5–24.2% | Moderate drought |
+| -0.70 to -0.50 | Abnormally Dry | 24.2–30.9% | Below normal |
+| -0.50 to +0.50 | Near Normal | 30.9–69.1% | Normal conditions |
+| +0.50 to +0.70 | Abnormally Moist | 69.1–75.8% | Above normal |
+| +0.70 to +1.20 | Moderately Moist | 75.8–88.5% | Moderately wet |
+| +1.20 to +1.50 | Very Moist | 88.5–93.3% | Very wet conditions |
+| +1.50 to +2.00 | Extremely Moist | 93.3–97.7% | Extremely wet conditions |
+| ≥ +2.00 | Exceptionally Moist | 97.7–100% | Extreme flooding risk |
+
+> Percentile bands are approximate (standard normal) and provided for intuitive frequency interpretation.
+
 
 ### Time Scales
 
diff --git a/docs/index.qmd b/docs/index.qmd
@@ -239,9 +239,9 @@ Learn through interactive tutorials with real TerraClimate data.
 
 **Modified/adapted from:** [climate-indices](https://github.com/monocongo/climate_indices) by James Adams ([monocongo](https://github.com/monocongo/))
 
-**Author:** Benny Istanto
-**Organization:** GOST/DEC Data Group, The World Bank
-**Email:** bistanto@worldbank.org
+**Author:** Benny Istanto</br>
+**Organization:** GOST/DEC Data Group, The World Bank</br>
+**Email:** bistanto@worldbank.org</br>
 
 ## Citation
 
diff --git a/docs/technical/implementation.qmd b/docs/technical/implementation.qmd
@@ -12,22 +12,22 @@ precip-index/
 │   ├── chunked.py           # Memory-efficient chunked processing
 │   ├── config.py            # Configuration and constants
 │   ├── utils.py             # PET, data validation, memory utilities
-│   ├── runtheory.py         # Drought event analysis
+│   ├── runtheory.py         # Event analysis (dry & wet)
 │   ├── visualization.py     # Plotting functions
 │   └── __init__.py          # Package exports
 ├── input/                   # User data (not in repo)
 ├── output/                  # Generated results
 │   ├── netcdf/
 │   ├── csv/
 │   └── plots/
-└── notebooks/               # Tutorials
+└── notebook/               # Tutorials
 ```
 
 ## Core Modules
 
 ### 1. indices.py
 
-**Purpose:** Calculate SPI and SPEI drought indices
+**Purpose:** Calculate SPI and SPEI indices
 
 **Key Functions:**
 
diff --git a/docs/tutorials/01-calculate-spi.qmd b/docs/tutorials/01-calculate-spi.qmd
@@ -126,7 +126,7 @@ print(f"  Zero values: {int((precip == 0).sum())} ({100 * float((precip == 0).su
 ```
 
 ::: {.callout-note}
-## Data Format
+### Data Format
 
 The precipitation data is in NetCDF format with dimensions `(time, lat, lon)`. TerraClimate provides monthly precipitation in mm/month at ~4km resolution.
 :::
@@ -184,7 +184,7 @@ print(f"  NaN values: {int(np.isnan(spi_12).sum())} ({100 * float(np.isnan(spi_1
 ```
 
 ::: {.callout-tip}
-## Calibration Period
+### Calibration Period
 
 We use 1991-2020 as the calibration period (30 years) following WMO recommendations. This period is used to fit the probability distribution. NaN values come from two sources: (1) the first 11 months where SPI-12 cannot be calculated, and (2) ocean grid cells with no data.
 :::
@@ -289,7 +289,7 @@ print("  Results are identical!" if max_diff < 1e-6 else "  Warning: Results dif
 ```
 
 ::: {.callout-tip}
-## Performance Benefits
+### Performance Benefits
 
 Using saved parameters is **5-10x faster** than refitting, ideal for operational monitoring where you update with new data regularly.
 :::
@@ -364,7 +364,7 @@ print("  - Extreme events persist longer at longer time scales")
 ```
 
 ::: {.callout-important}
-## Time Scale Interpretation
+### Time Scale Interpretation
 
 - **SPI-1:** Month-to-month meteorological anomalies
 - **SPI-3:** Seasonal agricultural drought
diff --git a/docs/tutorials/02-calculate-spei.qmd b/docs/tutorials/02-calculate-spei.qmd
@@ -138,7 +138,7 @@ print(f"  Output directory: {output_netcdf}")
 ```
 
 ::: {.callout-note}
-## PET Calculation Methods
+### PET Calculation Methods
 
 The `spei()` function accepts either:
 
@@ -284,7 +284,7 @@ else:
 When using temperature, the trend line shows how temperatures have changed over the record. Warming trends increase PET, which affects the water balance and makes SPEI more negative relative to SPI.
 
 ::: {.callout-tip}
-## Distribution Selection for SPEI
+### Distribution Selection for SPEI
 
 By default, SPEI uses the **Gamma** distribution. For SPEI, the **Pearson III** or **Log-Logistic** distributions are also available and may better handle the water balance data (P - PET), which can be negative:
 
@@ -464,7 +464,7 @@ print(f"  Difference: {spei_drought - spi_drought} months ({100*(spei_drought -
 ```
 
 ::: {.callout-important}
-## SPI vs SPEI: Key Differences
+### SPI vs SPEI: Key Differences
 
 **SPI (Precipitation only):**
 
@@ -571,7 +571,7 @@ print("  - Extreme events persist longer at longer time scales")
 ```
 
 ::: {.callout-note}
-## Time Scale Interpretation
+### Time Scale Interpretation
 
 - **SPEI-1:** Month-to-month meteorological anomalies
 - **SPEI-3:** Seasonal agricultural drought --- crop water stress
diff --git a/docs/tutorials/03-event-analysis.qmd b/docs/tutorials/03-event-analysis.qmd
@@ -191,7 +191,7 @@ print(events_dry[['start_date', 'end_date', 'duration', 'magnitude', 'intensity'
 ```
 
 ::: {.callout-note}
-## Threshold Selection
+### Threshold Selection
 
 Common thresholds for SPI/SPEI event analysis:
 
@@ -312,7 +312,7 @@ plt.show()
 ```
 
 ::: {.callout-important}
-## Bidirectional Analysis
+### Bidirectional Analysis
 
 The same functions work for both extremes:
 
diff --git a/docs/tutorials/04-visualization.qmd b/docs/tutorials/04-visualization.qmd
@@ -207,7 +207,7 @@ plt.show()
 Each annotation shows the duration (D) of the event in months, positioned at the event peak. Longer durations indicate more persistent drought conditions.
 
 ::: {.callout-tip}
-## Event Highlighting
+### Event Highlighting
 
 Events are highlighted with:
 
@@ -374,7 +374,7 @@ else:
 ```
 
 ::: {.callout-note}
-## Magnitude Types
+### Magnitude Types
 
 - **Cumulative**: Total deficit, monotonically increases during event --- like debt accumulation. Use for event comparison and total impact assessment.
 - **Instantaneous**: Current severity, varies within event --- like NDVI crop phenology. Use for monitoring evolution and trend detection.
@@ -614,7 +614,7 @@ print("Reset to default settings")
 ```
 
 ::: {.callout-tip}
-## Export Best Practices
+### Export Best Practices
 
 - **DPI**: 300 for publications, 150 for presentations, 72 for web
 - **Format**: PNG for raster, PDF/SVG for vector graphics
diff --git a/docs/user-guide/spi.qmd b/docs/user-guide/spi.qmd
diff --git a/index.md b/index.md
diff --git a/src/chunked.py b/src/chunked.py
