rsd 1.0.0__tar.gz

rsd-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,88 @@
+# Release workflow: triggered when a version tag (vMAJOR.MINOR.PATCH) is
+# pushed. Builds the sdist and wheel, publishes to PyPI via "trusted
+# publishing" (OpenID Connect - no API tokens stored in the repo), and
+# creates a corresponding GitHub Release.
+#
+# One-time setup on PyPI:
+#   1. Create the project page (or use a pending publisher).
+#   2. Add a Trusted Publisher pointing at thchilly/rsd, workflow
+#      publish.yml, environment "pypi".
+#   3. No further configuration on the GitHub side beyond this file -
+#      the OIDC handshake authenticates the publish step automatically.
+
+name: publish
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # hatch-vcs needs the full history to derive the version
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build backend
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Upload build artefacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+
+    steps:
+      - name: Download build artefacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Download build artefacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release with attached distributions
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

rsd-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,46 @@
+# Continuous integration: run the test suite on every push and pull request.
+# Matrix-tests across Python 3.10, 3.11, and 3.12 to catch version-specific
+# regressions before they land on main.
+
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch: {}
+
+jobs:
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest --cov=rsd --cov-report=xml --cov-report=term -ra
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false

rsd-1.0.0/.gitignore

@@ -0,0 +1,56 @@
+# Byte-compiled / optimised
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+*.whl
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checking caches
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# Environments
+.venv/
+venv/
+env/
+.env
+*.env
+
+# Editor / IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+ehthumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Docs builds
+docs/_build/
+site/
+.cache/

rsd-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+# pre-commit hooks for rsd.
+#
+# Install once per clone:   pre-commit install
+# Run manually:              pre-commit run --all-files
+#
+# Hooks run automatically before every git commit. If a hook auto-fixes
+# a file, the commit is aborted; re-stage the fixed file(s) and commit again.
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      # Linter: catch unused imports, undefined names, common bug patterns.
+      - id: ruff
+        args: [--fix]
+      # Formatter: enforce consistent code style (replaces black + isort).
+      # Example notebooks are excluded: their code is hand-formatted for
+      # teaching clarity (grouped call signatures, aligned tables), which
+      # the mechanical formatter would undo.
+      - id: ruff-format
+        exclude: ^examples/.*\.ipynb$
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        # --unsafe checks YAML syntax without resolving custom tags;
+        # mkdocs.yml uses a Python-specific tag for the Mermaid fence
+        # (!!python/name:pymdownx.superfences.fence_code_format).
+        args: [--unsafe]
+      - id: check-toml
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+        # Brand assets (banner PNGs) are intentionally large and render
+        # the README header on GitHub; exempt them from the
+        # accidental-large-file guard while keeping the limit for code.
+        exclude: ^assets/
+      - id: check-merge-conflict

rsd-1.0.0/.readthedocs.yaml

@@ -0,0 +1,26 @@
+# Read the Docs configuration for rsd
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  jobs:
+    pre_build:
+      # mkdocs-jupyter renders ../examples/*.ipynb via the symlink
+      # docs/examples -> ../examples. The symlink is checked into git
+      # so nothing extra is needed at build time.
+      - echo "Building rsd docs site"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - xarray
+    - requirements: docs/requirements.txt

rsd-1.0.0/.zenodo.json

@@ -0,0 +1,36 @@
+{
+  "title": "rsd: Reference-based standardization framework for hydroclimate drought indices",
+  "description": "A Python package implementing a hybrid empirical-parametric framework for standardized hydroclimate drought indices (SPI, SSI, SDI, SPEI) under a fixed reference distribution. Deseasonalizes per calendar month, pools residuals, and splices a Generalized Pareto Distribution tail onto an empirical CDF core so that values from different model runs, scenarios, or observational products are directly comparable on the same scale. Provides 1-D and xarray/dask N-D entry points, public-API input validation, custom warning categories, and a one-call diagnose() that verifies the exchangeability assumption underlying pooling. Companion paper: Tsilimigkras, Grillakis, & Koutroulis (2026), submitted to Water Resources Research.",
+  "creators": [
+    {
+      "name": "Tsilimigkras, Athanasios",
+      "affiliation": "Technical University of Crete"
+    }
+  ],
+  "keywords": [
+    "drought",
+    "standardized-index",
+    "SPI",
+    "SSI",
+    "SDI",
+    "SPEI",
+    "hydroclimate",
+    "extreme-value-theory",
+    "distribution-shift",
+    "reference-based",
+    "python"
+  ],
+  "license": "BSD-3-Clause",
+  "upload_type": "software",
+  "access_right": "open",
+  "related_identifiers": [
+    {
+      "identifier": "https://github.com/thchilly/rsd",
+      "relation": "isSourceOf",
+      "scheme": "url"
+    }
+  ],
+  "references": [
+    "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."
+  ]
+}

rsd-1.0.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [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](https://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.
+
+[Unreleased]: https://github.com/thchilly/rsd/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/thchilly/rsd/releases/tag/v1.0.0

rsd-1.0.0/CITATION.cff

@@ -0,0 +1,46 @@
+# CITATION.cff - machine-readable citation metadata consumed by GitHub's
+# "Cite this repository" button and by reference managers. The
+# preferred-citation block points at the methodology paper.
+
+cff-version: 1.2.0
+title: "Reference-based Standardization (RSD) for hydroclimate indices"
+message: "If you use this software, please cite the methodology paper listed under preferred-citation."
+authors:
+  - family-names: Tsilimigkras
+    given-names: Athanasios
+    email: atsilimigkras1@tuc.gr
+    affiliation: "Technical University of Crete"
+version: "1.0.0"
+date-released: "2026-05-22"
+license: BSD-3-Clause
+repository-code: "https://github.com/thchilly/rsd"
+url: "https://hydro-rsd.readthedocs.io"
+keywords:
+  - drought
+  - standardized-index
+  - SPI
+  - SSI
+  - SDI
+  - SPEI
+  - hydroclimate
+  - extreme-value-theory
+  - distribution-shift
+type: software
+
+preferred-citation:
+  type: article
+  authors:
+    - family-names: Tsilimigkras
+      given-names: Athanasios
+      email: atsilimigkras1@tuc.gr
+      affiliation: "Technical University of Crete"
+    - family-names: Grillakis
+      given-names: Manolis
+      affiliation: "Technical University of Crete"
+    - family-names: Koutroulis
+      given-names: Aristeidis
+      affiliation: "Technical University of Crete"
+  title: "A reference-based standardization framework for hydroclimate drought indices under distribution shift"
+  journal: "Water Resources Research"
+  year: 2026
+  notes: "Manuscript submitted to Water Resources Research; DOI pending acceptance."

rsd-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to rsd
+
+Thanks for your interest in contributing. This page covers how to set up a
+development environment, run the tests, and propose a change.
+
+## Setting up a development environment
+
+```bash
+git clone https://github.com/thchilly/rsd.git
+cd rsd
+pip install -e ".[dev]"
+pre-commit install
+```
+
+The `[dev]` extra pulls in `pytest`, `pytest-cov`, the xarray/dask
+stack (`[xarray]`), and matplotlib (`[diagnostics]`). `pre-commit
+install` activates the pre-commit hooks (ruff linting + formatting) so
+every commit is automatically checked before it lands.
+
+## Running tests
+
+```bash
+pytest                       # full suite
+pytest --cov=rsd             # with a coverage report
+pytest tests/test_core.py    # a single test file
+```
+
+Tests are expected to pass on Python 3.10, 3.11, and 3.12. Continuous
+integration runs the suite across all three on every push and pull request.
+
+## Proposing a change
+
+1. **Open an issue first** describing what you want to change and why. This
+   avoids you spending time on a change that may not align with the project
+   scope, and it gives other contributors a chance to comment.
+2. Fork the repository and create a feature branch off `main`.
+3. Make your change. Add or update tests if the change affects behaviour.
+4. Run `pytest` and `pre-commit run --all-files` until both are green.
+5. Open a pull request that references the issue.
+
+For non-trivial changes please also add a brief entry under `[Unreleased]`
+in `CHANGELOG.md`.
+
+## Reporting bugs
+
+Open a [GitHub issue](https://github.com/thchilly/rsd/issues) with:
+
+- A minimal reproducible example (a short script or notebook cell that
+  triggers the problem).
+- The expected behaviour and what you observed instead.
+- Your `rsd`, `numpy`, `scipy`, and Python versions.
+
+## Scope
+
+`rsd` is a focused methodology package for **reference-based standardisation
+of hydroclimate drought indices**. Contributions that extend the existing
+methodology (additional baseline methods, new diagnostics, better
+documentation, performance improvements, bug fixes) are very welcome.
+Feature requests that fall outside this scope (general time-series tooling,
+non-hydroclimate use cases, climate-model post-processing utilities) are
+better suited to other packages.
+
+## Versioning and releases
+
+The project follows [Semantic Versioning](https://semver.org/). Tagged
+releases (`vMAJOR.MINOR.PATCH`) trigger an automatic build and publication
+to PyPI via the `publish.yml` GitHub Actions workflow. Maintainers cut
+releases; contributors do not need to interact with the release machinery.
+
+## Code of conduct
+
+Be respectful, constructive, and patient in all project communication.
+Issue and pull-request discussions are public; please write accordingly.
+
+## License
+
+By contributing you agree that your contributions will be licensed under
+the project's [BSD 3-Clause License](LICENSE).

rsd-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Athanasios Tsilimigkras
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.