VineCopula Python API: Fit, Inspect, Sample
API reference for VineCopula: fit_r, fit_c, fit_d methods, Gaussian constructors, and tree inspection types VineStructureInfo, VineTreeInfo, VineEdgeInfo.
VineCopula implements pair-copula constructions (PCCs) in C-vine, D-vine, and R-vine structures. A vine model decomposes a multivariate distribution into a cascade of bivariate copulas arranged in a tree sequence. You fit a vine by choosing a structure kind (fit_c, fit_d, or fit_r) and optionally restricting the family set and selection criterion. You can also construct vines analytically from a Gaussian correlation matrix or from a fully specified tree list.
Fitting methods
VineCopula.fit_r(data, *, ...) → FitResult[VineCopula]
Fit an R-vine—the most flexible structure kind, where the tree sequence is learned from data.
VineCopula.fit_c(data, *, ...) → FitResult[VineCopula]
Fit a C-vine, where one variable acts as a central node at each tree level.
VineCopula.fit_d(data, *, ...) → FitResult[VineCopula]
Fit a D-vine, where variables are arranged in a path at each tree level.
All three fitting methods accept identical keyword arguments:
A 2-D array of pseudo-observations with shape (n_samples, n_dims) and dtype=float64. Values must be strictly in (0, 1).
Restrict which bivariate copula families are considered at each edge. Pass None to use all available families. Valid strings:
"independence", "gaussian", "student_t", "clayton", "frank", "gumbel", "khoudraji"
When True, rotated versions of asymmetric families (Clayton, Gumbel) are included in the candidate set. Disable to restrict to the canonical orientation.
Information criterion used for pair-copula family selection at each edge. Valid values: "aic", "bic".
Truncate the vine at a given tree depth, replacing all deeper trees with independence copulas. Pass None to fit all d - 1 trees.
If the Kendall's tau of an edge is below this threshold, that edge is set to independence without fitting. Pass None to disable.
Boundary clipping tolerance applied before density evaluation.
Maximum optimizer iterations per pair-copula.
Only accepted by fit_c and fit_d (not fit_r). Pins the canonical variable order explicitly; the fitter skips its structure-selection heuristic. Use this to set up exact conditional sampling: place the column you want to condition on at the end of order so that it becomes variable_order[0] (the Rosenblatt anchor). See Conditional sampling.
Example
import numpy as np
from rscopulas import VineCopula
rng = np.random.default_rng(0)
data = rng.uniform(0.01, 0.99, size=(600, 4))
result = VineCopula.fit_r(
data,
family_set=["gaussian", "clayton", "gumbel"],
criterion="bic",
truncation_level=2,
)
model = result.model
print("AIC:", result.diagnostics.aic)
print("structure:", model.structure_kind)
import numpy as np
from rscopulas import VineCopula
rng = np.random.default_rng(1)
data = rng.uniform(0.01, 0.99, size=(600, 4))
result = VineCopula.fit_c(data, criterion="aic")
model = result.model
samples = model.sample(200, seed=42)
import numpy as np
from rscopulas import VineCopula
rng = np.random.default_rng(2)
data = rng.uniform(0.01, 0.99, size=(600, 4))
result = VineCopula.fit_d(
data,
independence_threshold=0.05,
)
model = result.model
log_d = model.log_pdf(data)
Constructors
VineCopula.gaussian_c_vine(order, correlation) → VineCopula
Construct a C-vine with Gaussian pair-copulas from a variable ordering and a correlation matrix.
A permutation of variable indices specifying the C-vine ordering (root at order[0]).
A positive-definite correlation matrix of shape (d, d).
A VineCopula with Gaussian pair-copulas and C-vine structure.
VineCopula.gaussian_d_vine(order, correlation) → VineCopula
Construct a D-vine with Gaussian pair-copulas from a variable ordering and a correlation matrix.
A permutation of variable indices specifying the D-vine path order.
A positive-definite correlation matrix of shape (d, d).
A VineCopula with Gaussian pair-copulas and D-vine structure.
VineCopula.from_trees(kind, trees, *, truncation_level=None) → VineCopula
Construct a VineCopula from a fully specified list of VineTreeInfo objects or equivalent dicts.
Structure kind: "c", "d", or "r".
A list of tree specifications, one per level. Each element must be a VineTreeInfo instance or a compatible dict with level and edges keys.
Truncation depth for the resulting vine. Pass None to use all provided trees.
A fully specified VineCopula ready for log_pdf and sample.
Example
import numpy as np
from rscopulas import VineCopula
corr = np.array([
[1.0, 0.7, 0.4],
[0.7, 1.0, 0.5],
[0.4, 0.5, 1.0],
])
# Gaussian C-vine with variable order [0, 1, 2]
vine = VineCopula.gaussian_c_vine(order=[0, 1, 2], correlation=corr)
samples = vine.sample(300, seed=0)
log_d = vine.log_pdf(samples)
Instance methods
log_pdf(data, *, clip_eps=1e-12) → ndarray
Evaluate the vine log-density at each row of data.
A 2-D array of pseudo-observations matching the vine's dimension.
Boundary clipping tolerance.
A 1-D array of log-density values, one per row.
sample(n, *, seed=None) → ndarray
Draw n pseudo-observations from the vine copula. Implemented as inverse_rosenblatt(U) over a freshly drawn uniform matrix.
Number of samples.
Random seed for reproducibility.
A 2-D array of shape (n, dim) with values in (0, 1).
rosenblatt(data) → ndarray
Forward Rosenblatt transform U = F(V). Takes vine-distributed pseudo-observations and returns the associated independent uniforms. Input and output are both (n, dim) arrays indexed by the original variable label. inverse_rosenblatt(rosenblatt(V)) == V up to ~1e-8 drift.
A 2-D array of pseudo-observations matching the vine's dimension, with values in (0, 1).
A 2-D array of independent uniforms with the same shape and column layout as data.
inverse_rosenblatt(data) → ndarray
Inverse Rosenblatt transform V = F^{-1}(U). Takes a matrix of independent uniforms and returns a vine-distributed sample. This is the primitive behind sample and sample_conditional.
A 2-D array of independent uniforms with shape matching the vine's dimension.
A 2-D array of vine-distributed samples with the same shape as data.
sample_conditional(known, n, *, seed=None) → ndarray
Draw n samples from the vine conditional on known values for a subset of columns. See Conditional sampling for the full workflow, including the variable_order convention and how to set up the vine via fit_c(order=...) or fit_d(order=...).
Mapping of column index to a 1-D array of length n with values in (0, 1). The provided column indices must form a prefix of variable_order.
Number of samples.
Random seed controlling the non-conditioned columns.
A 2-D array of shape (n, dim) in original variable-label order. The columns in known are filled with the supplied values (bit-exact when k == 1 at the anchor; tight round-trip otherwise).
Raises rscopulas.NonPrefixConditioningError when the keys of known are not equal to set(variable_order[:k]). The error message suggests a re-fit pattern.
Properties
The vine structure kind: "c", "d", or "r".
The truncation depth. None means all d - 1 trees are active.
The variable ordering used by the vine structure.
Diagonal ordering used by the Rosenblatt transform. variable_order[0] is the Rosenblatt anchor (see Conditional sampling). For canonical C- and D-vines, variable_order[0] == order[-1].
A flat 1-D array containing the primary fitted parameter from each pair-copula edge in tree order.
VineStructureInfo
A frozen dataclass describing the vine's matrix representation and structure kind.
Structure kind: "c", "d", or "r".
The vine structure matrix of shape (d, d).
Effective truncation level, or None if the vine is not truncated.
VineTreeInfo
A frozen dataclass describing one level of the vine tree sequence.
Tree level, starting from 1 for the first (unconditional) tree.
All edges in this tree level.
VineEdgeInfo
A frozen dataclass describing a single pair-copula edge in the vine.
Tree level this edge belongs to.
The two conditioned variable indices for this edge.
The conditioning set (empty for tree 1 edges).
Pair-copula family name, e.g. "gaussian", "clayton", "khoudraji".
Rotation applied to the pair-copula: "R0", "R90", "R180", or "R270".
Fitted parameters for the pair-copula.
First shape parameter for Khoudraji copulas; None for all other families.
Second shape parameter for Khoudraji copulas; None for all other families.
Specification dict for the first base copula in a Khoudraji pair; None otherwise.
Specification dict for the second base copula in a Khoudraji pair; None otherwise.