mixle.stats.univariate.continuous.gaussian module

Evaluate, estimate, and sample from a gaussian distribution with mean mu and variance sigma2.

Defines the GaussianDistribution, GaussianSampler, GaussianAccumulatorFactory, GaussianAccumulator, GaussianEstimator, and the GaussianDataEncoder classes for use with mixle.

Data type: (float): The GaussianDistribution with mean mu and variance sigma2 > 0.0, has 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()

classmethod compute_declaration()

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)

Create an GaussianSampler object from parameters of GaussianDistribution instance.

Parameters:

seed (Optional[int]) – Used to set seed in random sampler.

Returns:

GaussianSampler object.

Return type:

GaussianSampler

estimator(pseudo_count=None)

Create GaussianEstimator with mu and sigma2 passed if pseudo_count is not None.

Arg variable pseudo_count is used to pass and re-weight mu and sigma2 of GaussianDistribution instance. Simply creates a GaussianEstimator with name passed if pseudo_count is None.

Parameters:

pseudo_count (Optional[float]) – Used to inflate sufficient statistics.

Returns:

GaussianEstimator object.

Return type:

GaussianEstimator

dist_to_encoder()

Returns a GaussianDataEncoder object for encoding sequences of data.

Return type:

GaussianDataEncoder

class GaussianSampler(dist, seed=None)

Bases: DistributionSampler

Parameters:

• dist (GaussianDistribution)

• seed (int | None)

sample(size=None)

Draw ‘size’ iid samples from GaussianSampler object.

Numpy array of length ‘size’ from Gaussian distribution with mean mu and scale sigma2 if size not None. Else a single sample is returned as float.

Parameters:

size (Optional[int]) – Treated as 1 if None is passed.

Returns:

‘size’ iid samples from Gaussian distribution.

Return type:

float | ndarray

class GaussianAccumulator(keys=None, name=None)

Bases: SequenceEncodableStatisticAccumulator

Parameters:

• keys (str | None)

• name (str | None)

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 GaussianAccumulator object with weighted observation

Note: Just calls update().

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 of GaussianAccumulator sufficient statistics with weighted observations.

Note: Just calls seq_update().

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)

Aggregates sufficient statistics with GaussianAccumulator member sufficient statistics.

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).

Parameters:

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

Returns:

GaussianAccumulator object.

Return type:

GaussianAccumulator

value()

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

Return type:

tuple[float, float, float, float]

from_value(x)

Assigns sufficient statistics of GaussianAccumulator instance to x.

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]) – See above for deatils.

Returns:

GaussianAccumulator object.

Return type:

GaussianAccumulator

key_merge(stats_dict)

Merge sufficient statistics of object instance with suff stats containing matching keys.

Parameters:

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

Returns:

None.

Return type:

None

key_replace(stats_dict)

Set sufficient statistics of object instance to suff_stats with matching keys.

Parameters:

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

Returns:

None.

Return type:

None

acc_to_encoder()

Returns a GaussianDataEncoder object for encoding sequences of data.

Return type:

GaussianDataEncoder

class GaussianAccumulatorFactory(name=None, keys=None)

Bases: StatisticAccumulatorFactory

Parameters:

• name (str | None)

• keys (str | None)

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)

Bases: ParameterEstimator

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)

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 GaussianDistribution object from sufficient statistics aggregated from data.

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),

obtained from aggregation of observations.

If member variable pseudo_count is not None, suff_stat is combined with re-weighted member instance variables suff_stat. If pseudo_count is None, arg suff_stat is used to form maximum likelihood estimates for mu and sigma2 of GaussianDistribution object.

Parameters:

• nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.

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

Returns:

GaussianDistribution object.

Return type:

GaussianDistribution

class GaussianDataEncoder

Bases: DataSequenceEncoder

GaussianDataEncoder object for encoding sequences of iid Gaussian observations with data type float.

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