mixle.stats.matrix.inverse_wishart module

Inverse-Wishart distribution – a distribution over symmetric positive-definite matrices.

If X^{-1} ~ Wishart(df, scale^{-1}) then X ~ InverseWishart(df, scale); it is the conjugate prior for a multivariate-normal covariance and the standard model for a random covariance matrix (rather than a random precision). With df > p - 1 and scale matrix Psi,

log f(X) = df/2 log|Psi| - df p/2 log 2 - log Gamma_p(df/2)

• (df+p+1)/2 log|X| - 1/2 tr(Psi X^{-1}).

df is a fixed, known parameter. When df > p + 1, the scale can be estimated by the explicit method-of-moments identity Psi = (df - p - 1) * mean(X). This package labels that operation as a mean-moment fit; it is not the inverse-Wishart likelihood MLE, and it is rejected where the required mean does not exist.

Reference: Mardia, Kent & Bibby, Multivariate Analysis (Academic Press, 1979).

exception InverseWishartMomentFitError

Bases: RuntimeError

Raised when the inverse-Wishart mean-moment fit is undefined.

class InverseWishartDistribution(df, scale, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

Inverse-Wishart distribution with df degrees of freedom and scale matrix scale (p, p).

Parameters:

• df (float)

• scale (ndarray)

• name (str | None)

• keys (str | None)

density(x)

Return the density at a single (p, p) SPD matrix.

Parameters:

x (ndarray)

Return type:

float

log_density(x)

Return the log-density at a single (p, p) SPD matrix (-inf if not symmetric or not positive definite).

Mirrors seq_log_density()’s routines exactly rather than merely approximately: uses batched_pd_logdet() (the same eigenvalue-based check) instead of cholesky_logdet() for positive-definiteness/log-determinant, and the same einsum trace contraction instead of trace(A @ B). Near the positive-definiteness boundary a Cholesky factorization and an eigendecomposition can round differently and even disagree on whether a matrix is PD at all, and a full matrix product summed via trace accumulates in a different order than the direct einsum contraction – both previously made this scalar path and the vectorized path diverge (in value, and occasionally in support) on the same input.

Parameters:

x (ndarray)

Return type:

float

seq_log_density(x)

Vectorized log-density for a stack of SPD matrices, shape (N, p, p) (-inf per row that is not symmetric or not positive definite).

np.linalg.inv, like np.linalg.cholesky (see batched_pd_logdet()’s docstring), raises LinAlgError for the WHOLE batch if even one matrix is singular – singular is just the not-positive-definite boundary case, already scored -inf below via is_valid, so its inverse is never actually used. Substitute the identity for invalid rows before inverting so the call always succeeds, mirroring how the scalar log_density() path never calls inv on a matrix it is about to reject.

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for drawing SPD matrices from this distribution.

Parameters:

seed (int | None)

Return type:

InverseWishartSampler

estimator(pseudo_count=None)

Return the fixed-df mean-moment estimator when that moment exists.

Parameters:

pseudo_count (float | None)

Return type:

InverseWishartMeanMomentEstimator

dist_to_encoder()

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

Return type:

InverseWishartDataEncoder

class InverseWishartSampler(dist, seed=None)

Bases: DistributionSampler

Draw SPD matrices by inverting a Bartlett-factorized precision draw.

Parameters:

• dist (InverseWishartDistribution)

• seed (int | None)

sample(size=None, *, batched=True)

Draw one or more inverse-Wishart SPD matrix samples.

Parameters:

• size (int | None)

• batched (bool)

Return type:

ndarray

class InverseWishartAccumulator(dim, name=None, keys=None)

Bases: _MeanScatterAccumulator

Accumulate the weighted sum of matrices sum_i w_i X_i and the total weight.

Parameters:

• dim (int)

• name (str | None)

• keys (str | None)

acc_to_encoder()

Return the encoder compatible with the accumulated matrix statistics.

Return type:

InverseWishartDataEncoder

class InverseWishartAccumulatorFactory(dim, name=None, keys=None)

Bases: StatisticAccumulatorFactory

Factory for InverseWishartAccumulator.

Parameters:

• dim (int)

• name (str | None)

• keys (str | None)

make()

Create an accumulator for weighted inverse-Wishart matrix observations.

Return type:

InverseWishartAccumulator

class InverseWishartMeanMomentEstimator(dim, df, name=None, keys=None)

Bases: ParameterEstimator

Fixed-df method-of-moments estimator based on the inverse-Wishart mean.

This is not a likelihood MLE. It is defined only for df > p + 1, where E[X] = Psi / (df-p-1) exists.

Parameters:

• dim (int)

• df (float)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return an accumulator factory for estimating the fixed-df scale matrix.

Return type:

InverseWishartAccumulatorFactory

estimate(nobs, suff_stat)

Estimate scale by the inverse-Wishart mean moment, not likelihood.

Parameters:

• nobs (float | None)

• suff_stat (tuple[ndarray, float])

Return type:

InverseWishartDistribution

class InverseWishartDataEncoder(dim)

Bases: DataSequenceEncoder

Encode a sequence of (p, p) matrices as an (N, p, p) float array.

Parameters:

dim (int)

seq_encode(x)

Encode a sequence of SPD matrices as a floating matrix stack.

Parameters:

x (Sequence[ndarray])

Return type:

ndarray

row_count(x)

Return the number of matrices after validating encoded geometry.

Parameters:

x (ndarray)

Return type:

int

InverseWishartEstimator

alias of InverseWishartMeanMomentEstimator