Update docs

Author: bennyistanto

docs/_quarto.yml

@@ -28,6 +28,8 @@ website:
             href: get-started/quick-start.qmd
           - text: "Configuration"
             href: get-started/configuration.qmd
+          - text: "Data Model & Outputs"
+            href: get-started/data-model.qmd
           - text: "Examples"
             href: get-started/examples.qmd
       - text: "Tutorials"
@@ -62,6 +64,7 @@ website:
         - get-started/installation.qmd
         - get-started/quick-start.qmd
         - get-started/configuration.qmd
+        - get-started/data-model.qmd
         - get-started/examples.qmd
 
     - title: "Tutorials"
@@ -90,6 +93,7 @@ website:
         - technical/index.qmd
         - text: "---"
         - technical/methodology.qmd
+        - technical/distributions.qmd
         - technical/implementation.qmd
         - technical/api-reference.qmd
         - text: "---"

docs/changelog.qmd

@@ -5,172 +5,66 @@ subtitle: "Version History and Updates"
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Calendar Versioning](https://calver.org/) (YYYY.M).
+This project adheres to [Calendar Versioning](https://calver.org/) (YYYY.M).
 
 ---
 
-## [2026.1.2] - 2026-01-27
-
-### Pluggable Probability Distributions
-
-Added support for multiple probability distributions across the entire SPI/SPEI pipeline. Default behavior (Gamma) is fully backward compatible.
-
-**New Module: `distributions.py`**
-
-- Unified API: `fit_distribution()`, `compute_cdf()`, `cdf_to_standard_normal()`
-- Five distributions: Gamma, Pearson III, Log-Logistic, GEV, Generalized Logistic
-- L-moments, Method of Moments, and MLE fitting with automatic fallback chains
-- Data diagnostics: `diagnose_data()`, `diagnose_fitting_failure()`
-- Goodness-of-fit testing and distribution comparison/selection
-- Robust parameter bounding and zero-inflation handling
-
-**Updated: `config.py`**
-
-- Distribution-aware variable naming: `spi_{distribution}_{scale}_{periodicity}`
-- `DISTRIBUTION_PARAM_NAMES` mapping for all five distribution types
-
-**Updated: `utils.py`**
-
-- Updated `get_variable_name()`, `get_variable_attributes()`, `get_fitting_param_name()`, `get_fitting_param_attributes()` with `distribution` parameter
-
-**Updated: `compute.py`**
-
-- `compute_index_parallel()` — `distribution` parameter with Gamma fast path and generic path
-- `_compute_params_generic()` — Generic parameter fitting via `distributions.py`
-- `_transform_to_normal_generic()` — Generic CDF-to-normal transformation
-- `compute_spi_1d()`, `compute_spei_1d()` — Distribution routing
-- `compute_index_dask()`, `compute_index_dask_to_zarr()` — Distribution pass-through
-
-**Updated: `indices.py`**
-
-- `spi()`, `spei()` — `distribution` parameter (default: `'gamma'`)
-- `spi_multi_scale()`, `spei_multi_scale()` — `distribution` parameter
-- `spi_global()`, `spei_global()` — `distribution` parameter
-- `save_fitting_params()` — Generic distribution-aware parameter storage
-- `load_fitting_params()` — Auto-detects distribution type from file attributes
-
-**Updated: `chunked.py`**
-
-- `compute_spi_chunked()`, `compute_spei_chunked()` — `distribution` parameter
-- Generic parameter array collection using `DISTRIBUTION_PARAM_NAMES`
-- `compute_spi_global()`, `compute_spei_global()` — `distribution` parameter
-
-**New Documentation**
-
-- [Probability Distributions](technical/distributions.qmd) — Distribution selection guide, mathematical background, usage examples
-
-### Configurable Metadata Attributes
-
-Added centralized, user-configurable metadata for all NetCDF output files. Institution, source, and other global attributes are no longer hardcoded.
-
-**New in `config.py`**
-
-- `DEFAULT_METADATA` — Module-level dict for default NetCDF global attributes (institution, source, references, etc.)
-- `get_global_attributes()` — Helper that merges defaults, computed attributes, and user overrides
-
-**Updated: `indices.py`**
-
-- `spi_multi_scale()`, `spei_multi_scale()` — `global_attrs` parameter for per-call metadata override
-- `spi_global()`, `spei_global()` — `global_attrs` parameter
-- `save_fitting_params()` — Now uses centralized metadata defaults (existing `global_attrs` parameter preserved)
-
-**Updated: `chunked.py`**
-
-- `compute_spi_chunked()`, `compute_spei_chunked()` — `distribution` and `global_attrs` parameters
-- `compute_spi_global()`, `compute_spei_global()` — `distribution` and `global_attrs` parameters
-
-**Updated: Notebook 05**
-
-- Configurable `BASE_DIR` for input/output paths — supports both Windows and WSL/Linux paths
-- Auto-detection of repository root and `src` directory
-- All example paths use configurable directory variables
-
-### Centralized Configuration Hub
-
-Refactored `config.py` as the single source of truth for all user-configurable settings. Helper functions moved to `utils.py`.
-
-**New in `config.py`**
-
-- `DISTRIBUTION_DISPLAY_NAMES` — Human-readable names for all five distributions
-- `PRECIP_VAR_PATTERNS` — Auto-detection patterns for precipitation variables in NetCDF
-- `PET_VAR_PATTERNS` — Auto-detection patterns for PET variables
-- `TEMP_VAR_PATTERNS` — Auto-detection patterns for temperature variables
-- `SPEI_WATER_BALANCE_OFFSET` — Configurable offset for SPEI water balance (default: 1000.0)
-- `__version__` — Package version string (moved from `__init__.py`)
-
-**Moved from `config.py` to `utils.py`**
-
-- `get_logger()`, `get_variable_name()`, `get_fitting_param_name()`, `get_long_name()`, `get_variable_attributes()`, `get_fitting_param_attributes()`, `get_global_attributes()` — all helper functions now in `utils.py`
-
-**Updated: All source modules**
-
-- Import paths updated across `compute.py`, `indices.py`, `chunked.py`, `visualization.py`, `runtheory.py`, `__init__.py`
-- Replaced duplicated `dist_display` dicts with `DISTRIBUTION_DISPLAY_NAMES` from config
-- Replaced inline variable detection patterns with configurable constants
-- Replaced hardcoded `1000.0` water balance offset with `SPEI_WATER_BALANCE_OFFSET`
-
-**New Documentation**
-
-- [Configuration Reference](get-started/configuration.qmd) — Complete guide to all configurable settings
-
----
-
-## [2026.1] - 2026-01-21
+## [2026.1] - January 2026
 
 ### Initial Release
 
-First public release of the precip-index package - a streamlined implementation of SPI and SPEI for climate extremes monitoring.
+First public release of the precip-index package — a streamlined Python implementation for calculating SPI and SPEI climate indices with comprehensive event analysis capabilities.
 
-**Modified/adapted from:** [climate-indices](https://github.com/monocongo/climate_indices) by James Adams (monocongo)
+### Core Features
 
-### Features
+**Climate Indices**
 
-**Climate Indices:**
-- SPI (Standardized Precipitation Index) calculation using Gamma distribution
-- SPEI (Standardized Precipitation Evapotranspiration Index) with Thornthwaite PET
-- Multi-scale support (1, 3, 6, 12, 24 months)
-- Parameter save/load functionality for faster recomputation
-- CF-compliant NetCDF output
+- SPI (Standardized Precipitation Index) and SPEI (Standardized Precipitation Evapotranspiration Index)
+- Multi-scale support: 1, 3, 6, 12, 24 months
+- Five probability distributions: Gamma, Pearson III, Log-Logistic, GEV, Generalized Logistic
+- Automatic PET calculation from temperature (Thornthwaite method)
+- Parameter save/load for operational workflows
+- CF-compliant NetCDF output with customizable metadata
 
-**Climate Extremes Analysis (Run Theory):**
-- Event identification for both drought (dry) and wet conditions
-- Time-series monitoring with dual magnitude (cumulative & instantaneous)
+**Run Theory Analysis**
+
+- Event identification for both dry (drought) and wet (flood) conditions
+- Dual magnitude tracking: cumulative and instantaneous
 - Gridded period statistics for decision support
-- Event characteristics: duration, magnitude, intensity, peak
-- Spatial aggregation and period comparison tools
+- Event characteristics: duration, magnitude, intensity, peak, inter-arrival
+
+**Visualization**
 
-**Visualization:**
-- WMO standard 11-category SPI/SPEI color classification
-- Event plots with automatic dry/wet differentiation
-- Timeline visualizations with multiple characteristics
+- WMO standard 11-category classification
+- Time series plots with event highlighting
 - Spatial statistics maps
+- Cross-distribution comparison charts
 
-### Technical Details
+### Technical Highlights
 
-- Optimized for global-scale gridded data
-- NumPy vectorization + Numba JIT compilation
-- CF Convention compliance (time, lat, lon)
-- Gamma distribution only (robust for arid regions)
-- Python 3.8+ support
+- Modular architecture: `indices.py`, `runtheory.py`, `distributions.py`, `visualization.py`
+- Centralized configuration via `config.py`
+- Memory-efficient chunked processing for global-scale data
+- NumPy vectorization with Numba JIT compilation
+- Robust fitting with automatic fallback chains (L-moments → Method of Moments → MLE)
+- Data diagnostics and goodness-of-fit testing
 
 ### Documentation
 
-- Comprehensive user guides for SPI, SPEI, and run theory
-- Jupyter notebook tutorials
-- Technical implementation documentation
-- Quick start guide
+- Comprehensive user guides for SPI, SPEI, run theory, and magnitude concepts
+- Technical documentation: methodology, distributions, implementation, API reference
+- Interactive Jupyter notebook tutorials
+- Quick start guide and configuration reference
 
 ---
 
 ## Future Releases
 
-Version 2026.2 and beyond will include:
 - Bug fixes and performance improvements
 - Additional test coverage
 - Enhanced documentation and examples
 - Community-requested features
 
 ---
 
-**For detailed technical implementation notes, see [Technical Documentation](technical/implementation.qmd)**
+**For detailed technical notes, see [Implementation Details](technical/implementation.qmd)**

docs/get-started/configuration.qmd

@@ -224,3 +224,12 @@ All configurable constants in `config.py`:
 | `DEFAULT_CHUNK_LON` | `500` | Chunked processing |
 | `MEMORY_MULTIPLIER` | `12.0` | Memory estimation |
 | `MEMORY_SAFETY_FACTOR` | `0.7` | Memory estimation |
+
+---
+
+## See Also
+
+- [Installation](installation.qmd) - Setup and dependencies
+- [Quick Start](quick-start.qmd) - First SPI/SPEI calculation
+- [Data Model & Outputs](data-model.qmd) - Input/output contracts
+- [Examples](examples.qmd) - Common use cases and code snippets