Metadata-Version: 2.4
Name: heavytails
Version: 0.6.3
Summary: Heavy-tailed probability distributions for research, teaching, and simulation.
License-Expression: MIT
License-File: LICENSE
Keywords: heavy-tailed,statistics,probability,extreme-values,distributions,finance,risk-management,tail-risk,extreme-value-theory
Author: Diogo Ribeiro
Author-email: dfr@esmad.ipp.pt
Maintainer: Diogo Ribeiro
Maintainer-email: dfr@esmad.ipp.pt
Requires-Python: >=3.10,<3.14
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Provides-Extra: cli
Provides-Extra: plot
Requires-Dist: matplotlib (>=3.9,<4.0) ; extra == "plot"
Requires-Dist: numpy (>=1.24,<3.0)
Requires-Dist: rich (>=14.0,<15.0) ; extra == "cli"
Requires-Dist: typer (>=0.20,<1.0) ; extra == "cli"
Project-URL: Changelog, https://github.com/DiogoRibeiro7/heavytails/blob/main/CHANGELOG.md
Project-URL: Documentation, https://diogoribeiro7.github.io/heavytails
Project-URL: Discussions, https://github.com/DiogoRibeiro7/heavytails/discussions
Project-URL: Homepage, https://github.com/DiogoRibeiro7/heavytails
Project-URL: Issues, https://github.com/DiogoRibeiro7/heavytails/issues
Project-URL: Repository, https://github.com/DiogoRibeiro7/heavytails
Description-Content-Type: text/markdown

# heavytails

**A library of heavy-tailed probability distributions, vectorised over NumPy**

[![CI](https://github.com/DiogoRibeiro7/heavytails/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DiogoRibeiro7/heavytails/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/DiogoRibeiro7/heavytails/branch/main/graph/badge.svg)](https://codecov.io/gh/DiogoRibeiro7/heavytails)
[![PyPI](https://img.shields.io/pypi/v/heavytails.svg)](https://pypi.org/project/heavytails/)
[![Python versions](https://img.shields.io/pypi/pyversions/heavytails.svg)](https://pypi.org/project/heavytails/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22045594.svg)](https://doi.org/10.5281/zenodo.22045594)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://diogoribeiro7.github.io/heavytails)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](https://mypy-lang.org/)

`heavytails` implements continuous and discrete heavy-tailed distributions, tail
index estimators, and diagnostic utilities with NumPy-backed vectorized
evaluation. Every density, quantile and sampler is derived from first
principles, so the implementation can be read, checked and taught rather than
taken on faith.

It targets research, teaching and simulation work in risk, finance, insurance and
extreme-value analysis.

---

## Features

- **NumPy-backed evaluation.** NumPy is the required runtime dependency, giving
  the distribution and estimator code efficient scalar and array evaluation.
- **Complete distribution interface.** PDF/PMF, CDF, survival function, quantile
  function and random sampling for every family, with survival functions computed
  directly so they stay accurate far into the tail where `1 - cdf(x)` has lost
  every significant digit.
- **Reproducible sampling** through a deterministic RNG wrapper.
- **Special functions from scratch** — incomplete gamma and incomplete beta —
  plus a safeguarded-Newton numeric PPF for families with no closed form.
- **Tail index estimation** with Hill-family, robust, bias-reduced,
  threshold-averaged and peaks-over-threshold estimators.
- **Parameter fitting** by maximum likelihood and method of moments, with
  AIC/BIC model comparison.
- **Diagnostics** for log–log tail plots and QQ plots.
- **Applied extreme value theory** — peaks-over-threshold selection with mean
  residual life and parameter-stability diagnostics, generalized Pareto fitting,
  return levels, tail-risk measures, actuarial frequency and severity models,
  and streaming estimators for data that does not fit in memory.
- **Dependent extremes** — elliptical and multivariate Student-t models with
  fitting, the tail dependence coefficient, Gaussian, Student-t, Gumbel and
  Galambos copulas, GARCH fitting, the extremal index and declustering.
- **A command-line interface** for sampling, fitting, comparison and
  benchmarking.
- **Ships type annotations** and a `py.typed` marker, so downstream type
  checkers see them. Note that NumPy's stubs are not followed by this project's
  own mypy configuration, so the array boundary is annotated but not verified
  against NumPy's types.

---

## Installation

```bash
pip install heavytails
```

The command-line interface needs two extra packages; install it with the `cli`
extra:

```bash
pip install "heavytails[cli]"
```

To work on the library itself:

```bash
git clone https://github.com/DiogoRibeiro7/heavytails.git
cd heavytails
poetry install --with dev,docs
```

Requires Python 3.10 or newer.

---

## Quick start

```python
from heavytails import BurrXII, Pareto, hill_estimator

pareto = Pareto(alpha=1.5, xm=1.0)

pareto.pdf(2.0)        # density
pareto.cdf(2.0)        # distribution function
pareto.sf(10.0)        # survival function: P(X > 10)
pareto.ppf(0.99)       # 99th percentile
samples = pareto.rvs(10_000, seed=42)

# Recover the tail index from the sample. The estimators return the
# extreme-value index gamma = 1 / alpha, so invert it to read alpha back.
gamma = hill_estimator(samples, k=100)   # ≈ 0.65
alpha = 1 / gamma                        # ≈ 1.53, against a true 1.5

burr = BurrXII(c=1.2, k=2.5, s=3.0)
burr.ppf(0.95)
```

### Command line

```bash
heavytails list-distributions
heavytails sample pareto --params '{"alpha": 2.0, "xm": 1.0}' -n 1000 -o samples.txt
heavytails estimate-tail samples.txt --method hill
heavytails compare samples.txt
```

Run `heavytails --help` for the full command list.

---

## Available distributions

### Continuous

| Distribution            | Module                   | Heavy-tail regime |
| ----------------------- | ------------------------ | ----------------- |
| Pareto                  | `heavy_tails`            | always            |
| Cauchy                  | `heavy_tails`            | always            |
| Student-t               | `heavy_tails`            | small ν           |
| Log-Normal              | `heavy_tails`            | always            |
| Weibull                 | `heavy_tails`            | k < 1             |
| Fréchet                 | `heavy_tails`            | always            |
| GEV (Fréchet branch)    | `heavy_tails`            | ξ > 0             |
| Generalized Pareto      | `extra_distributions`    | ξ > 0             |
| Burr XII                | `extra_distributions`    | always            |
| Log-Logistic (Fisk)     | `extra_distributions`    | always            |
| Inverse-Gamma           | `extra_distributions`    | always            |
| Beta-Prime              | `extra_distributions`    | always            |

### Discrete

| Distribution     | Module     | Heavy-tail regime |
| ---------------- | ---------- | ----------------- |
| Zipf             | `discrete` | always            |
| Yule–Simon       | `discrete` | always            |
| Discrete Pareto  | `discrete` | always            |

Every continuous family provides `pdf`, `cdf`, `sf`, `ppf` and `rvs`; every
discrete family provides `pmf`, `cdf`, `ppf` and `rvs`.

### Estimation and diagnostics

| Module         | Contents                                                   |
| -------------- | ---------------------------------------------------------- |
| `tail_index`   | Hill-family, robust, bias-reduced and POT estimators        |
| `threshold`    | Mean residual life, parameter stability, GPD fits, return levels |
| `risk`         | Value at risk, expected shortfall, tail conditional expectation |
| `actuarial`    | Frequency models, policy terms, layered severity, limited expected values |
| `streaming`    | Top-k, streaming and windowed tail-index estimation         |
| `multivariate` | Elliptical models, multivariate Student-t, tail dependence  |
| `copula`       | Gaussian, Student-t, Gumbel and Galambos copulas            |
| `timeseries`   | GARCH fitting, the extremal index, declustering             |
| `registry`     | Name-to-family lookup for generic code                      |
| `plotting`     | Log–log tail plots and QQ plots                             |
| `utilities`    | Data I/O, automatic fitting and model comparison            |
| `validation`   | Mathematical and numerical validation of the families       |
| `cli`          | Command-line entry point                                    |

---

## Documentation

Full documentation, including the mathematical background, is at
**<https://diogoribeiro7.github.io/heavytails>**.

To build it locally:

```bash
make docs-serve
```

---

## Research

The repository carries the replication package for *Sparse Contamination in
Tail-Index Estimation: Detectability, Negligibility, and Risk* at
[`research/sparse_contamination/replication_package/`](research/sparse_contamination/replication_package/),
archived with each release. It studies when a handful of contaminated order
statistics can be detected, when they can be ignored, and when they change a
risk number, using this library's spacing scan and harmonic-moment estimators.

The package holds the simulation drivers, the analysis-only scripts, the frozen
results, the provenance records and a SHA-256 manifest over every file.
`REPRODUCE.md` inside it regenerates every manuscript table and figure from the
archived artifacts, without re-running the simulation. It also states where the
evidence is thinner: the post-specified stress layer ships summaries only, so
its Monte Carlo standard errors can be read but not independently recomputed.

---

## Development

```bash
make install-dev   # install every dependency group
make hooks         # install the pre-commit hooks
make check         # everything CI runs: lint, format, types, tests, security
```

Individual targets are listed by `make help`. Contributions are welcome — see
[CONTRIBUTING.md](CONTRIBUTING.md) for the branch flow, commit conventions and
review process, and [ROADMAP.md](ROADMAP.md) for what is planned next.

Notable changes are recorded in [CHANGELOG.md](CHANGELOG.md).

---

## License

MIT License © 2025 Diogo Ribeiro. See [LICENSE](LICENSE).

---

## Citation

If you use this package in research or teaching, please cite it. GitHub's
"Cite this repository" button reads [CITATION.cff](CITATION.cff), or use:

> Ribeiro, D. (2026). *heavytails: A Python Library for Heavy-Tailed
> Probability Distributions* (Version 0.6.3) [Computer software]. Zenodo.
> <https://doi.org/10.5281/zenodo.22171166>

**Which DOI to use.** The citation above names a version, so it uses that
release's own DOI: [`10.5281/zenodo.22171166`](https://doi.org/10.5281/zenodo.22171166)
resolves to 0.6.3 and nothing else. Every release gets one, minted when Zenodo
archives it and listed under "Versions" on the record.
[`10.5281/zenodo.22045594`](https://doi.org/10.5281/zenodo.22045594) is the
*concept* DOI, which always resolves to the most recent release; cite it when
you mean "this software, any version" and the exact version is not part of the
claim.

```bibtex
@software{ribeiro_heavytails,
  author    = {Ribeiro, Diogo},
  title     = {heavytails: A Python Library for Heavy-Tailed
               Probability Distributions},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.22045594},
  url       = {https://doi.org/10.5281/zenodo.22045594}
}
```

Shared citation metadata is maintained in `CITATION.cff`; Zenodo-specific
archive metadata is maintained in `.zenodo.json`. Both list the papers the
library implements, so citing a specific estimator is a matter of copying the
entry rather than tracking it down.

