mixle.stats.multivariate.gumbel_copula module

Gumbel copula: an Archimedean copula with UPPER-tail dependence, on (0,1)^2 – the complement to Clayton.

Clayton concentrates dependence in the lower tail (joint crashes); Gumbel is its mirror, concentrating it in the UPPER tail (joint booms / simultaneous extremes on the high side, the tail that matters for insurance maxima, flood peaks, or a portfolio’s joint upside). It is Archimedean with generator phi(t) = (-log t)^theta, theta >= 1: theta = 1 is independence, theta -> inf is comonotonicity. The bivariate density is

C(u, v) = exp(-A), A = (x^theta + y^theta)^{1/theta}, x = -log u, y = -log v, c(u, v) = C(u, v) / (u v) * (x y)^{theta - 1} * (x^theta + y^theta)^{2/theta - 2} * (A + theta - 1).

Its upper-tail dependence coefficient is lambda_U = 2 - 2^{1/theta} (Clayton’s is lower-tail). Fit by Kendall’s-tau inversion tau = 1 - 1/theta so theta = 1 / (1 - tau); sampled by the positive-stable frailty construction (a totally-skewed stable mixing variable). Bivariate only, matching FrankCopulaDistribution – and exactly the pair-copula shape a vine consumes.

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

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

Bases: SequenceEncodableProbabilityDistribution

Gumbel copula on (0,1)^2 with upper-tail dependence parameter theta >= 1.

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:

GumbelCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

GumbelCopulaEstimator

dist_to_encoder()[source]

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

Return type:

UScoreEncoder

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

Bases: DistributionSampler

Positive-stable frailty: draw M ~ Stable(1/theta), E_i ~ Exp(1), u_i = exp(-(E_i / M)^{1/theta}).

Parameters:

  • dist (GumbelCopulaDistribution)

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

Bases: ParameterEstimator

Kendall’s-tau inversion: theta = 1 / (1 - tau) (clamped to theta >= 1).

Parameters:

  • name (str | None)

  • keys (str | None)

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:

GumbelCopulaDistribution