mixle.stats.multivariate.vine_copula module

Vine copula: build a high-dimensional dependence structure from a cascade of bivariate PAIR copulas.

A single copula family imposes ONE kind of dependence on every pair of variables at once – a Gaussian copula makes every pair tail-independent, a Clayton makes every pair lower-tail dependent. A vine (Bedford & Cooke; Aas et al. 2009) breaks that straitjacket: it factors a d-dimensional copula density into d(d-1)/2 BIVARIATE pair copulas arranged in a nested set of trees, each free to be a DIFFERENT family with its OWN parameter. So one edge can be Gaussian, another Clayton (lower-tail), another Gumbel (upper-tail) – per-edge dependence, chosen from the data.

This implements the canonical vine (C-vine): tree 1 couples a root variable to every other; tree 2 couples a second variable to the rest given the root; and so on. Density evaluation and sampling use each pair copula’s h-function (the conditional CDF h(a | b) = dC/db) and its inverse, recursively (Aas et al. 2009, Algorithms 1-2). Estimation is sequential (stepwise MLE): fit tree 1 on the raw uniform scores, transform to conditional pseudo-observations via the fitted h-functions, fit tree 2 on those, and so on – selecting the best pair-copula family per edge by likelihood.

Because a vine IS a copula (a density on (0,1)^d), CVineCopulaDistribution is a drop-in dependence CORE for CopulaDistribution – pair it with arbitrary marginals exactly like the Gaussian/Clayton/Frank/Gumbel/Student-t cores.

Reference: Aas, Czado, Frigessi & Bakken, “Pair-copula constructions of multiple dependence” (Insurance: Mathematics and Economics, 2009).

class CVineCopulaDistribution(dim, pairs, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

A canonical-vine (C-vine) copula on (0,1)^d: d(d-1)/2 bivariate pair copulas in a tree cascade.

pairs maps (tree, position) -> a fitted pair copula, tree in 1..d-1 and position in 1..d-tree (tree 1 links the root variable to each other; deeper trees link conditionally). Build one by hand, or fit with CVineCopulaEstimator (which selects a family per edge).

Parameters:

• dim (int)

• pairs (dict[tuple[int, int], Any])

• candidates (tuple[str, ...])

• name (str | None)

• keys (str | None)

log_density(u)

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

Parameters:

u (ndarray)

Return type:

float

seq_log_density(u)

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

Parameters:

u (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

CVineCopulaSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

CVineCopulaEstimator

dist_to_encoder()

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

Return type:

UScoreEncoder

class CVineCopulaSampler(dist, seed=None)

Bases: DistributionSampler

Inverse C-vine sampling (Aas et al. 2009, Algorithm 2): invert independent uniforms through the h-inverses.

Parameters:

• dist (CVineCopulaDistribution)

• seed (int | None)

sample(size=None)

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 CVineCopulaEstimator(dim, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)

Bases: ParameterEstimator

Sequential (stepwise) MLE: fit tree by tree on conditional pseudo-observations, best family per edge.

Parameters:

• dim (int)

• candidates (tuple[str, ...])

• name (str | None)

• keys (str | None)

accumulator_factory()

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

Return type:

BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)

Estimate a distribution from accumulated sufficient statistics.

Parameters:

• nobs (float | None)

• suff_stat (tuple[ndarray, ndarray])

Return type:

CVineCopulaDistribution

class DVineCopulaDistribution(dim, pairs, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

A drawable-vine (D-vine) copula on (0,1)^d: the second canonical vine, a PATH of pair copulas.

Where a C-vine has a star at each tree (one root linked to all), a D-vine has a path: tree 1 couples consecutive variables (1,2),(2,3),...,(d-1,d); deeper trees couple (i, i+j) given the variables between them. Same d(d-1)/2 pair copulas indexed (tree, position); different (path vs star) tree topology. Like the C-vine it is a drop-in dependence core for CopulaDistribution.

Parameters:

• dim (int)

• pairs (dict[tuple[int, int], Any])

• candidates (tuple[str, ...])

• name (str | None)

• keys (str | None)

log_density(u)

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

Parameters:

u (ndarray)

Return type:

float

seq_log_density(u)

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

Parameters:

u (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

DVineCopulaSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

DVineCopulaEstimator

dist_to_encoder()

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

Return type:

UScoreEncoder

class DVineCopulaSampler(dist, seed=None)

Bases: DistributionSampler

Inverse D-vine sampling (Aas et al. 2009, Algorithm 5): invert independent uniforms tree by tree.

Parameters:

• dist (DVineCopulaDistribution)

• seed (int | None)

sample(size=None)

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 DVineCopulaEstimator(dim, candidates=_DEFAULT_CANDIDATES, name=None, keys=None)

Bases: ParameterEstimator

Sequential (stepwise) MLE for a D-vine: fit tree by tree on conditional pseudo-obs, best family per edge.

Parameters:

• dim (int)

• candidates (tuple[str, ...])

• name (str | None)

• keys (str | None)

accumulator_factory()

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

Return type:

BufferedUScoreAccumulatorFactory

estimate(nobs, suff_stat)

Estimate a distribution from accumulated sufficient statistics.

Parameters:

• nobs (float | None)

• suff_stat (tuple[ndarray, ndarray])

Return type:

DVineCopulaDistribution