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)

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)

Return the probability density at a single observation.

Parameters:

x (float)

Return type:

float

log_density(x)

Return the log-density at a single observation (-inf outside the support).

Parameters:

x (float)

Return type:

float

seq_log_density(x)

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

Parameters:

x (ndarray)

Return type:

ndarray

classmethod compute_capabilities()

Describe backend support for generated GEV kernels.

classmethod compute_declaration()

Return the structured compute declaration for GEV distributions.

static backend_legacy_sufficient_statistics(x, params, engine)

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)

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)

Engine-neutral vectorized log-density for encoded data.

Parameters:

• x (Any)

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

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)

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)

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)

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

Parameters:

x (float)

Return type:

float

quantile(q)

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

Parameters:

q (float)

Return type:

float

mean()

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

Return type:

float

variance()

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)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

GeneralizedExtremeValueSampler

estimator(pseudo_count=None)

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

Parameters:

pseudo_count (float | None)

Return type:

GeneralizedExtremeValueEstimator

dist_to_encoder()

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

Return type:

GeneralizedExtremeValueDataEncoder

class GeneralizedExtremeValueSampler(dist, seed=None)

Bases: DistributionSampler

Draw iid GEV observations by inverse-CDF transform.

Parameters:

• dist (GeneralizedExtremeValueDistribution)

• seed (int | None)

sample(size=None)

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

Parameters:

size (int | None)

Return type:

float | ndarray

class GeneralizedExtremeValueAccumulator(name=None, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted first three moments for GEV estimation.

Parameters:

• name (str | None)

• keys (str | None)

update(x, weight, estimate)

Accumulate weighted first three raw moments for one observation.

Parameters:

• x (float)

• weight (float)

• estimate (GeneralizedExtremeValueDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize statistics from one observation.

Parameters:

• x (float)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Accumulate weighted first three raw moments from encoded data.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (GeneralizedExtremeValueDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Initialize statistics from encoded observations.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge another GEV sufficient-statistic tuple.

Parameters:

suff_stat (tuple[float, float, float, float])

Return type:

GeneralizedExtremeValueAccumulator

value()

Return raw moment sums and observation count.

Return type:

tuple[float, float, float, float]

from_value(x)

Replace accumulator contents from a sufficient-statistic tuple.

Parameters:

x (tuple[float, float, float, float])

Return type:

GeneralizedExtremeValueAccumulator

key_merge(stats_dict)

Merge keyed statistics into stats_dict when keys are configured.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this accumulator from keyed statistics when available.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return the encoder used by this accumulator.

Return type:

GeneralizedExtremeValueDataEncoder

class GeneralizedExtremeValueAccumulatorFactory(name=None, keys=None)

Bases: StatisticAccumulatorFactory

Factory for GeneralizedExtremeValueAccumulator.

Parameters:

• name (str | None)

• keys (str | None)

make()

Create a fresh GEV accumulator.

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)

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

Return an accumulator factory for GEV raw-moment statistics.

Return type:

GeneralizedExtremeValueAccumulatorFactory

estimate(nobs, suff_stat)

Estimate location, scale, and shape from weighted moments.

Parameters:

• nobs (float | None)

• suff_stat (tuple[float, float, float, float])

Return type:

GeneralizedExtremeValueDistribution

class GeneralizedExtremeValueDataEncoder

Bases: DataSequenceEncoder

Encode GEV observations as a float array.

seq_encode(x)

Encode observations as a floating-point array.

Parameters:

x (Sequence[float])

Return type:

ndarray