mixle.stats.matrix.wishart module¶

Wishart distribution – a distribution over symmetric positive-definite p-by-p matrices.

The Wishart is the distribution of a scatter matrix X = sum_{i=1}^{df} z_i z_i^T with z_i ~ N(0, scale); it is the matrix generalisation of the chi-square / gamma and the standard model for random covariance matrices (and the conjugate prior for a Gaussian precision). With df >= p degrees of freedom and scale matrix V,

log f(X) = (df-p-1)/2 log|X| - 1/2 tr(V^{-1} X) - df p/2 log 2 - df/2 log|V| - log Gamma_p(df/2),

where Gamma_p is the multivariate gamma. Since E[X] = df V the scale V is estimated in closed form as the mean scatter divided by df. The degrees of freedom may be supplied (WishartEstimator(dim, df=value)) or estimated by maximum likelihood (WishartEstimator(dim, df=None)) – the latter adds the sum log det(X) sufficient statistic and solves the profile-likelihood score for df by Newton’s method.

Reference: Wishart, ‘The generalised product moment distribution in samples…’, Biometrika (1928).

class WishartDistribution(df, scale, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

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)[source]

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

Parameters:: x (ndarray)
Return type:: float

log_density(x)[source]

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

Parameters:: x (ndarray)
Return type:: float

seq_log_density(x)[source]

Vectorized log-density for a stack of SPD matrices, shape (N, p, p).

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing SPD matrices from this distribution.

Parameters:: seed (int | None)
Return type:: WishartSampler

estimator(pseudo_count=None)[source]

Return a closed-form estimator for the scale at the fixed degrees of freedom df.

Parameters:: pseudo_count (float | None)
Return type:: WishartEstimator

dist_to_encoder()[source]

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

Return type:: WishartDataEncoder

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

Bases: DistributionSampler

Draw SPD matrices by the Bartlett decomposition X = L A A^T L^T with V = L L^T.

Parameters:

dist (WishartDistribution)
seed (int | None)

sample(size=None)[source]

Draw one SPD matrix or a stacked batch of independent Wishart samples.

Parameters:: size (int | None)
Return type:: ndarray

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

Bases: _MeanScatterAccumulator

Accumulate sum_i w_i X_i, the total weight, and sum_i w_i log det(X_i).

The extra sum_logdet statistic is what enables maximum-likelihood estimation of the degrees of freedom (the inverse-Wishart base accumulator, which does not need it, is left untouched).

Parameters:

dim (int)
name (str | None)
keys (str | None)

update(x, weight, estimate)[source]

Accumulate matrix scatter and log-determinant statistics for one observation.

Parameters:

x (ndarray)
weight (float)
estimate (Any | None)

Return type:

None

seq_update(x, weights, estimate)[source]

Accumulate matrix scatter and log-determinants from encoded observations.

Parameters:

x (ndarray)
weights (ndarray)
estimate (Any | None)

Return type:

None

combine(suff_stat)[source]

Merge serialized Wishart sufficient statistics into this accumulator.

Parameters:: suff_stat (tuple[ndarray, float, float])
Return type:: WishartAccumulator

value()[source]

Return scatter, total weight, and weighted log-determinant sum.

Return type:: tuple[ndarray, float, float]

from_value(x)[source]

Restore the accumulator from serialized Wishart sufficient statistics.

Parameters:: x (tuple[ndarray, float, float])
Return type:: WishartAccumulator

scale(c)[source]

Scale accumulated Wishart sufficient statistics by a constant.

Parameters:: c (float)
Return type:: WishartAccumulator

acc_to_encoder()[source]

Return an encoder for SPD matrix observations.

Return type:: WishartDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for WishartAccumulator.

Parameters:

dim (int)
name (str | None)
keys (str | None)

make()[source]

Create an empty Wishart accumulator.

Return type:: WishartAccumulator

class WishartEstimator(dim, df=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form scale estimator (V = mean(X)/df); df=None also fits the degrees of freedom by MLE.

With a fixed df the estimator returns only the closed-form scale (E[X] = df V). With df=None it additionally estimates the degrees of freedom from sum_i w_i log det(X_i) via Newton’s method on the profile log-likelihood (_solve_wishart_df()).

Parameters:

dim (int)
df (float | None)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return a factory for Wishart sufficient-statistic accumulators.

Return type:: WishartAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the Wishart scale and optionally degrees of freedom.

Parameters:

nobs (float | None)
suff_stat (tuple[ndarray, float, float])

Return type:

WishartDistribution

class WishartDataEncoder[source]

Bases: DataSequenceEncoder

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

seq_encode(x)[source]

Encode SPD matrix observations as a floating-point stack.

Parameters:: x (Sequence[ndarray])
Return type:: ndarray