mixle.stats.latent.probabilistic_pca module

Create, estimate, and sample from a Probabilistic PCA (PPCA) latent-factor model.

Defines the ProbabilisticPCADistribution, ProbabilisticPCASampler, ProbabilisticPCAAccumulatorFactory, ProbabilisticPCAAccumulator, ProbabilisticPCAEstimator, and the ProbabilisticPCADataEncoder classes for use with mixle.

Data type: np.ndarray[float] (a length-d real vector).

Probabilistic PCA is the latent linear-Gaussian model

z ~ N(0, I_q), x | z ~ N(W z + mu, sigma2 * I_d),

so marginally x ~ N(mu, C) with the structured covariance C = W W^T + sigma2 * I_d (a rank-q factor structure plus isotropic noise). It is the probabilistic foundation of PCA / factor analysis and gives a generative model, a likelihood, and a posterior over the latent factors E[z | x] = M^{-1} W^T (x - mu) (the low-dimensional embedding, exposed by transform), with M = W^T W + sigma2 * I_q.

Scoring uses the Woodbury identity, so the d-by-d inverse and log-determinant are obtained from a small q-by-q solve (C^{-1} = (I_d - W M^{-1} W^T) / sigma2 and log|C| = (d-q) log sigma2 + log|M|); the reduction is engine-neutral, so the model scores on NumPy and Torch. Estimation is the closed-form maximum-likelihood solution of Tipping & Bishop (1999): sigma2 is the mean of the discarded eigenvalues of the sample covariance and W is built from its top-q eigenpairs – no EM iteration.

class ProbabilisticPCADistribution(w, mu, sigma2, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Probabilistic PCA: x ~ N(mu, W W^T + sigma2 I) with q latent factors.

Parameters:
classmethod compute_capabilities()[source]
transform(x)[source]

Return the posterior mean of the latent factors E[z | x] = M^{-1} W^T (x - mu).

Parameters:

x (Sequence[float] | ndarray)

Return type:

ndarray

density(x)[source]

Return the probability density at a single observation.

Parameters:

x (Sequence[float] | ndarray)

Return type:

float

log_density(x)[source]

Return the log-density at a single observation.

Parameters:

x (Sequence[float] | ndarray)

Return type:

float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:

x (ndarray)

Return type:

ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:
Return type:

Any

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

ProbabilisticPCASampler

estimator(pseudo_count=None)[source]

Return a closed-form ML estimator with the latent dimension fixed at this model’s q.

Parameters:

pseudo_count (float | None)

Return type:

ProbabilisticPCAEstimator

dist_to_encoder()[source]

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

Return type:

ProbabilisticPCADataEncoder

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

Bases: DistributionSampler

Draw iid observations x = mu + W z + sigma * eps from a PPCA model.

Parameters:

  • dist (ProbabilisticPCADistribution)

  • seed (int | None)

sample(size=None)[source]

Draw size iid vectors (shape (d,) when size is None, else (size, d)).

Parameters:

size (int | None)

Return type:

ndarray

class ProbabilisticPCAAccumulator(dim=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate the weighted count, mean, and second-moment matrix (the PPCA sufficient statistics).

Parameters:

  • dim (int | None)

  • keys (str | None)

update(x, weight, estimate)[source]
Parameters:

  • x (ndarray)

  • weight (float)

  • estimate (ProbabilisticPCADistribution | None)

Return type:

None

initialize(x, weight, rng)[source]
Parameters:
Return type:

None

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

  • x (ndarray)

  • weights (ndarray)

  • estimate (ProbabilisticPCADistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]
Parameters:
Return type:

None

combine(suff_stat)[source]
Parameters:

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

Return type:

ProbabilisticPCAAccumulator

value()[source]
Return type:

tuple[float, ndarray | None, ndarray | None]

from_value(x)[source]
Parameters:

x (tuple[float, ndarray | None, ndarray | None])

Return type:

ProbabilisticPCAAccumulator

key_merge(stats_dict)[source]

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)[source]

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()[source]
Return type:

ProbabilisticPCADataEncoder

class ProbabilisticPCAAccumulatorFactory(dim=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for ProbabilisticPCAAccumulator.

Parameters:

  • dim (int | None)

  • keys (str | None)

make()[source]
Return type:

ProbabilisticPCAAccumulator

class ProbabilisticPCAEstimator(latent_dim, dim=None, min_sigma2=_MIN_SIGMA2, name=None, keys=None)[source]

Bases: ParameterEstimator

Closed-form maximum-likelihood estimator for PPCA (Tipping & Bishop eigen-solution).

Parameters:

  • latent_dim (int)

  • dim (int | None)

  • min_sigma2 (float)

  • name (str | None)

  • keys (str | None)

accumulator_factory()[source]
Return type:

ProbabilisticPCAAccumulatorFactory

estimate(nobs, suff_stat)[source]
Parameters:
Return type:

ProbabilisticPCADistribution

class ProbabilisticPCADataEncoder[source]

Bases: DataSequenceEncoder

Encode a sequence of length-d real vectors into an (n, d) float array.

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[Sequence[float]] | ndarray)

Return type:

ndarray