mixle.stats.univariate.continuous.inverse_gamma module¶

Create, estimate, and sample from an inverse-gamma distribution.

Defines the InverseGammaDistribution, InverseGammaSampler, InverseGammaAccumulatorFactory, InverseGammaAccumulator, InverseGammaEstimator, and the InverseGammaDataEncoder classes for use with mixle.

Data type: (float): The InverseGammaDistribution with shape alpha > 0 and rate (scale) beta > 0 has log-density

log(f(x; alpha, beta)) = alpha*log(beta) - lgamma(alpha) - (alpha + 1)*log(x) - beta / x,

for x > 0 (it is the law of 1/Y when Y ~ Gamma(alpha, 1/beta)). It is widely used as the conjugate prior for the variance of a Gaussian, so this class also exposes get_parameters / cross_entropy / entropy for the Bayesian (conjugate-prior) estimation path, in addition to being a standalone positive-support leaf.

It is a two-parameter exponential family with sufficient statistics (log x, 1/x); once the scalar normalizer alpha*log(beta) - lgamma(alpha) is precomputed the per-row score is linear in the encoded log x and 1/x fields, so the family gets generated NumPy, Torch, and Numba kernels.

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

class InverseGammaDistribution(alpha, beta, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Inverse-gamma distribution with shape alpha > 0 and rate beta > 0 on x > 0.

Parameters:

alpha (float)
beta (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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

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

Parameters:

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

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)[source]

Return inverse-gamma sufficient statistics T(x) = (log x, 1/x).

Parameters:

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

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return inverse-gamma natural parameters eta = (-(alpha + 1), -beta).

Parameters:

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

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return inverse-gamma log partition A = lgamma(alpha) - alpha * log(beta).

Parameters:

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

Return type:

Any

static exp_family_from_natural(eta)[source]

Return the inverse-gamma with natural parameters eta = (-(alpha + 1), -beta).

Parameters:: eta (Any)
Return type:: InverseGammaDistribution

static backend_log_density_from_params(log_x, inv_x, alpha, beta, log_const, engine)[source]

Engine-neutral inverse-gamma log-density from explicit parameters (linear in log x and 1/x).

Parameters:

log_x (Any)
inv_x (Any)
alpha (Any)
beta (Any)
log_const (Any)
engine (Any)

Return type:

Any

get_parameters()[source]

Return the (shape alpha, rate beta) pair (so this can serve as a conjugate prior).

Return type:: tuple[float, float]

cross_entropy(dist)[source]

Cross entropy -E_self[log dist(x)] for an inverse-gamma argument (closed form).

Parameters:: dist (InverseGammaDistribution)
Return type:: float

entropy()[source]

Returns the differential entropy in nats.

Return type:: float

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 (log x, 1/x) observations.

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

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[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[InverseGammaDistribution])
engine (Any)

Return type:

dict[str, Any]

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

Return an (n, k) matrix of inverse-gamma 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)[source]

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, Any]

cdf(x)[source]

Cumulative distribution function P(X <= x) = Q(alpha, beta/x) (0 for x <= 0).

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:: InverseGammaSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: InverseGammaEstimator

dist_to_encoder()[source]

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

Return type:: InverseGammaDataEncoder

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

Bases: DistributionSampler

Draw iid inverse-gamma observations as 1 / Gamma(alpha, 1/beta).

Parameters:

dist (InverseGammaDistribution)
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 InverseGammaAccumulator(keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted count, sum of reciprocals, and sum of negative logs for inverse-gamma estimation.

Parameters:: keys (str | None)

update(x, weight, estimate)[source]

Parameters:

x (float)
weight (float)
estimate (InverseGammaDistribution | 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])
weights (ndarray)
estimate (InverseGammaDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]

Parameters:

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

Return type:

None

combine(suff_stat)[source]

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

value()[source]

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

from_value(x)[source]

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

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:: InverseGammaDataEncoder

class InverseGammaAccumulatorFactory(keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for InverseGammaAccumulator.

Parameters:: keys (str | None)

make()[source]

Return type:: InverseGammaAccumulator

class InverseGammaEstimator(pseudo_count=None, suff_stat=None, threshold=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood estimator for the inverse-gamma shape and rate.

Fits the gamma distribution to the reciprocals y = 1/x (y ~ Gamma(alpha, 1/beta)) by the standard log-mean / mean shape equation, then maps back to (alpha, beta) = (k, 1/theta).

Parameters:

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

accumulator_factory()[source]

Return type:: InverseGammaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

InverseGammaDistribution

class InverseGammaDataEncoder[source]

Bases: DataSequenceEncoder

Encode inverse-gamma observations as (log x, 1/x) pairs.

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

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