mixle.stats.multivariate.gaussian_copula module

Gaussian copula: dependence structure on (0,1)^d decoupled from the marginals.

A copula is the joint distribution of U = (F_1(X_1), ..., F_d(X_d)) – each coordinate is its own marginal CDF, so every marginal is Uniform(0,1) and all that remains is the dependence. The Gaussian copula puts that dependence in a correlation matrix R: pull each uniform back to a standard normal z_i = Phi^{-1}(u_i) and let z ~ N(0, R). Its density on (0,1)^d is

c(u) = |R|^{-1/2} exp(-1/2 z^T (R^{-1} - I) z), z = Phi^{-1}(u),

(the Phi Jacobians cancel the standard-normal part of the multivariate normal). Modelling the dependence separately from the marginals is the whole point of copulas – couple any marginals you like (fit each separately) through one R. R is fit by the standard inversion estimator: the sample correlation of the transformed z.

Reference: Nelsen, An Introduction to Copulas (2nd ed., Springer, 2006).

class GaussianCopulaDistribution(corr, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gaussian copula on (0,1)^d with dependence given by a correlation matrix.

Parameters:
density(x)[source]

Return the copula density at a single point u in (0,1)^d.

Parameters:

x (ndarray)

Return type:

float

log_density(x)[source]

Return the log copula density at a single point u in (0,1)^d.

Parameters:

x (ndarray)

Return type:

float

seq_log_density(x)[source]

Vectorized log copula density for sequence-encoded observations (z = Phi^{-1}(u) rows).

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this copula.

Parameters:

seed (int | None)

Return type:

GaussianCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator that fits the correlation matrix by the inversion estimator.

Parameters:

pseudo_count (float | None)

Return type:

GaussianCopulaEstimator

dist_to_encoder()[source]

Return the data encoder (stores the normal-score transform z = Phi^{-1}(u)).

Return type:

GaussianCopulaDataEncoder

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

Bases: DistributionSampler

Draw u by sampling z ~ N(0, R) and mapping through the standard-normal CDF.

Parameters:

  • dist (GaussianCopulaDistribution)

  • 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 GaussianCopulaAccumulator(dim, name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate the weighted first and second moments of the normal scores z.

Parameters:

  • dim (int)

  • name (str | None)

  • keys (str | None)

update(x, weight, estimate)[source]
Parameters:

  • x (ndarray)

  • weight (float)

  • estimate (GaussianCopulaDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]
Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]
Parameters:

  • x (ndarray)

  • weights (ndarray)

  • estimate (GaussianCopulaDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]
Parameters:
Return type:

None

combine(suff_stat)[source]
Parameters:

suff_stat (tuple[ndarray, ndarray, float])

Return type:

GaussianCopulaAccumulator

value()[source]
Return type:

tuple[ndarray, ndarray, float]

from_value(x)[source]
Parameters:

x (tuple[ndarray, ndarray, float])

Return type:

GaussianCopulaAccumulator

key_merge(stats_dict)[source]

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)[source]

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()[source]
Return type:

GaussianCopulaDataEncoder

class GaussianCopulaAccumulatorFactory(dim, name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for GaussianCopulaAccumulator.

Parameters:

  • dim (int)

  • name (str | None)

  • keys (str | None)

make()[source]
Return type:

GaussianCopulaAccumulator

class GaussianCopulaEstimator(dim, min_eig=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Inversion estimator: the correlation of the normal scores z = Phi^{-1}(u).

Parameters:
accumulator_factory()[source]
Return type:

GaussianCopulaAccumulatorFactory

estimate(nobs, suff_stat)[source]
Parameters:
Return type:

GaussianCopulaDistribution

class GaussianCopulaDataEncoder[source]

Bases: DataSequenceEncoder

Encode each u row as its normal score z = Phi^{-1}(u).

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[ndarray])

Return type:

ndarray