mixle.stats.multivariate.multivariate_student_t module

Multivariate Student’s t distributions over real-valued vectors.

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 MultivariateStudentTSuffStat(count, sum_u, sum_ux, sum_uxx, anchored=None)[source]

Bases: tuple

A (count, sum_u, sum_ux, sum_uxx) statistic that also carries shift-anchored moments.

Behaves exactly like the plain 4-tuple everywhere it is indexed, unpacked, iterated or validated by student_t_moments() (it is one); anchored is the extra payload (anchor, sum_i w_i u_i (x_i - anchor), sum_i w_i u_i (x_i - anchor)(x_i - anchor)^T), the same EM-reweighted moments expressed about a data anchor instead of about the origin. Code that doesn’t know about the payload sees an ordinary tuple and the estimate falls back to the historical raw path.

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

Describe backend support for generated multivariate Student-t kernels.

classmethod compute_declaration()[source]

Return the structured compute declaration for multivariate Student-t distributions.

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, *, batched=True)[source]

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

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

Alongside those raw moments the accumulator keeps a CONDITIONING-GATED shift-anchored track. The M-step forms sum_uxx - mu sum_ux' - sum_ux mu' + sum_u mu mu', which loses ~``2*log2(abs(mean)/sd)`` bits to cancellation, so sd ~2 data at the Unix-epoch offset fitted a scale matrix collapsed to ~1e-6 (and a ValueError at 1e10) with no warning at all. Anchoring at a data value keeps every term of the scatter O(sum_u * spread^2), which makes the scale matrix shift-invariant. The track is gated: a chunk whose abs(mean)/spread ratio the raw form handles to ~1e-9 relative error (see needs_vector_anchor()) accumulates exactly the historical single-pass way – bit-identical statistics, no second pass. The raw moments remain the exchange format, so the anchored track rides along as a payload on MultivariateStudentTSuffStat.

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

Accumulate one EM reweighted vector observation.

Parameters:
Return type:

None

initialize(x, weight, rng)[source]

Initialize statistics from one vector observation.

Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]

Accumulate EM reweighted statistics from encoded vectors.

Parameters:

  • x (ndarray)

  • weights (ndarray)

  • estimate (MultivariateStudentTDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize statistics from encoded vectors.

Parameters:
Return type:

None

combine(suff_stat)[source]

Merge another multivariate Student-t sufficient-statistic tuple.

Parameters:

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

Return type:

MultivariateStudentTAccumulator

value()[source]

Return count, latent-weight total, weighted sum, and weighted second moment.

A plain 4-tuple for every consumer that treats it as one – student_t_moments included; once the shift-anchored track is live it is a MultivariateStudentTSuffStat that additionally carries those moments in its anchored attribute, so combine() can fold them in and MultivariateStudentTEstimator.estimate() can form a shift-invariant scale matrix.

Return type:

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

from_value(x)[source]

Replace accumulator contents from sufficient statistics.

Parameters:

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

Return type:

MultivariateStudentTAccumulator

scale(c)[source]

Scale the accumulated statistics in place by c, anchored track included.

The structural default round-trips through value()/from_value(), and scale_suff_stat rebuilds the payload as a PLAIN tuple – which drops the anchored track and undoes the repair. Scaling every weight by c scales both anchored moments by c and leaves the anchor (a data value, not a statistic) alone.

Parameters:

c (float)

Return type:

MultivariateStudentTAccumulator

acc_to_encoder()[source]

Return the encoder used by this accumulator.

Return type:

MultivariateStudentTDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for MultivariateStudentTAccumulator.

Parameters:
make()[source]

Create a fresh multivariate Student-t accumulator.

Return type:

MultivariateStudentTAccumulator

class MultivariateStudentTEstimator(dof=5.0, dim=None, pseudo_count=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.

The scale matrix is formed from shift-anchored statistics whenever the accumulated sufficient statistics carry that payload (see MultivariateStudentTAccumulator), which makes the fit SHIFT-EQUIVARIANT: estimating on x + c returns loc + c with the scale matrix unchanged, for any constant c the data can carry – epoch seconds (~1.7e9) and 2**31 included. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones that arrived already reduced from an engine kernel or an older serialization – the historical raw path is used bit-identically, and estimate warns rather than returning a scale matrix it cannot stand behind.

Residual limit, and it is representational rather than algorithmic. One M-step is shift-equivariant to ~1e-15, but a full EM run is not exactly so: the latent reweighting u_i = (nu + p)/(nu + delta_i) is a function of x_i - mu, and mu is a float64 at the data’s own magnitude, so it can only be placed on that grid – 1.2e-4 apart at offset 1e12. Snapping the un-shifted fit’s mu onto exactly that grid reproduces the shifted fit to 3e-14, which is what identifies the mechanism. The effect on the fitted scale matrix is bounded by roughly ulp(abs(mu)) / spread per iteration: 4e-8 at epoch seconds, 1e-7 at 2**31, 7e-5 at 1e12. Every consumer of a fitted location faces the same granularity, so there is no more precise answer to return; subtract a constant origin before fitting if a tighter one is needed.

Parameters:
accumulator_factory()[source]

Return an accumulator factory for fixed-dof Student-t EM statistics.

Return type:

MultivariateStudentTAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location and scale from EM reweighted statistics.

Parameters:
Return type:

MultivariateStudentTDistribution

class MultivariateStudentTDataEncoder(dim=None)[source]

Bases: DataSequenceEncoder

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

Parameters:

dim (int | None)

seq_encode(x)[source]

Encode observations as an (n, p) floating-point matrix.

Parameters:

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

Return type:

ndarray