GeneralisedExtremeValue#

class gpjax.distributions.GeneralisedExtremeValue(loc=0.0, scale=1.0, concentration=0.0, *, support_continuation=False, validate_args=None)[source]#

Bases: Distribution

The generalised extreme value (GEV) distribution.

The GEV distribution is the limit distribution of block maxima, for example annual maxima of daily rainfall. With \(t = 1 + \xi (y - \mu) / \sigma\), its cumulative distribution function is

\[F(y) = \exp\left(-t^{-1/\xi}\right), \qquad F(y) = \exp\left(-e^{-(y - \mu)/\sigma}\right) \quad (\xi = 0),\]

on the support \(t > 0\). The shape \(\xi\) (concentration) sets the tail:

\(\xi > 0\): heavy upper tail (Fréchet type), with the lower end point \(\mu - \sigma/\xi\);
\(\xi = 0\): the Gumbel distribution, with support on the real line;
\(\xi < 0\): bounded upper tail (Weibull type), with the upper end point \(\mu - \sigma/\xi\).

This is the climate convention. scipy.stats.genextreme uses \(c = -\xi\). The shape is called concentration, as in TensorFlow Probability, because shape is a method of every NumPyro distribution.

All methods are accurate and have finite gradients with respect to the value and to the three parameters at \(\xi = 0\) and near it: the ratios \(\log(1 + w)/w\) and \((e^a - 1)/a\) that cause \(0/0\) are Taylor series near zero.

Support continuation. Outside the support the exact log density is \(-\infty\), and it has no useful gradient. A Gaussian distribution over the location always has mass where an observation is outside the support (for \(\xi \neq 0\)), so an expected log-likelihood is \(-\infty\), and Gauss–Hermite nodes can fall outside the support. With support_continuation=True, log_prob is a pseudo-log-density that is finite everywhere:

Exact where the reduced variate \(u = \log(t)/\xi\) is at least \(-5\) (there \(F \geq \exp(-e^5) \approx 10^{-64}\)), and, when \(\xi < 0\), where \(t \geq 10^{-2}(1 + \xi)\).
Below the point where \(u = -5\), for every \(\xi\), the log density continues as the straight line in \(y\) with the same value and slope. This covers the region below the lower end point when \(\xi > 0\). It also bounds the slope of the double-exponential lower tail when \(\xi \leq 0\).
Above the point where \(t = 10^{-2}(1 + \xi)\), for \(\xi < 0\) only, the log density continues in the same way. This covers the region above the upper end point. The factor \(1 + \xi\) makes the slope there about \(-100/\sigma\) for every \(\xi\).

The continuation is continuously differentiable: at each junction, the value and the first derivatives with respect to \(y\), \(\mu\), \(\sigma\) and \(\xi\) agree on the two sides. The junctions move smoothly with \(\xi\), and the function is continuous in \(\xi\) through 0. Outside the support the gradient always points into the support: a gradient step increases the log density by a move of the location, the scale or the shape that brings the end point past the observation. The continuation is designed for \(\xi > -1\).

The continued function is a pseudo-density. It puts a small mass where the exact density is zero, and it changes the density in the two regions. For \(-0.5 \leq \xi \leq 0.5\) its total mass differs from 1 by at most \(3 \times 10^{-5}\), at \(\xi = -0.5\); there the exact probability of the upper region is \(2.5 \times 10^{-5}\). The difference is less than \(10^{-7}\) for \(\xi \geq -0.3\) and less than \(10^{-10}\) for \(\xi \geq -0.2\), and the lower region contributes about \(10^{-64}\). cdf, sf, icdf, isf, sample, mean and variance are always exact; only log_prob changes.

Example

>>> import jax.numpy as jnp
>>> from gpjax.distributions import GeneralisedExtremeValue
>>> dist = GeneralisedExtremeValue(loc=40.0, scale=12.0, concentration=0.1)
>>> level_100 = dist.return_level(100.0)
>>> probability = dist.sf(level_100)  # 0.01

Parameters:

loc (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The location \(\mu\).
scale (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The scale \(\sigma > 0\).
concentration (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The shape \(\xi\).
support_continuation (bool) – If True, log_prob uses the support continuation above. If False (the default), log_prob is exact and is -inf outside the support.
validate_args (bool | None) – Passed to numpyro.distributions.Distribution.

Expand for references to gpjax.distributions.GeneralisedExtremeValue

GeneralisedExtremeValue

cdf(value)[source]#

The cumulative distribution function \(P(Y \leq y)\).

Exact everywhere: 0 below the lower end point (\(\xi > 0\)), and 1 at and above the upper end point (\(\xi < 0\)).

Parameters:: value (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The point \(y\).
Returns:: The probability \(P(Y \leq y)\).
Return type:: Float[jaxlib._jax.Array, ‘…’] | Float[ndarray, ‘…’]

icdf(q)[source]#

The quantile function, the inverse of cdf().

\(q = 0\) gives the lower end point (\(-\infty\) if \(\xi \leq 0\)) and \(q = 1\) gives the upper end point (\(+\infty\) if \(\xi \geq 0\)).

Parameters:: q (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The probability \(q = P(Y \leq y)\).
Returns:: The quantile \(y\).
Return type:: Float[jaxlib._jax.Array, ‘…’] | Float[ndarray, ‘…’]

isf(p)[source]#

The inverse survival function, the inverse of sf().

The name follows scipy.stats. It is accurate for very small exceedance probabilities \(p\), where icdf(1 - p) loses digits.

Parameters:: p (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The exceedance probability \(p = P(Y > y)\).
Returns:: The level \(y\).
Return type:: Float[jaxlib._jax.Array, ‘…’] | Float[ndarray, ‘…’]

log_prob(value)[source]#

The log density at value.

Exact (-inf outside the support) by default. With support_continuation=True, the continued pseudo-log-density that is described in the class docstring.

Parameters:: value (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The point at which to evaluate the log density.
Returns:: The log density, with the broadcast shape of value and the batch shape.
Return type:: Float[jaxlib._jax.Array, ‘…’] | Float[ndarray, ‘…’]

property mean: Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...']#

The mean, \(\mu + \sigma\{\Gamma(1 - \xi) - 1\}/\xi\).

The mean is \(\mu + \sigma\gamma\) at \(\xi = 0\), and inf for \(\xi \geq 1\).

return_level(return_period)[source]#

The return level for return_period; see gev_return_level().

Parameters:: return_period (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The return period \(T > 1\), in blocks.
Returns:: The level that is exceeded with probability \(1/T\).
Return type:: Float[jaxlib._jax.Array, ‘…’] | Float[ndarray, ‘…’]

Expand for references to gpjax.distributions.GeneralisedExtremeValue.return_level

GeneralisedExtremeValue

return_period(level)[source]#

The return period of level; see gev_return_period().

Parameters:: level (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The level, in the units of the data.
Returns:: \(1 / P(Y > \text{level})\), which is inf where the exceedance probability is 0.
Return type:: Float[jaxlib._jax.Array, ‘…’] | Float[ndarray, ‘…’]

sample(key, sample_shape=())[source]#

Draw samples by the inverse of the cumulative distribution function.

A standard Gumbel draw \(G\) gives \(y = \mu + \sigma (e^{\xi G} - 1)/\xi\).

Parameters:

key (UInt32[jaxlib._jax.Array, '2'] | Key[jaxlib._jax.Array, '']) – A JAX PRNG key.
sample_shape (tuple[int, ...]) – Leading dimensions of the samples.

Returns:

Samples of shape sample_shape + batch_shape.

Return type:

Float[jaxlib._jax.Array, ‘…’] | Float[ndarray, ‘…’]

sf(value)[source]#

The survival function, or exceedance probability, \(P(Y > y)\).

The name follows scipy.stats (NumPyro has no survival function). It is computed as \(-\mathrm{expm1}(-e^{-u})\), not as \(1 - F(y)\), so very small probabilities (for example \(10^{-12}\)) keep their relative accuracy. It is exactly 1 below the lower end point (\(\xi > 0\)) and exactly 0 at and above the upper end point (\(\xi < 0\)).

Parameters:: value (float | int | Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...'] | Int[jaxlib._jax.Array, '...'] | Int[ndarray, '...']) – The point \(y\).
Returns:: The probability \(P(Y > y)\).
Return type:: Float[jaxlib._jax.Array, ‘…’] | Float[ndarray, ‘…’]

Expand for references to gpjax.distributions.GeneralisedExtremeValue.sf

GeneralisedExtremeValue

support = Real()#

Parameters:: x (ndarray | Array | number | int | float | complex)
Return type:: Array | ndarray | bool | number | bool | int | float | complex

property variance: Float[jaxlib._jax.Array, '...'] | Float[ndarray, '...']#

The variance, \(\sigma^2\{\Gamma(1 - 2\xi) - \Gamma(1 - \xi)^2\}/\xi^2\).

The variance is \(\sigma^2\pi^2/6\) at \(\xi = 0\), and inf for \(\xi \geq 1/2\).