API Documentation

pyvinecopulib.core

Core copula classes.

The core API exposes the bivariate copula model (Bicop), the vine copula model (Vinecop), the three flavours of regular vine structure used to describe how pair-copulas compose (RVineStructure, CVineStructure, DVineStructure), and the fit-control objects that carry the hyperparameters for both fits (FitControlsBicop and FitControlsVinecop).

For higher-level scikit-learn-compatible wrappers around these primitives (with fit / predict-style interfaces, DataFrame handling, and ensemble methods), see pyvinecopulib.sklearn. The examples/02_vine_copulas.ipynb and examples/03_vine_copulas_fit_sample.ipynb notebooks walk through end-to-end use of these classes.

Notes

When to use what.

• Bivariate dependence — Bicop. Pick a family explicitly via Bicop.from_family() or fit one from data with Bicop.from_data(); the family set considered during selection is controlled by FitControlsBicop and the family tags from pyvinecopulib.families.

• Multivariate dependence — Vinecop. The factory Vinecop.from_data() runs the Dissmann algorithm by default (tree_algorithm="mst_prim" on FitControlsVinecop); passing "random_weighted" switches to Wilson-weighted random trees instead, and supplying a hand-crafted RVineStructure (or one drawn from RVineStructure.simulate()) skips structure selection entirely.

• C-vine / D-vine special cases — CVineStructure and DVineStructure are the path-shaped and star-shaped specialisations of RVineStructure and can be passed anywhere an R-vine is accepted.

The concepts page is a primer with formulas, the pair-copula construction factorisation, available families, the two-step estimator, and structure selection.

Classes

pyvinecopulib.core.Bicop(*args, **kwargs)	A class for bivariate copula models.
pyvinecopulib.core.BicopLike(*args, **kwargs)	Contract for a bivariate (optionally conditional) pair copula.
pyvinecopulib.core.BicopBase(*args, **kwargs)	Canonical partial implementation of BicopLike.
pyvinecopulib.core.FitControlsBicop(*args, ...)	A class for controlling fits of bivariate copula models.
pyvinecopulib.core.Vinecop(*args, **kwargs)	A class for vine copula models.
pyvinecopulib.core.VinecopLike(*args, **kwargs)	Contract for a post-fit vine-copula evaluator.
pyvinecopulib.core.VinecopBase(*args, **kwargs)	Canonical array-agnostic vine cascades (numpy / torch).
pyvinecopulib.core.FitControlsVinecop(*args, ...)	A class for controlling fits of vine copula models.
pyvinecopulib.core.CVineStructure(*args, ...)	A class for C-vine structures.
pyvinecopulib.core.DVineStructure(*args, ...)	A class for D-vine structures.
pyvinecopulib.core.RVineStructure(*args, ...)	A class for R-vine structures.
pyvinecopulib.core.ConditioningContext(...)	Per-edge conditioning-context assembler.
pyvinecopulib.core.SimplifiedContext(*args, ...)	Simplified vine: forward only the external covariates x.
pyvinecopulib.core.NonSimplifiedContext(...)	Non-simplified vine: x_e = concat([u_D, x]) per edge.

pyvinecopulib.families

Bivariate copula families.

Every bivariate copula model in pyvinecopulib (and every pair-copula inside a vine) belongs to one of the families documented below. The BicopFamily enum holds the family tag; the module-level constants indep, gaussian, … are aliases for the enum members so that callers can write family_set=[gaussian, student] without the qualified prefix. The named family-group constants (parametric, elliptical, itau, …) are pre-built lists you can pass to pyvinecopulib.core.FitControlsBicop / pyvinecopulib.core.FitControlsVinecop to constrain the fitting search space.

See Also

pyvinecopulib.core.BicopBivariate copula model. Its family

attribute is a BicopFamily value.

pyvinecopulib.core.FitControlsBicop, pyvinecopulib.core.FitControlsVinecop

Their family_set argument accepts any of the lists above (or a custom subset).

Notes

Available families, grouped by mathematical class:

• Independence — indep.

• Elliptical — gaussian, student.

• Archimedean (single-parameter) — clayton, gumbel, frank, joe.

• Archimedean — BB family (two-parameter extensions) — bb1, bb6, bb7, bb8.

• Extreme-value — tawn (three parameters); gumbel is also an extreme-value copula.

• Nonparametric — tll (transformation local-likelihood estimator).

See BicopFamily for the per-member identifier.

Family groups — convenience lists of BicopFamily values:

• all — every family above.

• parametric — every family except tll.

• nonparametric — indep, tll.

• one_par — single-parameter parametric families (gaussian, clayton, gumbel, frank, joe).

• two_par — two-parameter parametric families (student, bb1, bb6, bb7, bb8).

• three_par — three-parameter parametric families (tawn).

• elliptical — gaussian, student.

• archimedean — clayton, gumbel, frank, joe, bb1, bb6, bb7, bb8.

• extreme_value — tawn, gumbel.

• bb — bb1, bb6, bb7, bb8.

• itau — families that support estimation by Kendall’s-\(\tau\) inversion (indep, gaussian, student, clayton, gumbel, frank, joe).

• analytic_derivs — families with closed-form derivatives of the density and h-functions (currently every parametric family). pdf_deriv and friends use these closed forms; parametric families outside the group fall back to central finite differences.

• lt — lower-tail dependent families (clayton, bb1, bb7, tawn).

• ut — upper-tail dependent families (gumbel, joe, bb1, bb6, bb7, bb8, tawn).

• rotationless — families that already cover positive and negative dependence and therefore have no rotation (indep, gaussian, student, frank, tll).

The concepts page provides a tabular overview of every family above with parameter ranges, rotations, tail dependence, and closed-form Kendall’s \(\tau\).

Classes

pyvinecopulib.families.BicopFamily(value[, ...])

A bivariate copula family identifier.

pyvinecopulib.utils

Utility primitives used alongside the core copula classes.

This subpackage groups the supporting functionality that copula modelling typically needs but that doesn’t fit inside the pyvinecopulib.core.Bicop / pyvinecopulib.core.Vinecop classes themselves:

• Univariate kernel density estimation — Kde1d is a boundary-corrected 1d KDE with built-in support for continuous and discrete margins. It is the marginal estimator used internally by pyvinecopulib.sklearn.VineDensity / pyvinecopulib.sklearn.VineRegressor and is reusable standalone for any 1d density problem.

• Pseudo-observations — to_pseudo_obs() rank-transforms a data matrix into the unit hypercube, the canonical input shape for fitting copulas.

• Dependence measures — wdm() computes weighted versions of Kendall’s \(\tau\), Spearman’s \(\rho\), Pearson, etc.

• Low-discrepancy sequences — sobol(), ghalton(), and simulate_uniform() (the high-level driver) produce quasi-random uniform points used by Monte-Carlo evaluation of copula CDFs and by random vine-structure generation.

• Plotting helper — pairs_copula_data() produces a pair-plot of a copula sample or a fitted Vinecop.

• Benchmarking — benchmark() runs a quick comparison of available pair-copula families on synthetic data; convenient for smoke-testing a fresh install.

Most users reach for these via pyvinecopulib.sklearn rather than calling them directly. The examples/07_kde1d.ipynb and examples/06_weighted_dependence_measures.ipynb notebooks demo Kde1d and wdm() in isolation.

Notes

The concepts page introduces pseudo-observations (the canonical input shape for copula fits) and dependence measures alongside the vine-copula factorisation.

Classes

pyvinecopulib.utils.Kde1d(*args, **kwargs)

Local-polynomial density estimation in 1-d.

Functions

pyvinecopulib.utils.to_pseudo_obs(x[, ...])
pyvinecopulib.utils.simulate_uniform(n, d[, ...])	Simulates from the multivariate uniform distribution.
pyvinecopulib.utils.wdm(x, y, method[, ...])	Calculates (weighted) dependence measures.
pyvinecopulib.utils.ghalton(n, d[, seeds])	Simulates from the multivariate Generalized Halton Sequence.
pyvinecopulib.utils.sobol(n, d[, seeds])	Simulates from the multivariate Sobol sequence.
pyvinecopulib.utils.pairs_copula_data(data)	Pair plot for copula data U in (0, 1)^d.
pyvinecopulib.utils.benchmark(data)

pyvinecopulib.sklearn

Scikit-learn-compatible vine-copula estimators.

This subpackage wraps the core pyvinecopulib machinery behind the standard sklearn BaseEstimator / fit / predict interface. Four estimators ship:

• VineDensity — non-parametric joint-density estimator. Fits univariate marginals with pyvinecopulib.utils.Kde1d, then a vine copula on the resulting pseudo-observations. Exposes score_samples / pdf / cdf / sample.

• VineRegressor — non-parametric conditional mean / quantile regressor built from a vine copula over (Y, X). Predictions are weighted statistics of the training responses.

• VineForestDensity and VineForestRegressor — ensembles of the above, fit on randomly sampled vine structures and pruned via a model-confidence-set selector. Predictions average across surviving members.

If you have not used vine copulas before, the concepts page introduces pair copulas, R-vines, and the default Transformed Local Likelihood (TLL) pair-copula family in ~5 minutes.

Requires scikit-learn, pandas, joblib, and scipy. Install with pip install pyvinecopulib[sklearn].

Notes

Backends. By default the estimators run on Vinecop (the default backend), so the sklearn module does not require PyTorch. Pass a configured TorchVinecopBackend via the backend= kwarg to route through the torch backend instead — see pyvinecopulib.sklearn.backends for a comparison and examples.

DataFrame input. Every estimator accepts both NumPy arrays and pandas DataFrames. DataFrames may mix numeric, ordered-categorical, and unordered-categorical columns; the latter are expanded to ordered {0, 1} dummies before fitting, and the same expansion is re-applied at predict time.

Low-level knobs. Pair family, threading, structure-selection algorithm, etc. are passed through to pyvinecopulib.core.FitControlsVinecop and pyvinecopulib.core.RVineStructure (carried inside the backend object). Reach for those directly whenever you need control beyond the sklearn convenience layer. See each class docstring for the full methodology and references.

Classes

pyvinecopulib.sklearn.VineDensity([backend, ...])	Vine-copula based density estimator.
pyvinecopulib.sklearn.VineForestDensity([...])	Forest of vine-copula density estimators.
pyvinecopulib.sklearn.VineForestRegressor([...])	Forest of vine-copula regressors.
pyvinecopulib.sklearn.VineRegressor([mean, ...])	Vine-copula based regressor (mean and quantile).

pyvinecopulib.sklearn.backends

Backends for the sklearn vine-copula estimators.

Each backend is a configured adapter that knows how to fit a vine on pseudo-observations and how to evaluate pdf / cdf / simulate on that vine. Two concrete backends ship:

• VinecopBackend (default) — wraps Vinecop. Holds an optional FitControlsVinecop and an optional RVineStructure. No PyTorch dependency; this is what the sklearn module uses out of the box.

• TorchVinecopBackend — wraps pyvinecopulib.torch.TorchVinecop. Holds an optional pyvinecopulib.torch.FitControlsTorchVinecop and an optional RVineStructure. Constructing this class triggers the torch import (it’s the explicit opt-in signal).

Notes

Which backend should I pick?

Stay on the default (VinecopBackend) when you want the fastest CPU-bound vine fits, multi-threaded evaluation (controls.num_threads), the full parametric pair-copula family set (Gaussian, Student, Clayton, Gumbel, Frank, Joe, BB families, …) and the non-parametric Transformed Local Likelihood (TLL) family — all backed by Vinecop.

Switch to TorchVinecopBackend when you need any of:

• GPU placement — drop a fitted vine on the GPU with .to("cuda") and evaluate batched pdf / cdf / simulate calls there.

• Autograd — the entire cascade is built from differentiable PyTorch ops, so gradients flow back through pdf / Rosenblatt outputs to any upstream parameters (e.g. learned marginals or feature transforms).

• Composition with PyTorch pipelines — the vine is a torch.nn.Module that drops into any other model.

The torch backend currently supports the TLL family only (which is both the default and what the GPU path is built around); other parametric families require VinecopBackend.

Examples

Pass a configured backend instance to any sklearn estimator via backend=:

from pyvinecopulib.sklearn import VineDensity
from pyvinecopulib.sklearn.backends import (
    VinecopBackend, TorchVinecopBackend,
)
from pyvinecopulib.torch import FitControlsTorchVinecop
import pyvinecopulib as pv
import torch

VineDensity()                                          # default
VineDensity(backend=VinecopBackend(
    controls=pv.FitControlsVinecop(num_threads=4),
))
VineDensity(backend=TorchVinecopBackend(
    controls=FitControlsTorchVinecop(
        device="cuda", dtype=torch.float32,
    ),
))

Classes

pyvinecopulib.sklearn.backends.VinecopBackend(*)	Default backend.
pyvinecopulib.sklearn.backends.TorchVinecopBackend(*)	PyTorch backend.

Functions

pyvinecopulib.sklearn.backends.resolve_backend(backend)

Coerce a user-supplied backend= value to a concrete backend.

pyvinecopulib.torch

PyTorch backend for vine copula evaluation.

This subpackage is a pure-PyTorch port of the evaluation chain in pyvinecopulib.core. Pick it when you need any of:

• GPU placement — every class is a torch.nn.Module, so .to("cuda") moves an entire vine to the GPU in one line.

• Autograd compatibility — the cascade is built from differentiable ops, so the joint density / Rosenblatt outputs flow gradients back to any upstream parameters (e.g. learned marginals or transforms).

• Composition with PyTorch pipelines — the modules drop in next to any other torch.nn.Module and respect the standard train / eval / state_dict protocol.

The default fits use the TLL family — Transformed Local Likelihood (Geenens 2014 [1]; Nagler 2018 [2]) — a non-parametric pair-copula estimator that fits a kernel density on a grid in the inverse-normal-transformed copula space. This is the same family exposed as tll and is the default everywhere in pyvinecopulib because it captures arbitrary non-Gaussian-like dependence without picking a parametric form.

If you have not used vine copulas before, the concepts page introduces pair copulas and R-vines in ~5 minutes.

Requires PyTorch. Install with pip install pyvinecopulib[torch].

See Also

pyvinecopulib.core : Reference vine-copula evaluators (default everywhere). pyvinecopulib.sklearn : sklearn-compatible vine-copula estimators that route through either backend.

Notes

What’s exposed.

• TorchBicop — evaluator for a single bivariate pair copula on a density grid. Build from a fitted Bicop via TorchBicop.from_bicop(), or fit directly from data via TorchBicop.from_data() (which dispatches on FitControlsTorchBicop: pure-torch TLL). Exposes the standard surface: pdf / cdf / hfunc1 / hfunc2 / hinv1 / hinv2 / simulate.

• TorchVinecop — evaluator for a full R-vine built on top of TorchBicop pair copulas. Provides pdf / cdf / rosenblatt / inverse_rosenblatt / simulate with the same signatures as Vinecop. The cascade mirrors Vinecop byte-for-byte; pdf / rosenblatt also accept batched=True (one stacked bicop call per tree level).

• FitControlsTorchBicop, FitControlsTorchVinecop — fit-time control dataclasses mirroring FitControlsBicop / FitControlsVinecop. Bundle method selection and method-specific knobs.

References

[1]

Geenens, G. (2014). Probit Transformation for Kernel Density Estimation on the Unit Interval. JASA 109(505), 346–358 — original TLL motivation.

[2]

Nagler, T. (2018). A Generic Approach to Nonparametric Function Estimation with Mixed Data. Statistics & Probability Letters 137, 326–330 — multivariate TLL.

Classes

pyvinecopulib.torch.TorchBicop([...])	PyTorch evaluator for a bivariate copula stored as a density grid.
pyvinecopulib.torch.TorchVinecop(...[, context])	PyTorch R-vine copula evaluator built on TorchBicop.
pyvinecopulib.torch.FitControlsTorchBicop([...])	Controls for from_data().
pyvinecopulib.torch.FitControlsTorchVinecop([...])	Controls for from_data() and the cascade.