mixle.stats.latent.gaussian_mixture module

Multivariate Gaussian mixtures built on the generic mixture machinery.

The Gaussian mixture classes are thin specializations of mixle.stats.latent.mixture. They construct multivariate-Gaussian components from packed (mu, sig2) arrays and reuse the generic mixture scoring, posterior, EM, fused-likelihood, keying, and stability behavior.

A K-component multivariate Gaussian mixture has density

P(x) = sum_{k=1}^{K} w_k * N(x; mu_k, sigma_k),

where each observation is a length-d real vector. sig2 may be supplied as full (K, d, d) covariance matrices or as per-component diagonal variances with shape (K, d).

class GaussianMixtureDistribution(mu, sig2, w=MISSING, name=None, weights=MISSING)

Bases: MixtureDistribution

Finite mixture of full-covariance multivariate Gaussian components.

The constructor packs each (mu[k], sig2[k]) pair into a MultivariateGaussianDistribution. Density, posterior responsibility, and vectorized scoring behavior are inherited from MixtureDistribution.

Parameters:

• mu (Sequence[Sequence[float]] | ndarray) – Component means with shape (K, d).

• sig2 (Sequence[Any] | ndarray) – Component covariance matrices with shape (K, d, d) or diagonal variances with shape (K, d).

• w (Sequence[float] | ndarray) – Mixture weights with length K.

• name (str | None) – Optional diagnostic name.

• weights (Sequence[float] | ndarray) – Alias for w.

mu

Component means as a (K, d) NumPy array.

sig2

Component covariance matrices as a (K, d, d) NumPy array.

dim

Observation dimension.

density_semantics()

Return exact-or-approximate density semantics joined from Gaussian components.

sampler(seed=None)

Return a sampler that draws vectors from this Gaussian mixture.

Parameters:

seed (int | None) – Optional seed for reproducible component and Gaussian draws.

Returns:

GaussianMixtureSampler bound to this distribution.

Return type:

GaussianMixtureSampler

estimator(pseudo_count=None)

Return an estimator with matching Gaussian component structure.

Parameters:

pseudo_count (float | None) – Optional smoothing mass for mixture weights.

Returns:

GaussianMixtureEstimator suitable for fitting length-d vectors.

Return type:

GaussianMixtureEstimator

dist_to_encoder()

Return the Gaussian mixture encoder for iid vector observations.

Return type:

GaussianMixtureDataEncoder

class GaussianMixtureSampler(dist, seed=None)

Bases: DistributionSampler

Sampler for iid draws from a Gaussian mixture.

Parameters:

• dist (GaussianMixtureDistribution) – Gaussian mixture distribution to sample from.

• seed (int | None) – Optional seed for reproducible component and Gaussian draws.

rng

Random state used for component labels.

compSamplers

Per-component Gaussian samplers.

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

Draw iid samples from the Gaussian mixture.

If size is None, a single length-d numpy array is returned. Otherwise a numpy array with shape (size, d) containing ‘size’ iid samples is returned. With batched=True (default) component draws are grouped and scattered – bit-identical to the per-draw loop (batched=False) but far faster, since each component sampler owns an independent RNG.

Parameters:

• size (Optional[int]) – Number of iid samples to draw.

• batched (bool) – Vectorize component draws (default); set False for the per-draw loop.

Returns:

Numpy array with shape (d,) if size is None, else with shape (size, d).

Return type:

ndarray

class GaussianMixtureAccumulator(accumulators, keys=(None, None), init='kmeans++')

Bases: MixtureAccumulator

EM accumulator for Gaussian mixture responsibilities and component stats.

Vectorized E-step, fused-likelihood tracking, scalar update/initialize, combine/value/from_value, and key merge/replace behavior are inherited from MixtureAccumulator. The specialization only supplies the Gaussian mixture encoder.

Parameters:

• accumulators (Sequence[SequenceEncodableStatisticAccumulator]) – Component accumulators, typically one multivariate Gaussian accumulator per component.

• keys (tuple[str | None, str | None]) – Optional shared-statistic keys for weights and components.

• init (str) – Initialization strategy, one of MIXTURE_INIT_STRATEGIES.

acc_to_encoder()

Return an encoder compatible with the component accumulators.

Return type:

GaussianMixtureDataEncoder

class GaussianMixtureEstimatorAccumulatorFactory(factories, dim, keys=(None, None), init='kmeans++')

Bases: MixtureAccumulatorFactory

Factory for Gaussian mixture EM accumulators.

Parameters:

• factories (Sequence[StatisticAccumulatorFactory]) – Component accumulator factories.

• dim (int) – Number of mixture components.

• keys (tuple[str | None, str | None]) – Optional shared-statistic keys for weights and components.

• init (str) – Initialization strategy, one of MIXTURE_INIT_STRATEGIES.

make()

Return a fresh Gaussian mixture accumulator.

Return type:

GaussianMixtureAccumulator

class GaussianMixtureEstimator(estimators, name=None, conj_prior_params=None, suff_stat=None, pseudo_count=None, keys=(None, None), robust=False, init=None)

Bases: MixtureEstimator

EM estimator for a multivariate Gaussian mixture.

The weight M-step and robustness options are inherited from MixtureEstimator. The specialization repacks fitted Gaussian components into (mu, sig2, w) arrays for a GaussianMixtureDistribution.

Parameters:

• estimators (Sequence[ParameterEstimator]) – Component estimators whose fitted components carry a mean vector and a covariance (mu and covar) – typically MultivariateGaussianEstimator or DiagonalGaussianEstimator. The univariate GaussianEstimator is refused at construction (its fitted component has no covariance to pack); spell a univariate Gaussian mixture MixtureEstimator([GaussianEstimator(), ...]).

• name (str | None) – Optional diagnostic name.

• conj_prior_params (Any | None) – Reserved compatibility slot.

• suff_stat (ndarray | None) – Optional prior component-count vector used with pseudo_count.

• pseudo_count (float | None) – Optional smoothing mass for mixture weights.

• keys (tuple[str | None, str | None]) – Optional shared-statistic keys for weights and components.

• robust (bool) – Enable the robust weight floor, as on MixtureEstimator.

• init (str | None) – Initialization strategy, one of MIXTURE_INIT_STRATEGIES; None selects the default "kmeans++".

accumulator_factory()

Return a Gaussian mixture accumulator factory.

Return type:

GaussianMixtureEstimatorAccumulatorFactory

accumulatorFactory()

Deprecated alias for accumulator_factory().

New code should call accumulator_factory. The camelCase name remains available for older callers and returns the same factory, but now emits a DeprecationWarning (see docs/support-policy.rst).

Return type:

GaussianMixtureEstimatorAccumulatorFactory

estimate(nobs, suff_stat)

Estimate a Gaussian mixture from aggregated EM sufficient statistics.

The component M-step and weight estimate reuse the generic mixture estimator path. The fitted component means and covariances are then repacked into a GaussianMixtureDistribution.

Parameters:

• nobs (float | None) – Unused compatibility argument from ParameterEstimator.

• suff_stat (tuple[ndarray, tuple[Any, ...]]) – (component_counts, component_suff_stats) tuple.

Returns:

Fitted Gaussian mixture distribution.

Return type:

GaussianMixtureDistribution

class GaussianMixtureDataEncoder(encoder=None)

Bases: MixtureDataEncoder

Encoder for iid vector observations in a Gaussian mixture.

Parameters:

encoder (DataSequenceEncoder | None) – Optional component encoder. Defaults to MultivariateGaussianDataEncoder.

GaussianMixtureAccumulatorFactory

alias of GaussianMixtureEstimatorAccumulatorFactory