Vine API¶

This page is the API reference entry point for vine classes and helper types. Usage examples and conceptual details live in the user guide:

Public Options¶

VineCopula.predict(...) supports:

given={var_index: u_value} for conditional generation in pseudo-observation space;
horizon='current'|'next' for dynamic edge prediction;
predictive_r_mode='grid'|'histogram'|None for SCAR-TM predictive parameter sampling. No other string values are supported;
rng=np.random.default_rng(seed) for reproducible Monte Carlo output.

It also supports:

predict_config=PredictConfig(...);
dynamic_conditioning='ignore'|'given_only';
mcmc_steps=<non-negative int> and mcmc_burnin=<non-negative int> for approximate conditional prediction;
return_diagnostics=True.

VineCopula.fit(...) additionally supports fit-time conditional-structure targeting:

given_vars=[...];
conditional_strict=True|False;
conditional_mode='suffix';
structure_search='beam'|'multi-start';
beam_width=<positive int>.

For detailed behavior of these options, see the guide pages linked above. The API signatures below are generated from the source docstrings.

candidates= and copulas= have different meanings for vine fitting. Pass candidates=[BivariateGaussianCopula, ...] to define the family pool used for automatic selection. Pass copulas=[[(CopulaClass, rotation), ...], ...] only when the family and rotation of every edge are fixed in advance. copulas= does not accept fitted copula instances.

Use vine.to_rvine_matrix() or RVineMatrix.from_model(vine) when you need the fitted R-vine structure as an RVineMatrix.

For new code, construct all generic modes through one class:

from pyscarcopula import VineCopula
from pyscarcopula.vine import RVineMatrix

auto = VineCopula()
c_vine = VineCopula.cvine(d=5, order=[0, 1, 2, 3, 4])
d_vine = VineCopula.dvine(d=5, order=[0, 1, 2, 3, 4])
arbitrary = VineCopula(
    structure=RVineMatrix.from_trees(d=5, trees=trees)
)

model.structure is the canonical public structure. model.natural_order_matrix exposes the numerical matrix convention; model.matrix is retained as a compatibility property.

Matrix layout and pyvinecopulib¶

pyscarcopula and pyvinecopulib can encode the same valid R-vine with matrices that look different. In particular:

model.structure.matrix is the canonical zero-based, lower-triangular RVineMatrix;
model.natural_order_matrix (and the compatibility property model.matrix) is the zero-based, upper-left anti-triangular runtime layout. Within each column, entries above the anti-diagonal run from the highest tree down to tree 0;
the raw matrix accepted by pyvinecopulib.RVineStructure.from_matrix() is one-based and stores tree 0 first within each column.

Therefore, merely adding one to model.matrix is not a valid conversion. For column c, let length = d - c: reverse the first length - 1 entries and add one, then copy the anti-diagonal entry at length - 1 with one added. Zero padding remains zero.

import numpy as np
import pyvinecopulib as pv

source = model.natural_order_matrix
target = np.zeros_like(source, dtype=np.uint64)
for column in range(model.d):
    length = model.d - column
    target[:length - 1, column] = (
        source[:length - 1, column][::-1] + 1
    )
    target[length - 1, column] = source[length - 1, column] + 1

pyvine_structure = pv.RVineStructure.from_matrix(target)

This is a representation conversion only; it does not change the underlying tree edge sets or the proximity condition.

VineCopula¶

`pyscarcopula.vine.vine.VineCopula` ¶

Generic vine copula with automatic or fixed structure.

Parameters:

Name	Type	Description	Default
`candidates`	`list of copula classes or None`	Family pool for per-edge selection. `None` uses the package default from `_selection._default_candidates`.	`None`
`allow_rotations`	`bool`	Whether to search over rotations for rotatable Archimedean families.	`True`
`criterion`	`('aic', 'bic', 'loglik')`	Model selection criterion used within and between families.	`'aic'`
`truncation_level`	`int or None`	If set, tree levels `>= truncation_level` use `truncation_fill`.	`None`
`truncation_fill`	`('mle', 'independent')`	For truncated trees, either fit edges with MLE only or force `IndependentCopula`.	`'mle'`
`threshold`	`float or None`	Pre-fit Kendall's tau threshold. If `abs(tau) < threshold`, an edge is set to `IndependentCopula` without fitting.	`0.0`
`min_edge_logL`	`float or None`	If set, any fitted edge with log-likelihood strictly below this threshold is replaced by `IndependentCopula`.	`None`
`transform_type`	`str`	Parameter transform passed through to candidate copulas.	`'softplus'`
`structure`	`RVineMatrix or None`	Fixed regular-vine structure. If omitted, the structure is selected automatically with the Dissmann procedure on every fit.	`None`
`vine_type`	`('cvine', 'dvine', 'rvine')`	Explicit structural mode for integrations such as GoF. Factories set this value automatically. With a direct fixed `structure`, `None` derives the mode from the structure.	`'cvine'`

Attributes (after fit)

d : int Number of variables. matrix : (d, d) int ndarray Zero-based natural-order runtime R-vine matrix derived from Czado (2019 Alg. 5.4). pyvinecopulib uses the opposite tree-level order above the anti-diagonal and one-based labels. Non-zero entries occupy the upper-left anti-triangle; the anti-diagonal M[d-1-col, col] is the leaf peeled at column col. trees : list of (d - 1) lists trees[t][i] = (conditioned_frozenset, conditioning_frozenset) in the canonical order decoded from structure. Each access returns a defensive nested-list copy. pair_copulas : dict pair_copulas[(t, col)] = PairCopula for the edge encoded at matrix tree level t and column col (0 <= col <= d-2-t).

`cvine(d, order=None, **kwargs)` `classmethod` ¶

Create a generic vine configured with a fixed C-vine structure.

`dvine(d, order=None, **kwargs)` `classmethod` ¶

Create a generic vine configured with a fixed D-vine structure.

`rvine(**kwargs)` `classmethod` ¶

Create a generic vine with automatic R-vine selection.

`fit(data, method='mle', *, to_pobs=False, copulas=None, config=None, given_vars=None, conditional_strict=True, conditional_mode='suffix', **kwargs)` ¶

Fit the R-vine and its pair-copula edge models.

The input must already be in pseudo-observation space unless to_pobs=True. Structure selection uses the instance-level family pool and selection options, while several structure and strategy options can be overridden for this call via **kwargs.

Parameters:

Name	Type	Description	Default
`data`	`(T, d) array-like`	Pseudo-observations in `(0, 1)`. If `to_pobs=True`, raw observations are converted column-wise with empirical ranks.	required
`method`	`str`	Estimation strategy for every non-independent selected pair copula. Common built-in values are `'mle'`, `'gas'` and `'scar-tm-ou'`; any method registered in the strategy registry may be used.	`'mle'`
`to_pobs`	`bool`	If True, transform `data` to pseudo-observations before fitting.	`False`
`copulas`	`list - of - lists or None`	Optional fixed edge families as `(copula_class, rotation)` in the canonical order returned by `structure.to_trees()` for each tree. If `None`, the best family is selected for each edge from the candidate pool. Use `candidates=` on the constructor for automatic family pools; `copulas=` is for pre-specified edge family/rotation specs, not copula instances.	`None`
`config`	`NumericalConfig or None`	Optional numerical configuration passed to pair-copula strategies.	`None`
`given_vars`	`iterable[int] or None`	Optional target set of variable indices for later conditional prediction. When provided, structure search prefers vines where these variables can be fixed exactly by the current suffix sampler.	`None`
`conditional_strict`	`bool`	If True and `given_vars` is set, raise `ValueError` when the selected structure cannot support exact conditional sampling for that target set. If False, fit succeeds and the result is reported through `fit_diagnostics`.	`True`
`conditional_mode`	`'suffix'`	Conditioning support mode enforced during fit. Currently only `'suffix'` is supported.	`'suffix'`
`**kwargs`	`Any`	Supported structure options include `truncation_level`, `truncation_fill`, `threshold`, `min_edge_logL`, `transform_type`, `structure_search`, `beam_width` and `dynamic_failure_policy` (`'fallback'`, `'keep'` or `'raise'`). Remaining keyword arguments are forwarded to the selected pair-copula strategy. Common strategy options include `alpha0`, `gtol`, `ftol`, `maxfun`, `maxiter`, `maxls`, `eps`, `verbose`, `scaling`, `K`, `grid_range`, `grid_method`, `adaptive`, `pts_per_sigma`, `analytical_grad` and `smart_init`.	`{}`

Returns:

Name	Type	Description
`self`	`VineCopula`	Enables chained calls, e.g. `VineCopula().fit(u).summary()`.

`log_likelihood(data=None, to_pobs=False)` ¶

Total log-likelihood.

With no argument returns the cached fitted log-likelihood. With an explicit data array, evaluates the complete fitted R-vine in the native traversal runtime.

`sample(n, u=None, rng=None, *, batch_rows=None, memory_budget_bytes=None)` ¶

Unconditional sampling from the fitted vine.

Samples in natural-order matrix order: columns are processed from right to left, and each new anti-diagonal leaf is recovered by applying inverse h-functions from the top tree down to tree 0.

Static vines are evaluated in bounded row batches. batch_rows controls the temporary vectorized workspace; the default is 8192. Dynamic edge trajectories retain their sequential full-path semantics and therefore are not split across batches.

`predict(n, u=None, rng=None, given=None, horizon='next', predictive_r_mode=None, predict_config=None, dynamic_conditioning='ignore', return_diagnostics=False, mcmc_steps=None, mcmc_burnin=None)` ¶

Draw predictive samples from the fitted R-vine.

given fixes variables in pseudo-observation space. Conditional sampling is supported when the fixed variables can be placed at the end of the R-vine variable order, read from the anti-diagonal of the natural-order matrix. This can be true in the fitted matrix itself or after rebuilding the same fitted tree structure into an equivalent natural-order matrix with those variables last.

When the model was fitted with given_vars=..., that exact target set is treated as the supported conditioning contract for the current exact sampler. Other given patterns still follow the usual best-effort check for whether the fixed variables can be placed at the end of the R-vine variable order.

For dynamic edges, horizon selects whether prediction starts from the current or next strategy-owned predictive state.

dynamic_conditioning='given_only' additionally lets fixed suffix observations update strategy-owned dynamic edge states when an edge pair is fully determined before any free variable is sampled. Static edges have no dynamic state, so 'given_only' is a no-op.

For arbitrary non-suffix given patterns, prediction uses a DAG initializer followed by MCMC. In that mode 'given_only' is reported as skipped rather than partially applied.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of predictive samples to draw.	required
`u`	`(T, d) array-like or None`	Reference pseudo-observations used to build current predictive edge states. If `None`, uses the data stored by the last `fit` call.	`None`
`horizon`	`('current', 'next')`	Predictive state timing for dynamic edges. Static MLE edges ignore this option.	`'current'`
`rng`	`Generator or None`	Random number generator. If `None`, a fresh default generator is created.	`None`
`given`	`dict[int, float] or None`	Fixed variable values in pseudo-observation space, keyed by zero-based variable index. Values must be in `(0, 1)`.	`None`
`predictive_r_mode`	`('grid', 'histogram')`	Predictive parameter sampling mode for strategies with non-point predictive state. `None` uses the strategy default.	`'grid'`
`dynamic_conditioning`	`('ignore', 'given_only')`	Whether fixed suffix observations may update eligible dynamic edge states before sampling free variables.	`'ignore'`
`predict_config`	`PredictConfig or None`	Optional bundled prediction options. Explicit non-default arguments passed to this method override the corresponding fields.	`None`
`return_diagnostics`	`bool`	If True, return `(samples, diagnostics)` instead of only samples.	`False`
`mcmc_steps`	`int or None`	Number of Metropolis-within-Gibbs single-coordinate updates used after the DAG initializer for arbitrary non-suffix `given` patterns. One full sweep contains one update per free variable. If `None`, a dimension-based default is used.	`None`
`mcmc_burnin`	`int or None`	Number of burn-in single-coordinate updates for the arbitrary- `given` MCMC fallback. If `None`, a dimension-based default is used.	`None`

Returns:

Name	Type	Description
`samples`	`(n, d) ndarray`	Predictive pseudo-observations.
	`samples, diagnostics : tuple`	Returned when `return_diagnostics=True`. Diagnostics include the conditioning method, suffix position, dynamic edge updates and MCMC acceptance, completed-sweep and convergence-warning information when applicable. `convergence_warning` is a conservative heuristic: it is set when a free coordinate accepts fewer than 2 percent of proposals or fewer than five moves per parallel chain. It is not a proof of convergence.

`summary(as_string=False)` ¶

Print R-vine structure summary.

By default the summary is printed and None is returned. Use summary(as_string=True) when a string value is needed.

Returns:

Name	Type	Description
`text`	`str or None`

`to_rvine_matrix()` ¶

Return this fitted structure as lower-triangular RVineMatrix.

RVineCopula compatibility name¶

RVineCopula is VineCopula. The old import remains supported, but it does not define a second runtime or a distinct R-vine model type.

Its methods and signatures are therefore the same as the canonical VineCopula API above.

PredictConfig¶

`pyscarcopula.PredictConfig` `dataclass` ¶

Prediction-time options shared by copulas, vines, and strategies.

Parameters:

Name	Type	Description	Default
`given`	`dict[int, float] or None`	Coordinates fixed during conditional sampling, expressed in pseudo-observation space.	`None`
`horizon`	`str`	Use "current" for the filtered state or "next" to advance one step.	`"next"`
`predictive_r_mode`	`str or None`	Sampling representation for a predictive scalar parameter: "grid" or "histogram". None selects the strategy-specific default.	`None`
`dynamic_conditioning`	`str`	Policy for updating dynamic vine edges from conditioned values: "ignore" or "given_only".	`"ignore"`
`return_diagnostics`	`bool`	Request prediction diagnostics from models that support them.	`False`
`mcmc_steps`	`int or None`	Optional non-negative counts of single-coordinate updates for conditional MCMC sampling. A full sweep updates every free variable.	`None`
`mcmc_burnin`	`int or None`	Optional non-negative counts of single-coordinate updates for conditional MCMC sampling. A full sweep updates every free variable.	`None`

Notes

Call validated after direct construction, or use replace, to normalize string values and validate integer controls.

`replace(**kwargs)` ¶

Return a validated copy with selected fields replaced.

`validated()` ¶

Return a normalized, validated copy of this configuration.

RVineMatrix¶

`pyscarcopula.vine._structure.RVineMatrix` ¶

R-vine structure encoded as a d x d lower-triangular matrix.

Convention (Dißmann et al. 2013, Joe 2014 Ch.6): - M is d x d, 0-indexed. - Diagonal M[i,i] = variable label at position i. - Below diagonal: M[k,i] for k > i gives the conditioned/conditioning structure at tree level (k - i).

For tree level t (1-indexed, t = 1..d-1): Edge at column i (i = 0..d-t-1): conditioned pair: (M[i,i], M[i+t, i]) conditioning set: {M[i+1,i], M[i+2,i], ..., M[i+t-1,i]}

Parameters:

Name	Type	Description	Default
`matrix`	`(d, d) int array`	R-vine matrix in the convention above.	required

`from_model(model)` `classmethod` ¶

Build a lower-triangular RVineMatrix from an RVineCopula.

`from_natural_order(matrix)` `classmethod` ¶

Convert a natural-order R-vine matrix to RVineMatrix.

`from_trees(d, trees)` `classmethod` ¶

Build a Bedford/Joe RVineMatrix from tree edge sets.

RVineCopula stores fitted structures as tree levels whose entries are (conditioned_frozenset, conditioning_frozenset). This helper converts that representation into the lower-triangular matrix convention used by :class:RVineMatrix.

`edge(tree, edge_idx)` ¶

Return the edge at (tree, edge_idx).

tree: 0-indexed tree level (0 = first tree) edge_idx: 0-indexed edge within tree

Returns:

Type	Description
`(var1, var2, cond_set) where:`	var1, var2 : int — conditioned variables cond_set : tuple of int — conditioning variables (empty for tree 0)

`edges_at_tree(tree)` ¶

All edges at a given tree level.

`n_trees()` ¶

`n_edges()` ¶

PairCopula¶

`pyscarcopula.vine._pair_copula.PairCopula` `dataclass` ¶

One fitted pair-copula edge.

This is the shared edge container for R-vines and C-vines. RVine uses param/log_likelihood/nfev/tau for matrix summaries; CVine additionally stores tree and idx for its level-indexed edge layout.

Attributes:

Name	Type	Description
`copula`	`BivariateCopula instance`	Family + rotation. Parameter is stored separately in `param`.
`param`	`float`	MLE copula parameter (0.0 for IndependentCopula).
`log_likelihood`	`float`	Edge log-likelihood at the fitted parameter.
`nfev`	`int`	Optimizer function evaluations (0 for closed-form / Independent).
`tau`	`float`	Empirical Kendall's tau on the pseudo-observations used to fit this edge (for diagnostics only).
`fit_result`	`FitResult`	Strategy result for this edge.
`tree`	`int or None`	Optional tree level for CVine-style layouts.
`idx`	`int or None`	Optional edge index within a CVine tree.
`fit_diagnostics`	`dict`	Edge-level fit provenance, including dynamic fallback details.

select_best_copula¶

`pyscarcopula.vine._selection.select_best_copula(u1, u2, candidates, allow_rotations=True, criterion='aic', transform_type='softplus', *, u_pair=None, tau_value=None, config=None, fit_kwargs=None)` ¶

Select best bivariate copula for (u1, u2) by AIC/BIC/logL.

Screening and refinement: Screening: rank itau estimates by AIC/BIC, keep top-N. Refinement: run L-BFGS-B on top-N, pick winner.

Always includes IndependentCopula as a baseline competitor.

Parameters:

Name	Type	Description	Default
`u1`	`(T,) arrays`		required
`u2`	`(T,) arrays`		required
`candidates`	`list of copula classes`		required
`allow_rotations`	`bool`		`True`
`criterion`	`'aic', 'bic', or 'loglik'`		`'aic'`
`transform_type`	`str`	Parameter transform forwarded to compatible candidate constructors.	`'softplus'`
`u_pair`	`(T, 2) array`	Precomputed `column_stack((u1, u2))`. When supplied, it must contain the same observations as `u1` and `u2` in the same order.	`None`
`tau_value`	`float`	Precomputed Kendall's tau for `u1` and `u2`. When omitted, the statistic is computed internally.	`None`
`config`	`NumericalConfig`	Native thread policy and MLE optimizer defaults.	`None`
`fit_kwargs`	`dict`	MLE optimizer overrides. A natural-space `alpha0` is accepted only with one non-independent candidate family; otherwise use itau starts.	`None`

Returns:

Type	Description
`SelectedCopula`	Named tuple with `.copula` and `.result` fields. It can still be unpacked as `best_copula, best_result` for backward compatibility.

`pyscarcopula.vine._selection.SelectedCopula` ¶

Bases: NamedTuple

Result returned by :func:select_best_copula.

The tuple shape is intentionally (copula, result) for backward compatibility with existing copula, result = ... callers.

Vine API¶

Public Options¶

Matrix layout and pyvinecopulib¶

VineCopula¶

pyscarcopula.vine.vine.VineCopula ¶

cvine(d, order=None, **kwargs) classmethod ¶

dvine(d, order=None, **kwargs) classmethod ¶

rvine(**kwargs) classmethod ¶

fit(data, method='mle', *, to_pobs=False, copulas=None, config=None, given_vars=None, conditional_strict=True, conditional_mode='suffix', **kwargs) ¶

log_likelihood(data=None, to_pobs=False) ¶

sample(n, u=None, rng=None, *, batch_rows=None, memory_budget_bytes=None) ¶

predict(n, u=None, rng=None, given=None, horizon='next', predictive_r_mode=None, predict_config=None, dynamic_conditioning='ignore', return_diagnostics=False, mcmc_steps=None, mcmc_burnin=None) ¶

summary(as_string=False) ¶

to_rvine_matrix() ¶

RVineCopula compatibility name¶

PredictConfig¶

pyscarcopula.PredictConfig dataclass ¶

replace(**kwargs) ¶

validated() ¶

RVineMatrix¶

pyscarcopula.vine._structure.RVineMatrix ¶

from_model(model) classmethod ¶

from_natural_order(matrix) classmethod ¶

from_trees(d, trees) classmethod ¶

edge(tree, edge_idx) ¶

edges_at_tree(tree) ¶

n_trees() ¶

n_edges() ¶

PairCopula¶

pyscarcopula.vine._pair_copula.PairCopula dataclass ¶

select_best_copula¶

pyscarcopula.vine._selection.select_best_copula(u1, u2, candidates, allow_rotations=True, criterion='aic', transform_type='softplus', *, u_pair=None, tau_value=None, config=None, fit_kwargs=None) ¶

pyscarcopula.vine._selection.SelectedCopula ¶

`pyscarcopula.vine.vine.VineCopula` ¶

`cvine(d, order=None, **kwargs)` `classmethod` ¶

`dvine(d, order=None, **kwargs)` `classmethod` ¶

`rvine(**kwargs)` `classmethod` ¶

`fit(data, method='mle', *, to_pobs=False, copulas=None, config=None, given_vars=None, conditional_strict=True, conditional_mode='suffix', **kwargs)` ¶

`log_likelihood(data=None, to_pobs=False)` ¶

`sample(n, u=None, rng=None, *, batch_rows=None, memory_budget_bytes=None)` ¶

`predict(n, u=None, rng=None, given=None, horizon='next', predictive_r_mode=None, predict_config=None, dynamic_conditioning='ignore', return_diagnostics=False, mcmc_steps=None, mcmc_burnin=None)` ¶

`summary(as_string=False)` ¶

`to_rvine_matrix()` ¶

`pyscarcopula.PredictConfig` `dataclass` ¶

`replace(**kwargs)` ¶

`validated()` ¶

`pyscarcopula.vine._structure.RVineMatrix` ¶

`from_model(model)` `classmethod` ¶

`from_natural_order(matrix)` `classmethod` ¶

`from_trees(d, trees)` `classmethod` ¶

`edge(tree, edge_idx)` ¶

`edges_at_tree(tree)` ¶

`n_trees()` ¶

`n_edges()` ¶

`pyscarcopula.vine._pair_copula.PairCopula` `dataclass` ¶

`pyscarcopula.vine._selection.select_best_copula(u1, u2, candidates, allow_rotations=True, criterion='aic', transform_type='softplus', *, u_pair=None, tau_value=None, config=None, fit_kwargs=None)` ¶

`pyscarcopula.vine._selection.SelectedCopula` ¶