rcopula

Copula modelling in Python — a full-featured replication of R's copula package, verified against it numerically.

Status: pre-1.0, under active development. The API may change before 1.0.

Why this exists

R's copula package is the most complete copula toolkit in any language. Python's options are fragmented, and roughly 60–70% of R copula's statistical surface has no Python equivalent at all:

• no multiplier-bootstrap goodness-of-fit anywhere;
• no nested Archimedean copulas anywhere, because they need an exponentially tilted stable sampler that does not exist in NumPy, SciPy or any copula package;
• no Khoudraji device, general rotation wrapper, or arbitrary-copula mixtures;
• no Kendall distribution function K, no general Rosenblatt transform;
• not one Python package returns standard errors for a fitted copula;
• families missing under one API: Joe, AMH, Plackett, FGM, Marshall–Olkin, Galambos, Hüsler–Reiss, Tawn, t-EV, Fréchet bounds.

rcopula closes that gap, and proves it: every deterministic quantity is checked against fixtures generated by running the real R package — and separately against the definitions themselves, so agreeing with R cannot be mistaken for being right.

It also goes past R where the gap was worth closing:

• time-varying copulas — Patton (2006) and score-driven (GAS) recursions, plus Engle's DCC for a correlation matrix that moves;
• discrete and mixed margins — the exact inclusion-exclusion likelihood, with the identifiability caveat stated rather than buried;
• vines — R/C/D, in pure NumPy;
• automatic family selection, JSON serialization, and bootstrap confidence intervals with measured coverage.

What copulas are for

Sklar's theorem says any joint distribution splits cleanly into its margins and a copula that carries all the dependence. That separation is the whole point:

• Model dependence and margins independently. Fit each margin however you like — a GARCH residual distribution, a kernel density, a fitted Gamma — then fit the dependence structure separately.
• Dependence measures that don't lie. Kendall's τ and Spearman's ρ are invariant under monotone marginal transforms; Pearson correlation is not. Pearson also reports ~0 for strongly dependent pairs (e.g. y = x²).
• Tail dependence. Gaussian dependence says extreme joint events are essentially impossible. Real markets disagree. A t or Clayton copula prices joint crashes correctly; a Gaussian one does not. This distinction is not cosmetic — it changes VaR materially.

Choosing a family

Install

pip install rcopula

Quick start

import rcopula as rc
from scipy import stats

# Construct and sample
cop = rc.ClaytonCopula(theta=2.0, dim=3)
u = cop.rvs(1000, random_state=42)

cop.pdf(u)  # density
cop.cdf(u)  # distribution function
cop.tau()  # Kendall's tau  -> 0.5
cop.lambda_()  # TailDependence(lower=0.7071, upper=0.0)

# Calibrate from a target dependence
rc.GumbelCopula.from_tau(0.5)  # theta = 2.0

# Fit, with standard errors
res = rc.fit(rc.GumbelCopula(dim=2), u[:, :2], method="mpl")
print(res.summary())

# Attach margins (Sklar, second direction)
mv = rc.CopulaDistribution(
    cop, margins=[stats.norm(1, 2), stats.expon(scale=1 / 3), stats.gamma(2)]
)
x = mv.rvs(1000, random_state=0)

# Goodness of fit
rc.gof_test(rc.ClaytonCopula(dim=3), x, simulation="mult")

Datasets

Nothing is bundled: R copula's datasets are GPL-3 and this package is MIT, so copying them in would be a licence conflict. Instead the loader ships URLs, licences and SHA-256 digests, and fetches permissively-licensed sources on first use.

flood = rc.datasets.load("nwis_peaks")  # USGS, public domain
wine = rc.datasets.load("uci_wine_quality_red")  # UCI, CC BY 4.0
flood.attrs["citation"]

Five sources: USGS annual peak flows and NOAA GHCN-Daily (both live endpoints, so unpinnable), and three static UCI tables — abalone, red wine quality and NASA aerofoil self-noise — whose SHA-256 is checked on every fetch. A test asserts no data file is ever committed.

Examples

Twenty-seven scripts in examples/, each of which runs and asserts its own claims — so they cannot drift out of date without failing:

python examples/04_tail_dependence.py     # what tau does not tell you
python examples/13_hydrology_return_periods.py
pytest tests/test_examples.py             # run them all

They cover the R book chapters; applied finance (CDO tranches, basket and CMS spread options, pairs trading, copula-GARCH, operational risk); hydrology, climate compound extremes, structural reliability and survival analysis; the statistics and machine-learning uses (mutual information, robust covariance, synthetic data, conditional independence); vines; the nine diagnostic plots; time-varying dependence; count data; quasi-random sampling; Archimedean internals at d = 100; nested trees; and what rounding does to a rank statistic.

Coming from R?

The API is Pythonic (scipy/statsmodels verbs), but R's option strings are preserved so you can paste them across.

There is a vine copula tutorial that reproduces Aas et al. (2009) equation by equation — the D-vine and C-vine factorisations agree with the printed formulas to 2e-15, and the paper's count of "12 D-vines and 12 C-vines" in four dimensions is reproduced by enumeration.

The full translation table, an API reference, and the notes on where R is the less accurate side are in the documentation (make docs to read it locally).

How parity is verified

R's RNG cannot be matched bit-for-bit by NumPy, so verification splits in two:

• Deterministic quantities — densities, CDFs, generators, Pickands functions, τ/ρ/λ, iTau/iRho, Rosenblatt transforms, the Kendall function, and every GoF statistic — must match R to ~1e-10.
• RNG-dependent quantities — R's random draws are exported to CSV and fed into Python, making everything downstream deterministic. Fitted parameters must match to ~1e-6 and standard errors to ~1e-5. Only bootstrap p-values remain stochastic, and those are checked statistically.

Fixtures live in tests/golden/ and are committed, so CI needs no R. Regenerate with make golden. A published parity report lists every replicated function and its maximum observed deviation.

License and relationship to R copula

rcopula is MIT. R's copula is GPL-3. No R source code was translated into this project — every algorithm is implemented from its originating published paper, and the R package is used solely as a black-box test oracle. See NOTICE and CONTRIBUTING.md.

rcopula is not affiliated with or endorsed by the authors of the R copula package.