mixle.stats.univariate.continuous.inverse_gaussian module¶

Create, estimate, and sample from an inverse Gaussian (Wald) distribution.

Defines the InverseGaussianDistribution, InverseGaussianSampler, InverseGaussianAccumulatorFactory, InverseGaussianAccumulator, InverseGaussianEstimator, and the InverseGaussianDataEncoder classes for use with mixle.

Data type: (float): The InverseGaussianDistribution with mean mu > 0.0 and shape lam > 0.0 has

log-density

log(f(x; mu, lam)) = 0.5 * (log(lam) - log(2*pi) - 3*log(x)) - lam*(x - mu)**2 / (2*mu**2*x),

for x > 0.0, else -np.inf.

The inverse Gaussian is a two-parameter exponential family with sufficient statistics (x, 1/x):

log(f) = base(x) + eta1*x + eta2*(1/x) - A(mu, lam),
base(x) = -0.5*log(2*pi) - 1.5*log(x), eta1 = -lam / (2*mu**2), eta2 = -lam / 2, A(mu, lam) = -0.5*log(lam) - lam/mu.

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

Reference: Chhikara & Folks, The Inverse Gaussian Distribution (Dekker, 1989).

class InverseGaussianDistribution(mu, lam, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Inverse Gaussian (Wald) distribution with mean mu > 0 and shape lam > 0 on x > 0.

Parameters:

mu (float)
lam (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

static exp_family_sufficient_statistics(x, engine)[source]

Return the (x, 1/x) sufficient statistics for generated scoring.

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return the (-lam/(2*mu^2), -lam/2) 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 the inverse Gaussian log partition -0.5*log(lam) - lam/mu.

Parameters:

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

Return type:

Any

static exp_family_base_measure(x, engine)[source]

Return the support base measure -0.5*log(2*pi) - 1.5*log(x) (or -inf off support).

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

Any

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

Return per-row (count, x, 1/x) sufficient statistics in accumulator order.

Parameters:

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

Return type:

tuple[Any, …]

density(x)[source]

Return the probability density at a single observation.

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

log_density(x)[source]

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

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

seq_log_density(x)[source]

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

Parameters:: x (Tuple[ndarray, ndarray, ndarray]) – Tuple of observations, reciprocals, and log values produced by the InverseGaussianDataEncoder.
Returns:: Numpy array of log-density values, with -inf entries off the positive support.
Return type:: ndarray

static backend_log_density_from_params(vals, inv_vals, log_vals, mu, lam, engine)[source]

Engine-neutral inverse Gaussian log-density from explicit parameters.

Parameters:

vals (Any)
inv_vals (Any)
log_vals (Any)
mu (Any)
lam (Any)
engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any, Any])
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[InverseGaussianDistribution])
engine (Any)

Return type:

dict[str, Any]

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

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

Parameters:

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

Return type:

Any

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

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

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

Return type:

tuple[Any, Any, Any]

cdf(x)[source]

Cumulative distribution function P(X <= x) (Wald, via scipy invgauss).

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

quantile(q)[source]

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

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

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: InverseGaussianSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (Optional[float]) – Re-weight the sufficient statistics of this instance toward its own moments when not None (a simple ridge toward the current parameters).
Returns:: InverseGaussianEstimator object.
Return type:: InverseGaussianEstimator

dist_to_encoder()[source]

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

Return type:: InverseGaussianDataEncoder

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

Bases: DistributionSampler

Draw iid inverse Gaussian (Wald) observations.

Parameters:

dist (InverseGaussianDistribution)
seed (int | None)

sample(size=None)[source]

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

Parameters:: size (int | None)
Return type:: float | ndarray

class InverseGaussianAccumulator(keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted count, sum, and sum of reciprocals for inverse Gaussian estimation.

Parameters:: keys (str | None)

update(x, weight, estimate)[source]

Parameters:

x (float)
weight (float)
estimate (InverseGaussianDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]

Parameters:

x (float)
weight (float)
rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)[source]

Parameters:

x (tuple[ndarray, ndarray, ndarray])
weights (ndarray)
estimate (InverseGaussianDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]

Parameters:

x (tuple[ndarray, ndarray, ndarray])
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Parameters:: suff_stat (tuple[float, float, float])
Return type:: InverseGaussianAccumulator

value()[source]

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

from_value(x)[source]

Parameters:: x (tuple[float, float, float])
Return type:: InverseGaussianAccumulator

key_merge(stats_dict)[source]

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

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

Return type:: InverseGaussianDataEncoder

class InverseGaussianAccumulatorFactory(keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for InverseGaussianAccumulator.

Parameters:: keys (str | None)

make()[source]

Return type:: InverseGaussianAccumulator

class InverseGaussianEstimator(pseudo_count=None, suff_stat=None, min_param=_MIN_IG_PARAM, max_param=_MAX_IG_PARAM, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the inverse Gaussian mean and shape.

The MLE is closed form: mu = mean(x) and 1/lam = mean(1/x) - 1/mu.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_param (float)
max_param (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: InverseGaussianAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

InverseGaussianDistribution

class InverseGaussianDataEncoder[source]

Bases: DataSequenceEncoder

Encode inverse Gaussian observations as x, 1/x, and log(x).

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

Parameters:: x (Sequence[float])
Return type:: tuple[ndarray, ndarray, ndarray]