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, prior=None)

Bases: SequenceEncodableProbabilityDistribution

Univariate Gaussian distribution.

Parameters:

• mu (float)

• sigma2 (float)

• name (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)

Draw iid samples from the Gaussian distribution.

Parameters:

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

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 a numerics receipt.

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 error-bound bookkeeping (abs_total, n for sum and sum2) into the receiving accumulator when both sides are compensated. Code that doesn’t know about compensated accumulation (serialization, generic scale_suff_stat, …) 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), the receipt is folded in too – its (abs_total, n) fields add exactly, just like sum/count above, so error_bound() composes correctly across combined partitions.

Parameters:

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

Returns:

This accumulator.

Return type:

GaussianAccumulator

error_bound()

Return the running numerics-error bound receipt for sum/sum2.

None when this accumulator was not constructed with compensated=True – the disabled default carries no receipt to report.

Return type:

dict[str, float] | None

value()

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

When compensated, 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, so combine() can fold it in.

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

key_merge(stats_dict)

Merge sufficient statistics from stats_dict when this accumulator’s key is present.

Parameters:

stats_dict (Dict[str, Any]) – Dict mapping keys to sufficient statistics.

Returns:

None.

Return type:

None

key_replace(stats_dict)

Replace sufficient statistics from suff_stats when this accumulator’s key is present.

Parameters:

stats_dict (Dict[str, Any]) – Dict mapping keys to sufficient statistics.

Returns:

None.

Return type:

None

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.

Parameters:

• pseudo_count (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