mixle.stats.multivariate.multivariate_student_t module

Create, estimate, and sample from a multivariate Student’s t distribution.

Defines the MultivariateStudentTDistribution, MultivariateStudentTSampler, MultivariateStudentTAccumulatorFactory, MultivariateStudentTAccumulator, MultivariateStudentTEstimator, and the MultivariateStudentTDataEncoder classes for use with mixle.

Data type: np.ndarray[float] (a length-p real vector).

x ~ MVT(dof, loc, shape) with degrees of freedom nu = dof > 0, location vector mu (length p), and a p-by-p symmetric positive-definite scale matrix Sigma. The log-density is

log(f(x)) = gammaln((nu + p)/2) - gammaln(nu/2) - 0.5*p*log(nu*pi) - 0.5*log|Sigma|

  • 0.5*(nu + p)*log(1 + delta(x)/nu),

where delta(x) = (x - mu)’ Sigma^{-1} (x - mu) is the squared Mahalanobis distance. As nu -> inf the distribution converges to MVN(mu, Sigma); for nu > 2 the covariance is nu/(nu - 2) * Sigma. The heavy tails make it a robust alternative to the multivariate normal.

Estimation keeps nu fixed and runs the EM / iteratively-reweighted update (each observation gets the latent-scale weight u_i = (nu + p)/(nu + delta_i) under the current estimate), which is the standard maximum-likelihood scheme for a known degrees of freedom. The engine-neutral backend_log_density_from_params gives the family generated NumPy and Torch scoring.

Reference: Kotz & Nadarajah, Multivariate t Distributions and Their Applications (Cambridge, 2004).

class MultivariateStudentTDistribution(dof, loc, shape, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Multivariate Student’s t distribution with degrees of freedom dof, location mu, and scale Sigma.

Parameters:
classmethod compute_capabilities()[source]
classmethod compute_declaration()[source]
static backend_log_density_from_params(x, mu, inv_shape, log_const, dof, dim, engine)[source]

Engine-neutral multivariate Student’s t log-density from fitted parameters.

Parameters:
Return type:

Any

condition(observed)[source]

Return the conditional distribution over the unobserved dimensions given observed.

The conditional of a multivariate Student-t is again a multivariate Student-t. With observed dimensions o (Mahalanobis d_o) and unobserved u:

dof’ = dof + |o|, mu’ = mu_u + S_uo S_oo^{-1} (x_o - mu_o), shape’ = (dof + d_o)/(dof + |o|) * (S_uu - S_uo S_oo^{-1} S_ou),

i.e. the location shifts like the Gaussian conditional but the scale is inflated by how far the observed coordinates fall in the tails (given=-style conditional sampling). Raises if no dimension is left unobserved.

Parameters:

observed (dict[int, float])

Return type:

MultivariateStudentTDistribution

marginal(keep)[source]

Return the marginal over the dimensions keep: MVT(dof, mu[keep], shape[keep, keep]).

A multivariate Student-t marginal keeps the same degrees of freedom and simply restricts the location and shape to the kept coordinates (order preserved).

Parameters:

keep (Sequence[int])

Return type:

MultivariateStudentTDistribution

density(x)[source]

Return the probability density at a single observation.

Parameters:

x (Sequence[float] | ndarray)

Return type:

float

log_density(x)[source]

Return the log-density at a single observation.

Parameters:

x (Sequence[float] | ndarray)

Return type:

float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:

x (ndarray)

Return type:

ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:
Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for equal-dimensional multivariate Student’s t mixtures.

Parameters:

  • dists (Sequence[MultivariateStudentTDistribution])

  • engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of multivariate Student’s t component log densities.

Parameters:
Return type:

Any

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

MultivariateStudentTSampler

estimator(pseudo_count=None)[source]

Return an EM estimator that keeps dof fixed at this distribution’s value.

Parameters:

pseudo_count (float | None)

Return type:

MultivariateStudentTEstimator

dist_to_encoder()[source]

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

Return type:

MultivariateStudentTDataEncoder

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

Bases: DistributionSampler

Draw iid multivariate Student’s t observations as mu + Z * sqrt(nu / G).

Parameters:

  • dist (MultivariateStudentTDistribution)

  • seed (int | None)

sample(size=None)[source]

Draw size iid vectors (shape (p,) when size is None, else (size, p)).

Parameters:

size (int | None)

Return type:

ndarray

class MultivariateStudentTAccumulator(dof, dim=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate the EM/IRLS sufficient statistics for multivariate Student’s t estimation.

The reweighting u_i = (nu + p)/(nu + delta_i) is computed from the previous estimate; with no estimate (initialization) every u_i = 1, which seeds the fit with the Gaussian moment statistics.

Parameters:
update(x, weight, estimate)[source]
Parameters:
Return type:

None

initialize(x, weight, rng)[source]
Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]
Parameters:

  • x (ndarray)

  • weights (ndarray)

  • estimate (MultivariateStudentTDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]
Parameters:
Return type:

None

combine(suff_stat)[source]
Parameters:

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

Return type:

MultivariateStudentTAccumulator

value()[source]
Return type:

tuple[float, float, ndarray | None, ndarray | None]

from_value(x)[source]
Parameters:

x (tuple[float, float, ndarray | None, ndarray | None])

Return type:

MultivariateStudentTAccumulator

key_merge(stats_dict)[source]

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)[source]

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()[source]
Return type:

MultivariateStudentTDataEncoder

class MultivariateStudentTAccumulatorFactory(dof, dim=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for MultivariateStudentTAccumulator.

Parameters:
make()[source]
Return type:

MultivariateStudentTAccumulator

class MultivariateStudentTEstimator(dof=5.0, dim=None, min_ridge=_MIN_RIDGE, name=None, keys=None)[source]

Bases: ParameterEstimator

Fixed-dof EM estimator for the multivariate Student’s t location and scale matrix.

Parameters:
accumulator_factory()[source]
Return type:

MultivariateStudentTAccumulatorFactory

estimate(nobs, suff_stat)[source]
Parameters:
Return type:

MultivariateStudentTDistribution

class MultivariateStudentTDataEncoder[source]

Bases: DataSequenceEncoder

Encode a sequence of length-p real vectors into an (n, p) float array.

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[Sequence[float]] | ndarray)

Return type:

ndarray