mixle.stats.multivariate.frank_copula module

Frank copula: a symmetric Archimedean copula with NO tail dependence, on (0,1)^2.

The Frank copula is the symmetric Archimedean member: unlike Clayton (lower-tail) it is radially symmetric and has no tail dependence, and unlike the Gaussian it can be fit by a single interpretable parameter. Crucially it spans the FULL dependence range – theta > 0 is positive dependence, theta < 0 NEGATIVE dependence, theta -> 0 independence – so it is the natural core when the coupling may be either sign. Bivariate density

c(u, v) = theta * (1 - e^{-theta}) * e^{-theta (u + v)} / [ (1 - e^{-theta}) - (1 - e^{-theta u})(1 - e^{-theta v}) ]^2 .

Fit by 1-D maximum likelihood on theta (its Kendall’s-tau relation involves the Debye function, so direct MLE on the copula likelihood is both simpler and exact). Sampled by conditional inversion. Bivariate only: the general-d Frank density is not a clean closed form, so d != 2 is rejected rather than approximated.

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

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

Bases: SequenceEncodableProbabilityDistribution

Frank copula on (0,1)^2 with dependence parameter theta (any sign; 0 = independence).

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:

FrankCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

FrankCopulaEstimator

dist_to_encoder()[source]

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

Return type:

UScoreEncoder

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

Bases: DistributionSampler

Conditional inversion: draw u1, w uniform, solve v from the conditional C(v | u1) = w.

Parameters:

  • dist (FrankCopulaDistribution)

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

Bases: ParameterEstimator

1-D maximum likelihood on theta over [-40, 40] (golden section on the copula log-likelihood).

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:

FrankCopulaDistribution