heavytails

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

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

pip install heavytails

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

pip install "heavytails[cli]"

To work on the library itself:

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

Requires Python 3.10 or newer.

Quick start

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

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

Discrete

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

Estimation and diagnostics

Documentation

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

To build it locally:

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/, 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

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 for the branch flow, commit conventions and review process, and ROADMAP.md for what is planned next.

Notable changes are recorded in CHANGELOG.md.

License

MIT License © 2025 Diogo Ribeiro. See LICENSE.

Citation

If you use this package in research or teaching, please cite it. GitHub's "Cite this repository" button reads 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 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 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.

@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.