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

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

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 one sample or an array of iid samples by inverse CDF.

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]

Accumulate weighted first and second moments for one observation.

Parameters:

x (float)
weight (float)
estimate (GeneralizedParetoDistribution | 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 and second moments from encoded data.

Parameters:

x (ndarray)
weights (ndarray)
estimate (GeneralizedParetoDistribution | 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 generalized-Pareto sufficient-statistic tuple.

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

value()[source]

Return accumulated sum, second moment sum, and count.

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

from_value(x)[source]

Replace accumulator contents from a sufficient-statistic tuple.

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

key_merge(stats_dict)[source]

Merge keyed statistics into stats_dict when keys are configured.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

key_replace(stats_dict)[source]

Replace this accumulator from keyed statistics when available.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

acc_to_encoder()[source]

Return the encoder used by this accumulator.

Return type:: GeneralizedParetoDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for GeneralizedParetoAccumulator.

Parameters:

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

make()[source]

Create a fresh generalized-Pareto accumulator.

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 an accumulator factory for generalized-Pareto moments.

Return type:: GeneralizedParetoAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate scale and shape from exceedance moments at the fixed location.

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 observations as a floating-point array.

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