rsd 1.0.0__py3-none-any.whl

rsd/README.md

@@ -0,0 +1,156 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/thchilly/rsd/main/assets/rsd_logo_banner.png" alt="rsd - Reference-based standardization framework for drought indices under distribution shift" width="100%">
+</p>
+
+# rsd
+
+*Standardized drought indices (SPI, SSI, SDI, SPEI) that are **comparable** across model runs, scenarios, and reanalysis products.*
+
+Full documentation: <https://hydro-rsd.readthedocs.io>
+
+`rsd` computes standardized hydroclimate indices by fitting the CDF from a
+fixed reference dataset rather than from the target itself, so that values
+from different model runs, scenarios, or observational products can be
+compared on the same scale.
+
+## Why RSD?
+
+Standard implementations of SPI/SSI standardize each series against itself,
+which removes the cross-series differences you want to measure. RSD solves
+three interdependent problems:
+
+1. **Fixed reference** - fit the CDF once from a reference period or
+   dataset; evaluate target values against it.
+2. **GPD tail extension** - empirical CDFs cap at the observed range. RSD
+   fits Generalized Pareto Distribution tails for smooth extrapolation
+   beyond the reference sample.
+3. **Pooled deseasonalization** - per-month samples are too sparse to
+   fit EVT tails. A 50-year record gives ~50 values per calendar month;
+   the top/bottom 10% (the tail) is only ~5 exceedances per month - too
+   few for a stable GPD fit. RSD removes the per-month location and
+   scale, then pools all 12 months into one sample (~600 values, ~60
+   exceedances per tail) where the fit becomes feasible.
+
+This pooling is what keeps RSD usable on short records. With 20 years
+of monthly data (typical for satellite-era datasets) the pooled tail
+still has ~24 exceedances - enough to fit a single GPD - while a
+per-month tail fit would have only ~2 exceedances per month per tail
+and is infeasible.
+
+Monthwise ECDF and fully parametric (e.g. gamma) methods are also included
+as baselines.
+
+## Requirements
+
+- Python ≥ 3.10
+- NumPy ≥ 1.24
+- SciPy ≥ 1.10
+
+Optional extras:
+
+- `[xarray]` - xarray ≥ 2023.1, dask ≥ 2023.1 (N-D + parallel computation)
+- `[diagnostics]` - matplotlib ≥ 3.7 (`rsd.diagnose` plots)
+
+## Installation
+
+```bash
+pip install rsd                  # NumPy/SciPy only
+pip install rsd[xarray]          # adds xarray + dask support
+pip install rsd[diagnostics]     # adds matplotlib for rsd.diagnose
+pip install rsd[all]             # everything above
+```
+
+## Quick start
+
+In RSD vocabulary, the **reference** defines what "normal" looks like (e.g.
+observed climate over a baseline period) and the **target** is the series
+you want to score against that normal (e.g. a future projection or a
+different scenario). Output `z` is in standard-normal units: `z ≈ 0` is
+climatology and `|z| > 2` is extreme.
+
+```python
+import numpy as np
+import rsd
+
+# 1-D: standardize a 1200-month target against a 600-month reference
+rng = np.random.default_rng(0)
+months_ref = np.tile(np.arange(1, 13), 50)    # 600 months
+months_tgt = np.tile(np.arange(1, 13), 100)   # 1200 months
+ref = rng.gamma(shape=2, scale=5, size=600)
+tgt = rng.gamma(shape=2, scale=5, size=1200)
+
+z = rsd.standardize(
+    target=tgt,
+    reference=ref,
+    months_target=months_tgt,
+    months_reference=months_ref,
+    scale=3,                                   # 3-month accumulation (e.g. SPI-3)
+)
+```
+
+```python
+# N-D: xarray wrapper (dask-parallelized for large grids).
+# Months are extracted automatically from the time coordinate, so you do
+# not pass months_target / months_reference here.
+import rsd
+
+z = rsd.standardize_xr(
+    target=target_da,        # xr.DataArray with a "time" dimension
+    reference=ref_da,        # xr.DataArray with a "time" dimension
+    method="rsd",            # or "monthwise_ecdf" / "monthwise_parametric"
+    scale=3,
+    parallel=True,
+)
+```
+
+### Diagnostics
+
+`rsd.diagnose(values, months, name, ...)` is the one-call entry point
+that verifies the exchangeability assumption underlying RSD pooling. It
+prints an overview block (configuration plus extracted seasonal location
+and scale), renders a combined summary figure (before / after
+deseasonalization KDEs), and prints an Anderson-Darling omnibus plus
+per-month Kolmogorov-Smirnov leave-one-out report. Pass `bounds=(L, U)`
+to add a logit-bounded pathway alongside the baseline; add
+`auto_bounds=True` to also see a heuristic data-driven bound via
+`rsd.estimate_bounds`. Use `quiet=True` for batch / CI runs. See the
+`diagnostics_showcase.ipynb` notebook for a worked example.
+
+## Methods
+
+| method | description |
+|--------|-------------|
+| `"rsd"` | Deseasonalize -> pool -> ECDF core + GPD tails |
+| `"monthwise_ecdf"` | Per-month empirical CDF (classical SPI-style) |
+| `"monthwise_parametric"` | Per-month parametric fit (gamma, norm, …) |
+
+The `monthwise_ecdf` baseline matches the SDAT framework of
+[Farahmand & AghaKouchak (2015)](https://doi.org/10.1016/j.advwatres.2014.11.012).
+The `monthwise_parametric` path defaults to `floc=0` (the canonical SPI
+convention of [Stagge et al. (2015)](https://doi.org/10.1002/joc.4267));
+pass `floc=None` to recover scipy's free-location 3-parameter fit.
+
+## Contributing & issues
+
+Bug reports and questions are welcome at
+<https://github.com/thchilly/rsd/issues>. Contributions follow the workflow
+in [CONTRIBUTING.md](https://github.com/thchilly/rsd/blob/main/CONTRIBUTING.md).
+
+## How to cite
+
+If you use this package in your research, please cite the methodology 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.
+
+For reproducibility, you may additionally cite the specific software version:
+
+> Tsilimigkras, A. (2026). *rsd*: Reference-based standardization
+> framework for hydroclimate drought indices (Version 1.0.0)
+> [Computer software]. Zenodo DOI: pending.
+
+## License
+
+BSD 3-Clause

rsd/__init__.py

@@ -0,0 +1,57 @@
+"""RSD: Reference-based standardization framework for hydroclimate drought indices.
+
+A hybrid empirical-parametric standardized-index framework with a fixed
+reference distribution. Provides :func:`standardize` for 1-D series and
+:func:`standardize_xr` for N-D xarray DataArrays (with dask parallelism).
+
+All public-API outputs are float32 standardized z-scores; internal
+computations run in float64 throughout the pipeline and are cast to
+float32 only at the final storage boundary.
+
+Custom warning categories (:class:`RSDFitWarning`,
+:class:`RSDDegenerateWarning`) signal tail-fit fallbacks and degenerate
+reference months. Filter them with the standard
+``warnings.filterwarnings`` machinery if needed.
+"""
+
+from rsd._version import __version__
+from rsd._warnings import RSDDegenerateWarning, RSDFitWarning
+from rsd.core import standardize
+from rsd.defaults import METHODS
+from rsd.transform import logit_transform, inverse_logit_transform
+
+
+def __getattr__(name: str):
+    """Lazy import for optional-dependency modules."""
+    if name == "standardize_xr":
+        from rsd.xarray import standardize_xr
+
+        return standardize_xr
+    if name == "diagnostics":
+        from importlib import import_module
+
+        return import_module("rsd.diagnostics")
+    if name == "diagnose":
+        from rsd.diagnostics import diagnose
+
+        return diagnose
+    if name == "estimate_bounds":
+        from rsd.diagnostics import estimate_bounds
+
+        return estimate_bounds
+    raise AttributeError(f"module 'rsd' has no attribute {name!r}")
+
+
+__all__ = [
+    "standardize",
+    "standardize_xr",
+    "METHODS",
+    "__version__",
+    "logit_transform",
+    "inverse_logit_transform",
+    "RSDFitWarning",
+    "RSDDegenerateWarning",
+    "diagnostics",
+    "diagnose",
+    "estimate_bounds",
+]

rsd/_kernels.py

@@ -0,0 +1,230 @@
+"""Pure-NumPy 1-D kernels for each standardization method.
+
+Each kernel operates on pre-accumulated 1-D arrays and returns
+float32 z-scores. These are the inner loops called by core.py
+(for 1-D inputs) and xarray.py (for N-D inputs via apply_ufunc).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from rsd.defaults import (
+    DEFAULT_LOC,
+    DEFAULT_MIN_TAIL_SIZE,
+    DEFAULT_PLOTTING_POSITION,
+    DEFAULT_SCALE_METHOD,
+    DEFAULT_TAIL_QUANTILE,
+    DEFAULT_DISTRIBUTION,
+    MIN_REF_SIZE,
+)
+from rsd.deseasonalize import compute_seasonal_params, deseasonalize
+from rsd.ecdf import ecdf_probs
+from rsd.parametric import fit_monthwise, monthwise_cdf
+from rsd.tails import fit_gpd_tails, hybrid_cdf
+from rsd.transform import cdf_to_zscore
+
+
+def kernel_rsd_1d(
+    tgt_accum: np.ndarray,
+    ref_accum: np.ndarray,
+    months_tgt: np.ndarray,
+    months_ref: np.ndarray,
+    tail_quantile: float = DEFAULT_TAIL_QUANTILE,
+    min_tail_size: int = DEFAULT_MIN_TAIL_SIZE,
+    loc: str = DEFAULT_LOC,
+    scale_method: str = DEFAULT_SCALE_METHOD,
+    plotting_position: str | tuple[float, float] = DEFAULT_PLOTTING_POSITION,
+) -> np.ndarray:
+    """RSD hybrid method: deseasonalize → pool → ECDF core + GPD tails → z-score.
+
+    Parameters
+    ----------
+    tgt_accum : 1-D float array
+        Accumulated target values. For bounded variables, these are expected
+        to be already logit-transformed by the caller (see :func:`rsd.standardize`).
+    ref_accum : 1-D float array
+        Accumulated reference values, in the same space as *tgt_accum*.
+    months_tgt : 1-D int array
+        Calendar months (1-12) for target.
+    months_ref : 1-D int array
+        Calendar months (1-12) for reference.
+    tail_quantile : float
+        Fraction of the pooled reference assigned to each tail (default
+        0.10). See :func:`rsd.standardize` for the validation rules and
+        the cross-validation against reference length.
+    min_tail_size : int
+        Minimum number of exceedances required for the GPD fit; below
+        this the affected tail falls back to ECDF-only with an
+        ``RSDFitWarning`` (default 20). See :func:`rsd.standardize`.
+    loc : {"median", "mean"}
+        Location estimator used by deseasonalization (default "median").
+    scale_method : {"iqr", "std"}
+        Scale estimator used by deseasonalization (default "iqr").
+    plotting_position : str or (float, float)
+        Plotting position formula for the ECDF core. Accepts a known
+        name from :data:`rsd.defaults.PLOTTING_POSITIONS` or an (a, b)
+        2-tuple (default "gringorten").
+
+    Returns
+    -------
+    np.ndarray (float32)
+        Standardized z-scores. Same length as *tgt_accum*. Internal
+        computations run in float64; the output is cast to float32 for
+        memory efficiency at the storage boundary.
+
+    Notes
+    -----
+    The kernel operates on already-accumulated values. For bounded variables,
+    the logit pre-transform is applied at the public-API layer
+    (:func:`rsd.standardize` / :func:`rsd.standardize_xr`) before accumulation,
+    so by the time data reaches this kernel the values are already in
+    unbounded logit space.
+    """
+    out = np.full(len(tgt_accum), np.nan, dtype=np.float32)
+
+    # Early bailout
+    valid_ref = np.isfinite(ref_accum).sum()
+    valid_tgt = np.isfinite(tgt_accum).sum()
+    if valid_ref < MIN_REF_SIZE or valid_tgt == 0:
+        return out
+
+    # Step 1: Deseasonalize
+    params = compute_seasonal_params(
+        ref_accum, months_ref, loc=loc, scale_method=scale_method
+    )
+    z_ref = deseasonalize(ref_accum, months_ref, params)
+    z_tgt = deseasonalize(tgt_accum, months_tgt, params)
+
+    # Step 2: Pool reference (finite values only)
+    z_ref_clean = z_ref[np.isfinite(z_ref)]
+    if len(z_ref_clean) < MIN_REF_SIZE:
+        return out
+    sorted_ref = np.sort(z_ref_clean)
+
+    # Step 3: Fit GPD to the lower and upper tails of the pooled reference
+    lower_tail, upper_tail = fit_gpd_tails(
+        sorted_ref,
+        tail_quantile=tail_quantile,
+        min_tail_size=min_tail_size,
+        plotting_position=plotting_position,
+    )
+
+    # Step 4: Hybrid CDF
+    p = hybrid_cdf(
+        z_tgt, sorted_ref, lower_tail, upper_tail, plotting_position=plotting_position
+    )
+
+    # Step 5: Transform to z-scores
+    out = cdf_to_zscore(p)
+    return out
+
+
+def kernel_monthwise_ecdf_1d(
+    tgt_accum: np.ndarray,
+    ref_accum: np.ndarray,
+    months_tgt: np.ndarray,
+    months_ref: np.ndarray,
+    plotting_position: str | tuple[float, float] = DEFAULT_PLOTTING_POSITION,
+) -> np.ndarray:
+    """Classical monthwise ECDF: per-month empirical CDF → z-score.
+
+    For each calendar month, build a separate ECDF from the reference
+    values for that month and evaluate target values against it.
+
+    Parameters
+    ----------
+    tgt_accum : 1-D float array
+        Accumulated target values.
+    ref_accum : 1-D float array
+        Accumulated reference values.
+    months_tgt : 1-D int array
+        Calendar months (1-12) for target.
+    months_ref : 1-D int array
+        Calendar months (1-12) for reference.
+    plotting_position : str or (float, float)
+        Plotting position formula passed to the per-month ECDF
+        (default "gringorten"). Accepts a known name from
+        :data:`rsd.defaults.PLOTTING_POSITIONS` or an (a, b) 2-tuple.
+
+    Returns
+    -------
+    np.ndarray (float32)
+        Standardized z-scores. Same length as *tgt_accum*. Internal
+        computations run in float64; the output is cast to float32 for
+        memory efficiency at the storage boundary.
+    """
+    p = np.full(len(tgt_accum), np.nan, dtype=np.float64)
+
+    for m in range(1, 13):
+        ref_mask = months_ref == m
+        tgt_mask = months_tgt == m
+
+        ref_vals = ref_accum[ref_mask]
+        ref_vals = ref_vals[np.isfinite(ref_vals)]
+
+        if len(ref_vals) == 0 or not tgt_mask.any():
+            continue
+
+        sorted_ref = np.sort(ref_vals)
+        tgt_vals = tgt_accum[tgt_mask]
+
+        probs = ecdf_probs(tgt_vals, sorted_ref, plotting_position)
+
+        # Preserve NaN from target
+        probs = np.where(np.isfinite(tgt_vals), probs, np.nan)
+        p[tgt_mask] = probs
+
+    return cdf_to_zscore(p)
+
+
+def kernel_monthwise_parametric_1d(
+    tgt_accum: np.ndarray,
+    ref_accum: np.ndarray,
+    months_tgt: np.ndarray,
+    months_ref: np.ndarray,
+    distribution: str = DEFAULT_DISTRIBUTION,
+    prob_zero: bool = False,
+    floc: float | None = 0,
+) -> np.ndarray:
+    """Classical monthwise parametric: per-month distribution fit → z-score.
+
+    For each calendar month, fit a scipy distribution to the reference
+    values for that month and evaluate the target CDF.
+
+    Parameters
+    ----------
+    tgt_accum : 1-D float array
+        Accumulated target values.
+    ref_accum : 1-D float array
+        Accumulated reference values.
+    months_tgt : 1-D int array
+        Calendar months (1-12) for target.
+    months_ref : 1-D int array
+        Calendar months (1-12) for reference.
+    distribution : str
+        Name of a scipy.stats continuous distribution.
+    prob_zero : bool
+        If True, handle zero-inflation for distributions with support
+        at or above 0.
+    floc : float or None, default 0
+        Fixed location parameter for distributions with support at or
+        above 0. Default ``0`` matches the canonical Stagge SPI
+        convention. ``None`` recovers scipy's free-location fit.
+
+    Returns
+    -------
+    np.ndarray (float32)
+        Standardized z-scores. Same length as *tgt_accum*. Internal
+        computations run in float64; the output is cast to float32 for
+        memory efficiency at the storage boundary.
+    """
+    fit = fit_monthwise(
+        ref_accum,
+        months_ref,
+        distribution=distribution,
+        prob_zero=prob_zero,
+        floc=floc,
+    )
+    p = monthwise_cdf(tgt_accum, months_tgt, fit)
+    return cdf_to_zscore(p)

rsd/_validation.py

@@ -0,0 +1,217 @@
+"""Input validation for the public RSD API.
+
+These helpers are called at the function entry of :func:`rsd.standardize`
+and :func:`rsd.standardize_xr` so that obviously-invalid inputs raise a
+clear ``ValueError`` (or ``TypeError``) immediately, instead of producing
+silently-wrong output or a cryptic error from deep inside the pipeline.
+
+The validators are intentionally small and unit-testable; each one
+focuses on a single parameter and is independent of the others.
+"""
+
+from __future__ import annotations
+
+import numbers
+
+import numpy as np
+
+from rsd.defaults import METHODS, PLOTTING_POSITIONS
+
+
+def validate_method(method: str) -> None:
+    if method not in METHODS:
+        raise ValueError(
+            f"Unknown method {method!r}. Choose from: {', '.join(METHODS)}"
+        )
+
+
+def validate_scale(scale: int) -> None:
+    if not isinstance(scale, (int, np.integer)) or bool(isinstance(scale, bool)):
+        raise ValueError(f"scale must be a positive integer, got {scale!r}")
+    if int(scale) < 1:
+        raise ValueError(f"scale must be >= 1, got {int(scale)}")
+
+
+def validate_agg(agg: str) -> None:
+    if agg not in ("sum", "mean"):
+        raise ValueError(f"agg must be 'sum' or 'mean', got {agg!r}")
+
+
+def validate_loc(loc: str) -> None:
+    if loc not in ("median", "mean"):
+        raise ValueError(f"loc must be 'median' or 'mean', got {loc!r}")
+
+
+def validate_scale_method(scale_method: str) -> None:
+    if scale_method not in ("iqr", "std"):
+        raise ValueError(f"scale_method must be 'iqr' or 'std', got {scale_method!r}")
+
+
+def validate_tail_quantile(tail_quantile: float) -> None:
+    if not isinstance(
+        tail_quantile, (int, float, np.floating, np.integer)
+    ) or isinstance(tail_quantile, bool):
+        raise ValueError(
+            f"tail_quantile must be a number in (0, 0.20], got {tail_quantile!r}"
+        )
+    value = float(tail_quantile)
+    if not (0.0 < value <= 0.20):
+        raise ValueError(
+            f"tail_quantile must be in (0, 0.20], got {value}. "
+            f"Values >= 0.5 produce overlapping tails. Values > 0.20 collapse "
+            f"the empirical core. Values <= 0 disable tail fitting entirely "
+            f"(use a pure-ECDF method instead)."
+        )
+
+
+def validate_min_tail_size(min_tail_size: int) -> None:
+    if not isinstance(min_tail_size, (int, np.integer)) or isinstance(
+        min_tail_size, bool
+    ):
+        raise ValueError(
+            f"min_tail_size must be an integer >= 10, got {min_tail_size!r}"
+        )
+    if int(min_tail_size) < 10:
+        raise ValueError(
+            f"min_tail_size must be >= 10, got {int(min_tail_size)}. "
+            f"Fewer than 10 exceedances per tail makes the GPD fit unreliable."
+        )
+
+
+def validate_bounds_scalar(bounds) -> None:
+    """For the 1-D :func:`rsd.standardize` path.
+
+    ``bounds`` must be ``None`` or a 2-tuple of finite scalars with
+    strict lower < upper.
+    """
+    if bounds is None:
+        return
+    if not (hasattr(bounds, "__len__") and len(bounds) == 2):
+        raise ValueError(f"bounds must be a (lower, upper) 2-tuple, got {bounds!r}")
+    lower, upper = bounds
+    try:
+        lower_f = float(lower)
+        upper_f = float(upper)
+    except (TypeError, ValueError) as e:
+        raise ValueError(
+            f"bounds must be a (lower, upper) 2-tuple of numbers, "
+            f"got ({lower!r}, {upper!r})"
+        ) from e
+    if not (np.isfinite(lower_f) and np.isfinite(upper_f)):
+        raise ValueError(
+            f"bounds must contain finite numbers, got ({lower_f}, {upper_f})"
+        )
+    if lower_f >= upper_f:
+        raise ValueError(
+            f"bounds lower ({lower_f}) must be strictly less than upper ({upper_f})"
+        )
+
+
+def validate_bounds_xr(bounds) -> None:
+    """For the :func:`rsd.standardize_xr` path.
+
+    Each bound may be a scalar OR an xarray DataArray (for per-pixel
+    bounds). Scalar-vs-scalar ordering is checked here; DataArray
+    bounds defer ordering checks to runtime broadcasting.
+    """
+    if bounds is None:
+        return
+    if not (hasattr(bounds, "__len__") and len(bounds) == 2):
+        raise ValueError(f"bounds must be a (lower, upper) 2-tuple, got {bounds!r}")
+    lower, upper = bounds
+    if isinstance(lower, numbers.Number) and isinstance(upper, numbers.Number):
+        validate_bounds_scalar(bounds)
+    # If either is a DataArray, defer ordering check to _logit_transform_xr.
+
+
+def validate_plotting_position(pp) -> None:
+    if isinstance(pp, str):
+        if pp not in PLOTTING_POSITIONS:
+            valid = sorted(PLOTTING_POSITIONS)
+            raise ValueError(
+                f"Unknown plotting_position name {pp!r}. "
+                f"Choose from: {valid}, or pass a 2-tuple (a, b) of floats."
+            )
+        return
+    if hasattr(pp, "__len__") and len(pp) == 2:
+        try:
+            float(pp[0])
+            float(pp[1])
+        except (TypeError, ValueError) as e:
+            raise ValueError(
+                f"plotting_position 2-tuple must contain numbers, got {pp!r}"
+            ) from e
+        return
+    raise ValueError(
+        f"plotting_position must be a known name or a 2-tuple of floats, got {pp!r}"
+    )
+
+
+def validate_months(months: np.ndarray, name: str) -> np.ndarray:
+    """Months must be a 1-D integer array with values strictly in [1, 12].
+
+    Returns the (possibly cast) int32 array for downstream use.
+    """
+    arr = np.asarray(months)
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be 1-D, got {arr.ndim}-D")
+    if arr.dtype.kind not in ("i", "u"):
+        try:
+            arr = arr.astype(np.int32, casting="safe")
+        except TypeError as e:
+            raise ValueError(
+                f"{name} must contain integers in [1, 12], "
+                f"got dtype {np.asarray(months).dtype}"
+            ) from e
+    out_of_range = (arr < 1) | (arr > 12)
+    if out_of_range.any():
+        bad = arr[out_of_range]
+        sample = bad[:5].tolist()
+        raise ValueError(
+            f"{name} must contain integers in [1, 12]; "
+            f"found {int(out_of_range.sum())} out-of-range value(s) "
+            f"(examples: {sample}). The calendar-month convention is "
+            f"1=January through 12=December."
+        )
+    return arr.astype(np.int32, copy=False)
+
+
+def validate_floc(floc) -> None:
+    """``floc`` for the parametric path: either ``None`` or a finite number."""
+    if floc is None:
+        return
+    if isinstance(floc, bool):
+        raise ValueError(f"floc must be None or a finite number, got {floc!r}")
+    if not isinstance(floc, (int, float, np.floating, np.integer)):
+        raise ValueError(f"floc must be None or a finite number, got {floc!r}")
+    if not np.isfinite(float(floc)):
+        raise ValueError(
+            f"floc must be a finite number (or None to disable), got {floc!r}"
+        )
+
+
+def validate_reference_length_for_tail_fit(
+    n_reference: int,
+    scale: int,
+    tail_quantile: float,
+    min_tail_size: int,
+) -> None:
+    """Reject up-front configurations where GPD tail fitting cannot succeed.
+
+    After ``scale``-step accumulation the effective pooled reference length
+    is at most ``n_reference - scale + 1``. The expected number of
+    exceedances per tail is ``n_pooled * tail_quantile``; we require this
+    to be at least ``min_tail_size`` for a meaningful GPD fit.
+    """
+    n_pooled_est = max(0, int(n_reference) - int(scale) + 1)
+    expected = float(n_pooled_est) * float(tail_quantile)
+    if expected < float(min_tail_size):
+        raise ValueError(
+            f"Reference is too short for GPD tail fitting at the requested "
+            f"configuration: n_reference={n_reference}, scale={scale} "
+            f"(pooled n ~ {n_pooled_est}), tail_quantile={tail_quantile} "
+            f"→ expected exceedances per tail ~ {expected:.1f}, "
+            f"but min_tail_size={min_tail_size}. "
+            f"Provide a longer reference, lower tail_quantile, or lower "
+            f"min_tail_size (>= 10)."
+        )

rsd/_version.py

@@ -0,0 +1,11 @@
+"""Version management for the rsd package."""
+
+try:
+    from importlib.metadata import version, PackageNotFoundError
+
+    try:
+        __version__ = version("rsd")
+    except PackageNotFoundError:
+        __version__ = "0.0.0.dev0"
+except ImportError:
+    __version__ = "0.0.0.dev0"

rsd/_warnings.py

@@ -0,0 +1,24 @@
+"""Custom warning categories emitted by the RSD pipeline.
+
+Users can silence or escalate these categories independently of generic
+``UserWarning`` traffic, e.g.::
+
+    import warnings, rsd
+    warnings.filterwarnings("ignore", category=rsd.RSDFitWarning)
+    warnings.filterwarnings("error",  category=rsd.RSDDegenerateWarning)
+"""
+
+from __future__ import annotations
+
+
+class RSDFitWarning(UserWarning):
+    """A parametric fit (GPD, exponential, or scipy monthwise distribution)
+    fell back or failed for a sample. The pipeline still returns a value
+    using a documented fallback path (e.g., ECDF-only on GPD failure)."""
+
+
+class RSDDegenerateWarning(UserWarning):
+    """An input sample is degenerate (zero spread, constant series, or
+    fully outside the declared physical bounds) and was handled by a
+    fallback that may make downstream results undefined or NaN for the
+    affected positions."""