mixle.stats.univariate.continuous.half_normal module

Create, estimate, and sample from a half-normal distribution (folded normal at 0).

Defines the HalfNormalDistribution, HalfNormalSampler, HalfNormalAccumulatorFactory, HalfNormalAccumulator, HalfNormalEstimator, and the HalfNormalDataEncoder classes for use with mixle.

Data type: (float): The HalfNormalDistribution with scale sigma > 0.0 has log-density

log(f(x; sigma)) = 0.5*log(2/pi) - log(sigma) - x**2 / (2*sigma**2), for x >= 0.0,

and -np.inf otherwise.

The half-normal is a one-parameter exponential family with sufficient statistic x**2:

log(f) = base(x) + eta*x**2 - A(sigma),

base(x) = 0.5*log(2/pi), (a constant on the support x >= 0) eta = -1 / (2*sigma**2), A(sigma) = log(sigma).

Declaring those pieces gives the family generated NumPy/Torch/Numba scoring through the shared exponential-family compute path, exactly as for the Gamma and inverse Gaussian families.

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

class HalfNormalDistribution(sigma, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

Half-normal distribution with scale sigma > 0 on x >= 0.

Parameters:

• sigma (float)

• name (str | None)

• keys (str | None)

classmethod compute_capabilities()

classmethod compute_declaration()

static exp_family_sufficient_statistics(x, engine)

Return the (x**2,) sufficient statistic for generated scoring.

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)

Return the (-1/(2*sigma^2),) natural parameter for generated scoring.

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)

Return the half-normal log partition log(sigma).

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

Any

static exp_family_base_measure(x, engine)

Return the support base measure 0.5*log(2/pi) (or -inf off support x >= 0).

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

Any

static exp_family_legacy_sufficient_statistics(x, params, engine)

Return per-row (count, x**2) sufficient statistics in accumulator order.

Parameters:

• x (tuple[Any, Any])

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

density(x)

Return the probability density at a single observation.

Parameters:

x (float)

Return type:

float

log_density(x)

Return the log-density at a single observation (or -inf off support).

Parameters:

x (float)

Return type:

float

seq_log_density(x)

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

Parameters:

x (Tuple[ndarray, ndarray]) – Tuple of observations and squared observations produced by the HalfNormalDataEncoder.

Returns:

Numpy array of log-density values, with -inf entries off the non-negative support.

Return type:

ndarray

static backend_log_density_from_params(vals, sq_vals, sigma, engine)

Engine-neutral half-normal log-density from explicit parameters.

Parameters:

• vals (Any)

• sq_vals (Any)

• sigma (Any)

• engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density for encoded data.

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked parameters for a homogeneous mixture kernel.

Parameters:

• dists (Sequence[HalfNormalDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

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

Parameters:

• x (tuple[Any, Any])

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

• x (tuple[Any, Any])

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, Any]

cdf(x)

Cumulative distribution function P(X <= x) (0 for x < 0).

Parameters:

x (float)

Return type:

float

quantile(q)

Inverse CDF F^{-1}(q).

Parameters:

q (float)

Return type:

float

entropy()

Differential entropy 0.5*log(pi*sigma^2/2) + 1/2.

Return type:

float

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

HalfNormalSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (Optional[float]) – Re-weight the second moment toward this instance’s own E[x**2] = sigma**2 when not None (a simple ridge toward the current parameter).

Returns:

HalfNormalEstimator object.

Return type:

HalfNormalEstimator

dist_to_encoder()

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

Return type:

HalfNormalDataEncoder

class HalfNormalSampler(dist, seed=None)

Bases: DistributionSampler

Draw iid half-normal observations as |N(0, sigma**2)|.

Parameters:

• dist (HalfNormalDistribution)

• seed (int | None)

sample(size=None)

Draw size iid observations (a float when size is None).

Parameters:

size (int | None)

Return type:

float | ndarray

class HalfNormalAccumulator(keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted count and sum of squares for half-normal estimation.

Parameters:

keys (str | None)

update(x, weight, estimate)

Parameters:

• x (float)

• weight (float)

• estimate (HalfNormalDistribution | None)

Return type:

None

initialize(x, weight, rng)

Parameters:

• x (float)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• estimate (HalfNormalDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Parameters:

suff_stat (tuple[float, float])

Return type:

HalfNormalAccumulator

value()

Return type:

tuple[float, float]

from_value(x)

Parameters:

x (tuple[float, float])

Return type:

HalfNormalAccumulator

key_merge(stats_dict)

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)

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

Return type:

HalfNormalDataEncoder

class HalfNormalAccumulatorFactory(keys=None)

Bases: StatisticAccumulatorFactory

Factory for HalfNormalAccumulator.

Parameters:

keys (str | None)

make()

Return type:

HalfNormalAccumulator

class HalfNormalEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)

Bases: ParameterEstimator

Maximum-likelihood estimator for the half-normal scale: sigma = sqrt(mean(x**2)).

Parameters:

• pseudo_count (float | None)

• suff_stat (float | None)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return type:

HalfNormalAccumulatorFactory

estimate(nobs, suff_stat)

Parameters:

• nobs (float | None)

• suff_stat (tuple[float, float])

Return type:

HalfNormalDistribution

class HalfNormalDataEncoder

Bases: DataSequenceEncoder

Encode half-normal observations as x and x**2.

seq_encode(x)

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[float])

Return type:

tuple[ndarray, ndarray]