Skip to content

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

1.0.0 - 2026-05-25

First public release, accompanying the methodology paper submitted to Water Resources Research (Tsilimigkras, 2026).

Added

  • rsd.standardize - 1-D entry point for three standardisation methods that share a common interface: the hybrid empirical/parametric RSD method, a monthwise ECDF baseline, and a monthwise parametric baseline.
  • rsd.standardize_xr - xarray/dask wrapper for N-D spatial computation; parallelises across pixels per chunk.
  • rsd.diagnose - one-call diagnostics that verify the exchangeability assumption underlying RSD pooling and compare baseline vs bounded vs auto-bound pathways side by side.
  • rsd.estimate_bounds - heuristic percentile-based bounds estimator for bounded variables, paired with explicit warnings about its non-physical nature.
  • bounds= parameter on the RSD path for bounded variables (e.g. soil moisture); the logit pre-transform is applied before accumulation so both agg="sum" and agg="mean" work consistently.
  • Custom warning categories rsd.RSDFitWarning and rsd.RSDDegenerateWarning so users can filter or escalate them with warnings.filterwarnings.

Design choices

  • Public API uses positional-or-keyword arguments for the data inputs and keyword-only arguments for all configuration parameters, preventing silent positional mix-ups.
  • Internal pipeline runs in float64; outputs are cast to float32 at the storage boundary for memory efficiency.
  • Public API rejects out-of-range parameters at the function boundary (months outside [1, 12], tail_quantile outside (0, 0.20], min_tail_size < 10, references too short for the requested tail fit).
  • The monthwise parametric path uses the canonical Stagge SPI convention (floc=0) by default for distributions with non-negative support.

Documentation

  • Quick-start examples for both 1-D and N-D usage in README.md.
  • API reference and method overview at hydro-rsd.readthedocs.io.
  • Runnable example notebooks under examples/.

Notes

  • Companion paper: Tsilimigkras, A., Grillakis, M., & Koutroulis, A. (2026). A reference-based standardization framework for hydroclimate drought indices under distribution shift. Manuscript submitted to Water Resources Research. DOI pending acceptance.