VineForestRegressor

class VineForestRegressor(base_params=None, n_vines=100, vines_sampling='uniform', bootstrap=True, val_fraction=0.25, best_only=False, method='da_mcs_marg', alpha=0.05, add_dissmann=True, random_state=None, n_jobs=1, verbose=False)

Forest of vine-copula regressors.

An ensemble of VineRegressor base learners fitted on randomly sampled vine structures. Survivors are selected via a model confidence set (MCS) on a held-out validation split, and the conditional weights \(w_i(x)\) from the single-vine estimating equation framework are averaged across survivors before being used to compute conditional means or quantiles.

The ensemble is built via hold-out random search with model-confidence-set (MCS) survivor selection:

  1. A fraction val_fraction of the training data is held out for survivor selection.

  2. n_vines candidate vine structures are sampled. With vines_sampling="uniform" the structure is drawn uniformly over R-vines via Joe’s algorithm (Joe, Cooke & Kurowicka, 2011); with "local" each tree is drawn from the Kendall’s-tau-weighted distribution \(P(T) \propto \prod_{(j, k) \in T} |\hat\tau_{j, k}|\) via Wilson’s loop-erased random walk. Each candidate is fit on a bootstrap resample of the training portion.

  3. Each candidate’s per-sample log-likelihood is evaluated on the validation set. The resulting \(n_{\text{val}} \times M\) loss matrix is fed to a dual-split DA test (Vatter & Nagler, 2026; Kim & Ramdas, 2025) to compute the model confidence set (Hansen, Lunde & Nason, 2011). method selects per-model coverage ("da_mcs_marg") vs familywise coverage ("da_mcs_unif"); add_dissmann=True adds the Dissmann-structure baseline as a candidate.

  4. Survivors are refit on the full training data; predictions are averaged across survivors at evaluation time. For the regressor, conditional weights derived from \(c_{Y, X}\) are averaged and row-normalised once at the ensemble level.

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 the ensemble of vine regressors.

predict(X)

Predicts conditional mean and/or quantiles from the ensemble.

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.

[5]

Joe, H., Cooke, R. M. and Kurowicka, D. (2011). Regular vines: generation algorithm and number of equivalence classes. In Dependence Modeling: Vine Copula Handbook, 219–231. World Scientific.

[6]

Joe, H. (2014). Dependence Modeling with Copulas. CRC Press.

[7]

Wilson, D. B. (1996). Generating random spanning trees more quickly than the cover time. Proceedings of STOC ‘96, 296–303.

[8]

Hansen, P. R., Lunde, A. and Nason, J. M. (2011). The Model Confidence Set. Econometrica, 79(2), 453–497.

[9]

Kim, I. and Ramdas, A. (2025). Locally minimax optimal and dimension-agnostic discrete argmin inference. arXiv:2503.21639.

Examples

>>> import numpy as np
>>> from pyvinecopulib.sklearn import VineForestRegressor
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((300, 3))
>>> y = X @ [1.5, -0.8, 0.4] + 0.2 * rng.standard_normal(300)
>>> forest = VineForestRegressor(
...     base_params={"quantiles": [0.1, 0.5, 0.9]},
...     n_vines=10, n_jobs=1,
... ).fit(X[:200], y[:200])
>>> forest.predict(X[200:205])

Methods

__init__

Ensemble of vine-copula regressors with random structures.

fit

Fits the ensemble of vine regressors.

predict

Predicts conditional mean and/or quantiles from the ensemble.