mixle.analysis.spatial_mixture module

Spatial mixture: a mixture whose latent labels live on a grid under a Markov-random-field prior.

A plain mixture treats observations as exchangeable. When the observations sit on a grid (an image, a field of measurements, a map) the latent component labels are spatially coherent – neighbouring cells tend to share a component. This adds a Potts / Ising smoothness prior over the label field, P(z) proportional to exp(beta * sum_{i~j} 1[z_i == z_j]), on top of an arbitrary per-component mixle emission distribution. It generalizes MixtureDistribution with spatial coupling and reduces to it at beta = 0; inference is mean-field variational EM. The emission family is any mixle estimator (Gaussian, multivariate Gaussian, categorical, …), so the spatial structure is the only thing this class adds – everything about what each component emits is delegated to the library.

class SpatialMixture(shape, n_components, emission, beta=1.0)[source]

Bases: object

A grid-structured mixture with a Potts prior on the latent labels and pluggable mixle emissions.

Parameters:

  • shape – grid shape, e.g. (nx, ny) or (nx, ny, nz) – defines the neighbour structure.

  • n_components (int) – number of mixture components (latent classes).

  • emission – a mixle ParameterEstimator for the per-component family, e.g. MultivariateGaussianEstimator() – this is what makes the class domain-agnostic.

  • beta (float) – Potts coupling (>= 0); larger smooths the labels more. 0 is an ordinary mixture.

fit(observations, *, max_iter=40, mf_iter=3, seed=0)[source]

Fit by mean-field variational EM. observations is a length-prod(shape) sequence of per-cell observations (row order matches shape.ravel()); each is a single emission datum.

Robustness: components are initialized by a short hard-assignment pass and the Potts coupling is annealed from 0 to beta over the first iterations, so components form before the smoothness prior is applied (a strong prior on a degenerate init otherwise collapses every cell into one).

Parameters:
Return type:

SpatialMixture

responsibilities()[source]

The posterior label probabilities, (prod(shape), n_components) – a simplex per cell.

Return type:

ndarray

labels()[source]

The MAP label field, reshaped to shape.

Return type:

ndarray

entropy()[source]

Per-cell posterior entropy (label uncertainty), reshaped to shape.

Return type:

ndarray

component(j)[source]

The fitted mixle emission distribution of component j.

Parameters:

j (int)

Return type:

Any