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)

Bases: SequenceEncodableProbabilityDistribution

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

Parameters:

• corr (ndarray)

• name (str | None)

• keys (str | None)

density(x)

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

Parameters:

x (ndarray)

Return type:

float

log_density(x)

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

Parameters:

x (ndarray)

Return type:

float

seq_log_density(x)

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

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for drawing observations from this copula.

Parameters:

seed (int | None)

Return type:

GaussianCopulaSampler

estimator(pseudo_count=None)

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

Parameters:

pseudo_count (float | None)

Return type:

GaussianCopulaEstimator

dist_to_encoder()

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

Return type:

GaussianCopulaDataEncoder

class GaussianCopulaSampler(dist, seed=None)

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)

Draw one copula sample or a batch of independent copula samples.

Parameters:

size (int | None)

Return type:

ndarray

class GaussianCopulaAccumulator(dim, name=None, keys=None)

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)

Accumulate weighted normal-score moments for one copula observation.

Parameters:

• x (ndarray)

• weight (float)

• estimate (GaussianCopulaDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize the sufficient statistics with one weighted observation.

Parameters:

• x (ndarray)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Accumulate weighted moments from encoded normal-score observations.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (GaussianCopulaDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Initialize the sufficient statistics from encoded observations.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge serialized normal-score moments into this accumulator.

Parameters:

suff_stat (tuple[ndarray, ndarray, float])

Return type:

GaussianCopulaAccumulator

value()

Return the weighted first moments, second moments, and total weight.

Return type:

tuple[ndarray, ndarray, float]

from_value(x)

Restore the accumulator from serialized normal-score moments.

Parameters:

x (tuple[ndarray, ndarray, float])

Return type:

GaussianCopulaAccumulator

key_merge(stats_dict)

Merge this accumulator into a keyed statistics dictionary.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this accumulator from a keyed statistics dictionary.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return an encoder that produces normal-score observations.

Return type:

GaussianCopulaDataEncoder

class GaussianCopulaAccumulatorFactory(dim, name=None, keys=None)

Bases: StatisticAccumulatorFactory

Factory for GaussianCopulaAccumulator.

Parameters:

• dim (int)

• name (str | None)

• keys (str | None)

make()

Create an empty Gaussian copula accumulator.

Return type:

GaussianCopulaAccumulator

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

Bases: ParameterEstimator

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

Parameters:

• dim (int)

• min_eig (float)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return a factory for Gaussian copula sufficient-statistic accumulators.

Return type:

GaussianCopulaAccumulatorFactory

estimate(nobs, suff_stat)

Estimate the copula correlation matrix from normal-score moments.

Parameters:

• nobs (float | None)

• suff_stat (tuple[ndarray, ndarray, float])

Return type:

GaussianCopulaDistribution

class GaussianCopulaDataEncoder

Bases: DataSequenceEncoder

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

seq_encode(x)

Encode copula observations by clipping and applying the normal quantile.

Parameters:

x (Sequence[ndarray])

Return type:

ndarray