Rscopulas: Copula Modeling for Python and Rust
rscopulas fits, evaluates, and samples copula models on pseudo-observations using a shared Rust core — up to ~100× faster than R's VineCopula stack.
Rscopulas is a copula modeling library for scientists and researchers who need to model statistical dependence structures. It gives you a NumPy-first Python API and a native Rust library, both powered by the same Rust core. You supply pseudo-observations in the open unit hypercube (0, 1)^d, and rscopulas handles fitting, log-density evaluation, sampling, and diagnostics — with validated inputs and reference-tested results throughout.
What is a pseudo-observation?
A pseudo-observation is a data point that has already been transformed to the open unit interval (0, 1). Rscopulas works exclusively with pseudo-observations: it does not estimate marginal distributions for you.
Before calling any rscopulas API, transform each margin of your raw data to uniforms — using a parametric fit, an empirical CDF, or rank-based scaling — then pass the result to the library. Every entry must satisfy 0 < u < 1 strictly; boundary values are rejected with a clear error.
The workflow is: raw data → transform each margin to uniforms → pass pseudo-observations to rscopulas → fit, evaluate, and sample.
Supported copula families
Rscopulas supports a broad range of dependence structures across both the Python and Rust APIs:
- Elliptical: Gaussian, Student t
- Archimedean: Clayton, Frank, Gumbel–Hougaard
- Pair copulas: bivariate pair kernels with h-functions, inverses, and rotations; Khoudraji asymmetric compositions of two base pair kernels
- Vine copulas: C-vine, D-vine, and R-vine with mixed pair families and optional truncation
- Hierarchical Archimedean (HAC): nested Archimedean construction and fitting
Two idiomatic APIs, one Rust core
Rscopulas ships two surfaces over the same compiled Rust library:
| Surface | Description |
|---|---|
Python (rscopulas) | NumPy-first API built with PyO3 and maturin. Includes an optional viz extra for density plots, scatter plots, and vine structure graphs. |
Rust (rscopulas) | Primary library crate with traits, PseudoObs, execution policy (ExecPolicy / Device), and accelerated paths. |
Python users keep a familiar NumPy interface without falling back to pure-Python orchestration on the hot path — the heavy work runs in Rust.
Performance
Rscopulas is benchmarked against R's copula and VineCopula packages on a shared mixed R-vine harness. Representative results from a single development machine (2026-04-18):
| Workload | Rust vs R | Python vs R | Mean times (Rust / Python / R) |
|---|---|---|---|
| Fit | 3.1× | 3.4× | 7.1 ms / 6.5 ms / 22.1 ms |
| Sample | 4.0× | 4.0× | 28.4 ms / 27.9 ms / 112.9 ms |
log_pdf | 114× | 111× | 22.9 µs / 23.5 µs / 2.60 ms |
You can reproduce these numbers locally with python benchmarks/run.py from
the repository root. Results vary by CPU and R package version.
Fit diagnostics
Every call to fit returns a FitResult containing the fitted model and a FitDiagnostics object with log-likelihood, AIC, BIC, a convergence flag, and an iteration count. You can use these to compare models and verify that optimization converged.