retlev {POT} | R Documentation

## Return Level Plot

### Description

`retlev` is a generic function used to show return level plot. The function invokes particular `methods` which depend on the `class` of the first argument. So the function makes a return level plot for POT models.

### Usage

    retlev(fitted, ...)

    ## S3 method for class 'uvpot'
    retlev(fitted, npy, main, xlab, ylab, xlimsup,
    ci = TRUE, points = TRUE, ...)
    ## S3 method for class 'mcpot'
    retlev(fitted, opy, exi, main, xlab, ylab, xlimsup,
    ...)

### Arguments

`fitted` | A fitted object. When using the POT package, an object of class `'uvpot'` or `'mcpot'`. Most often, the return of `fitgpd` or `fitmcgpd` functions.
`npy` | The mean Number of events Per Year (or more generally per block).if missing, setting it to 1.
`main` | The title of the graphic. If missing, the title is set to `"Return Level Plot"`.
`xlab,ylab` | The labels for the x and y axis. If missing, they are set to `"Return Period (Years)"` and `"Return Level"` respectively.
`xlimsup` | Numeric. The right limit for the x-axis. If missing, a suited value is computed.
`ci` | Logical. Should the 95% pointwise confidence interval be plotted?
`points` | Logical. Should observations be plotted?
`...` | Other arguments to be passed to the `plot` function.
`opy` | The number of Observations Per Year (or more generally per block). If missing, it is set it to 365 i.e. daily values with a warning.
`exi` | Numeric. The extremal index. If missing, an estimate is given using the `fitexi` function.

### Details

For class `"uvpot"`, the return level plot consists of plotting the theoretical quantiles in function of the return period (with a logarithmic scale for the x-axis). For the definition of the return period see the `prob2rp` function. Thus, the return level plot consists of plotting the points defined by:

(T(p), F^{-1}(p))

where T(p) is the return period related to the non exceedance probability p, F^{-1} is the fitted quantile function.

If `points = TRUE`, the probabilities p_j related to each observation are computed using the following plotting position estimator proposed by Hosking (1995):

p_j = (j - 0.35) / n

where n is the total number of observations.

If the theoretical model is correct, the points should be “close” to the “return level” curve.

For class `"mcpot"`, let X_1, …,X_n be the first n observations from a stationary sequence with marginal distribution function F. Thus, we can use the following (asymptotic) approximation:

Pr[max{X_1,…,X_n} <= x] = [F(x)]^(n theta)

where theta is the extremal index.

Thus, to obtain the T-year return level, we equate this equation to 1 - 1/T and solve for x.

### Value

A graphical window. In addition, it returns invisibly the return level function.

### Warning

For class `"mcpot"`, though this is computationally expensive, we recommend to give the extremal index estimate using the `dexi` function. Indeed, there is a severe bias when using the Ferro and Segers (2003) estimator - as it is estimated using observation and not the Markov chain model.

### Author(s)

Mathieu Ribatet

### References

Hosking, J. R. M. and Wallis, J. R. (1995). A comparison of unbiased and plotting-position estimators of L moments. Water Resources Research. 31(8): 2019–2025.

Ferro, C. and Segers, J. (2003). Inference for clusters of extreme values. Journal of the Royal Statistical Society B. 65: 545–556.

### See Also

`prob2rp`, `fitexi`.

### Examples

    #for uvpot class
    x <- rgpd(75, 1, 2, 0.1)
    pwmu <- fitgpd(x, 1, "pwmu")
    rl.fun <- retlev(pwmu)
    rl.fun(100)

    #for mcpot class
    data(ardieres)
    Mcalog <- fitmcgpd(ardieres[,"obs"], 5, "alog")
    retlev(Mcalog, opy = 990)

[Package POT version 1.1-7 Index]