mixle.stats.multivariate.rvine_copula module

Regular vine (R-vine): the general vine that subsumes both the C-vine and the D-vine.

A C-vine forces every tree to be a star (one root linked to all); a D-vine forces every tree to be a path. A regular vine lifts both restrictions: each tree may be ANY spanning tree (subject to the proximity condition that consecutive trees nest correctly), so the pair-copula construction can follow whatever dependence graph the data actually has. This is the general object (Bedford & Cooke 2002; Dißmann et al. 2013) of which C- and D-vines are special cases.

The practical payoff is automatic structure selection: rather than fixing the order by hand, RVineCopulaEstimator runs Dißmann’s greedy algorithm – tree 1 is the maximum spanning tree over |Kendall's tau| among all pairs; each deeper tree is the maximum spanning tree over the previous tree’s edges (respecting proximity), weighted by the conditional |tau| – and fits the best pair-copula family per edge as it goes. So the vine picks both its shape and its per-edge families from the data.

Because a vine IS a copula on (0,1)^d, RVineCopulaDistribution is a drop-in dependence core for CopulaDistribution, exactly like the C-vine, D-vine, and the elliptical/Archimedean cores.

This module reuses the bivariate pair copulas (with their h-functions) from mixle.stats.multivariate.vine_copula.

Reference: Dißmann, Brechmann, Czado & Kurowicka, “Selecting and estimating regular vine copulae and application to financial returns” (Computational Statistics & Data Analysis, 2013).

class RVineCopulaDistribution(dim, trees, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A regular-vine copula on (0,1)^d: an arbitrary tree sequence of bivariate pair copulas.

Construct with RVineCopulaEstimator (Dißmann selection), which picks the tree structure AND a pair-copula family per edge from data. trees is the fitted structure (a list of trees, each a list of _Edge); dim the number of variables.

Parameters:
log_density(u)[source]

Return the log-density or log-mass at a single observation.

Parameters:

u (ndarray)

Return type:

float

seq_log_density(u)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:

u (ndarray)

Return type:

ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

RVineCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

RVineCopulaEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:

UScoreEncoder

class RVineCopulaSampler(dist, seed=None)[source]

Bases: DistributionSampler

Sample by inverse Rosenblatt over the fitted structure (generic numerical conditional inversion).

Parameters:

  • dist (RVineCopulaDistribution)

  • seed (int | None)

sample(size=None)[source]

Draw observations.

Combinator samplers (mixture/sequence/…) accept batched. With batched=True (the default) each child stream is drawn in one vectorized call instead of a per-draw Python loop – far faster. Because every child sampler owns an independent RandomState, batching consumes each stream in the same order as the loop, so the draws are identical to the legacy path. batched=False forces that legacy per-draw loop as a guaranteed- stable reference. Leaf samplers are already vectorized and ignore the flag.

Parameters:

size (int | None)

Return type:

ndarray

class RVineCopulaEstimator(dim, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)[source]

Bases: ParameterEstimator

Dißmann selection + sequential MLE: choose the tree structure and per-edge family from data.

Parameters:
accumulator_factory()[source]

Return the accumulator factory used to collect this estimator’s sufficient statistics.

Return type:

BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a distribution from accumulated sufficient statistics.

Parameters:
Return type:

RVineCopulaDistribution