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.

The M-step is shift-equivariant: fitting x + c returns loc + c with an unchanged scale and shape. That does not come for free from raw power sums – the central third moment differenced out of E[x^3] loses about 3*log2(abs(mean)/sd) bits, and the variance about twice that – so the accumulator carries a conditioning-gated shift-anchored moment track alongside the raw sums (see GeneralizedExtremeValueAccumulator).

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

class GeneralizedExtremeValueSuffStat(sum_, sum2_, sum3_, count_, min_val, max_val, anchored=None)[source]

Bases: tuple

A (sum, sum2, sum3, count, min_val, max_val) statistic that also carries a side payload.

Behaves exactly like the plain 6-tuple everywhere it is indexed, unpacked, or iterated (it is one); anchored is the shift-anchored payload (anchor, sum_i w_i (x_i - anchor)^k for k = 1..3) the accumulator maintains alongside the raw power sums so the M-step survives large-offset data. Code that doesn’t know about the payload (generic scale_suff_stat, serializers, …) sees an ordinary tuple and the estimate falls back to the historical raw path.

Parameters:

sum_ (float)
sum2_ (float)
sum3_ (float)
count_ (float)
min_val (float)
max_val (float)
anchored (tuple[float, float, float, float] | None)

Return type:

GeneralizedExtremeValueSuffStat

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]: Describe backend support for generated GEV kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for GEV distributions.

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

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

Deliberately not wired into the declaration as legacy_sufficient_statistics. The generated statistic path reduces every declared statistic with a weighted sum, ignoring StatisticSpec.additive, so it cannot produce the observed range the M-step needs to keep the fitted support around the data (see _shape_covering_range()) – it would silently hand estimate a summed min and max. GEV therefore accumulates through the host seq_update, which is three dot products for a univariate leaf; engine-resident scoring via backend_seq_log_density is unaffected. Reinstate this hook once the generated path honours non-additive support bounds.

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 abs(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

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

entropy()[source]

Differential entropy log(scale) + euler_gamma * xi + euler_gamma + 1.

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, *, batched=True)[source]

Draw one sample or an array of iid samples by inverse CDF.

Parameters:

size (int | None)
batched (bool)

Return type:

float | ndarray

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

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted first three moments and the observed range for GEV estimation.

The range is not a moment: it is the support bound the estimate has to respect, since a GEV with xi != 0 is bounded on one side and moment matching alone can place that bound inside the sample. See _shape_covering_range().

Alongside the raw sums the accumulator keeps a CONDITIONING-GATED shift-anchored track, sum_i w_i (x_i - anchor)^k for k = 1..3 about a data anchor. The method of moments needs central moments, and differencing them out of raw power sums is the classic cancellation-prone form: at sd ~0.6 and offset 1.7e9 the raw variance is wrong by a factor of thousands and the raw third moment has no correct digits at all, which drives the shape onto its bound and the scale tens of times too large – silently. Anchoring keeps every term of the scatter O(count * spread^3), making the M-step shift-equivariant.

The gate keeps the historical path bit-identical for well-conditioned data: a chunk whose abs(mean)/spread ratio the raw form handles to ~1e-9 relative (see _needs_anchor()) accumulates exactly the way it always did, with no anchor and no second pass. The raw sums remain the exchange format, so the anchored track rides along as a payload on GeneralizedExtremeValueSuffStat; a consumer that drops the payload simply gets the historical raw estimate back.

Parameters:

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

update(x, weight, estimate)[source]

Accumulate weighted first three raw moments and the observed range for one observation.

Parameters:

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

Return type:

None

initialize(x, weight, rng)[source]

Initialize statistics from one observation.

Parameters:

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

Return type:

None

seq_update(x, weights, estimate)[source]

Accumulate weighted first three raw moments and the observed range from encoded data.

Parameters:

x (ndarray)
weights (ndarray)
estimate (GeneralizedExtremeValueDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize statistics from encoded observations.

Parameters:

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

Return type:

None

combine(suff_stat)[source]

Merge another GEV sufficient-statistic tuple.

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

value()[source]

Return raw moment sums, observation count, and the observed range.

The returned object is a plain 6-tuple for every consumer that treats it as one; once the shift-anchored track is live it additionally carries the anchored moments in its .anchored attribute, so combine() can fold them in and GeneralizedExtremeValueEstimator.estimate() can use them for the reduced moments. The payload is withheld when the track was seeded from raw statistics that had already lost their central moments (see _activate_anchor()), so a pool that cannot honestly claim shift-equivariance reports the historical raw statistics instead of a worse anchored guess.

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

from_value(x)[source]

Replace accumulator contents from a sufficient-statistic tuple.

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

scale(c)[source]

Scale accumulated evidence while preserving the observed range.

The shift-anchored track scales with the raw sums; leaving it behind would turn a scaled accumulator back into the ill-conditioned raw path.

Parameters:: c (float)
Return type:: GeneralizedExtremeValueAccumulator

acc_to_encoder()[source]

Return the encoder used by this accumulator.

Return type:: GeneralizedExtremeValueDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for GeneralizedExtremeValueAccumulator.

Parameters:

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

make()[source]

Create a fresh GEV accumulator.

Return type:: GeneralizedExtremeValueAccumulator

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

Bases: ParameterEstimator

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

This is a moment estimator, not an MLE: the shape is solved from the skewness-vs-xi relation, and the shape is additionally constrained so the fitted support covers the observed range (see _shape_covering_range()). Whenever that constraint rewrites the shape – or the rewritten shape still scores the extreme observation catastrophically and the estimate falls back to the Gumbel limit – the returned distribution is not the raw moment fit, and the change is recorded in numerical_repairs() so fit_provenance() carries it (MXR-080-1202).

The reduced moments are formed about a reference point rather than about zero whenever the accumulated statistics carry a shift-anchored payload (see GeneralizedExtremeValueAccumulator), which makes the fit shift-equivariant: estimate on x + c returns loc + c with scale and shape unchanged. With a plain raw tuple – statistics restored from an older serialization, or a hand-built one – the historical raw path is used unchanged.

Parameters:

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

accumulator_factory()[source]

Return an accumulator factory for GEV raw-moment statistics.

Return type:: GeneralizedExtremeValueAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location, scale, and shape from weighted moments, keeping the data in support.

Parameters:

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

Return type:

GeneralizedExtremeValueDistribution

class GeneralizedExtremeValueDataEncoder[source]

Bases: DataSequenceEncoder

Encode GEV observations as a float array.

seq_encode(x)[source]

Encode observations as a floating-point array.

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