mixle.stats.latent.gaussian_mixture module¶

Create, estimate, and sample from a mixture of multivariate Gaussian distributions.

Defines the GaussianMixtureDistribution, GaussianMixtureSampler, GaussianMixtureAccumulator, GaussianMixtureEstimatorAccumulatorFactory, GaussianMixtureEstimator, and the GaussianMixtureDataEncoder classes for use with mixle.

Data type: Union[List[float], np.ndarray]. Each observation is a length-d real vector.

A K-component multivariate Gaussian mixture has density

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

where w is a vector of K mixture weights summing to 1.0, mu_k is the length-d mean of component k, and sigma_k is the d-by-d positive-definite covariance matrix of component k. For convenience the covariance argument ‘sig2’ may also be given as a (K, d) array of per-component diagonal variances, which is expanded to full diagonal covariance matrices.

Implementation note: GaussianMixtureDistribution and friends are thin specializations of the generic mixture machinery in mixle.stats.latent.mixture. The vectorized E-step (seq_log_density, seq_posterior, Accumulator.seq_update, the fused-EM _track_ll path), scalar update/posterior, weight M-step, and key merge/replace are all inherited unchanged – the only Gaussian-specific pieces are constructing the multivariate-Gaussian components from (mu, sig2), repacking mu/covar in estimate(), the (n, d) ndarray sampler output, and the Gaussian data encoder.

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

Bases: MixtureDistribution

GaussianMixtureDistribution object for a mixture of full-covariance multivariate Gaussians.

A thin specialization of MixtureDistribution whose components are MultivariateGaussianDistribution objects built from (mu, sig2). All density/posterior machinery is inherited from the base mixture; only the (mu, sig2) constructor packing, __str__, and the Gaussian sampler/encoder wiring are Gaussian-specific.

Parameters:

mu (Union[Sequence[Sequence[float]], np.ndarray]) – Component means with shape (K, d).
sig2 (Union[Sequence[Any], np.ndarray]) – Component covariances. Either a (K, d, d) array of full covariance matrices or a (K, d) array of per-component diagonal variances.
w (Union[Sequence[float], np.ndarray]) – Mixture weights of length K, must sum to 1.0.
name (Optional[str]) – Assign string name to GaussianMixtureDistribution object.
weights (Sequence[float] | ndarray)

dim

Dimension d of the component Gaussians.

Type:: int

num_components

Number of mixture components K.

Type:: int

mu

Component means with shape (K, d).

Type:: np.ndarray

sig2

Component covariance matrices with shape (K, d, d).

Type:: np.ndarray

w

Mixture weights of length K.

Type:: np.ndarray

zw

Boolean array, True where a mixture weight is exactly 0.0.

Type:: np.ndarray

log_w

Log of mixture weights, -np.inf where zw is True.

Type:: np.ndarray

components

Component distributions.

Type:: List[MultivariateGaussianDistribution]

name

Name of object instance.

Type:: Optional[str]

density_semantics()[source]

What log_density returns relative to the true log-density (default: exact).

Override to declare that this distribution’s log_density is a variational lower bound (ELBO), an upper bound, or an approximation rather than the exact log p(x). This is surfaced as the ExactDensity capability and noted in mixle.describe(), so code that needs an exact likelihood can require(x, ExactDensity) instead of silently trusting a bound.

sampler(seed=None)[source]

Create GaussianMixtureSampler for sampling from GaussianMixtureDistribution instance.

Parameters:: seed (Optional[int]) – Seed to set for sampling with RandomState.
Returns:: GaussianMixtureSampler object.
Return type:: GaussianMixtureSampler

estimator(pseudo_count=None)[source]

Create GaussianMixtureEstimator for estimating GaussianMixtureDistribution.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics in estimation.
Returns:: GaussianMixtureEstimator object.
Return type:: GaussianMixtureEstimator

dist_to_encoder()[source]

Returns a GaussianMixtureDataEncoder object for encoding sequences of iid observations.

Return type:: GaussianMixtureDataEncoder

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

Bases: DistributionSampler

GaussianMixtureSampler object used to generate samples from a GaussianMixtureDistribution.

Parameters:

dist (GaussianMixtureDistribution) – GaussianMixtureDistribution to draw samples from.
seed (Optional[int]) – Seed to set for sampling with RandomState.

dist

GaussianMixtureDistribution to draw samples from.

Type:: GaussianMixtureDistribution

rng

Seeded RandomState for sampling component labels.

Type:: RandomState

compSamplers

Samplers for each mixture component.

Type:: List[MultivariateGaussianSampler]

sample(size=None, *, batched=True)[source]

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

Bases: MixtureAccumulator

GaussianMixtureAccumulator object used to aggregate sufficient statistics of observed data.

A thin specialization of MixtureAccumulator: the vectorized E-step (seq_update / seq_initialize, the fused-EM _track_ll path), scalar update/initialize, combine/value/from_value, and key merge/replace are all inherited unchanged. Only the Gaussian data encoder is Gaussian-specific.

Parameters:

accumulators (Sequence[SequenceEncodableStatisticAccumulator]) – Accumulators for the mixture components (one MultivariateGaussianAccumulator per component).
keys (Tuple[Optional[str], Optional[str]]) – Set keys for weights and mixture components.

acc_to_encoder()[source]

Returns a GaussianMixtureDataEncoder object for encoding sequences of iid observations.

Return type:: GaussianMixtureDataEncoder

class GaussianMixtureEstimatorAccumulatorFactory(factories, dim, keys=(None, None))[source]

Bases: MixtureAccumulatorFactory

GaussianMixtureEstimatorAccumulatorFactory object for creating GaussianMixtureAccumulator objects.

Parameters:

factories (Sequence[StatisticAccumulatorFactory]) – Factories for the component accumulators.
dim (int) – Number of mixture components K. Must equal the length of factories.
keys (Tuple[Optional[str], Optional[str]]) – Keys for weights and component aggregations.

factories

Factories for the component accumulators.

Type:: Sequence[StatisticAccumulatorFactory]

dim

Number of mixture components K.

Type:: int

keys

Keys for weights and component aggregations.

Type:: Tuple[Optional[str], Optional[str]]

make()[source]

Returns a GaussianMixtureAccumulator with freshly made component accumulators.

Return type:: GaussianMixtureAccumulator

class GaussianMixtureEstimator(estimators, name=None, conj_prior_params=None, suff_stat=None, pseudo_count=None, keys=(None, None))[source]

Bases: MixtureEstimator

GaussianMixtureEstimator object for estimating GaussianMixtureDistribution from sufficient statistics.

A thin specialization of MixtureEstimator: the weight M-step (incl. pseudo_count / suff_stat regularization) is inherited unchanged; only the final repacking of the estimated components into a GaussianMixtureDistribution (reading each component’s mu / covar) is Gaussian-specific.

Parameters:

estimators (Sequence[ParameterEstimator]) – ParameterEstimator objects for the mixture components (typically MultivariateGaussianEstimator objects).
name (Optional[str]) – Set name for object instance.
conj_prior_params (Optional[Any]) – Reserved for conjugate prior parameters (currently unused).
suff_stat (Optional[np.ndarray]) – Prior mixture weights used with pseudo_count to regularize the weight estimate. Must have length equal to the number of components.
pseudo_count (Optional[float]) – Used to re-weight the mixture weight sufficient statistics in estimation.
keys (Tuple[Optional[str], Optional[str]]) – Set keys for the weights and component statistics.

num_components

Number of mixture components K.

Type:: int

estimators

Component estimators.

Type:: Sequence[ParameterEstimator]

pseudo_count

Weight regularization constant.

Type:: Optional[float]

suff_stat

Prior mixture weights.

Type:: Optional[np.ndarray]

conj_prior_params

Reserved for conjugate prior parameters (currently unused).

Type:: Optional[Any]

keys

Keys for the weights and component statistics.

Type:: Tuple[Optional[str], Optional[str]]

name

Name of object instance.

Type:: Optional[str]

accumulator_factory()[source]

Returns a GaussianMixtureEstimatorAccumulatorFactory built from the component estimators.

Return type:: GaussianMixtureEstimatorAccumulatorFactory

accumulatorFactory()[source]

Deprecated alias for accumulator_factory().

Return type:: GaussianMixtureEstimatorAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a GaussianMixtureDistribution from aggregated sufficient statistics.

The component M-step and weight estimate (incl. pseudo_count / suff_stat regularization) reuse the generic MixtureEstimator path; the estimated components are then repacked into a GaussianMixtureDistribution via each component’s mu / covar.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (tuple[ndarray, tuple[Any, ...]]) – Tuple of (component counts, tuple of K component sufficient statistics).

Returns:

GaussianMixtureDistribution object.

Return type:

GaussianMixtureDistribution

class GaussianMixtureDataEncoder(encoder=None)[source]

Bases: MixtureDataEncoder

GaussianMixtureDataEncoder object for encoding sequences of iid Gaussian mixture observations.

Parameters:: encoder (Optional[DataSequenceEncoder]) – DataSequenceEncoder for the component distributions. Defaults to a MultivariateGaussianDataEncoder.

encoder

DataSequenceEncoder for the component distributions.

Type:: DataSequenceEncoder

GaussianMixtureAccumulatorFactory: alias of GaussianMixtureEstimatorAccumulatorFactory