mixle.stats.univariate.continuous.gamma module¶

Create, estimate, and sample from a gamma distribution with shape k and scale theta.

Defines the GammaDistribution, GammaSampler, GammaAccumulatorFactory, GammaAccumulator, GammaEstimator, and the GammaDataEncoder classes for use with mixle.

Data type: (float): The GammaDistribution with shape k > 0.0 and scale theta > 0.0, has log-density: log(f(x;k,theta)) = -gammaln(k) - k*log(theta) + (k-1) * log(x) - x / theta, for x > 0.0, else -np.inf

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

class GammaFisherView(dist)[source]

Bases: FixedFisherView

Parameters:: dist (Any)

class GammaDistribution(k, theta, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gamma distribution parameterized by shape and scale.

Parameters:

k (float)
theta (float)
name (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

static exp_family_sufficient_statistics(x, engine)[source]

Return Gamma sufficient statistics for generated scoring.

Parameters:

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

Return type:

tuple[Any, …]

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

Return per-row Gamma sufficient statistics in accumulator order.

Parameters:

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

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Gamma 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 Gamma log partition for generated scoring.

Parameters:

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

Return type:

Any

static exp_family_base_measure(x, engine)[source]

Return Gamma support base measure for generated scoring.

Parameters:

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

Return type:

Any

get_parameters()[source]

Return the (shape k, scale theta) pair.

Lets a GammaDistribution serve as a conjugate prior (on a Poisson/Exponential rate, or a Gamma scale) under the unified Bayesian estimation protocol.

Return type:: tuple[float, float]

cross_entropy(dist)[source]

Cross entropy -E_self[log dist(x)] for a Gamma argument (closed form).

Used as the conjugate prior/posterior cross-entropy term in variational Bayes (e.g. the ELBO global term in DPM for Poisson/Exponential-rate components).

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

entropy()[source]

Returns the differential entropy in nats.

Return type:: float

density(x)[source]

Density of gamma distribution evaluated at x.

See log_density() for details.

Parameters:: x (float) – Positive real-valued number.
Returns:: Density of gamma distribution evaluated at x.
Return type:: float

log_density(x)[source]

Log-density of gamma distribution evaluated at x.

Log-density given by, If x > 0.0,

log(f(x;k,theta)) = -gammaln(k) - k*log(theta) + (k-1) * log(x) - x / theta,

else,: -np.inf

Parameters:: x (float) – Positive real-valued number.
Returns:: Log-density of gamma distribution evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of sequence encoded observations from gamma distribution.

Input must be x (Tuple[ndarray, ndarray]):: x[0]: Numpy array of floats containing observations from gamma distribution. x[1]: Numpy array of floats containing log of observation values.

Parameters:: x (Tuple[np.ndarray, np.ndarray]) – See above for details.
Returns:: Numpy array containing log-density evaluated at all observations of encoded sequence x.
Return type:: ndarray

static backend_log_density_from_params(vals, log_vals, k, theta, engine)[source]

Engine-neutral gamma log-density from explicit parameters.

Parameters:

vals (Any)
log_vals (Any)
k (Any)
theta (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])
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Gamma parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GammaDistribution])
engine (Any)

Return type:

dict[str, Any]

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

Return an (n, k) matrix of 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 Gamma 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) (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 E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

skewness()[source]

Skewness 2/sqrt(k).

Return type:: float

kurtosis()[source]

Excess kurtosis 6/k.

Return type:: float

mode()[source]

Mode (k-1)*theta for k>=1, else 0.

Return type:: float

sampler(seed=None)[source]

Create a GammaSampler object from GammaDistribution.

Parameters:: seed (Optional[int]) – Set seed on random number generator.
Returns:: GammaSampler object.
Return type:: GammaSampler

estimator(pseudo_count=None)[source]

Creates GammaEstimator object from GammaDistribution instance.

Parameters:: pseudo_count (Optional[float]) – Re-weight the sufficient statistics of GammaDistribution instance if not None.
Returns:: GammaEstimator object.
Return type:: GammaEstimator

dist_to_encoder()[source]

Returns GammaDataEncoder object for encoding sequence of GammaDistribution observations.

Return type:: GammaDataEncoder

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

Bases: DistributionSampler

Parameters:

dist (GammaDistribution)
seed (int | None)

sample(size=None)[source]

Draw ‘size’-iid observations from GammaSampler.

Parameters:: size (Optional[int]) – Number of iid samples to draw from GammaSampler.
Returns:: Single sample (float) if size is None, else a numpy array of floats containing iid samples from GammaDistribution.
Return type:: float | ndarray

class GammaAccumulator(keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Parameters:: keys (str | None)

initialize(x, weight, rng)[source]

Initialize sufficient statistics of GammaAccumulator with weighted observation.

Note: Just calls update.

Parameters:

x (float) – Positive real-valued observation of gamma.
weight (float) – Positive real-valued weight for observation x.
rng (Optional[RandomState]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

seq_initialize(x, weights, rng)[source]

Vectorized initialization of GammaAccumulator sufficient statistics with weighted observations.

Note: Just calls seq_update().

Parameters:

x (Tuple[ndarray, ndarray]) – Tuple of Numpy array of observations and log(observations).
weights (ndarray) – Numpy array of positive floats.
rng (Optional[RandomState]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

update(x, weight, estimate)[source]

Update sufficient statistics for GammaAccumulator with one weighted observation.

Parameters:

x (float) – Observation from gamma distribution.
weight (float) – Weight for observation.
estimate (Optional[GammaDistribution]) – 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 (Tuple[ndarray, ndarray]) – Tuple of Numpy array of observations and log(observations).
weights (ndarray) – Numpy array of positive floats.
estimate (Optional[GammaDistribution]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

combine(suff_stat)[source]

Aggregates sufficient statistics with GammaAccumulator member sufficient statistics.

Parameters:: suff_stat (Tuple[float, float, float]) – Aggregated count, sum, sum_of_logs.
Returns:: ExponentialAccumulator
Return type:: GammaAccumulator

value()[source]

Returns Tuple[float, float, float] containing sufficient statistics of GammaAccumulator.

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

from_value(x)[source]

Sets sufficient statistics GammaAccumulator to x.

Parameters:: x (Tuple[float, float, float]) – Sufficient statistics tuple of length three..
Returns:: ExponentialAccumulator
Return type:: GammaAccumulator

key_merge(stats_dict)[source]

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

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

Return GammaDataEncoder for encoding sequence of data.

Return type:: GammaDataEncoder

class GammaAccumulatorFactory(keys=None)[source]

Bases: StatisticAccumulatorFactory

Parameters:: keys (str | None)

make()[source]

Returns GammaAccumulator object with keys passed.

Return type:: GammaAccumulator

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

Bases: ParameterEstimator

Parameters:

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

accumulator_factory()[source]

Create GammaAccumulatorFactory with keys passed.

Return type:: GammaAccumulatorFactory

estimate(nobs, suff_stat)[source]

Obtain GammaDistribution from aggregated sufficient statistics of observed data.

Takes sufficient statistic aggregated from observed data:: suff_stat[0]: weighted sum of observations suff_stat[1]: weighted sum of log-observations suff_stat[2]: weighted observation count.

Parameters:

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

Returns:

GammaDistribution object.

Return type:

GammaDistribution

static estimate_shape(avg_sum, avg_sum_of_logs, threshold)[source]

Estimates the shape parameter of GammaDistribution.

Parameters:

avg_sum (float) – Weighted sum of gamma observations.
avg_sum_of_logs (float) – Weighted log sum of gamma observations.
threshold (float) – Threshold used for assessing convergence of shape estimation.

Returns:

Estimate of shape parameter ‘k’.

Return type:

float

class GammaDataEncoder[source]

Bases: DataSequenceEncoder

GammaDataEncoder object for encoding sequences of iid Gamma observations with data type float.

seq_encode(x)[source]

Encode iid sequence of gamma observations for vectorized “seq_” function calls.

Note: Each entry of x must be positive float.

Parameters:: x (Union[List[float], np.ndarray]) – IID sequence of gamma distributed observations.
Returns:: Tuple of x as numpy array and log(x).
Return type:: tuple[ndarray, ndarray]