mixle.stats.multivariate.student_t_copula module

Student-t copula: an elliptical copula like the Gaussian but with heavy, SYMMETRIC tail dependence.

The Gaussian copula is tail-INDEPENDENT: extreme joint moves are asymptotically as rare as independence would predict – the flaw widely blamed for underpricing joint defaults in the 2008 crisis. The Student-t copula keeps the Gaussian’s correlation matrix R but pulls each uniform back through a t_nu quantile instead of a normal one, giving symmetric UPPER- and lower-tail dependence controlled by the degrees of freedom nu (small nu = heavy joint tails; nu -> inf recovers the Gaussian copula). Its density on (0,1)^d is the multivariate-t density at the t-scores z_i = t_nu^{-1}(u_i) divided by the product of univariate-t densities:

c(u) = f_mvt(z; R, nu) / prod_i f_t(z_i; nu).

Fit by the elliptical inversion estimator (R = the correlation of the t-scores, consistent since a multivariate t has correlation R) with nu chosen by a profile likelihood over a small grid.

Reference: Demarta & McNeil, “The t Copula and Related Copulas” (Int. Stat. Review, 2005).

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

Bases: SequenceEncodableProbabilityDistribution

Student-t copula on (0,1)^d with correlation corr and degrees of freedom df.

Parameters:

  • corr (np.ndarray)

  • df (float)

  • name (str | None)

  • keys (str | None)

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:

StudentTCopulaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

StudentTCopulaEstimator

dist_to_encoder()[source]

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

Return type:

UScoreEncoder

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

Bases: DistributionSampler

Draw z ~ mvt(R, nu) (Gaussian scaled by a chi-square) then map through the univariate t_nu CDF.

Parameters:

  • dist (StudentTCopulaDistribution)

  • 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 StudentTCopulaEstimator(dim, min_eig=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Inversion for R (correlation of the t-scores) + profile likelihood over nu on a grid.

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

StudentTCopulaDistribution