Skip to content

Extreme Value Parameters#

statista.parameters.extreme_value #

L-moments parameter estimation for extreme value distributions.

Distributions: GEV, Gumbel, Generalized Pareto.

ConvergenceError #

Bases: Exception

Custom exception for convergence errors in L-moment calculations.

Source code in src/statista/parameters/extreme_value.py 
20
21
22
23
class ConvergenceError(Exception):
    """Custom exception for convergence errors in L-moment calculations."""

    pass

gev(lmoments) #

Estimate parameters for the Generalized Extreme Value (GEV) distribution.

The Generalized Extreme Value distribution combines the Gumbel, Frechet, and Weibull distributions into a single family to model extreme values. The distribution is characterized by three parameters: shape, location, and scale.

Parameters:

Name Type Description Default
lmoments list[float | int]

A list of L-moments [l1, l2, l3, ...] where: - l1 is the mean (first L-moment) - l2 is the L-scale (second L-moment) - l3 is the L-skewness (third L-moment) At least 3 L-moments must be provided.

 required

Returns:

Type Description
list[float | int]

A list of distribution parameters [shape, location, scale] where: - shape: Controls the tail behavior of the distribution - location: Shifts the distribution along the x-axis - scale: Controls the spread of the distribution

Raises:

Type Description
ValueError

If the L-moments are invalid (l2 <= 0 or |l3| >= 1).
ConvergenceError

If the parameter estimation algorithm fails to converge.

Examples:

  • Estimate GEV parameters from L-moments: 
    >>> from statista.parameters import Lmoments
  • Calculate L-moments from data 
    >>> data = [10.2, 15.7, 20.3, 25.9, 30.1, 35.6, 40.2]
>>> lmom = Lmoments(data)
>>> l_moments = lmom.calculate(nmom=3)

  • Estimate GEV parameters 

    >>> params = Lmoments.gev(l_moments)
>>> print(f"Shape: {params[0]}, Location: {params[1]}, Scale: {params[2]}")
Shape: 0.3055099485469931, Location: 21.413657588990556, Scale: 11.868352699813734

  • Using predefined L-moments: 

    >>> from statista.parameters import Lmoments

  • Predefined L-moments 
    >>> l_moments = [10.0, 2.0, 0.1]
  • Estimate GEV parameters 
    >>> params = Lmoments.gev(l_moments)
>>> print(f"Shape: {params[0]}, Location: {params[1]}, Scale: {params[2]}")
Shape: 0.11189502871959642, Location: 8.490058310239982, Scale: 3.1676863588272224
Note

The GEV distribution has the cumulative distribution function: F(x) = exp(-[1 + xi((x-mu)/sigma)]^(-1/xi)) for xi != 0 F(x) = exp(-exp(-(x-mu)/sigma)) for xi = 0 (Gumbel case)

Where xi is the shape parameter, mu is the location parameter, and sigma is the scale parameter.

Source code in src/statista/parameters/extreme_value.py 
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def gev(lmoments: list[float | int]) -> list[float | int]:
    """Estimate parameters for the Generalized Extreme Value (GEV) distribution.

    The Generalized Extreme Value distribution combines the Gumbel, Frechet, and Weibull
    distributions into a single family to model extreme values. The distribution is
    characterized by three parameters: shape, location, and scale.

    Args:
        lmoments: A list of L-moments [l1, l2, l3, ...] where:
            - l1 is the mean (first L-moment)
            - l2 is the L-scale (second L-moment)
            - l3 is the L-skewness (third L-moment)
            At least 3 L-moments must be provided.

    Returns:
        A list of distribution parameters [shape, location, scale] where:
            - shape: Controls the tail behavior of the distribution
            - location: Shifts the distribution along the x-axis
            - scale: Controls the spread of the distribution

    Raises:
        ValueError: If the L-moments are invalid (l2 <= 0 or |l3| >= 1).
        ConvergenceError: If the parameter estimation algorithm fails to converge.

    Examples:
        - Estimate GEV parameters from L-moments:
          ```python
          >>> from statista.parameters import Lmoments

          ```
          - Calculate L-moments from data
          ```python
          >>> data = [10.2, 15.7, 20.3, 25.9, 30.1, 35.6, 40.2]
          >>> lmom = Lmoments(data)
          >>> l_moments = lmom.calculate(nmom=3)

          ```
          - Estimate GEV parameters
          ```python
          >>> params = Lmoments.gev(l_moments)
          >>> print(f"Shape: {params[0]}, Location: {params[1]}, Scale: {params[2]}")
          Shape: 0.3055099485469931, Location: 21.413657588990556, Scale: 11.868352699813734

          ```

        - Using predefined L-moments:
          ```python
          >>> from statista.parameters import Lmoments

          ```
          - Predefined L-moments
          ```python
          >>> l_moments = [10.0, 2.0, 0.1]

          ```
          - Estimate GEV parameters
          ```python
          >>> params = Lmoments.gev(l_moments)
          >>> print(f"Shape: {params[0]}, Location: {params[1]}, Scale: {params[2]}")
          Shape: 0.11189502871959642, Location: 8.490058310239982, Scale: 3.1676863588272224

          ```

    Note:
        The GEV distribution has the cumulative distribution function:
        F(x) = exp(-[1 + xi((x-mu)/sigma)]^(-1/xi)) for xi != 0
        F(x) = exp(-exp(-(x-mu)/sigma)) for xi = 0 (Gumbel case)

        Where xi is the shape parameter, mu is the location parameter, and sigma is the scale parameter.
    """
    dl2 = np.log(2)
    dl3 = np.log(3)
    # COEFFICIENTS OF RATIONAL-FUNCTION APPROXIMATIONS FOR XI
    a0 = 0.28377530
    a1 = -1.21096399
    a2 = -2.50728214
    a3 = -1.13455566
    a4 = -0.07138022
    b1 = 2.06189696
    b2 = 1.31912239
    b3 = 0.25077104
    c1 = 1.59921491
    c2 = -0.48832213
    c3 = 0.01573152
    d1 = -0.64363929
    d2 = 0.08985247

    t3 = lmoments[2]
    # if std <= 0 or third moment > 1
    if lmoments[1] <= 0 or abs(t3) >= 1:
        raise ValueError(LMOMENTS_INVALID_ERROR)

    if t3 <= 0:
        G = (a0 + t3 * (a1 + t3 * (a2 + t3 * (a3 + t3 * a4)))) / (
            1 + t3 * (b1 + t3 * (b2 + t3 * b3))
        )
        if t3 >= -0.8:
            shape = G
            gam = np.exp(sp.special.gammaln(1 + G))
            scale = lmoments[1] * G / (gam * (1 - 2 ** (-G)))
            loc = lmoments[0] - scale * (1 - gam) / G
            para = [shape, loc, scale]
            return para

        if t3 <= -0.97:
            G = 1 - np.log(1 + t3) / dl2

        t0 = (t3 + 3) * 0.5

        for _ in range(1, MAXIT):
            x2 = 2 ** (-G)
            x3 = 3 ** (-G)
            xx2 = 1 - x2
            xx3 = 1 - x3
            t = xx3 / xx2
            deriv = (xx2 * x3 * dl3 - xx3 * x2 * dl2) / (xx2**2)
            gold = G
            G = G - (t - t0) / deriv
            if abs(G - gold) <= EPS * G:
                shape = G
                gam = np.exp(sp.special.gammaln(1 + G))
                scale = lmoments[1] * G / (gam * (1 - 2 ** (-G)))
                loc = lmoments[0] - scale * (1 - gam) / G
                para = [shape, loc, scale]
                return para
        raise ConvergenceError("Iteration has not converged")
    else:
        Z = 1 - t3
        G = (-1 + Z * (c1 + Z * (c2 + Z * c3))) / (1 + Z * (d1 + Z * d2))
        if abs(G) < ninf:
            # Gumbel
            scale = lmoments[1] / dl2
            loc = lmoments[0] - EU * scale
            para = [0, loc, scale]
        else:
            # GEV
            shape = G
            gam = np.exp(sp.special.gammaln(1 + G))
            scale = lmoments[1] * G / (gam * (1 - 2 ** (-G)))
            loc = lmoments[0] - scale * (1 - gam) / G
            # multiply the shape by -1 to follow the + ve shape parameter equation (+ve value means heavy tail)
            # para = [-1 * shape, loc, scale]
            para = [shape, loc, scale]

        return para

gumbel(lmoments) #

Estimate parameters for the Gumbel distribution.

The Gumbel distribution (also known as the Type I Extreme Value distribution) is used to model the maximum or minimum of a number of samples of various distributions. It is characterized by two parameters: location and scale.

Parameters:

Name Type Description Default
lmoments list[float | int]

A list of L-moments [l1, l2, ...] where: - l1 is the mean (first L-moment) - l2 is the L-scale (second L-moment) At least 2 L-moments must be provided.

 required

Returns:

Type Description
list[float | int]

A list of distribution parameters [location, scale] where: - location: Shifts the distribution along the x-axis - scale: Controls the spread of the distribution

Raises:

Type Description
ValueError

If the L-moments are invalid (l2 <= 0).

Examples:

  • Estimate Gumbel parameters from L-moments: 
    >>> from statista.parameters import Lmoments
  • Calculate L-moments from data 
    >>> data = [10.2, 15.7, 20.3, 25.9, 30.1, 35.6, 40.2]
>>> lmom = Lmoments(data)
>>> l_moments = lmom.calculate(nmom=2)

  • Estimate Gumbel parameters 

    >>> params = Lmoments.gumbel(l_moments)
>>> print(f"Location: {params[0]}, Scale: {params[1]}")
Location: 19.892792078673775, Scale: 9.590487033719015

  • Using predefined L-moments: 

    >>> from statista.parameters import Lmoments

  • Predefined L-moments 
    >>> l_moments = [10.0, 2.0]
  • Estimate Gumbel parameters 
    >>> params = Lmoments.gumbel(l_moments)
>>> print(f"Location: {params[0]}, Scale: {params[1]}")
Location: 8.334507645446266, Scale: 2.8853900817779268
Note

The Gumbel distribution has the cumulative distribution function: F(x) = exp(-exp(-(x-mu)/beta))

Where mu is the location parameter and beta is the scale parameter.

The Gumbel distribution is a special case of the GEV distribution with shape parameter = 0.

Source code in src/statista/parameters/extreme_value.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
def gumbel(lmoments: list[float | int]) -> list[float | int]:
    """Estimate parameters for the Gumbel distribution.

    The Gumbel distribution (also known as the Type I Extreme Value distribution) is
    used to model the maximum or minimum of a number of samples of various distributions.
    It is characterized by two parameters: location and scale.

    Args:
        lmoments: A list of L-moments [l1, l2, ...] where:
            - l1 is the mean (first L-moment)
            - l2 is the L-scale (second L-moment)
            At least 2 L-moments must be provided.

    Returns:
        A list of distribution parameters [location, scale] where:
            - location: Shifts the distribution along the x-axis
            - scale: Controls the spread of the distribution

    Raises:
        ValueError: If the L-moments are invalid (l2 <= 0).

    Examples:
        - Estimate Gumbel parameters from L-moments:
          ```python
          >>> from statista.parameters import Lmoments

          ```
          - Calculate L-moments from data
          ```python
          >>> data = [10.2, 15.7, 20.3, 25.9, 30.1, 35.6, 40.2]
          >>> lmom = Lmoments(data)
          >>> l_moments = lmom.calculate(nmom=2)

          ```
          - Estimate Gumbel parameters
          ```python
          >>> params = Lmoments.gumbel(l_moments)
          >>> print(f"Location: {params[0]}, Scale: {params[1]}")
          Location: 19.892792078673775, Scale: 9.590487033719015

          ```

        - Using predefined L-moments:
          ```python
          >>> from statista.parameters import Lmoments

          ```
          - Predefined L-moments
          ```python
          >>> l_moments = [10.0, 2.0]

          ```
          - Estimate Gumbel parameters
          ```python
          >>> params = Lmoments.gumbel(l_moments)
          >>> print(f"Location: {params[0]}, Scale: {params[1]}")
          Location: 8.334507645446266, Scale: 2.8853900817779268

          ```

    Note:
        The Gumbel distribution has the cumulative distribution function:
        F(x) = exp(-exp(-(x-mu)/beta))

        Where mu is the location parameter and beta is the scale parameter.

        The Gumbel distribution is a special case of the GEV distribution with shape parameter = 0.
    """
    if lmoments[1] <= 0:
        raise ValueError(LMOMENTS_INVALID_ERROR)
    else:
        para2 = lmoments[1] / np.log(2)
        para1 = lmoments[0] - EU * para2
        para = [para1, para2]
        return para

generalized_pareto(lmoments) #

Estimate parameters for the Generalized Pareto distribution.

The Generalized Pareto distribution is a flexible three-parameter family of distributions used to model the tails of other distributions. It is characterized by location, scale, and shape parameters.

Parameters:

Name Type Description Default
lmoments list[float | int]

A list of L-moments [l1, l2, l3, ...] where: - l1 is the mean (first L-moment) - l2 is the L-scale (second L-moment) - l3 is the L-skewness (third L-moment) At least 3 L-moments must be provided.

 required

Returns:

Type Description
list[float] | None

A list of distribution parameters [location, scale, shape] where: - location: Shifts the distribution along the x-axis (lower bound) - scale: Controls the spread of the distribution - shape: Controls the tail behavior of the distribution
list[float] | None

Returns None if the L-moments are invalid.

Examples:

  • Estimate Generalized Pareto parameters from L-moments: 
    >>> from statista.parameters import Lmoments
  • Calculate L-moments from data 
    >>> data = [0.8, 1.5, 2.3, 3.7, 4.1, 5.6, 6.9]
>>> lmom = Lmoments(data)
>>> l_moments = lmom.calculate(nmom=3)

  • Estimate Generalized Pareto parameters 

    >>> params = Lmoments.generalized_pareto(l_moments)
>>> if params:
...   print(f"Location: {params[0]}, Scale: {params[1]}, Shape: {params[2]}")
Location: -0.016221198156681993, Scale: 5.901814181656014, Shape: 0.6516129032258066

  • Using predefined L-moments: 

    >>> from statista.parameters import Lmoments

  • Predefined L-moments 
    >>> l_moments = [10.0, 2.0, 0.1]
  • Estimate Generalized Pareto parameters 
    >>> params = Lmoments.generalized_pareto(l_moments)
>>> if params:
...     print(f"Location: {params[0]}, Scale: {params[1]}, Shape: {params[2]}")
Location: 4.7272727272727275, Scale: 8.628099173553718, Shape: 0.6363636363636362
Note

The Generalized Pareto distribution has the cumulative distribution function: F(x) = 1 - [1 - k(x-mu)/alpha]^(1/k) for k != 0 F(x) = 1 - exp(-(x-mu)/alpha) for k = 0

Where mu is the location parameter, alpha is the scale parameter, and k is the shape parameter.

The method returns None if: - The second L-moment (l2) is less than or equal to zero - The absolute value of the third L-moment (l3) is greater than or equal to 1

These conditions indicate invalid L-moments for the Generalized Pareto distribution.

The shape parameter determines the tail behavior: - k < 0: The distribution has an upper bound - k = 0: The distribution is exponential - k > 0: The distribution has a heavy upper tail

Source code in src/statista/parameters/extreme_value.py 
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
def generalized_pareto(
    lmoments: list[float | int],
) -> list[float] | None:
    """Estimate parameters for the Generalized Pareto distribution.

    The Generalized Pareto distribution is a flexible three-parameter family of distributions
    used to model the tails of other distributions. It is characterized by location, scale,
    and shape parameters.

    Args:
        lmoments: A list of L-moments [l1, l2, l3, ...] where:
            - l1 is the mean (first L-moment)
            - l2 is the L-scale (second L-moment)
            - l3 is the L-skewness (third L-moment)
            At least 3 L-moments must be provided.

    Returns:
        A list of distribution parameters [location, scale, shape] where:
            - location: Shifts the distribution along the x-axis (lower bound)
            - scale: Controls the spread of the distribution
            - shape: Controls the tail behavior of the distribution
        Returns None if the L-moments are invalid.

    Examples:
        - Estimate Generalized Pareto parameters from L-moments:
          ```python
          >>> from statista.parameters import Lmoments

          ```
          - Calculate L-moments from data
          ```python
          >>> data = [0.8, 1.5, 2.3, 3.7, 4.1, 5.6, 6.9]
          >>> lmom = Lmoments(data)
          >>> l_moments = lmom.calculate(nmom=3)

          ```
          - Estimate Generalized Pareto parameters
          ```python
          >>> params = Lmoments.generalized_pareto(l_moments)
          >>> if params:
          ...   print(f"Location: {params[0]}, Scale: {params[1]}, Shape: {params[2]}")
          Location: -0.016221198156681993, Scale: 5.901814181656014, Shape: 0.6516129032258066

          ```

        - Using predefined L-moments:
          ```python
          >>> from statista.parameters import Lmoments

          ```
          - Predefined L-moments
          ```python
          >>> l_moments = [10.0, 2.0, 0.1]

          ```
          - Estimate Generalized Pareto parameters
          ```python
          >>> params = Lmoments.generalized_pareto(l_moments)
          >>> if params:
          ...     print(f"Location: {params[0]}, Scale: {params[1]}, Shape: {params[2]}")
          Location: 4.7272727272727275, Scale: 8.628099173553718, Shape: 0.6363636363636362

          ```

    Note:
        The Generalized Pareto distribution has the cumulative distribution function:
        F(x) = 1 - [1 - k(x-mu)/alpha]^(1/k) for k != 0
        F(x) = 1 - exp(-(x-mu)/alpha) for k = 0

        Where mu is the location parameter, alpha is the scale parameter, and k is the shape parameter.

        The method returns None if:
        - The second L-moment (l2) is less than or equal to zero
        - The absolute value of the third L-moment (l3) is greater than or equal to 1

        These conditions indicate invalid L-moments for the Generalized Pareto distribution.

        The shape parameter determines the tail behavior:
        - k < 0: The distribution has an upper bound
        - k = 0: The distribution is exponential
        - k > 0: The distribution has a heavy upper tail
    """
    t3 = lmoments[2]
    if lmoments[1] <= 0:
        print(LMOMENTS_INVALID_ERROR)
        return None

    if abs(t3) >= 1:
        print(LMOMENTS_INVALID_ERROR)
        return None

    g = (1 - 3 * t3) / (1 + t3)

    para3 = g
    para2 = (1 + g) * (2 + g) * lmoments[1]
    para1 = lmoments[0] - para2 / (1 + g)
    para = [para1, para2, para3]
    return para