mixle.stats.univariate.continuous.generalized_pareto module¶

Generalized Pareto distribution (GPD): the peaks-over-threshold law of extreme exceedances.

By the Pickands-Balkema-de Haan theorem the distribution of exceedances over a high threshold of almost any distribution converges to a GPD, which makes it the workhorse for modelling tail risk (hydrology, finance, reliability). With threshold loc = mu, scale sigma > 0 and shape xi, for y = x - mu >= 0:

f(x) = (1/sigma) (1 + xi * y / sigma) ** (-1/xi - 1) (xi != 0), f(x) = (1/sigma) exp(-y / sigma) (xi == 0, the exponential tail).

xi > 0 is a heavy (Pareto) tail, xi = 0 exponential, xi < 0 a tail with a finite upper endpoint at mu - sigma/xi. The threshold mu is treated as a fixed, known level (chosen, not fit – the standard peaks-over-threshold setup); sigma and xi are fit by method of moments, which is closed-form: xi = (1 - m^2/v)/2 and sigma = m (1 - xi) from the exceedance mean m and variance v (valid for xi < 1/2, where the variance is finite).

Reference: Pickands, ‘Statistical inference using extreme order statistics’, Ann. Statist. (1975).

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

Bases: SequenceEncodableProbabilityDistribution

Generalized Pareto distribution with threshold loc, scale > 0 and shape xi.

Parameters:

scale (float)
shape (float)
loc (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 GPD moment sums in accumulator order (sum, sum2, count).

Parameters:

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

Return type:

tuple[Any, …]

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

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

Parameters:

x (Any)
scale (Any)
shape (Any)
loc (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 GPD parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GeneralizedParetoDistribution])
engine (Any)

Return type:

dict[str, Any]

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

Return an (n, k) matrix of GPD 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 GPD moment sums (sum, sum2, count) 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) (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/(1-xi) for xi < 1, else inf.

Return type:: float

variance()[source]

Variance scale^2 / ((1-xi)^2 (1-2xi)) for xi < 1/2, else inf.

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return a method-of-moments estimator for scale and shape at the fixed threshold loc.

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

dist_to_encoder()[source]

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

Return type:: GeneralizedParetoDataEncoder

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

Bases: DistributionSampler

Draw iid GPD observations by inverse-CDF transform.

Parameters:

dist (GeneralizedParetoDistribution)
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 GeneralizedParetoAccumulator(name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted first and second moments for GPD estimation.

Parameters:

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

update(x, weight, estimate)[source]

Parameters:

x (float)
weight (float)
estimate (GeneralizedParetoDistribution | 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 (GeneralizedParetoDistribution | 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:: GeneralizedParetoAccumulator

value()[source]

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

from_value(x)[source]

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

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

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

Bases: StatisticAccumulatorFactory

Factory for GeneralizedParetoAccumulator.

Parameters:

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

make()[source]

Return type:: GeneralizedParetoAccumulator

class GeneralizedParetoEstimator(loc=0.0, pseudo_count=None, min_scale=1.0e-12, xi_max=0.5 - 1.0e-6, xi_min=-10.0, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for GPD scale and shape at a fixed threshold loc.

Parameters:

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

accumulator_factory()[source]

Return type:: GeneralizedParetoAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

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

Return type:

GeneralizedParetoDistribution

class GeneralizedParetoDataEncoder[source]

Bases: DataSequenceEncoder

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