# retlev: Return Level Plot In POT: Generalized Pareto Distribution and Peaks Over Threshold

## 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

 ```1 2 3 4 5 6 7 8``` ```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.

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.

`prob2rp`, `fitexi`.
 ``` 1 2 3 4 5 6 7 8 9 10``` ```#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) ```