VineDensity

class VineDensity(backend=None, batch_size=100, random_state=None)

Vine-copula based density estimator.

A scikit-learn-compatible non-parametric joint density estimator. The joint density is factorised into one-dimensional marginals (estimated with kernel density) and a vine copula capturing the dependence structure. After fitting, pdf / score_samples evaluate the density at new points and sample draws from the fitted joint distribution.

The estimator follows the standard pyvinecopulib two-step pipeline: a univariate kernel density estimator (Kde1d) is fit to each column, the marginal CDFs transform the data to pseudo-observations \(U_j = \hat F_j(X_j) \in [0, 1]\), and a vine copula is fit on the pseudo-observations. For discrete columns the left limit \(\hat F_j(X_j^-)\) is also stacked so the vine sees a continuous proxy. Unordered categoricals are first expanded to ordered {0, 1} dummies via expand_factors.

Fit-time configuration is bundled in a backend object passed via backend=. The default VinecopBackend wraps Vinecop and has no extra dependencies; TorchVinecopBackend routes the same pipeline through the PyTorch evaluator (GPU / autograd). See the concepts page for the underlying vine-copula construction.

By Sklar’s theorem the joint density factorises as

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

with \(c\) further decomposed into pair copulas indexed by a vine structure (Bedford & Cooke, 2002; Aas et al., 2009). Passing copula_only=True to pdf returns the copula factor \(c(\mathbf{u})\) alone.

Discrete (or expanded unordered-categorical) columns are handled via Kde1d’s type="discrete" mode: pseudo-observations stack \(\hat F_j(X_j)\) and \(\hat F_j(X_j^-)\) so the vine evaluation sees the appropriate continuous proxy. Handled transparently by fit and pdf.

Methods

cdf(X[, N, random_state])	Evaluates the joint CDF at the given samples.
fit(X[, y])	Fits the joint density to the training data.
pdf(X[, copula_only])	Evaluates the joint density at the given samples.
sample([n_samples, random_state])	Draws samples from the fitted joint density.
score(X[, y])	Mean log-likelihood over a sample (sklearn score convention).
score_samples(X)	Evaluates the per-sample log-likelihood under the fitted density.

References

[1]

Bedford, T. and Cooke, R. M. (2002). Vines–a new graphical model for dependent random variables. The Annals of Statistics, 30(4), 1031–1068.

[2]

Aas, K., Czado, C., Frigessi, A. and Bakken, H. (2009). Pair-copula constructions of multiple dependence. Insurance: Mathematics and Economics, 44(2), 182–198.

[3]

Nagler, T. and Vatter, T. (2024). Solving Estimating Equations With Copulas. Journal of the American Statistical Association, 119(546), 1168–1180.

[4]

Vatter, T. and Nagler, T. (2026). Throwing Vines at the Wall: Structure Learning via Random Search. arXiv preprint arXiv:2510.20035.

Examples

>>> import numpy as np
>>> from pyvinecopulib.sklearn import VineDensity
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((500, 3))
>>> density = VineDensity().fit(X)
>>> density.score_samples(X[:3])

Methods

__init__	Vine-copula based density estimator.
cdf	Evaluates the joint CDF at the given samples.
fit	Fits the joint density to the training data.
pdf	Evaluates the joint density at the given samples.
sample	Draws samples from the fitted joint density.
score	Mean log-likelihood over a sample (sklearn score convention).
score_samples	Evaluates the per-sample log-likelihood under the fitted density.