nsevt 0.1.0__tar.gz

nsevt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elí Gaiska Salomón Guzmán
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nsevt-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: nsevt
+Version: 0.1.0
+Summary: Non-stationary extreme-value tail risk with honest uncertainty: permutation-calibrated trend tests, power/MDE, multi-source transportability, and block-conformal prediction under temporal dependence.
+Author-email: Elí Gaiska Salomón Guzmán <salomon.eli@colpos.mx>
+Maintainer-email: Elí Gaiska Salomón Guzmán <salomon.eli@colpos.mx>
+License: MIT
+Project-URL: Homepage, https://github.com/GaiskaSalomon/nsevt
+Project-URL: Repository, https://github.com/GaiskaSalomon/nsevt
+Project-URL: Issues, https://github.com/GaiskaSalomon/nsevt/issues
+Keywords: extreme value theory,generalized Pareto,non-stationarity,permutation test,conformal prediction,Wasserstein,climate extremes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.7
+Provides-Extra: demo
+Requires-Dist: streamlit>=1.30; extra == "demo"
+Requires-Dist: pandas>=1.3; extra == "demo"
+Requires-Dist: matplotlib>=3.5; extra == "demo"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# nsevt — non-stationary extreme-value tail risk with honest uncertainty
+
+[![CI](https://github.com/GaiskaSalomon/nsevt/actions/workflows/ci.yml/badge.svg)](https://github.com/GaiskaSalomon/nsevt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/nsevt.svg)](https://pypi.org/project/nsevt/)
+[![Python versions](https://img.shields.io/pypi/pyversions/nsevt.svg)](https://pypi.org/project/nsevt/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`nsevt` is a small, dependency-light Python package (NumPy + SciPy) for the
+**honest** analysis of trends in environmental extremes. It packages a workflow
+that existing EVT tools (`extRemes`, `ismev`, `POT`, `pyextremes`, `texmex`) do
+not offer as a single, tested pipeline:
+
+1. **Bounded-tail detection** — a peaks-over-threshold GPD fit with a
+   profile-likelihood interval for the shape and a bootstrap of the finite upper
+   endpoint (`ξ<0` ⇒ a finite physical ceiling).
+2. **A permutation-calibrated trend test** on the tail scale — exact in finite
+   samples, avoiding the unreliable asymptotic χ² for a boundary-adjacent
+   parameter on a few hundred exceedances.
+3. **Power / minimum-detectable-effect** — turns any non-rejection into a
+   quantitative statement of what the record can resolve.
+4. **Multi-source transportability** ("evidence arena") — does an apparent trend
+   *survive* changing the data source, or is it an instrumental artifact?
+5. **Block-conformal prediction bands** — distribution-free coverage for extreme
+   quantiles **under temporal dependence**.
+6. **A two-scale Wasserstein trend test** for a series of distributions each
+   estimated from a small per-period sample, with an exact
+   location/scale/shape energy decomposition.
+
+The numerics of the GPD and permutation machinery are ported verbatim from the
+frozen, unit-tested research code, so results are reproducible and identical.
+
+## Install
+
+```bash
+pip install -e .            # from this directory
+pip install -e ".[demo]"    # also install the Streamlit demo dependencies
+```
+
+## Quick start
+
+```python
+import numpy as np, nsevt
+
+rng = np.random.default_rng(0)
+# 500 observations; tail excesses above u=40 are bounded (xi<0)
+x = 40 + rng.gamma(2.0, 8.0, size=500)
+
+fit = nsevt.gpd_pot(x, threshold=40)
+print(fit.summary())
+print("1-in-100 return level:", fit.return_level(100, rate=(x > 40).mean()))
+
+# is there a trend in the tail scale? (block = year label per observation)
+year = rng.integers(1980, 2024, size=500)
+tr = nsevt.trend_permutation(x[x > 40] - 40, year[x > 40])
+print("trend/decade:", round(tr["trend_per_decade"], 3),
+      "p_perm:", tr["p_permutation"])
+
+# what can the record resolve?
+mde = nsevt.min_detectable_effect(x[x > 40] - 40, year[x > 40])
+print("MDE per decade:", mde["mde_per_decade"])
+
+# distribution-free 90% prediction band under dependence
+band = nsevt.block_conformal(x, threshold=40, alpha=0.10)
+print("upper bound at sigma:", band.predict_upper(fit.sigma))
+```
+
+## The multi-source arena
+
+```python
+arena = nsevt.transportability(
+    [("operational", x_op, year_op),
+     ("independent", x_ind, year_ind),
+     ("homogenized", x_homog, year_homog)],
+    threshold=40)
+print(arena.table())
+```
+
+The verdict distinguishes a **robust bounded tail** (shape reproduces in every
+source) from an **apparent trend that does not survive** the change of source —
+the core methodological contribution of the accompanying research.
+
+## Modules
+
+| module | purpose |
+|---|---|
+| `nsevt.gpd` | POT-GPD fit, profile CI for ξ, endpoint bootstrap, return levels |
+| `nsevt.trend` | permutation trend test, power/MDE, block-bootstrap trend CI |
+| `nsevt.transportability` | multi-source evidence arena |
+| `nsevt.conformal` | block / split conformal prediction bands for tails |
+| `nsevt.twoscale` | two-scale Wasserstein distributional trend test + energy split |
+
+## Tests
+
+```bash
+pip install ".[test]" && pytest
+```
+
+## License
+
+MIT. See `LICENSE`.

nsevt-0.1.0/README.md

@@ -0,0 +1,100 @@
+# nsevt — non-stationary extreme-value tail risk with honest uncertainty
+
+[![CI](https://github.com/GaiskaSalomon/nsevt/actions/workflows/ci.yml/badge.svg)](https://github.com/GaiskaSalomon/nsevt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/nsevt.svg)](https://pypi.org/project/nsevt/)
+[![Python versions](https://img.shields.io/pypi/pyversions/nsevt.svg)](https://pypi.org/project/nsevt/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`nsevt` is a small, dependency-light Python package (NumPy + SciPy) for the
+**honest** analysis of trends in environmental extremes. It packages a workflow
+that existing EVT tools (`extRemes`, `ismev`, `POT`, `pyextremes`, `texmex`) do
+not offer as a single, tested pipeline:
+
+1. **Bounded-tail detection** — a peaks-over-threshold GPD fit with a
+   profile-likelihood interval for the shape and a bootstrap of the finite upper
+   endpoint (`ξ<0` ⇒ a finite physical ceiling).
+2. **A permutation-calibrated trend test** on the tail scale — exact in finite
+   samples, avoiding the unreliable asymptotic χ² for a boundary-adjacent
+   parameter on a few hundred exceedances.
+3. **Power / minimum-detectable-effect** — turns any non-rejection into a
+   quantitative statement of what the record can resolve.
+4. **Multi-source transportability** ("evidence arena") — does an apparent trend
+   *survive* changing the data source, or is it an instrumental artifact?
+5. **Block-conformal prediction bands** — distribution-free coverage for extreme
+   quantiles **under temporal dependence**.
+6. **A two-scale Wasserstein trend test** for a series of distributions each
+   estimated from a small per-period sample, with an exact
+   location/scale/shape energy decomposition.
+
+The numerics of the GPD and permutation machinery are ported verbatim from the
+frozen, unit-tested research code, so results are reproducible and identical.
+
+## Install
+
+```bash
+pip install -e .            # from this directory
+pip install -e ".[demo]"    # also install the Streamlit demo dependencies
+```
+
+## Quick start
+
+```python
+import numpy as np, nsevt
+
+rng = np.random.default_rng(0)
+# 500 observations; tail excesses above u=40 are bounded (xi<0)
+x = 40 + rng.gamma(2.0, 8.0, size=500)
+
+fit = nsevt.gpd_pot(x, threshold=40)
+print(fit.summary())
+print("1-in-100 return level:", fit.return_level(100, rate=(x > 40).mean()))
+
+# is there a trend in the tail scale? (block = year label per observation)
+year = rng.integers(1980, 2024, size=500)
+tr = nsevt.trend_permutation(x[x > 40] - 40, year[x > 40])
+print("trend/decade:", round(tr["trend_per_decade"], 3),
+      "p_perm:", tr["p_permutation"])
+
+# what can the record resolve?
+mde = nsevt.min_detectable_effect(x[x > 40] - 40, year[x > 40])
+print("MDE per decade:", mde["mde_per_decade"])
+
+# distribution-free 90% prediction band under dependence
+band = nsevt.block_conformal(x, threshold=40, alpha=0.10)
+print("upper bound at sigma:", band.predict_upper(fit.sigma))
+```
+
+## The multi-source arena
+
+```python
+arena = nsevt.transportability(
+    [("operational", x_op, year_op),
+     ("independent", x_ind, year_ind),
+     ("homogenized", x_homog, year_homog)],
+    threshold=40)
+print(arena.table())
+```
+
+The verdict distinguishes a **robust bounded tail** (shape reproduces in every
+source) from an **apparent trend that does not survive** the change of source —
+the core methodological contribution of the accompanying research.
+
+## Modules
+
+| module | purpose |
+|---|---|
+| `nsevt.gpd` | POT-GPD fit, profile CI for ξ, endpoint bootstrap, return levels |
+| `nsevt.trend` | permutation trend test, power/MDE, block-bootstrap trend CI |
+| `nsevt.transportability` | multi-source evidence arena |
+| `nsevt.conformal` | block / split conformal prediction bands for tails |
+| `nsevt.twoscale` | two-scale Wasserstein distributional trend test + energy split |
+
+## Tests
+
+```bash
+pip install ".[test]" && pytest
+```
+
+## License
+
+MIT. See `LICENSE`.

nsevt-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nsevt"
+version = "0.1.0"
+description = "Non-stationary extreme-value tail risk with honest uncertainty: permutation-calibrated trend tests, power/MDE, multi-source transportability, and block-conformal prediction under temporal dependence."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Elí Gaiska Salomón Guzmán", email = "salomon.eli@colpos.mx" }]
+maintainers = [{ name = "Elí Gaiska Salomón Guzmán", email = "salomon.eli@colpos.mx" }]
+keywords = ["extreme value theory", "generalized Pareto", "non-stationarity",
+            "permutation test", "conformal prediction", "Wasserstein", "climate extremes"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = ["numpy>=1.21", "scipy>=1.7"]
+
+[project.optional-dependencies]
+demo = ["streamlit>=1.30", "pandas>=1.3", "matplotlib>=3.5"]
+test = ["pytest>=7.0"]
+dev = ["build>=1.0", "twine>=5.0", "pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/GaiskaSalomon/nsevt"
+Repository = "https://github.com/GaiskaSalomon/nsevt"
+Issues = "https://github.com/GaiskaSalomon/nsevt/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nsevt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nsevt-0.1.0/src/nsevt/__init__.py

@@ -0,0 +1,38 @@
+"""nsevt: non-stationary extreme-value tail risk with honest uncertainty.
+
+A small, dependency-light toolkit for the *honest* analysis of trends in
+environmental extremes:
+
+* :func:`gpd_pot` -- peaks-over-threshold GPD fit with a profile-likelihood
+  interval for the shape and a bootstrap of the finite upper endpoint;
+* :func:`trend_permutation` / :func:`min_detectable_effect` -- a
+  permutation-calibrated test of a tail-scale trend and a Monte-Carlo
+  power/MDE analysis (what can this record actually resolve?);
+* :func:`transportability` -- the multi-source "evidence arena": does a trend
+  survive changing the data source, or is it an artifact?
+* :func:`block_conformal` -- distribution-free prediction bands for extreme
+  quantiles with coverage guarantees under temporal dependence;
+* :func:`twoscale_trend` -- a Wasserstein/Frechet-mean trend test for a series
+  of distributions estimated from small per-period samples.
+
+The numerics of the GPD and permutation machinery are ported verbatim from the
+frozen, unit-tested code of the accompanying research, so results are identical.
+"""
+from .gpd import fit_gpd, profile_ci_xi, upper_endpoint, gpd_pot, GPDFit
+from .trend import (trend_permutation, trend_power, min_detectable_effect,
+                    block_bootstrap_trend_ci)
+from .transportability import transportability, ArenaResult, SourceResult
+from .conformal import block_conformal, split_conformal, ConformalBand
+from .twoscale import twoscale_trend, wasserstein_decomposition, TwoScaleResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "fit_gpd", "profile_ci_xi", "upper_endpoint", "gpd_pot", "GPDFit",
+    "trend_permutation", "trend_power", "min_detectable_effect",
+    "block_bootstrap_trend_ci",
+    "transportability", "ArenaResult", "SourceResult",
+    "block_conformal", "split_conformal", "ConformalBand",
+    "twoscale_trend", "wasserstein_decomposition", "TwoScaleResult",
+    "__version__",
+]

nsevt-0.1.0/src/nsevt/conformal.py

@@ -0,0 +1,138 @@
+"""Block-conformal prediction bands for non-stationary extreme quantiles.
+
+Classical split-conformal prediction gives finite-sample coverage under
+*exchangeability*, which temporally dependent extremes violate.  Block conformal
+calibrates over contiguous temporal **blocks** treated as the approximately
+exchangeable units, yielding
+
+    P(X in C_alpha) >= 1 - alpha - o(1)
+
+under beta-mixing, with the o(1) term controlled by the block length.  The
+non-conformity score is the **standardized excess** ``s = (x - u)/sigma``: by the
+pivotal property of the GPD, dividing by the (possibly covariate-dependent)
+scale removes the covariate/non-stationarity, leaving a common score law across
+covariate values.
+
+Implements the method of the block-conformal-EVT manuscript.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+import numpy as np
+
+from .gpd import fit_gpd
+
+
+@dataclass
+class ConformalBand:
+    """A one-sided upper conformal prediction band for a tail."""
+    threshold: float
+    alpha: float
+    q_standardized: float
+    method: str
+    n_blocks: int
+    block_length: int
+
+    def predict_upper(self, scale: float) -> float:
+        """Upper prediction bound ``u + q * sigma`` at scale ``sigma``."""
+        return float(self.threshold + self.q_standardized * scale)
+
+    def coverage(self, x_new: Sequence[float], scale) -> float:
+        """Empirical coverage of the band on new exceedances ``x_new``.
+
+        ``scale`` is a scalar or per-observation array of ``sigma`` values used
+        to build the band for each new point.
+        """
+        x_new = np.asarray(x_new, float)
+        scale = np.broadcast_to(np.asarray(scale, float), x_new.shape)
+        upper = self.threshold + self.q_standardized * scale
+        return float(np.mean(x_new <= upper))
+
+
+def _blocks(n: int, block_length: Optional[int], n_blocks: Optional[int]):
+    if block_length is None and n_blocks is None:
+        block_length = max(2, int(round(n ** 0.5)))  # ell ~ sqrt(T)
+    if block_length is None:
+        block_length = max(2, n // int(n_blocks))
+    edges = list(range(0, n, block_length))
+    return [(edges[i], min(edges[i] + block_length, n)) for i in range(len(edges))]
+
+
+def block_conformal(x: Sequence[float], threshold: float, alpha: float = 0.1,
+                    scale=None, order: Optional[Sequence] = None,
+                    block_length: Optional[int] = None,
+                    n_blocks: Optional[int] = None) -> ConformalBand:
+    """One-sided block-conformal upper band for peaks over ``threshold``.
+
+    Parameters
+    ----------
+    x : array
+        Raw observations; only ``x > threshold`` are used as calibration
+        exceedances.
+    threshold : float
+        Tail threshold ``u``.
+    alpha : float
+        Miscoverage level; the band targets coverage ``>= 1 - alpha``.
+    scale : float or array, optional
+        Per-observation GPD scale ``sigma`` used to standardize excesses.  If
+        ``None``, a constant scale is estimated by GPD MLE on the exceedances.
+        For non-stationary/covariate-dependent tails, pass ``sigma(z_i)``.
+    order : array, optional
+        Temporal ordering key for the exceedances (e.g. time); blocks are formed
+        on the sorted order.  If ``None``, input order is assumed temporal.
+    block_length, n_blocks : int, optional
+        Block size / count.  Default block length ``~ sqrt(#exceedances)``.
+    """
+    x = np.asarray(x, float)
+    mask = x > threshold
+    z = x[mask] - threshold
+    if z.size < 4:
+        raise ValueError(f"only {z.size} exceedances; need >= 4 for calibration")
+    if scale is None:
+        sigma = fit_gpd(z)["sigma"]
+        s = z / sigma
+    else:
+        scale = np.asarray(scale, float)
+        sc = scale[mask] if scale.shape == x.shape else scale
+        s = z / sc
+    if order is not None:
+        order = np.asarray(order)[mask] if np.asarray(order).shape == x.shape else np.asarray(order)
+        s = s[np.argsort(order, kind="stable")]
+
+    blocks = _blocks(len(s), block_length, n_blocks)
+    # per-block aggregate score: within-block (1-alpha) quantile
+    agg = np.array([np.quantile(s[a:b], 1 - alpha) for a, b in blocks if b > a])
+    K = len(agg)
+    if K < 2:
+        raise ValueError("need >= 2 calibration blocks; reduce block_length")
+    # finite-sample conformal quantile of the block aggregates
+    lvl = min(1.0, np.ceil((1 - alpha) * (K + 1)) / K)
+    q = float(np.quantile(agg, lvl))
+    bl = blocks[0][1] - blocks[0][0]
+    return ConformalBand(threshold=float(threshold), alpha=float(alpha),
+                         q_standardized=q, method="block-conformal",
+                         n_blocks=K, block_length=int(bl))
+
+
+def split_conformal(x: Sequence[float], threshold: float, alpha: float = 0.1,
+                    scale=None) -> ConformalBand:
+    """Marginal split-conformal upper band (ignores temporal dependence).
+
+    Provided as the baseline whose coverage the block version corrects under
+    dependence; use :func:`block_conformal` for dependent extremes.
+    """
+    x = np.asarray(x, float)
+    mask = x > threshold
+    z = x[mask] - threshold
+    if z.size < 4:
+        raise ValueError(f"only {z.size} exceedances; need >= 4")
+    sigma = fit_gpd(z)["sigma"] if scale is None else None
+    s = z / (sigma if scale is None else np.asarray(scale, float)[mask])
+    n = len(s)
+    lvl = min(1.0, np.ceil((1 - alpha) * (n + 1)) / n)
+    q = float(np.quantile(s, lvl))
+    return ConformalBand(threshold=float(threshold), alpha=float(alpha),
+                         q_standardized=q, method="split-conformal",
+                         n_blocks=1, block_length=n)