retlev: Return Level Plot

View source: R/default-gen-retlev.R

retlevR Documentation

Return Level Plot


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.


retlev(object, ...)

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



A fitted object. When using the POT package, an object of class 'uvpot' or 'mcpot'. Most often, the return of fitgpd or fitmcgpd functions.


The mean Number of events Per Year (or more generally per block).if missing, setting it to 1.


The title of the graphic. If missing, the title is set to "Return Level Plot".


The labels for the x and y axis. If missing, they are set to "Return Period (Years)" and "Return Level" respectively.


Numeric. The right limit for the x-axis. If missing, a suited value is computed.


Logical. Should the 95% pointwise confidence interval be plotted?


Logical. Should observations be plotted?


Other arguments to be passed to the plot function.


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.


Numeric. The extremal index. If missing, an estimate is given using the fitexi function.


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.


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


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


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.


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

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

POT documentation built on April 14, 2022, 5:07 p.m.