mixle.stats.univariate.continuous.gaussian module

Gaussian distributions, estimators, accumulators, samplers, and encoders.

For real-valued observations, GaussianDistribution(mu, sigma2) has sigma2 > 0 and log-density:

log(f(x;mu, sigma2)) = -0.5*log(2*pi*sigma2) - 0.5*(x-mu)^2/sigma2, for real-valued x.

Reference: Johnson, Kotz & Balakrishnan, Continuous Univariate Distributions (2nd ed., Wiley, 1994/95).

class GaussianFisherView(dist)

Bases: FixedFisherView

Fisher view over the Gaussian’s (sum, sum2, count, count2) sufficient statistics.

Parameters:

dist (Any)

class GaussianDistribution(mu, sigma2, name=None, keys=None, prior=None)

Bases: SequenceEncodableProbabilityDistribution

Univariate Gaussian distribution.

Parameters:

• mu (float)

• sigma2 (float)

• name (str | None)

• keys (str | None)

• prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()

Declare backend support for generated Gaussian density kernels.

classmethod compute_declaration()

Return the generated-compute declaration for the Gaussian distribution.

static exp_family_sufficient_statistics(x, engine)

Return Gaussian sufficient statistics for generated scoring.

Parameters:

• x (Any)

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)

Return per-row Gaussian sufficient statistics in accumulator order.

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)

Return Gaussian natural parameters for generated scoring.

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)

Return Gaussian log partition for generated scoring.

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

Any

set_prior(prior)

Attach a parameter prior and precompute conjugate-prior expectations.

With a NormalGamma(mu0, lam, a, b) prior over (mu, tau=1/sigma2) this caches the variational expected natural parameters [ea, eb, e1, e2] so that expected_log_density(x) = x*(e1 + x*e2) - ea + eb (the VB E-step term). Any other prior (including None) leaves the distribution a plain point model.

Parameters:

prior (SequenceEncodableProbabilityDistribution | None)

Return type:

None

expected_log_density(x)

Variational expectation E_q[log p(x | mu, tau)] under the NormalGamma prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:

x (float)

Return type:

float

seq_expected_log_density(x)

Vectorized expected_log_density over sequence-encoded observations.

Parameters:

x (ndarray)

Return type:

ndarray

density(x)

Density of Gaussian distribution at observation x.

See log_density() for details.

Parameters:

x (float) – Real-valued observation of Gaussian.

Returns:

Density of Gaussian at x.

Return type:

float

log_density(x)

Log-density of Gaussian distribution at observation x.

Log-density of Gaussian with mean mu and variance sigma2 given by,

log(f(x;mu, sigma2)) = -0.5*log(2*pi*sigma2) - 0.5*(x-mu)^2/sigma2, for real-valued x.

Parameters:

x (float) – Real-valued observation of Gaussian.

Returns:

Log-density at observation x.

Return type:

float

seq_ld_lambda()

Return vectorized log-density callables for encoded data.

Return type:

list[Callable]

seq_log_density(x)

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:

x (np.ndarray) – Numpy array of floats.

Returns:

Numpy array of log-density (float) of len(x).

Return type:

ndarray

static backend_log_density_from_params(x, mu, sigma2, engine)

Engine-neutral Gaussian log-density from explicit parameters.

Parameters:

• x (Any)

• mu (Any)

• sigma2 (Any)

• engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density for encoded data.

Parameters:

• x (Any)

• engine (Any)

Return type:

Any

gradient_log_prior(priors, prior_strength, torch, engine)

Distribution-owned MAP prior contribution for Gaussian parameters.

Parameters:

• priors (Any)

• prior_strength (float)

• torch (Any)

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked Gaussian parameters for a homogeneous mixture kernel.

Parameters:

• dists (Sequence[GaussianDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of Gaussian log densities.

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Return stacked Gaussian sufficient statistics using engine-resident arrays.

Parameters:

• x (Any)

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, Any, Any, Any]

cdf(x)

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

Parameters:

x (float)

Return type:

float

quantile(q)

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

Parameters:

q (float)

Return type:

float

to_fisher(**kwargs)

Return the Gaussian’s own Fisher view.

mean()

Mean E[X] of the distribution.

Return type:

float

variance()

Variance Var[X] of the distribution.

Return type:

float

entropy()

Differential entropy 0.5*log(2*pi*e*sigma2).

Return type:

float

skewness()

Skewness (0).

Return type:

float

kurtosis()

Excess kurtosis (0).

Return type:

float

mode()

Mode (= the mean mu).

Return type:

float

sampler(seed=None)

Return a sampler for iid draws from this distribution.

Parameters:

seed (int | None) – Optional seed for the sampler’s random state.

Returns:

A configured GaussianSampler.

Return type:

GaussianSampler

estimator(pseudo_count=None)

Return an estimator initialized from this distribution’s shape.

Parameters:

pseudo_count (float | None) – Optional smoothing count applied to the current mean and variance.

Returns:

A GaussianEstimator.

Return type:

GaussianEstimator

dist_to_encoder()

Return an encoder for iid scalar Gaussian observations.

Return type:

GaussianDataEncoder

class GaussianSampler(dist, seed=None)

Bases: DistributionSampler

Draw independent samples from a GaussianDistribution.

Parameters:

• dist (GaussianDistribution)

• seed (int | None)

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

Draw iid samples from the Gaussian distribution.

Parameters:

• size (int | None) – Number of iid samples to draw. None returns a scalar sample.

• batched (bool)

Returns:

A scalar draw when size is None; otherwise an array of draws.

Return type:

float | ndarray

class GaussianSuffStat(sum_, sum2_, count_, count2_, receipt=None)

Bases: tuple

A (sum, sum2, count, count2) sufficient statistic that also carries side payloads.

Behaves exactly like the plain 4-tuple everywhere it is indexed, unpacked, or iterated (it is one); receipt is extra payload that GaussianAccumulator.combine() reads to fold the Kahan round-off bookkeeping (abs_total, n for sum and sum2) into the receiving accumulator when both sides are compensated, and anchored is the shift-anchored moment payload (anchor, sum_i w_i*(x_i - anchor), sum_i w_i*(x_i - anchor)^2) the accumulator maintains alongside the raw moments so the M-step variance survives large-offset data (see GaussianAccumulator). Code that doesn’t know about either payload (generic scale_suff_stat, engine kernels, …) sees an ordinary tuple.

Parameters:

• sum_ (float)

• sum2_ (float)

• count_ (float)

• count2_ (float)

• receipt (dict | None)

class GaussianAccumulator(keys=None, name=None, compensated=False)

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted first and second moments for Gaussian estimation.

Parameters:

• keys (str | None)

• name (str | None)

• compensated (bool)

update(x, weight, estimate)

Update sufficient statistics for GaussianAccumulator with one weighted observation.

Parameters:

• x (float) – Observation from Gaussian distribution.

• weight (float) – Weight for observation.

• estimate (Optional['GaussianDistribution']) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

initialize(x, weight, rng)

Initialize with a weighted observation.

Parameters:

• x (float) – Observation from Gaussian distribution.

• weight (float) – Weight for observation.

• rng (Optional[RandomState]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

seq_initialize(x, weights, rng)

Vectorized initialization from encoded weighted observations.

Parameters:

• x (ndarray) – Numpy array of floats.

• weights (ndarray) – Numpy array of positive floats.

• rng (Optional[RandomState]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

seq_update(x, weights, estimate)

Vectorized update of sufficient statistics from encoded sequence x.

Parameters:

• x (ndarray) – Numpy array of floats.

• weights (ndarray) – Numpy array of positive floats.

• estimate (Optional['GaussianDistribution']) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

combine(suff_stat)

Merge sufficient statistics into this accumulator.

Arg passed suff_stat is tuple of four floats:

suff_stat[0] (float): Sum of weighted observations (sum_i w_i*X_i), suff_stat[1] (float): Sum of weighted observations (sum_i w_i*X_i^2), suff_stat[2] (float): Sum of weighted observations (sum_i w_i), suff_stat[3] (float): Sum of weighted observations (sum_i w_i).

When this accumulator is compensated and suff_stat carries a numerics-error receipt (see value() / GaussianSuffStat), its float64 magnitude and exact term-count fields are folded in too.

Parameters:

suff_stat (Tuple[float, float, float, float]) – See above for details.

Returns:

This accumulator.

Return type:

GaussianAccumulator

scale(c)

Scale the accumulated statistics in place by c, anchored track included.

The structural default round-trips through value() and from_value(), and scale_suff_stat rebuilds the payload as a PLAIN tuple – which drops the anchored attribute, so from_value sees raw-only statistics and restarts the track unactivated. The scaled accumulator then estimates through the cancellation-prone raw form and undoes the whole shift-anchored repair: measured on sd-0.5 data at mean 1e15, seq_update then scale(0.37) fitted sigma2 = 1e+22 where the same weights passed to seq_update directly fitted 0.24625. Scaling every weight by c is reachable from ordinary use – HMM/LDA/hierarchical-mixture child accumulators and streaming EM’s batch mixing all do it.

Uniform weight scaling is exactly linear in both anchored moments and leaves the anchor (a data value, not a statistic) alone, so the track scales as the raw moments do.

The moment arithmetic lives in scale_anchored_triple; this method is pure attribute wiring, and its body is byte-identical to the Logistic/Gaussian sibling accumulator’s – flagged by the duplicate-body scanner and accepted in the manifest deliberately, because de-duplicating the wiring itself would mean a mixin coupling both classes’ private attribute names, a bigger structural change than the release stage warrants for zero remaining bug-risk (the shared math is what could drift; this cannot).

Parameters:

c (float)

Return type:

GaussianAccumulator

error_bound()

Return historical round-off diagnostics for sum/sum2.

None when this accumulator was not constructed with compensated=True – the disabled default carries no receipt to report. The compensated values are asymptotic estimates, not certified error bounds; the method name is retained for compatibility.

Return type:

dict[str, float] | None

value()

Returns sufficient statistics of GaussianAccumulator object (Tuple[float, float, float, float]).

When compensated, or once any data has been seen (so the shift-anchored moment track is live), the returned value is a GaussianSuffStat – a drop-in 4-tuple (indexing/unpacking/iteration all behave identically) that additionally carries the numerics-error receipt in its .receipt attribute and the anchored moments in its .anchored attribute, so combine() can fold them in and GaussianEstimator.estimate() can compute a shift-invariant variance.

Return type:

tuple[float, float, float, float]

from_value(x)

Replace this accumulator’s sufficient statistics.

Arg passed x is tuple of four floats:

x[0] (float): Sum of weighted observations (sum_i w_i*X_i), x[1] (float): Sum of weighted observations (sum_i w_i*X_i^2), x[2] (float): Sum of weighted observations (sum_i w_i), x[3] (float): Sum of weighted observations (sum_i w_i).

Parameters:

x (tuple[float, float, float, float]) – Tuple of (sum, sum2, count, count2).

Returns:

This accumulator.

Return type:

GaussianAccumulator

acc_to_encoder()

Return an encoder compatible with Gaussian scalar observations.

Return type:

GaussianDataEncoder

class GaussianAccumulatorFactory(name=None, keys=None, compensated=False)

Bases: StatisticAccumulatorFactory

Parameters:

• name (str | None)

• keys (str | None)

• compensated (bool)

make()

Return a GaussianAccumulator object with name and keys passed.

Return type:

GaussianAccumulator

class GaussianEstimator(pseudo_count=(None, None), suff_stat=(None, None), name=None, keys=None, prior=None, min_covar=None, compensated=False)

Bases: ParameterEstimator

Estimate Gaussian mean and variance from accumulated sufficient statistics.

The variance is formed from shift-anchored statistics whenever the accumulated statistics carry that payload (see GaussianAccumulator), which makes the fit shift-equivariant at any data offset. Statistics that arrive WITHOUT that payload cannot be corrected here – the information cancellation destroyed is not in them any more – and that is a reachable state, not a theoretical one: an engine kernel stacks the declared (sum, sum2, count, count2) moments directly, so optimize(x + 1.7e9, GaussianEstimator(), engine=NUMPY_ENGINE) on sd ~2 data returned a variance 7.9e9 times too large. estimate now WARNS in that case rather than returning it silently; the remedy is to accumulate through GaussianAccumulator (which anchors automatically) or to subtract a constant origin from the data before fitting.

ON GENUINELY DEGENERATE (zero-spread) DATA the equivariance guarantee above does not apply, and cannot: the true variance of a point mass is 0 and the true density is a Dirac delta, so the floor returned is a convention, not a measurement, and no offset makes one convention more correct than another. This estimator’s convention is ratio * mu**2 (scale-relative, so it is a UV of noise on 10 uV data and 2.9e10 on data at the Unix epoch); its sibling DiagonalGaussianEstimator uses a flat 1e-8 regardless of magnitude – the two disagree by up to 18 orders of magnitude on identical degenerate input (T1-05, campaign four), and neither is “right”. A caller that needs a specific, fixed value on this exact input – not just a safeguard against it – should pass min_covar=<value> explicitly, which both estimators honor exactly.

Parameters:

• pseudo_count (float | tuple[float | None, float | None])

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

• name (str | None)

• keys (str | None)

• prior (SequenceEncodableProbabilityDistribution | None)

• min_covar (float | None)

• compensated (bool)

accumulator_factory()

Return GaussianAccumulatorFactory with name and keys passed.

Return type:

GaussianAccumulatorFactory

model_log_density(model)

Log-density of the model parameters under the NormalGamma prior (ELBO global term).

The prior is over (mu, tau=1/sigma2), so the model’s (mu, sigma2) is mapped accordingly.

Parameters:

model (GaussianDistribution)

Return type:

float

estimate(nobs, suff_stat)

Estimate a Gaussian distribution from aggregated sufficient statistics.

The tuple is interpreted as (sum_x, sum_x2, count_for_mean, count_for_variance). Optional pseudo-counts smooth the corresponding mean and variance estimates.

Parameters:

• nobs (float | None) – Unused; accepted for the ParameterEstimator interface.

• suff_stat (tuple[float, float, float, float]) – Aggregated Gaussian sufficient statistics.

Returns:

A fitted Gaussian distribution.

Return type:

GaussianDistribution

class GaussianDataEncoder

Bases: DataSequenceEncoder

Encoder for iid scalar Gaussian observations.

seq_encode(x)

Encode sequence of iid Gaussian observations.

Data type must be List[float] or np.ndarray[float].

Parameters:

x (Union[List[float], np.ndarray]) – Sequence of iid Gaussian observations.

Returns:

A numpy array of floats.

Return type:

ndarray