retlev: Return Level Plot

In POT: Generalized Pareto Distribution and Peaks Over Threshold

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(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,
...)

Arguments

object	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 = \frac{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, \ldots,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\left[\max\left\{X_1,\ldots,X_n\right\} \leq x \right] = \left[ F(x) \right]^{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)

POT documentation built on May 6, 2025, 3:01 a.m.