mixle.stats.univariate.continuous.generalized_extreme_value module¶

Generalized Extreme Value distribution (GEV): the limit law of block maxima.

By the Fisher-Tippett-Gnedenko theorem the normalized maximum of a large block of iid observations converges to a GEV, the standard model for extremes (flood levels, wind speeds, record losses). With location mu, scale sigma > 0 and shape xi (the EVT sign convention; scipy’s genextreme uses c = -xi), for z = (x - mu)/sigma:

log f = -log sigma - (1/xi + 1) log s - s ** (-1/xi), s = 1 + xi z > 0 (xi != 0), log f = -log sigma - z - exp(-z) (xi == 0, Gumbel).

xi > 0 is the heavy-tailed Frechet type (support x >= mu - sigma/xi), xi = 0 the Gumbel type (all reals), xi < 0 the bounded Weibull type (x <= mu - sigma/xi). All three parameters are fit by method of moments: the shape is solved from the (monotone) skewness-vs-xi relation, then scale from the variance and location from the mean.

Reference: Coles, An Introduction to Statistical Modeling of Extreme Values (Springer, 2001).

class GeneralizedExtremeValueDistribution(loc, scale, shape, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Generalized Extreme Value distribution with location loc, scale > 0 and shape xi.

Parameters:

loc (float)
scale (float)
shape (float)
name (str | None)
keys (str | None)

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 (-inf outside the support).

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

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

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

Per-row GEV moment sums in accumulator order (sum, sum2, sum3, count).

Parameters:

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

Return type:

tuple[Any, …]

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

Engine-neutral GEV log-density; the |xi| < tol Gumbel limit is selected per element.

s^{-1/xi} is computed as exp(-log(s)/xi) so the whole expression stays on engine ops.

Parameters:

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

Return type:

Any

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]

Stacked GEV parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GeneralizedExtremeValueDistribution])
engine (Any)

Return type:

dict[str, Any]

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

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

Parameters:

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

Return type:

Any

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

Stacked GEV moment sums (sum, sum2, sum3, count) using engine-resident arrays.

Parameters:

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

Return type:

tuple[Any, Any, Any, Any]

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact).

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

quantile(q)[source]

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

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

mean()[source]

Mean: loc + scale*(Gamma(1-xi)-1)/xi (loc+scale*euler_gamma at xi=0); inf for xi>=1.

Return type:: float

variance()[source]

Variance: scale^2 (Gamma(1-2xi)-Gamma(1-xi)^2)/xi^2 (scale^2 pi^2/6 at xi=0); inf for xi>=1/2.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return a method-of-moments estimator for loc, scale and shape.

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

dist_to_encoder()[source]

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

Return type:: GeneralizedExtremeValueDataEncoder

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

Bases: DistributionSampler

Draw iid GEV observations by inverse-CDF transform.

Parameters:

dist (GeneralizedExtremeValueDistribution)
seed (int | None)

sample(size=None)[source]

Draw observations.

Combinator samplers (mixture/sequence/…) accept batched. With batched=True (the default) each child stream is drawn in one vectorized call instead of a per-draw Python loop – far faster. Because every child sampler owns an independent RandomState, batching consumes each stream in the same order as the loop, so the draws are identical to the legacy path. batched=False forces that legacy per-draw loop as a guaranteed- stable reference. Leaf samplers are already vectorized and ignore the flag.

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

class GeneralizedExtremeValueAccumulator(name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted first three moments for GEV estimation.

Parameters:

name (str | None)
keys (str | None)

update(x, weight, estimate)[source]

Parameters:

x (float)
weight (float)
estimate (GeneralizedExtremeValueDistribution | 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 (GeneralizedExtremeValueDistribution | 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, float])
Return type:: GeneralizedExtremeValueAccumulator

value()[source]

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

from_value(x)[source]

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

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

class GeneralizedExtremeValueAccumulatorFactory(name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for GeneralizedExtremeValueAccumulator.

Parameters:

name (str | None)
keys (str | None)

make()[source]

Return type:: GeneralizedExtremeValueAccumulator

class GeneralizedExtremeValueEstimator(pseudo_count=None, min_scale=1.0e-12, xi_max=1.0 / 3.0 - 1.0e-4, xi_min=-1.0, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for GEV location, scale and shape.

Parameters:

pseudo_count (float | None)
min_scale (float)
xi_max (float)
xi_min (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: GeneralizedExtremeValueAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

GeneralizedExtremeValueDistribution

class GeneralizedExtremeValueDataEncoder[source]

Bases: DataSequenceEncoder

Encode GEV 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