NCL Home > Documentation > Functions > Statistics, Extreme values

# extval_recurrence_table

Calculates the recurrence interval (return period), cumulative and exceedence probabilities based upon a time series.

Available in version 6.4.0 and later.

## Prototype

```	function extval_recurrence_table (
time [*] : numeric,
x        : numeric,
dims [*] : integer,
opt  [1] : logical
)

return_val
```

## Arguments

time

A numeric array containing 'time' steps. Actually any unique numbering can be used. For example, if N=dimsizes(x), then time=ispan(1,N,1)

x

A numeric array containing observations corresponding to each 'time' step. Currently, the only variables allowed are x(ntim), x(time,npts) and x(time,nlat,mlon).

dims

Currently not used. Set to zero.

opt

A logical scalar to which optional attributes may be attached. If opt=False, the returned array is in the order input to the function. If opt=True and the attrobute rank_order is present and opt@rank_order=True, the returned table will be in order by rank.

## Return value

Return seven (7) ranked table entries:

• 'time' entry
• 'x' value associated with the 'time'
• Cumulative Probability Rank
• Cumulative Probability
• Exceedance Probability Rank
• Exceedance Probability
• Recurrence Interval
See Examples.

## Description

The annual exceedance probability (AEP) is the chance or probability of an event (eg., a rainfall or flooding event) occurring annually. AEP is usually expressed as a percentage. Bigger rainfall events occur (are exceeded) less often and will therefore have a lesser annual probability.

It should be noted that there are multiple methods for estimating probabilities of exceedance or non-exceedance of ranked data (R).

```     R/N                  ; state of California
(R-0.5)/N             ; Hazen
R/(N+1)              ; Weibull   <==== used here
(R-0.44 )/(N+0.12)    ; Gringoren  (WMO, 1983)
(R-0.375)/(N+0.25)    ; Sevruk and Geiger
```
However, the differences between the various methods are typically quite small. See Table 1 and Table 2 of Reces (2004). extval_recurrence_table uses the 'Weibull' recurrence interval formulation.

From Wikipedia: It has been shown by Gumbel that the estimator R/(N+1) for the probability of an event wherei R is the rank number of the observed value in the data series and N is the total number of observations is an unbiased estimator of the cumulative probability around the mode of the distribution. Therefore, this estimator is often used as a plotting position .

References:

```Raes, D (2004):  Frequency Analysis of Rainfall Data
ICTP (International Center for Theoretical Physics (2444-10)
```

## Examples

Example 1

This example is from http://geog.uoregon.edu/amarcus/geog422/Handout_Recurrence_calcs.htm.

```
yyyy  = ispan(1931, 1940, 1)                         ; year
prc   = (/1306, 1345, 1032, 1580, 1293, 1497, 1469, 1392, 1037, 1633/)  ; mm

table = extval_recurrence_table(yyyy, prc, 0, False)
printVarSummary (table)                              ; [10] x [7]
write_matrix (table, "2f7.0,5f9.2", False)
```
The (edited) output is:
```                    Cum.     Cum.    Exceed  Exceed   Recurrence
yyyy   prc     Prob.    Prob.    Prob.   Prob.    Interval
Rank              Rank
----  ----     ----     ----     ----     ----     ----
1931  1306     4.00     0.36     7.00     0.64     1.57
1932  1345     5.00     0.45     6.00     0.55     1.83
1933  1032     1.00     0.09    10.00     0.91     1.10
1934  1580     9.00     0.82     2.00     0.18     5.50
1935  1293     3.00     0.27     8.00     0.73     1.38
1936  1497     8.00     0.73     3.00     0.27     3.67
1937  1469     7.00     0.64     4.00     0.36     2.75
1938  1392     6.00     0.55     5.00     0.45     2.20
1939  1037     2.00     0.18     9.00     0.82     1.22
1940  1633    10.00     0.91     1.00     0.09    11.00
```
Example 2

Same data as Example 1 but the table is returned in 'rank order'.

```   opt = True
opt@rank_order = True

TABLE = extval_recurrence_table(yyyy, prc, 0, opt)
write_matrix (TABLE, "2f7.0,5f9.2", False)
```
The (edited) output is:
```                    Cum.     Cum.    Exceed  Exceed   Recurrence
yyyy   prc     Prob.    Prob.    Prob.   Prob.    Interval
Rank              Rank
----  ----     ----     ----     ----     ----     ----
1933  1032     1.00     0.09    10.00     0.91     1.10
1939  1037     2.00     0.18     9.00     0.82     1.22
1935  1293     3.00     0.27     8.00     0.73     1.38
1931  1306     4.00     0.36     7.00     0.64     1.57
1932  1345     5.00     0.45     6.00     0.55     1.83
1938  1392     6.00     0.55     5.00     0.45     2.20
1937  1469     7.00     0.64     4.00     0.36     2.75
1936  1497     8.00     0.73     3.00     0.27     3.67
1934  1580     9.00     0.82     2.00     0.18     5.50
1940  1633    10.00     0.91     1.00     0.09    11.00

```
Example 3

Let x(time,npts) then:

```   opt   = False
;opt   = True
;opt@rank_order = True

time  = x&time   ; any unique time

table = extval_recurrence_table(time, x, 0, opt)
printVarSummary(table)   ; (npts, ntim, 7)
```
Example 4

Let x(time,lat,lon) then:

```   opt   = False
;opt   = True
;opt@rank_order = True

time  = x&time   ; any unique time

table = extval_recurrence_table(time, x, 0, opt)
printVarSummary(table)   ; (nlat, mlon, ntim, 7)
```
Example 5

Generically, this is the same as Example 2 but for different data. This data is used for Example 6 on the 'Extreme Value' application page.

```  flood  = (/ 312,590,248,670,365,770,465,545,315,115,232,260,655,675  \
, 455,1020,700,570,853,395,926,99,680,121,976,916,921,191  \
, 187,377,128,582,744,710,520,672,645,655,918,512,255,1126 \
,1386,1394,600,950,731,700,1407,1284,165,1496,809          /)
nflood = dimsizes(flood)   ; nflood=53
yyyy   = ispan(1,nflood,1)

opt   = True
opt@rank_order = True

table = extval_recurrence_table(yyyy, flood, 0, opt)
printVarSummary(table)
```
The (edited) output is:
```                    Cum.     Cum.    Exceed  Exceed   Recurrence
yyyy  Flood    Prob.    Prob.    Prob.   Prob.    Interval
Rank              Rank
----  ----     ----     ----     ----     ----     ----
22.    99.     1.00     1.85    53.00    98.15     1.02
10.   115.     2.00     3.70    52.00    96.30     1.04
24.   121.     3.00     5.56    51.00    94.44     1.06
31.   128.     4.00     7.41    50.00    92.59     1.08
51.   165.     5.00     9.26    49.00    90.74     1.10
29.   187.     6.00    11.11    48.00    88.89     1.12
28.   191.     7.00    12.96    47.00    87.04     1.15
11.   232.     8.00    14.81    46.00    85.19     1.17
3.   248.     9.00    16.67    45.00    83.33     1.20
41.   255.    10.00    18.52    44.00    81.48     1.23
12.   260.    11.00    20.37    43.00    79.63     1.26
1.   312.    12.00    22.22    42.00    77.78     1.29
9.   315.    13.00    24.07    41.00    75.93     1.32
5.   365.    14.00    25.93    40.00    74.07     1.35
30.   377.    15.00    27.78    39.00    72.22     1.38
20.   395.    16.00    29.63    38.00    70.37     1.42
15.   455.    17.00    31.48    37.00    68.52     1.46
7.   465.    18.00    33.33    36.00    66.67     1.50
40.   512.    19.00    35.19    35.00    64.81     1.54
35.   520.    20.00    37.04    34.00    62.96     1.59
8.   545.    21.00    38.89    33.00    61.11     1.64
18.   570.    22.00    40.74    32.00    59.26     1.69
32.   582.    23.00    42.59    31.00    57.41     1.74
2.   590.    24.00    44.44    30.00    55.56     1.80
45.   600.    25.00    46.30    29.00    53.70     1.86
37.   645.    26.00    48.15    28.00    51.85     1.93
13.   655.    27.00    50.00    27.00    50.00     2.00
38.   655.    28.00    51.85    26.00    48.15     2.08
4.   670.    29.00    53.70    25.00    46.30     2.16
36.   672.    30.00    55.56    24.00    44.44     2.25
14.   675.    31.00    57.41    23.00    42.59     2.35
23.   680.    32.00    59.26    22.00    40.74     2.45
17.   700.    33.00    61.11    21.00    38.89     2.57
48.   700.    34.00    62.96    20.00    37.04     2.70
34.   710.    35.00    64.81    19.00    35.19     2.84
47.   731.    36.00    66.67    18.00    33.33     3.00
33.   744.    37.00    68.52    17.00    31.48     3.18
6.   770.    38.00    70.37    16.00    29.63     3.38
53.   809.    39.00    72.22    15.00    27.78     3.60
19.   853.    40.00    74.07    14.00    25.93     3.86
26.   916.    41.00    75.93    13.00    24.07     4.15
39.   918.    42.00    77.78    12.00    22.22     4.50
27.   921.    43.00    79.63    11.00    20.37     4.91
21.   926.    44.00    81.48    10.00    18.52     5.40
46.   950.    45.00    83.33     9.00    16.67     6.00
25.   976.    46.00    85.19     8.00    14.81     6.75
16.  1020.    47.00    87.04     7.00    12.96     7.71
42.  1126.    48.00    88.89     6.00    11.11     9.00
50.  1284.    49.00    90.74     5.00     9.26    10.80
43.  1386.    50.00    92.59     4.00     7.41    13.50
44.  1394.    51.00    94.44     3.00     5.56    18.00
49.  1407.    52.00    96.30     2.00     3.70    27.00
52.  1496.    53.00    98.15     1.00     1.85    54.00
```