mixle.stats.univariate.continuous.log_gaussian module¶

Evaluate, estimate, and sample from a log-gaussian distribution with location mu and scale sigma2.

Defines the LogGaussianDistribution, LogGaussianSampler, LogGaussianAccumulatorFactory, LogGaussianAccumulator, LogGaussianEstimator, and the LogGaussianDataEncoder classes for use with mixle.

Data type: (float): The LogGaussianDistribution with mu and sigma2 > 0.0, has log-density: log(f(x;mu, sigma2)) = -log(2*pi*sigma2) - log(x) - (log(x)-mu)^2/sigma2, for positive-valued x.

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

class LogGaussianFisherView(dist)[source]

Bases: FixedFisherView

Parameters:: dist (Any)

class LogGaussianDistribution(mu, sigma2, name=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Log-normal distribution where log(X) is Gaussian with mean mu and variance sigma2.

Parameters:

mu (float)
sigma2 (float)
name (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

static exp_family_sufficient_statistics(x, engine)[source]

Return log-Gaussian sufficient statistics for generated scoring.

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row log-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)[source]

Return log-Gaussian natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return log-Gaussian log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

Any

static exp_family_base_measure(x, engine)[source]

Return log-Gaussian base measure for generated scoring.

Parameters:

x (Any)
engine (Any)

Return type:

Any

set_prior(prior)[source]

Attach a parameter prior and precompute conjugate-prior expectations.

With a NormalGamma(mu0, lam, a, b) prior over (mu, tau=1/sigma2) of log(X) this caches the variational expected natural parameters [ea, eb, e1, e2] exactly as in the Gaussian case, so that expected_log_density(x) = y*(e1 + y*e2) - ea + eb - y with y = log(x). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

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

With a conjugate prior this is the Gaussian VB expected log-likelihood evaluated at log(x), plus the Jacobian term -log(x); without a prior it falls back to log_density(x).

Parameters:: x (float)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded (logged) observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Density of Log-Gaussian distribution at observation x.

See log_density() for details.

Parameters:: x (float) – Positive real-valued number.
Returns:: Density of Log-Gaussian at x.
Return type:: float

log_density(x)[source]

Log-density of log-Gaussian distribution at observation x.

Log-density of log-Gaussian with log-mean mu and log-variance sigma2 given by,: log(f(x;mu, sigma2)) = -0.5*log(2*pi*sigma2) - log(x) - 0.5*(log(x)-mu)^2/sigma2, for positive x.

Parameters:: x (float) – Positive valued observation of log-Gaussian.
Returns:: Log-density at observation x.
Return type:: float

seq_ld_lambda()[source]

Return vectorized log-density callables for fast scoring.

Return type:: list[Callable]

seq_log_density(x)[source]

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)[source]

Engine-neutral log-Gaussian log-density on log-encoded data.

Parameters:

x (Any)
mu (Any)
sigma2 (Any)
engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for log-encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

Any

gradient_log_prior(priors, prior_strength, torch, engine)[source]

Distribution-owned MAP prior contribution for log-Gaussian parameters.

Parameters:

priors (Any)
prior_strength (float)
torch (Any)
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked log-Gaussian parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[LogGaussianDistribution])
engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)[source]

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

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked log-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)[source]

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

Parameters:: x (float)
Return type:: float

quantile(q)[source]

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

Parameters:: q (float)
Return type:: float

to_fisher(**kwargs)[source]: Return this distribution’s own Fisher view.

mean()[source]

Mean exp(mu + sigma2/2).

Return type:: float

variance()[source]

Variance (exp(sigma2) - 1) * exp(2 mu + sigma2).

Return type:: float

entropy()[source]

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

Return type:: float

sampler(seed=None)[source]

Create an LogGaussianSampler object from parameters of LogGaussianDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: LogGaussianSampler object.
Return type:: LogGaussianSampler

estimator(pseudo_count=None)[source]

Create LogGaussianEstimator from attribute variables.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: LogGaussianEstimator object.
Return type:: LogGaussianEstimator

dist_to_encoder()[source]

Returns a LogGaussianDataEncoder object for encoding sequences of data.

Return type:: LogGaussianDataEncoder

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

Bases: DistributionSampler

Parameters:

dist (LogGaussianDistribution)
seed (int | None)

sample(size=None)[source]

Draw ‘size’ iid samples from LogGaussianSampler object.

Numpy array of length ‘size’ from log-Gaussian distribution with scale beta 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 LogGaussianAccumulator(keys=None, name=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Parameters:

keys (str | None)
name (str | None)

update(x, weight, estimate)[source]

Update sufficient statistics for LogGaussianAccumulator with one weighted observation.

Parameters:

x (float) – Observation from log-Gaussian distribution.
weight (float) – Weight for observation.
estimate (Optional['GaussianDistribution']) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

initialize(x, weight, rng)[source]

Initialize LogGaussianAccumulator object with weighted observation

Note: Just calls update().

Parameters:

x (float) – Observation from log-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)[source]

Vectorized initialization of LogGaussianAccumulator 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)[source]

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)[source]

Aggregates sufficient statistics with LogGaussianAccumulator member sufficient statistics.

Arg passed suff_stat is tuple of four floats:: suff_stat[0] (float): Sum of weighted observations (sum_i w_i*log(X_i)), suff_stat[1] (float): Sum of weighted observations (sum_i w_i*log(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:: LogGaussianAccumulator

value()[source]

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

Return type:: tuple[float, float, float, float]

from_value(x)[source]

Assigns sufficient statistics of LogGaussianAccumulator instance to x.

Arg passed x is tuple of four floats:: x[0] (float): Sum of weighted observations (sum_i w_i*log(X_i)), x[1] (float): Sum of weighted observations (sum_i w_i*log(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 details
Returns:: LogGaussianAccumulator object.
Return type:: LogGaussianAccumulator

key_merge(stats_dict)[source]

Merges LogGaussianAccumulator sufficient statistics with sufficient statistics contained in suff_stat dict that share the same key.

Parameters:: stats_dict (Dict[str, Any]) – Dict containing ‘key’ string for LogGaussianAccumulator objects to combine sufficient statistics.
Returns:: None.
Return type:: None

key_replace(stats_dict)[source]

Set the sufficient statistics of LogGaussianAccumulator to stats_key sufficient statistics if key is in: stats_dict.

Parameters:: stats_dict (Dict[str, Any]) – Dictionary mapping keys string ids to LogGaussianAccumulator objects.
Returns:: None.
Return type:: None

acc_to_encoder()[source]

Returns a LogGaussianDataEncoder object for encoding sequences of data.

Return type:: LogGaussianDataEncoder

class LogGaussianAccumulatorFactory(name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Parameters:

name (str | None)
keys (str | None)

make()[source]

Return a LogGaussianAccumulator object with name and keys passed.

Return type:: LogGaussianAccumulator

class LogGaussianEstimator(pseudo_count=(None, None), suff_stat=(None, None), min_covar=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Parameters:

pseudo_count (tuple[float | None, float | None])
suff_stat (tuple[float | None, float | None])
min_covar (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Return GaussianAccumulatorFactory with name and keys passed.

Return type:: LogGaussianAccumulatorFactory

model_log_density(model)[source]

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

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

Parameters:: model (LogGaussianDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a LogGaussianDistribution 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*log(X_i)), suff_stat[1] (float): Sum of weighted observations (sum_i w_i*log(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.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (tuple[float, float, float, float]) – See above for details.

Returns:

LogGaussianDistribution object.

Return type:

LogGaussianDistribution

class LogGaussianDataEncoder[source]

Bases: DataSequenceEncoder

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

seq_encode(x)[source]

Encode sequence of iid Log-Gaussian observations.

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

Parameters:: x (Union[List[float], np.ndarray]) – Sequence of iid log-Gaussian observations.
Returns:: A numpy array of floats.
Return type:: ndarray