Concepts
A self-contained tour of the ideas behind pyvinecopulib. The
emphasis is on the formulas you’ll see in docstrings and the API
classes that implement them. Skimming this page first should make
the rest of the documentation much easier to navigate; revisit it
whenever a docstring throws an unfamiliar symbol your way.
Sklar’s theorem and pseudo-observations
A copula is a multivariate distribution with uniform-\([0, 1]\) marginals. By Sklar’s theorem (Sklar, 1959), every joint distribution \(F\) on \(\mathbb{R}^d\) factorizes as
where \(F_1, \ldots, F_d\) are the marginal CDFs and \(C : [0, 1]^d \to [0, 1]\) is the copula. When the marginals are continuous \(C\) is unique. Differentiating both sides gives the corresponding density factorization
so the log-likelihood splits cleanly into a sum of marginal log-likelihoods and a copula log-likelihood:
This justifies a two-step inference-functions-for-margins estimator (Joe & Xu, 1996): first fit the \(d\) univariate marginals; then fit the copula on the pseudo-observations
Both halves of that factorization are first-class here. The marginal
half is the pyvinecopulib.margins subpackage — nonparametric by
default (pyvinecopulib.core.Kde1d, a boundary-corrected 1-d
KDE that also handles ordered-discrete data), parametric with family
selection when you want it, or any distribution object you already
have. The copula half is pyvinecopulib.core.Bicop and
pyvinecopulib.core.Vinecop. The object that holds both, and so
gives you \(f\) and \(F\) on the scale of the data rather than
on the copula scale, is pyvinecopulib.core.Vinedist — see
Vine distributions.
Two convenience helpers convert raw data to pseudo-observations and measure dependence on them:
pyvinecopulib.utils.to_pseudo_obs()ranks each column to \((0, 1)\), the canonical input shape for the copula classes.pyvinecopulib.utils.wdm()computes weighted versions of Kendall’s \(\tau\), Spearman’s \(\rho\), Blomqvist’s \(\beta\), Hoeffding’s \(D\), and Pearson correlation — margin-free dependence measures that drive both diagnostics and Dissmann’s structure-selection heuristic.
Most of this page is about \(c\) — how a vine represents and fits it, which is where the modeling choices live. Keep in mind while reading that the marginal factor never goes away: it is what makes the model a distribution rather than a dependence structure, and it is the factor that Vine distributions puts back.
Bivariate copulas
The atomic object is the bivariate copula
pyvinecopulib.core.Bicop. It exposes the standard surface
expected from a \(d = 2\) distribution on
\([0, 1]^2\):
\(c(u_1, u_2)\) — copula density —
pyvinecopulib.core.Bicop.pdf();\(C(u_1, u_2)\) — copula CDF —
pyvinecopulib.core.Bicop.cdf();random sampling on \([0, 1]^2\) —
pyvinecopulib.core.Bicop.sample().
Pair copulas inside a vine also need h-functions, the partial conditional CDFs
and their inverses \(h_1^{-1}\), \(h_2^{-1}\). These map to
pyvinecopulib.core.Bicop.hfunc1(),pyvinecopulib.core.Bicop.hfunc2(),pyvinecopulib.core.Bicop.hinv1(),pyvinecopulib.core.Bicop.hinv2().
H-functions are the core operation of vine evaluation: they turn the
\([0, 1]^2\) outputs of one tree into the conditional
pseudo-observations consumed by the next, and their inverses drive
pyvinecopulib.core.Vinecop.sample() and
pyvinecopulib.core.Vinecop.inverse_rosenblatt().
Every Bicop belongs to one of the families catalogued in
Available families below; switch families via
pyvinecopulib.core.FitControlsBicop.
Vine structures
Estimating a fully-flexible \(d\)-dimensional copula directly is hard once \(d\) is larger than a handful. Pair-copula constructions (Joe, 1996; Bedford & Cooke, 2001, 2002) sidestep that by decomposing the joint copula density into a product of \(d(d-1)/2\) bivariate building blocks. The order of conditioning is encoded by a graphical object called a vine.
Definition (regular vine)
A regular vine (R-vine) on \(d\) variables is a sequence of trees \((V_t, E_t)\), \(t = 1, \ldots, d - 1\), with
\(V_1 = \{1, \ldots, d\}\),
\(V_t = E_{t-1}\) for \(t \ge 2\),
the proximity condition: two nodes in \((V_{t+1}, E_{t+1})\) are connected only if the corresponding edges in \((V_t, E_t)\) share a node.
A vine copula labels each edge \(e \in E_t\) with a conditioned set \(\{j_e, k_e\}\) and a conditioning set \(D_e \subset \{1, \ldots, d\} \setminus \{j_e, k_e\}\), plus a bivariate pair-copula \(c_{j_e, k_e \mid D_e}\) describing the conditional dependence between \(U_{j_e}\) and \(U_{k_e}\) given \(\mathbf U_{D_e}\). See Czado & Nagler (2022) for a textbook treatment.
In pyvinecopulib the structure object is
pyvinecopulib.core.RVineStructure, with the two well-known
specializations
pyvinecopulib.core.DVineStructure— every tree is a path; convenient for ordered-conditioning regression.pyvinecopulib.core.CVineStructure— every tree is a star; convenient when one variable drives the others.
Both can be passed anywhere an R-vine is accepted, and
sample() draws structures uniformly at
random (Joe, 2011) — the basis of the
Structure selection section below.
Pair-copula construction
With the structure fixed, the vine-copula density factorizes as
where the conditional pseudo-observations \(u_{j_e \mid D_e} = C_{j_e \mid D_e}(u_{j_e} \mid \mathbf u_{D_e})\) are obtained tree-by-tree from h-functions of the lower-tree pair copulas. Concretely, if an edge in tree \(t + 1\) has conditioned set \(\{j, k\}\) and conditioning set \(D \cup \{\ell\}\), then
i.e. the conditional pseudo-obs at level \(t + 1\) is an
h-function of the pair-copula one level down. This recursive
structure is what
pyvinecopulib.core.Vinecop.rosenblatt() evaluates forward
(data \(\to\) independent uniforms) and what
pyvinecopulib.core.Vinecop.inverse_rosenblatt() evaluates
backward (uniforms \(\to\) data — used by
pyvinecopulib.core.Vinecop.sample()).
CDF evaluation is harder: there is no closed form for
\(C(\mathbf u)\) in general, so
pyvinecopulib.core.Vinecop.cdf() uses Monte-Carlo integration
with the quasi-random uniforms produced by
pyvinecopulib.utils.sample_uniform()
(sobol() or
ghalton() sequences). Increase N to
trade compute for accuracy.
The same factorization backs the PyTorch port
pyvinecopulib.torch.TorchVinecop (every pair copula is a
pyvinecopulib.torch.TorchTllBicop); its cascade matches
pyvinecopulib.core.Vinecop’s to floating-point tolerance, and
additionally
offers a batched=True fast path, which fires one stacked pair-copula
call per group of edges that do not depend on each other – a tree level
for pdf and rosenblatt, a level of the dependency graph for
inverse_rosenblatt.
Simplifying assumption
The conditional pair-copulas in the previous section may, in principle, depend on the conditioning value \(\mathbf u_{D_e}\). The simplifying assumption states that they do not:
Under this assumption the model reduces to a collection of
two-dimensional copulas, which is what makes vines practical.
The choice of vine structure becomes required — different
structures yield different approximations of the same true
density. See Stoeber, Joe & Czado (2013), Spanhel & Kurz (2019)
and Nagler (2025) for the theoretical discussion. Every fit in
pyvinecopulib.core.Vinecop (and hence the sklearn /
torch wrappers) uses the simplified model;
pyvinecopulib.core.FitControlsVinecop controls which
families to consider, which structures to search, and how to
truncate the model in higher dimensions.
A vine’s controls are pair controls:
FitControlsVinecop derives from
FitControlsBicop, so one object configures both
halves of a vine fit – the vine reads the settings it owns, and the rest reach
its pair copulas unchanged. That is why
select(), which chooses a structure, is
annotated with the vine controls while
fit(), which has no structure to choose, is
annotated with the pair controls: the narrower type is all fit reads, and a
vine controls object satisfies it. The same holds for
FitControlsTorchVinecop.
The array-agnostic VinecopBase can go
further: a NonSimplifiedContext lets each
pair copula also depend on its conditioning-set value
\(\mathbf u_{D_e}\), giving a actually non-simplified vine.
External covariates are a separate axis: the default
SimplifiedContext forwards them too, so an
x-dependent copula may still satisfy the simplifying assumption.
Both are advanced extension points (see Extending: custom and conditional pair copulas) —
the built-in fit stays simplified and independent of external
covariates.
Available families
Every pair-copula in pyvinecopulib belongs to one of the families
below. The first column links the family constant, which lives on
pyvinecopulib.families and can be passed to
pyvinecopulib.core.FitControlsBicop.family_set
(or the same attribute on
pyvinecopulib.core.FitControlsVinecop) to restrict the
fit-time search space.
Parameter ranges below are the conventional textbook ones; the
exact bounds Bicop enforces are visible via
pyvinecopulib.core.Bicop.parameters_lower_bounds and
pyvinecopulib.core.Bicop.parameters_upper_bounds. The
“Kendall’s \(\tau\)” column says how
pyvinecopulib.core.Bicop.parameters_to_tau() obtains the value:
in closed form, or by quadrature.
parameters_to_tau() is available for every
family. Its inverse tau_to_parameters() is
not: it needs \(\tau\) to determine the parameters completely, which
holds only for the one-parameter families indep, gaussian,
clayton, gumbel, frank and joe. In particular it raises for
student, even though student belongs to
pyvinecopulib.families.itau — that group means “fittable by
inverting \(\tau\)”, not “invertible here”, because \(\tau\) pins
the correlation and leaves the degrees of freedom free.
Family |
Identifier |
Type |
Pars |
Range |
Rotations |
Tail dep. |
Kendall’s \(\tau\) |
|---|---|---|---|---|---|---|---|
Independence |
|
— |
0 |
— |
none |
none |
\(0\) |
Gaussian |
|
elliptical |
1 |
\(\rho \in (-1, 1)\) |
rotationless |
none |
\((2/\pi) \arcsin \rho\) |
Student |
|
elliptical |
2 |
\(\rho \in (-1, 1)\), \(\nu > 2\) |
rotationless |
symmetric |
\((2/\pi) \arcsin \rho\) |
Clayton |
|
Archimedean |
1 |
\(\theta > 0\) |
0° / 90° / 180° / 270° |
lower |
\(\theta / (\theta + 2)\) |
Gumbel |
|
Arch. / EV |
1 |
\(\theta \ge 1\) |
0° / 90° / 180° / 270° |
upper |
\(1 - 1/\theta\) |
Frank |
|
Archimedean |
1 |
\(\theta \in \mathbb{R} \setminus \{0\}\) |
rotationless |
none |
via Debye function |
Joe |
|
Archimedean |
1 |
\(\theta \ge 1\) |
0° / 90° / 180° / 270° |
upper |
series expansion |
BB1 |
|
Arch. (2-par) |
2 |
\(\theta > 0\), \(\delta \ge 1\) |
0° / 90° / 180° / 270° |
lower + upper |
closed form |
BB6 |
|
Arch. (2-par) |
2 |
\(\theta \ge 1\), \(\delta \ge 1\) |
0° / 90° / 180° / 270° |
upper |
by quadrature |
BB7 |
|
Arch. (2-par) |
2 |
\(\theta \ge 1\), \(\delta > 0\) |
0° / 90° / 180° / 270° |
lower + upper |
by quadrature |
BB8 |
|
Arch. (2-par) |
2 |
\(\theta \ge 1\), \(\delta \in (0, 1]\) |
0° / 90° / 180° / 270° |
upper |
by quadrature |
Tawn |
|
extreme-value |
3 |
bounded; see
|
0° / 90° / 180° / 270° |
upper (asymmetric) |
by quadrature |
TLL |
|
nonparametric |
— |
— |
data-driven |
data-driven |
rank-based |
The non-elliptical, non-radially-symmetric parametric families are
labeled with a rotation in
\(\{0°, 90°, 180°, 270°\}\); rotation 0° is the base form
(positive dependence, lower-tail-heavy for Clayton, upper-tail-heavy
for Gumbel / Joe, …), 180° is the survival copula (covers the
opposite tail), and 90° / 270° provide negative dependence variants.
pyvinecopulib.core.Bicop.flip() flips between rotations
0° \(\leftrightarrow\) 180° and 90° \(\leftrightarrow\) 270°.
Each fitted pair copula also reports its tail-dependence coefficients in the
four corners of the unit square as the read-only
taildep matrix (NaN for tll) and
Blomqvist’s \(\beta = 4\,C(0.5, 0.5) - 1\) as
beta; the maps
parameters_to_taildep() and
parameters_to_beta() evaluate them at arbitrary
parameters.
Family-group constants (also in pyvinecopulib.families) are
pre-built lists you can pass directly to
family_set:
all— every family listed above.parametric— every family excepttll.nonparametric—indepandtll.one_par/two_par/three_par— grouped by parameter count (one-parameter parametric / two-parameter parametric / three-parameter parametric).elliptical—gaussian,student.archimedean—clayton,gumbel,frank,joe,bb1,bb6,bb7,bb8.extreme_value—tawn,gumbel.bb—bb1,bb6,bb7,bb8.rotationless— families that already cover both positive and negative dependence (indep,gaussian,student,frank,tll).lt/ut— families with lower- / upper-tail dependence.itau— families that support estimation by Kendall’s-\(\tau\) inversion (indep,gaussian,student,clayton,gumbel,frank,joe).
The notebook examples/01_bivariate_copulas.ipynb walks through
a fit on synthetic data for several of these families.
Estimation
Vine fitting is a two-step procedure inherited from Sklar’s theorem and pseudo-observations:
Marginals. Each \(F_j\) is estimated independently —
pyvinecopulib.core.Kde1d(a boundary-corrected 1-d KDE) is the default both for the sklearn estimators and the notebook examples.Kde1dsupports continuous, integer-discrete, and zero-inflated numerical input via itsvar_typeargument. Raw categorical labels are not accepted; encode them before fitting only when an integer-valued model is appropriate.Copula. Given pseudo-observations \(\hat U_{i \cdot} = (\hat F_1(X_{i,1}), \ldots, \hat F_d(X_{i,d}))\), the joint copula is fit by
pyvinecopulib.core.Vinecop.from_data()(orpyvinecopulib.core.Vinecop.select()for in-place re-fitting).
The pair-copula estimator on each edge depends on the chosen
family. Three regimes are available via
pyvinecopulib.core.FitControlsBicop:
Maximum likelihood (
parametric_method="mle") — the default for parametric families; numerically optimizes the per-edge log-likelihood under the family’s parameter constraints.Kendall’s :math:`tau` inversion (
parametric_method="itau") — restricted to families in theitaugroup; usestau_to_parameters()to back out the parameters from the empirical \(\hat\tau\). Cheaper than MLE and the conventional choice for very high-dimensional vines.Nonparametric TLL (family
tll—pyvinecopulib.families.tll) — Transformed Local Likelihood (Geenens, 2014; Nagler, 2018). The copula density is estimated on a grid in the inverse-normal-transformed space \((z_1, z_2) = (\Phi^{-1}(u_1), \Phi^{-1}(u_2))\), where local-likelihood machinery is well-behaved at the boundary of the unit square. Bandwidth selection is automatic; thenonparametric_methodandnonparametric_multknobs onFitControlsBicoptune the kernel order and the bandwidth multiplier respectively.
TLL is the default family for both
Vinecop and
TorchVinecop because it captures
arbitrary non-Gaussian-like dependence (heavy tails, asymmetry)
without committing to a parametric form, and
because its density-grid representation is exactly what
pyvinecopulib.torch.TorchTllBicop consumes for GPU and
autograd evaluation.
Family selection across the parametric set runs by AIC / BIC /
mBIC inside pyvinecopulib.core.Bicop.select(); choose the
selection criterion via
pyvinecopulib.core.FitControlsBicop.selection_criterion.
For asymptotics on a parametric fit, both Bicop and Vinecop expose the
log-likelihood score (scores), its observation-average (gradient), the
Hessian (hessian), and the score covariance (scores_cov) at the fitted
parameters; on Vinecop these accept an optional per-observation
parameters matrix for evaluation off the fitted point.
Vine distributions
A vine copula is a model for dependence: everything on the preceding
sections lives on the copula scale, \(u \in [0, 1]^d\). A vine
distribution is Sklar’s theorem as an object —
pyvinecopulib.core.Vinedist pairs any vine with one univariate
margin per variable, and evaluates on the scale of the data:
dist = pv.Vinedist.from_data(y) # Kde1d margins by default
dist.logpdf(y) # log f(y), not log c(u)
dist.sample(1000, seeds=[1]) # draws on the data scale
dist.cdf(y)
Without it, using a fitted vine as a distribution means recomputing \(\hat F_j(x_j)\) by hand, assembling the copula-scale matrix, evaluating \(\log c\), and adding \(\sum_j \log \hat f_j(x_j)\) back — a chain that is easy to get subtly wrong, and one whose discrete case needs a second column per variable with atoms.
The marginal contract
A margin is anything with pdf, cdf and icdf (the inverse
cdf). That is the whole required surface — the
pyvinecopulib.core.MarginLike protocol — and it is
small, because every member added is one a foreign distribution object
must happen to have. Structural implementations of the protocol and Kde1d
are accepted directly. scipy.stats distributions
distributions are adapted automatically, as are continuous
torch.distributions families that implement cdf (including Normal,
Gamma and LogNormal). Torch distributions with atoms are rejected
because they do not expose the left-limit cdf a vine needs;
pyvinecopulib.margins.as_margin() adapts what needs adapting and
is idempotent, and
pyvinecopulib.margins.register_margin_adapter() teaches it about
an ecosystem it does not know.
One definition does most of the work. pdf means the density with
respect to the margin’s own reference measure: a Lebesgue density for a
continuous margin, a probability mass at an atom, and whichever applies
pointwise for a mixed one. Write \(w_j\) for that quantity,
and the log-density identity of Sklar’s theorem and pseudo-observations holds verbatim in every case:
There is no discreteness branch in the likelihood path — the discrete
pair-copula density already divides by the marginal mass
(Discrete data), so \(w_j\) cancels exactly where it
should. This is why pdf and not pmf is the name on the protocol,
and it is worth knowing when adapting a foreign object: in SciPy’s newer
distribution API pdf at an atom is \(+\infty\), and the mass is
pmf, so a discrete SciPy object must be routed through
as_margin rather than passed straight through.
Everything past pdf / cdf / icdf carries a default in the
protocol: var_type ("c", "d", "zi"), cdf_left
for \(F(y^-)\), logpdf, sample, support,
supports_covariates / supports_weights, and the fit / select
/ controls_class a vine distribution calls. Each default is the fallback
its consumer would otherwise apply, so a margin that inherits
MarginLike and defines only pdf / cdf /
icdf behaves as a fixed, unconditional, continuous margin.
Exogenous conditional distributions
An exogenous conditional distribution \(Y \mid X=x\) is distinct from both a non-simplified vine and conditioning-set sampling. It applies the same row-aligned covariate matrix, shape \((n, p)\), to the two halves of Sklar’s factorization:
A custom margin or vine opts in with supports_covariates=True.
pyvinecopulib.core.Vinedist then validates that x is
two-dimensional with one row per observation and forwards that same
matrix to every conditional component. Unconditional components remain
valid alongside them and simply do not receive x.
There is no built-in fitter for both conditional halves.
pyvinecopulib.core.Vinedist.from_data() can fit a custom
conditional margin specification, but its automatic copula fit is the
x-independent pyvinecopulib.core.Vinecop. When dependence
must vary with \(X\), fit custom pairs through
pyvinecopulib.core.VinecopBase.fit(), host them in a
VinecopBase subclass that declares covariate support, and compose the
parts explicitly. examples/03_vine_distributions.ipynb checks such
a model against an analytic bivariate-normal density; notebook 10
develops the custom-pair machinery.
The inherited Monte-Carlo pyvinecopulib.core.VinecopBase.cdf()
does not support external covariates, because each integration draw
would need the corresponding conditional design. Consequently
pyvinecopulib.core.Vinedist.cdf() also raises for this custom
conditional vine. Density, Rosenblatt transforms, likelihood, and
sampling do accept row-aligned x.
Choosing margins
Which class each margin is comes from the distribution:
VinedistBase.margin_class, beside the vinecop_class that names its
copula half. pv.Vinedist names Kde1d; naming another is a two-line
subclass, and it is what the sklearn estimators’ distribution= selects
too. What varies per column is configuration and declaration, and they are
separate arguments: margin_controls= says how a margin is fitted or
selected, and var_types= / supports= say what the variable is –
one entry per variable, exactly as var_types does on
pyvinecopulib.core.Bicop.from_data().
pv.Vinedist.from_data(y) # `Kde1d` per column
class ParametricVinedist(pv.Vinedist): # a SciPy family per column
margin_class = SciPyMargin
ParametricVinedist.from_data(
df,
margin_controls={"income": FitControlsMargin(selection_criterion="bic")},
supports=[(0.0, None), None], # bound one column only
)
Margins follow the same construct-then-fit pattern as Bicop,
Vinecop and Kde1d, with fit returning self. One class is
therefore both the specification and the fitted object, which is what lets a
distribution composed by construction mix the two: a margin with no fit of
its own is fixed, so pv.Vinedist(copula, [frozen, Kde1d()]).fit(y)
re-estimates the second and leaves the first exactly as it was built.
Choosing that family is pyvinecopulib.margins.SciPyMargin.select(),
a method on the margin rather than a separate class – the shape
pyvinecopulib.core.Bicop.select() has always had, so after the call the
margin is the winning family. Two choices in it have reasons. The candidate
set is curated and partitioned by support, not “every family in SciPy”: an
unconstrained sweep is actively misleading, because a family whose reported
support is wider than its density integrates over can win on likelihood without
being a candidate any statistician would accept. And a candidate that
fails is refused with a reason rather than silently skipped — a
column where every candidate fails raises, naming each family and why.
on_failure="fallback" asks for a KDE margin instead, with one
warning; it is never a normal, since marginal misspecification distorts
the pseudo-observations and biases the copula.
What a bound means to the KDE margin
Kde1d takes xmin and xmax, and stating them is worth doing
whenever the support is actually known: without them the fitted grid is
padded past the data, so a variable that cannot be negative picks up
density below zero. What a bound means depends on the variable type,
and the three cases differ in ways worth knowing.
For a continuous variable the bounds are the support, and the fit
transforms onto them — a probit transform when both ends are finite, a
fourth-root one when a single end is. Two consequences: the transform is
where an explicitly supplied bandwidth is interpreted, so
kde.bandwidth is not on the data’s scale for a bounded fit; and a
one-sided fit is scale equivariant, so fitting in meters and in
millimeters give the same answer after rescaling.
For a discrete variable the bounds are the integer support — the
lowest and highest level that can occur — and both they and the data must
be integers. Fitting jitters tied observations within their unit cells,
so the fitted grid runs from xmin - 0.5 to xmax + 0.5: half a unit
wider at each end, because that is where the boundary cells stop. The
grid you read back therefore overhangs the bounds you gave, which is
correct rather than surprising — the probability mass is formed from the
density at the integer levels alone and normalized over the declared
support, so pdf is exactly zero outside it. Negative levels are fine.
For a zero-inflated variable the bounds constrain only the continuous
part. The exact zeros are a separate point mass and need not lie inside
[xmin, xmax], while every nonzero observation must; and no half-unit
adjustment applies, since there are no jitter cells.
boundary_repair (on by default) lets a finite endpoint be fitted with
a dedicated boundary estimator rather than the transformed bulk fit. It is
eligibility rather than a guarantee: it needs a finite bound and at least
sixteen observations, and an endpoint whose local behavior is ambiguous
keeps the bulk estimate. With neither bound set it does nothing.
The status quo as a special case
pyvinecopulib.utils.to_pseudo_obs() is the scaled empirical cdf
\(\tfrac{n}{n + 1} \hat F^{\text{ECDF}}_j\), so fitting a Vinecop
on to_pseudo_obs(x) is fitting a vine distribution whose margins are
that rank transform. The familiar workflow did not become a different
thing; it became the configuration in which the margins carry no
parameters of their own.
What that configuration cannot give you is a joint density. The empirical
distribution is atomic — it has no density with respect to Lebesgue
measure — so there is nothing to multiply the copula density by, and no
log-likelihood on the original scale. Kde1d is the smoothed version of
the same idea and does have one, which is why it is the default margin
rather than the ranks.
What two-step estimation costs
from_data estimates the margins first and then the copula on the
resulting pseudo-observations — the inference-functions-for-margins
estimator (Joe & Xu, 1996). It is consistent and it is what makes
high-dimensional vines tractable, but it is not full maximum
likelihood, and three consequences are worth stating:
Standard errors from the copula step alone are too small, because they condition on \(\hat F_j\) as if it were \(F_j\). Valid inference needs the sandwich form that accounts for the marginal estimation (Godambe, 1991).
Marginal error propagates into the copula, not the reverse. A misspecified margin distorts every pseudo-observation and therefore the fitted dependence; a misspecified copula leaves the marginal fits untouched. Spend the modeling effort accordingly.
Family selection is itself an estimation step. A likelihood or an interval computed at the selected margin ignores the selection, and a winner that beat the runner-up by a fraction of an AIC unit is not an established family. Where the distinction matters, name the family instead of searching for it —
SciPyMargin("gamma")fits the family you chose, andselect()on a named margin leaves it alone — or refit the shortlist yourself and compare the criteria you care about.
examples/03_vine_distributions.ipynb works through the whole
surface, including a mixed continuous / count example and a custom
margin written against pyvinecopulib.core.MarginBase.
Discrete data
Sklar’s theorem does not identify a unique copula when a margin has
atoms, so a discrete variable cannot be summarized by
\(\hat F_j(x)\) alone: the estimator also needs the left limit
\(\hat F_j(x^-)\), the value the cdf takes just below the jump.
Mark which variables are discrete with var_types — "c" for
continuous, "d" for discrete, one entry per variable — and supply
the extra column each discrete variable needs.
There are two ways to lay those columns out, and every method taking
u accepts either:
Expanded, \(n \times 2d\): the \(d\) cdf values, then \(d\) left-limit values. The left-limit column of a continuous variable is simply equal to its cdf column.
Compact, \(n \times (d + k)\): the \(d\) cdf values, then one left-limit column per discrete variable, in variable order. With \(k\) discrete variables out of \(d\), this is the expanded layout with the redundant continuous columns dropped.
The two agree exactly — the compact form only omits columns that carry no information. For an all-continuous model \(k = 0\) and both collapse to the familiar \(n \times d\) matrix.
You only assemble those columns when you are working with a copula
directly. pyvinecopulib.core.Vinedist builds the compact layout
itself from each margin’s cdf and cdf_left, so a model with
atom-carrying margins takes the plain \(n \times d\) data matrix and
the left limits never surface in user code (Vine distributions).
The reason the same likelihood formula covers continuous, discrete and
mixed variables without a branch is that the pair-copula density below
divides by the marginal mass, which is exactly the factor the marginal
term contributes.
The same rule applies pairwise to pyvinecopulib.core.Bicop
(\(n \times 4\) expanded, \(n \times (2 + k)\) compact) and to
the conditioning values passed to
pyvinecopulib.core.Vinecop.sample_conditional(), where a
discrete conditioning variable likewise contributes two columns.
The examples/04_discrete_variables.ipynb notebook works an example
end to end, from raw counts to a fitted vine;
examples/03_vine_distributions.ipynb shows the same model as a
distribution, with the layout handled for you.
Two arguments elsewhere in the API are consequences of the same non-uniqueness, and both change what you get rather than only how fast you get it:
randomize_discrete(onpyvinecopulib.core.Vinecop.rosenblatt(), defaultTrue) decides what the transform returns at an atom. The conditional distribution there is an interval, not a point, so the transform draws uniformly within \([F(x^-), F(x)]\). That is what makes the output actually uniform — the randomized transform is the one whose distributional statement holds — but it also makes the call non-deterministic. Passseedsto reproduce it, orrandomize_discrete=Falseto take the upper endpoint instead and accept output that is not uniform.step_wise(on theVinecopscore family:scores,gradient,hessian,scores_cov) selects which likelihood is differentiated.Truedifferentiates the step-wise (sequential, tree-by-tree) estimator that was actually fitted;Falsedifferentiates the joint likelihood. They answer different questions: the step-wise gradient vanishes at the fitted model by construction, the joint one does not. Sandwich standard errors for a sequentially fitted vine want the step-wise form.
Saving and loading models
Bicop, Vinecop, RVineStructure, Kde1d and Vinedist
all serialize the same way. to_file / from_file write and read a
file; to_json / from_json do the same through a string:
vine.to_file("model.json") # JSON text
vine.to_file("model.cbor") # binary CBOR
reloaded = pv.Vinecop.from_file("model.cbor")
The format follows the filename: a name ending in .cbor selects
binary CBOR, anything else JSON. CBOR is smaller
and faster to parse and is the better choice for large vines; JSON stays
the default because it is readable and diffable.
These classes also pickle, which serializes through the JSON form, so a
fitted model round-trips through anything that speaks pickle
(copy.deepcopy, joblib, a multiprocessing queue). The
pyvinecopulib.sklearn estimators pickle as ordinary estimators.
A Vinedist stores both halves: the copula through its own
to_json, and one payload per margin. The margins this package ships
– Kde1d and SciPyMargin – serialize
themselves; a margin class you wrote needs a to_json returning a
mapping, plus one call to register_margin_json so it can be read
back. The pyvinecopulib.torch modules are nn.Module s and use
PyTorch’s own state_dict instead.
Structure selection
The vine structure \(\mathcal V\) is rarely known in advance,
and the number of regular vines on \(d\) variables grows as
\(2^{(d-3)(d-2)/2 - 1} d!\) (Morales-Napoles, 2011; Joe, 2011)
— super-exponential, so exhaustive search is infeasible beyond a
handful of variables. Two algorithms are exposed via
pyvinecopulib.core.FitControlsVinecop.tree_algorithm:
"mst_prim"— Dissmann’s greedy heuristic (Dissmann et al., 2013), which is the default. Builds the trees one at a time as maximum-spanning-trees weighted by absolute Kendall’s \(\tau\) (or the criterion of your choice — seetree_criterion). It is fast and remains the de-facto standard (Czado & Nagler, 2022)."random_weighted"— Wilson-weighted random spanning trees; draws a random structure with edge probabilities proportional to the absolute dependence on each candidate edge. Use it when you want a randomized alternative to the greedy structure — for example to draw several candidates and compare their held-out likelihoods.
One of the available criteria, Chatterjee’s \(\xi\) ("cxi"), is
asymmetric — it measures how far one variable is a function of the other.
A spanning-tree edge weight has to be symmetric, so the larger of the two
directions is used; and because \(\xi\) breaks ties in the predictor at
random, it is a function of its arguments only up to that tie ordering, which
wdm’s seeds argument controls.
Selection is further tunable through
FitControlsVinecop: supply a custom edge weight via
tree_criterion_function (any
callable (data, weights) -> float returning a scalar dependence measure),
make random searches reproducible with
seeds, and toggle whether rotated
families are considered with
allow_rotations.
Vine truncation
For sparse models in higher dimensions, set
pyvinecopulib.core.FitControlsVinecop.trunc_lvl to an
integer \(T < d - 1\): pair copulas in trees
\(T + 1, \ldots, d - 1\) are forced to indep, reducing
both fit time and statistical degrees of freedom. The same effect
can be triggered automatically via the mBIC criterion (Nagler,
2019).
Conditional sampling and conditioning-aware vines
A fitted vine can sample from the conditional distribution of a subset of
variables given fixed values of the rest, via
pyvinecopulib.core.Vinecop.sample_conditional(). The conditioning
variables are the last k of the vine order
(order): each row of u_cond is one
conditioning point and the corresponding output row is drawn from the remaining
variables’ distribution conditional on that point (implemented as a Rosenblatt
transform of the conditioning variables followed by an inverse Rosenblatt
transform, so discrete conditioning variables are supported too).
The conditioning variables can also be named explicitly, with
sample_conditional(u_cond, conditioning_set=[...]) — 1-based indices.
Note that the two forms map u_cond’s columns differently: without the
argument, column i is the i-th variable of the order tail; with it,
column i is conditioning_set[i]. The same argument is available on
pyvinecopulib.core.Vinecop.rosenblatt() and
inverse_rosenblatt(), which then hold those
variables fixed rather than the order tail. In every case the vine is
evaluated through a reoriented view and the model is left unchanged.
Not every set is admissible as a sampling-order tail; when it is not, a
RuntimeError says so. Conditioning is cheapest when the set already sits at
the tail, and two tools arrange that:
pyvinecopulib.core.FitControlsVinecop.conditioning_set— select a vine whose order ends with a chosen set of variables (their own optimal sub-vine is fit first, then placed at the tail). Requires an MSTtree_algorithm.pyvinecopulib.core.Vinecop.reorient()— relabel an already-fitted vine to an equivalent one whose order tail equals a given set, without refitting. This is value-preserving:pdfandloglikare invariant.
The same three tools are array-agnostic, so a custom or PyTorch vine
conditions the same way: pyvinecopulib.core.VinecopBase.sample_conditional(),
conditioning_set on its Rosenblatt transforms, and
pyvinecopulib.core.VinecopBase.select()’s own conditioning_set.
pyvinecopulib.core.VinecopBase.reorient() is the one that differs in
shape: it returns the relabeled structure and pair copulas rather than
mutating, because the base class leaves pair storage to the subclass. A
relabeling is refused on a non-simplified vine — it can permute the columns of
the conditioning matrix each pair copula receives, which makes the result a
different model rather than the same one in a different order. Conditioning on
the variables already at the tail needs no relabeling and is always allowed.
These operations condition on variables that are themselves part of the vine;
they do not supply an external design matrix. For pair copulas that depend on
their edge conditioning-set values, see the extending guide (example notebook
10). For a full exogenous \(Y \mid X=x\) model, see
Exogenous conditional distributions and example notebook 03. A fitted vine’s
tree-by-tree decomposition — the conditioned pairs, conditioning sets, and
pair-copulas — is
available as nested lists through
pyvinecopulib.core.Vinecop.get_trees(), and a bare structure round-trips
through pyvinecopulib.core.RVineStructure.get_trees() /
pyvinecopulib.core.RVineStructure.from_trees().
Vine regression
For conditional inference, fix one variable as the response \(Y\) and stack it with the predictors to model the joint distribution \((Y, \mathbf X)\). Any conditional summary of interest is then solved out of the estimating equation (Nagler, 2018)
with \(\psi_\beta(y) = y - \beta\) recovering the conditional mean \(\beta(\mathbf x) = \mathbb E[Y \mid \mathbf X = \mathbf x]\) and \(\psi_\beta(y) = \mathbb 1\{y < \beta(\mathbf x)\} - \tau\) recovering the conditional \(\tau\)-quantile. In practice the integral is taken on the probability scale, substituting \(p = \hat F_Y(y)\), and replaced by a weighted sum over a fixed grid of levels \(\{p_1, \ldots, p_G\} \subset (0, 1)\):
with \(\Delta_g\) the spacing of the nodes. The substitution cancels the marginal density \(\hat f_Y\) that the response-scale form of the same sum carries, so the rule asks the response margin for nothing but its inverse CDF and places every node inside its support by construction.
pyvinecopulib.sklearn.VineRegressor solves this
numerically. Pass the quantile levels you want via the
quantiles= constructor argument; the predicted conditional
mean is always returned when mean=True. The node count is
n_nodes=, and use_grid=False swaps the quadrature for the
exact weighted sum over the training responses. Batching over test
rows is controlled by batch_size=.
Where to next
pyvinecopulib.core.Bicopandpyvinecopulib.core.Vinecop— the core classes that implement everything above. The notebooksexamples/01_bivariate_copulas.ipynb,examples/02_vine_copulas.ipynb, andexamples/03_vine_distributions.ipynbwalk through end-to-end use.Kde1dis the default margin and stands alone as a 1-d kernel density (notebookexamples/07_kde1d.ipynb).pyvinecopulib.margins— the marginal half of a vine distribution:SciPyMarginand (named, or chosen from the data), andFitControlsMarginto configure either (notebookexamples/03_vine_distributions.ipynb).The four contracts and their canonical bases in
pyvinecopulib.core—BicopLike/BicopBase,VinecopLike/VinecopBase,MarginLike/MarginBase,VinedistLike/VinedistBase— are what a custom pair copula, margin, vine or distribution subclasses (notebookexamples/10_extending_pyvinecopulib.ipynb).pyvinecopulib.sklearn— scikit-learn-compatible estimatorsVineDensityandVineRegressor. The notebookexamples/08_sklearn_estimators.ipynbdemonstrates them. Both estimators fit aVinedistby default, anddistribution=TorchVinedistroutes the same pipeline through PyTorch.pyvinecopulib.torch— PyTorch evaluatorsTorchTllBicopandTorchVinecopfor GPU placement and autograd. Notebookexamples/09_torch_evaluator.ipynb.pyvinecopulib.utils—wdm()for weighted dependence measures (notebookexamples/06_weighted_dependence_measures.ipynb);sobol(),ghalton(),sample_uniform()for the low-discrepancy sequences that back Monte-Carlo CDF evaluation;to_pseudo_obs()andpairs_copula_data()for input preparation and pair-plot diagnostics.The API Documentation page is the autogenerated API reference; the Examples toctree lists all worked notebooks.
The examples/04_discrete_variables.ipynb notebook covers the
discrete-margin extension (Panagiotelis, Czado & Joe, 2012; Funk,
Nagler & Czado, 2025), which replaces the marginal CDF derivatives in
Sklar’s theorem and pseudo-observations by finite differences (transparent to the
user — pass var_types=["d", ...] to
pyvinecopulib.core.Vinecop.from_data() or set
var_type="d" on pyvinecopulib.core.Kde1d).
A discrete variable needs its left limit \(F(x^-)\) alongside
\(F(x)\), and there are two ways to supply them. The expanded layout is
(n, 2d): the first \(d\) columns are \(F(x)\), the next \(d\)
are \(F(x^-)\) for the same variables in the same order, with continuous
columns simply repeated. Its shape does not depend on var_types, which is
what makes it the easier convention to write against. The compact layout is
(n, d + k): the same first \(d\) columns, then left limits for the
\(k\) discrete variables only, in the order they appear. Both are accepted
wherever discrete data is; for an all-continuous model they coincide at
(n, d). The same applies per pair to
pyvinecopulib.core.Bicop.from_data(), with \(d = 2\).
Extending: custom and conditional pair copulas
The evaluators pyvinecopulib.core.Bicop /
Vinecop and their PyTorch counterparts
pyvinecopulib.torch.TorchTllBicop /
TorchVinecop are concrete implementations
of two array-agnostic contracts, evaluated on either NumPy or PyTorch
arrays:
BicopLike— a pair copula, exposingpdf/hfunc1/hfunc2/hinv1/hinv2/sample, plus what hosting it needs:cdfandwith_var_typeson a discrete edge,flipin structure selection, andfit/selectwhere it is re-estimated. Those carry defaults that raise, naming the class, so declining one is a clear refusal rather than a missing attribute;VinecopLike— a fitted vine, exposingpdf/cdf/rosenblatt/inverse_rosenblatt/sampleon anRVineStructure;MarginLike— a univariate margin, exposingpdf/cdf/icdf;VinedistLike— the two halves together on the data scale, exposing the same evaluation surface in terms ofyrather thanu.
You can plug your own pair copula into a vine by implementing the
contract — most easily by subclassing the canonical partial
implementations BicopBase /
VinecopBase, which fill in almost
everything from a few primitives. A BicopBase subclass need only
define the leaves _pdf_raw / _hfunc1_raw / _hfunc2_raw and
inherits numerical hinv1 / hinv2, sample, loglik, and
plot. The public members are concrete dispatchers that apply the pair’s
var_types before reaching a leaf, so overriding one of those orphans
the leaf beneath it (_flip_raw and _cdf_raw are the two optional
additions, needed to reuse the pair in structure selection and to host it on
a discrete edge respectively); a
VinecopBase subclass need only return its pairs from
get_pair_copula and inherits the whole tree-by-tree cascade. The
bases are pure Python (no PyTorch), so custom pairs also work in a
torch-less environment.
Fitting is declared rather than implemented wherever it can be. A
VinecopBase subclass that names bicop_class – the pair-copula class it
fits – gets from_data with no callback, because a pair class is itself a
fitter; naming it also lets structure selection refuse a pair copula without
flip before it reads the data. Adding set_pair_copulas on top is what
lets fit and select install what they fitted and hand back self.
A fit_edge callback remains the hook for a actually custom or conditional
per-edge fit.
The same holds one level up: a custom vine distribution subclasses
VinedistBase and inherits the entire data-scale
surface with no hook at all, because a vine distribution is determined by its
two halves. Hooks are needed only to make it fittable —
from_data() runs the two-step estimator
once, in the base, and asks the subclass which margin class to default to, how
to fit the copula, and how to coerce input arrays.
Vinedist (NumPy and a
Vinecop) and
TorchVinedist are the two shipped subclasses.
Fitting has one shape throughout: on all four bases fit mutates and returns
self, from_data constructs, and — where there is a family or a structure
to choose — select returns self too. Configuration travels as a
ControlsLike, anything exposing to_dict(),
which is how one call site accepts both the core FitControls* objects and
the PyTorch ones. And a vine’s controls are pair controls —
FitControlsVinecop is a
FitControlsBicop, and
FitControlsTorchVinecop likewise — so one object
configures both halves of a vine fit, and the settings a vine does not read
reach its pair copulas unchanged.
Every method carries an optional external covariate matrix x. A vine
whose pairs read it declares supports_covariates=True; the default
SimplifiedContext forwards it without
changing whether the vine is simplified. To lift the
simplifying assumption, host the pairs
under a NonSimplifiedContext: the cascade
then prepends each edge’s conditioning-set values
\(\mathbf u_{D_e}\) to any external covariates and threads the
combined matrix to the pair. pyvinecopulib.core.VinecopBase.fit()
is the hook for fitting either kind of custom vine edge by edge. See
Exogenous conditional distributions for the full data-scale
\(Y \mid X\) composition and its fitting boundary.
A custom pair copula reaches a discrete edge
too. The vine owns the discreteness: declare var_types when binding
it, and pyvinecopulib.core.VinecopBase.pair_var_types() says which
of the pairs sees an argument with atoms. Declaring such a pair through
with_var_types builds the mixed-discrete density and h-functions out
of its continuous primitives, so the only thing to add is a _cdf_raw.
A pair that can measure an atom more directly overrides
rect_prob() and
cond_interval_prob(), which is what
TorchTllBicop does; one that models atoms
itself – Bicop – needs none of that: it is declared the same way
and answers for the whole surface.
fit() and
select() take var_types as
well, and hand each edge’s types to the fit_edge callback.
Custom vines also condition: see conditional sampling for sample_conditional / reorient and the
conditioning_set arguments, which need flip on the pair copulas.
The examples/10_extending_pyvinecopulib.ipynb notebook is a
worked, end-to-end walk-through: a custom Gaussian pair copula hosted
first in a simplified vine (matching
pyvinecopulib.core.Vinecop.from_structure()), then a Gumbel one on
a discrete edge, and finally separate non-simplified and
external-covariate extensions. Notebook 10 composes the latter with
conditional margins into \(Y \mid X\).
References
Sklar (1959). Fonctions de répartition à n dimensions et leurs marges. Publ. Inst. Statist. Univ. Paris 8, 229–231.
Bedford & Cooke (2001, 2002). Probability density decomposition for conditionally dependent random variables modeled by vines / Vines — a new graphical model for dependent random variables. Annals of Mathematics and Artificial Intelligence 32, 245–268 / Annals of Statistics 30(4), 1031–1068.
Joe (1996). Families of m-variate distributions with given margins and m(m-1)/2 bivariate dependence parameters. In: Distributions with Fixed Marginals and Related Topics (IMS Lecture Notes 28), 120–141.
Joe & Xu (1996). The estimation method of inference functions for margins for multivariate models. Technical Report 166, Department of Statistics, University of British Columbia.
Godambe (1991). Estimating Functions. Oxford Statistical Science Series 7, Oxford University Press.
Aas, Czado, Frigessi & Bakken (2009). Pair-copula constructions of multiple dependence. Insurance: Mathematics and Economics 44(2), 182–198.
Dissmann, Brechmann, Czado & Kurowicka (2013). Selecting and estimating regular vine copulae and application to financial returns. Computational Statistics & Data Analysis 59, 52–69.
Joe (2011). Dependence comparisons of vine copulae with four or more variables. In: Dependence Modeling: Vine Copula Handbook, 139–164.
Geenens (2014). Probit Transformation for Kernel Density Estimation on the Unit Interval. JASA 109(505), 346–358.
Nagler (2018). A Generic Approach to Nonparametric Function Estimation with Mixed Data. Statistics & Probability Letters 137, 326–330.
Nagler, Schepsmeier, Stoeber, Brechmann, Graeler & Erhardt (2018). VineCopula: Statistical inference of vine copulas. R package.
Nagler (2019). Model selection in sparse high-dimensional vine copula models with an application to portfolio risk. Journal of Multivariate Analysis 172, 180–198.
Spanhel & Kurz (2019). Simplified vine copula models: approximations based on the simplifying assumption. Electronic Journal of Statistics 13(1), 1254–1291.
Czado & Nagler (2022). Vine Copula Based Modeling. Annual Review of Statistics and Its Application 9, 453–477.
Panagiotelis, Czado & Joe (2012). Pair Copula Constructions for Multivariate Discrete Data. JASA 107(499), 1063–1072.
Funk, Nagler & Czado (2025). Discrete and mixed pair-copula constructions revisited. (In press.)