VineRegressor

class VineRegressor(mean=True, quantiles=None, backend=None, batch_size=100, use_grid=True, normalize_weights=True, random_state=None)

Vine-copula based regressor (mean and quantile).

A scikit-learn-compatible non-parametric regressor that predicts the conditional mean \(\mathbb{E}[Y \mid X = x]\) and/or conditional \(\tau\)-quantiles of Y given covariates X by fitting a vine copula to the joint distribution of \((Y, X)\) and reducing prediction to a weighted statistic of the training responses.

For a target functional \(\beta(x)\) characterised by \(\mathbb{E}[\psi_\beta(Y) \mid X = x] = 0\) (Nagler & Vatter, 2024), the fitted conditional density \(\hat f_{Y \mid X}(\cdot \mid x)\) solves

\[\int \psi_\beta(y)\, \hat f_{Y \mid X}(y \mid x)\, dy = 0.\]

Setting \(\psi_\beta(y) = y - \beta\) recovers the conditional mean (a closed-form weighted average of the training responses); setting \(\psi_\beta(y) = \mathbf{1}\{y < \beta\} - \tau\) recovers the conditional \(\tau\)-quantile (a weighted quantile via numpy.quantile() with method="inverted_cdf").

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

fit(X, y)	Fits a vine copula to the joint distribution of (Y, X).
predict(X)	Predicts the conditional mean and/or quantiles of Y given X.
set_score_request(*[, sample_weight])	Configure whether metadata should be requested to be passed to the score method.

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 VineRegressor
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((200, 3))
>>> y = X @ [1.5, -0.8, 0.4] + 0.2 * rng.standard_normal(200)
>>> est = VineRegressor(quantiles=[0.1, 0.5, 0.9]).fit(X, y)
>>> est.predict(X[:5])

Methods

__init__	Sklearn-compatible vine-copula regressor.
fit	Fits a vine copula to the joint distribution of (Y, X).
predict	Predicts the conditional mean and/or quantiles of Y given X.