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

None

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

None

combine(suff_stat)[source]
Parameters:

suff_stat (tuple[ndarray, float, float])

Return type:

WishartAccumulator

value()[source]
Return type:

tuple[ndarray, float, float]

from_value(x)[source]
Parameters:

x (tuple[ndarray, float, float])

Return type:

WishartAccumulator

scale(c)[source]

Scale linear sufficient statistics in-place by c.

The structural default is correct for ordinary weighted sums, nested tuples/lists/dicts, and numeric arrays. Families whose value() payload includes non-linear metadata such as support bounds must override this method and leave that metadata unscaled.

Parameters:

c (float)

Return type:

WishartAccumulator

acc_to_encoder()[source]
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]
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:
accumulator_factory()[source]
Return type:

WishartAccumulatorFactory

estimate(nobs, suff_stat)[source]
Parameters:
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 the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[ndarray])

Return type:

ndarray