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

\[F(x_1, \ldots, x_d) \;=\; C\bigl(F_1(x_1), \ldots, F_d(x_d)\bigr),\]

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

\[f(x_1, \ldots, x_d) \;=\; c\bigl(F_1(x_1), \ldots, F_d(x_d)\bigr) \, \prod_{j=1}^{d} f_j(x_j),\]

so the log-likelihood splits cleanly into a sum of marginal log-likelihoods and a copula log-likelihood:

\[\log f(\mathbf x) \;=\; \log c\bigl(F_1(x_1), \ldots, F_d(x_d)\bigr) \;+\; \sum_{j=1}^{d} \log f_j(x_j).\]

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

\[\hat u_{ij} \;=\; \hat F_j(x_{ij}), \qquad i = 1, \ldots, n, \; j = 1, \ldots, d.\]

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\):

Pair copulas inside a vine also need h-functions, the partial conditional CDFs

\[\begin{split}h_1(u_1, u_2) \;&=\; \mathbb{P}(U_2 \le u_2 \mid U_1 = u_1) \;=\; \frac{\partial C(u_1, u_2)}{\partial u_1}, \\[4pt] h_2(u_1, u_2) \;&=\; \mathbb{P}(U_1 \le u_1 \mid U_2 = u_2) \;=\; \frac{\partial C(u_1, u_2)}{\partial u_2},\end{split}\]

and their inverses \(h_1^{-1}\), \(h_2^{-1}\). These map to

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

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

\[c(\mathbf u) \;=\; \prod_{t = 1}^{d - 1} \prod_{e \in E_t} c_{j_e, k_e \mid D_e}\!\bigl( u_{j_e \mid D_e}, \; u_{k_e \mid D_e} \,\big|\, \mathbf u_{D_e} \bigr),\]

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

\[u_{j \mid D \cup \{\ell\}} \;=\; h_1\!\bigl(u_{j \mid D}, \; u_{\ell \mid D};\; c_{j, \ell \mid D}\bigr),\]

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:

\[c_{j_e, k_e \mid D_e}(u, v \mid \mathbf u_{D_e}) \;\equiv\; c_{j_e, k_e \mid D_e}(u, v), \qquad \forall \mathbf u_{D_e}.\]

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

pyvinecopulib.families.indep

—

0

—

none

none

\(0\)

Gaussian

pyvinecopulib.families.gaussian

elliptical

1

\(\rho \in (-1, 1)\)

rotationless

none

\((2/\pi) \arcsin \rho\)

Student

pyvinecopulib.families.student

elliptical

2

\(\rho \in (-1, 1)\), \(\nu > 2\)

rotationless

symmetric

\((2/\pi) \arcsin \rho\)

Clayton

pyvinecopulib.families.clayton

Archimedean

1

\(\theta > 0\)

0° / 90° / 180° / 270°

lower

\(\theta / (\theta + 2)\)

Gumbel

pyvinecopulib.families.gumbel

Arch. / EV

1

\(\theta \ge 1\)

0° / 90° / 180° / 270°

upper

\(1 - 1/\theta\)

Frank

pyvinecopulib.families.frank

Archimedean

1

\(\theta \in \mathbb{R} \setminus \{0\}\)

rotationless

none

via Debye function

Joe

pyvinecopulib.families.joe

Archimedean

1

\(\theta \ge 1\)

0° / 90° / 180° / 270°

upper

series expansion

BB1

pyvinecopulib.families.bb1

Arch. (2-par)

2

\(\theta > 0\), \(\delta \ge 1\)

0° / 90° / 180° / 270°

lower + upper

closed form

BB6

pyvinecopulib.families.bb6

Arch. (2-par)

2

\(\theta \ge 1\), \(\delta \ge 1\)

0° / 90° / 180° / 270°

upper

by quadrature

BB7

pyvinecopulib.families.bb7

Arch. (2-par)

2

\(\theta \ge 1\), \(\delta > 0\)

0° / 90° / 180° / 270°

lower + upper

by quadrature

BB8

pyvinecopulib.families.bb8

Arch. (2-par)

2

\(\theta \ge 1\), \(\delta \in (0, 1]\)

0° / 90° / 180° / 270°

upper

by quadrature

Tawn

pyvinecopulib.families.tawn

extreme-value

3

bounded; see parameters_lower_bounds

0° / 90° / 180° / 270°

upper (asymmetric)

by quadrature

TLL

pyvinecopulib.families.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 except tll.

  • nonparametric — indep and tll.

  • 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:

  1. 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. Kde1d supports continuous, integer-discrete, and zero-inflated numerical input via its var_type argument. Raw categorical labels are not accepted; encode them before fitting only when an integer-valued model is appropriate.

  2. 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() (or pyvinecopulib.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 the itau group; uses tau_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; the nonparametric_method and nonparametric_mult knobs on FitControlsBicop tune 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,

\[\begin{split}w_j \;=\; \begin{cases} f_j(x_j) & \text{$x_j$ in the continuous part,} \\[2pt] F_j(x_j) - F_j(x_j^-) & \text{$x_j$ an atom,} \end{cases}\end{split}\]

and the log-density identity of Sklar’s theorem and pseudo-observations holds verbatim in every case:

\[\log f(\mathbf x) \;=\; \log c(\mathbf u) \;+\; \sum_{j=1}^{d} \log w_j .\]

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:

\[f(\mathbf y \mid \mathbf x) = c_{\mathbf x}\!\left( F_1(y_1 \mid \mathbf x), \ldots, F_d(y_d \mid \mathbf x) \right) \prod_{j=1}^d f_j(y_j \mid \mathbf x).\]

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, and select() 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 (on pyvinecopulib.core.Vinecop.rosenblatt(), default True) 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. Pass seeds to reproduce it, or randomize_discrete=False to take the upper endpoint instead and accept output that is not uniform.

  • step_wise (on the Vinecop score family: scores, gradient, hessian, scores_cov) selects which likelihood is differentiated. True differentiates the step-wise (sequential, tree-by-tree) estimator that was actually fitted; False differentiates 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 — see tree_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:

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)

\[\int \psi_\beta(y) \, \hat f(y \mid \mathbf x) \, dy \;=\; 0,\]

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)\):

\[\sum_{g = 1}^G \psi_\beta\!\bigl(\hat F_Y^{-1}(p_g)\bigr) \, \hat c_{\mathcal V, \mathcal D}\!\bigl( p_g, \, \hat F_{\mathbf X}(\mathbf x) \bigr) \, \Delta_g \;\approx\; 0,\]

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.Bicop and pyvinecopulib.core.Vinecop — the core classes that implement everything above. The notebooks examples/01_bivariate_copulas.ipynb, examples/02_vine_copulas.ipynb, and examples/03_vine_distributions.ipynb walk through end-to-end use. Kde1d is the default margin and stands alone as a 1-d kernel density (notebook examples/07_kde1d.ipynb).

  • pyvinecopulib.margins — the marginal half of a vine distribution: SciPyMargin and (named, or chosen from the data), and FitControlsMargin to configure either (notebook examples/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 (notebook examples/10_extending_pyvinecopulib.ipynb).

  • pyvinecopulib.sklearn — scikit-learn-compatible estimators VineDensity and VineRegressor. The notebook examples/08_sklearn_estimators.ipynb demonstrates them. Both estimators fit a Vinedist by default, and distribution=TorchVinedist routes the same pipeline through PyTorch.

  • pyvinecopulib.torch — PyTorch evaluators TorchTllBicop and TorchVinecop for GPU placement and autograd. Notebook examples/09_torch_evaluator.ipynb.

  • pyvinecopulib.utils — wdm() for weighted dependence measures (notebook examples/06_weighted_dependence_measures.ipynb); sobol(), ghalton(), sample_uniform() for the low-discrepancy sequences that back Monte-Carlo CDF evaluation; to_pseudo_obs() and pairs_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, exposing pdf / hfunc1 / hfunc2 / hinv1 / hinv2 / sample, plus what hosting it needs: cdf and with_var_types on a discrete edge, flip in structure selection, and fit / select where 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, exposing pdf / cdf / rosenblatt / inverse_rosenblatt / sample on an RVineStructure;

  • MarginLike — a univariate margin, exposing pdf / cdf / icdf;

  • VinedistLike — the two halves together on the data scale, exposing the same evaluation surface in terms of y rather than u.

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