mixle.stats.multivariate.clayton_copula module

Clayton copula: an Archimedean copula with lower-tail dependence, on (0,1)^d.

Where the Gaussian copula is symmetric and tail-independent, the Clayton copula concentrates dependence in the LOWER tail: joint small values (a market crash where everything drops together) are far more likely than its correlation alone would suggest. It is Archimedean with generator phi(t) = (t^{-theta} - 1)/theta, theta > 0; theta -> 0 is independence, larger theta is stronger lower-tail dependence. The d-dimensional density is

c(u) = [prod_{k=1}^{d-1} (1 + k*theta)] * (prod_i u_i)^{-(1+theta)} * S^{-(d + 1/theta)}, S = sum_i u_i^{-theta} - (d - 1),

exchangeable (one parameter for every pair). Fit by Kendall’s-tau inversion: tau = theta / (theta + 2) so theta = 2*tau / (1 - tau) (averaged over pairs in d > 2). Sampled by the Marshall-Olkin frailty construction (a Gamma mixing variable shared across coordinates).

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

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

Bases: SequenceEncodableProbabilityDistribution

Clayton copula on (0,1)^d with lower-tail dependence parameter theta > 0.

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:

ClaytonCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

ClaytonCopulaEstimator

dist_to_encoder()[source]

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

Return type:

UScoreEncoder

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

Bases: DistributionSampler

Marshall-Olkin frailty: draw V ~ Gamma(1/theta, 1), E_i ~ Exp(1), u_i = (1 + E_i/V)^{-1/theta}.

Parameters:

  • dist (ClaytonCopulaDistribution)

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

Bases: ParameterEstimator

Kendall’s-tau inversion: theta = 2*tau / (1 - tau) (pair-averaged for d > 2).

Parameters:

  • dim (int)

  • 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:

ClaytonCopulaDistribution