mixle.stats.univariate.continuous.gumbel module¶

Create, estimate, and sample from a Gumbel (extreme value type I, maxima) distribution.

Defines the GumbelDistribution, GumbelSampler, GumbelAccumulatorFactory, GumbelAccumulator, GumbelEstimator, and the GumbelDataEncoder classes for use with mixle.

Data type: (float): The GumbelDistribution with location loc (mu) and scale beta > 0 has log-density

log(f(x; mu, beta)) = -log(beta) - z - exp(-z), z = (x - mu) / beta,

on the whole real line. It models the distribution of maxima; the mean is mu + beta*gamma (gamma the Euler-Mascheroni constant) and the variance is (pi^2 / 6) * beta^2, which the moment estimator inverts.

The per-row log-density lowers cleanly to the shared symbolic kernel, so the family gets generated NumPy, Torch, and Numba scoring through backend_log_density_from_params.

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

class GumbelDistribution(loc=0.0, scale=1.0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gumbel (extreme value type I) distribution with location loc and scale beta > 0.

Parameters:

loc (float)
scale (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 Gumbel sufficient statistics in accumulator order.

Parameters:

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

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, loc, scale, engine)[source]

Engine-neutral Gumbel log-density from explicit parameters.

Parameters:

x (Any)
loc (Any)
scale (Any)
engine (Any)

Return type:

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.

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

seq_log_density(x)[source]

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

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

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Gumbel parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GumbelDistribution])
engine (Any)

Return type:

dict[str, Any]

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

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

Parameters:

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

Return type:

Any

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

Return stacked Gumbel sufficient statistics using engine-resident arrays.

Parameters:

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

Return type:

tuple[Any, Any, Any]

cdf(x)[source]

Cumulative distribution function P(X <= x).

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

quantile(q)[source]

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

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

entropy()[source]

Differential entropy log(scale) + euler_gamma + 1.

Return type:: float

skewness()[source]

Skewness 12*sqrt(6)*zeta(3)/pi^3.

Return type:: float

kurtosis()[source]

Excess kurtosis (12/5).

Return type:: float

mode()[source]

Mode (= the location loc).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return a moment estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

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

Return type:: GumbelDataEncoder

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

Bases: DistributionSampler

Draw iid Gumbel observations.

Parameters:

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

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted first and second moments for Gumbel estimation.

Parameters:: keys (str | None)

update(x, weight, estimate)[source]

Parameters:

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

Return type:

None

seq_initialize(x, weights, rng)[source]

Parameters:

x (ndarray)
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

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

value()[source]

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

from_value(x)[source]

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

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

class GumbelAccumulatorFactory(keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for GumbelAccumulator.

Parameters:: keys (str | None)

make()[source]

Return type:: GumbelAccumulator

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

Bases: ParameterEstimator

Moment estimator for the Gumbel location and scale.

Inverts the Gumbel moments: beta = sqrt(6 * var) / pi and loc = mean - beta * gamma where gamma is the Euler-Mascheroni constant.

Parameters:

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

accumulator_factory()[source]

Return type:: GumbelAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

GumbelDistribution

class GumbelDataEncoder[source]

Bases: DataSequenceEncoder

Encode Gumbel observations as a float array.

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

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