Return Level Plot for GEV Fits

A return level plot is constructed for a GEV-type model.

Usage

rlplot.gevff(object, show.plot = TRUE,
    probability = c((1:9)/100, (1:9)/10, 0.95, 0.99, 0.995, 0.999),
    add.arg = FALSE, xlab = if(log.arg) "Return Period (log-scale)" else
    "Return Period", ylab = "Return Level",
    main = "Return Level Plot",
    pch = par()$pch, pcol.arg = par()$col, pcex = par()$cex,
    llty.arg = par()$lty, lcol.arg = par()$col, llwd.arg = par()$lwd,
    slty.arg = par()$lty, scol.arg = par()$col, slwd.arg = par()$lwd,
    ylim = NULL, log.arg = TRUE, CI = TRUE, epsilon = 1e-05, ...)

Arguments

object

A VGAM extremes model of the GEV-type, produced by vglm with a family function either "gev" or "gevff".

show.plot

Logical. Plot it? If FALSE no plot will be done.

probability

Numeric vector of probabilities used.

add.arg

Logical. Add the plot to an existing plot?

xlab

Caption for the x-axis. See par.

ylab

Caption for the y-axis. See par.

main

Title of the plot. See title.

pch

Plotting character. See par.

pcol.arg

Color of the points. See the col argument of par.

pcex

Character expansion of the points. See the cex argument of par.

llty.arg

Line type. Line type. See the lty argument of par.

lcol.arg

Color of the lines. See the col argument of par.

llwd.arg

Line width. See the lwd argument of par.

slty.arg, scol.arg, slwd.arg

Correponding arguments for the lines used for the confidence intervals. Used only if CI=TRUE.

ylim

Limits for the y-axis. Numeric of length 2.

log.arg

Logical. If TRUE then log="" otherwise log="x". This changes the labelling of the x-axis only.

CI

Logical. Add in a 95 percent confidence interval?

epsilon

Numeric, close to zero. Used for the finite-difference approximation to the first derivatives with respect to each parameter. If too small, numerical problems will occur.

...

Arguments passed into the plot function when setting up the entire plot. Useful arguments here include sub and las.

Details

A return level plot plots \(z_p\) versus \(\log(y_p)\). It is linear if the shape parameter \(\xi=0\). If \(\xi<0\) then the plot is convex with asymptotic limit as \(p\) approaches zero at \(\mu-\sigma / \xi\). And if \(\xi>0\) then the plot is concave and has no finite bound. Here, \(G(z_p) = 1-p\) where \(0<p<1\) (\(p\) corresponds to the argument probability) and \(G\) is the cumulative distribution function of the GEV distribution. The quantity \(z_p\) is known as the return level associated with the return period \(1/p\). For many applications, this means \(z_p\) is exceeded by the annual maximum in any particular year with probability \(p\).

The points in the plot are the actual data.

Value

In the post slot of the object is a list called rlplot with list components

yp

-log(probability), which is used on the x-axis.

zp

values which are used for the y-axis

lower, upper

lower and upper confidence limits for the 95 percent confidence intervals evaluated at the values of probability (if CI=TRUE).

References

Coles, S. (2001). An Introduction to Statistical Modeling of Extreme Values. London: Springer-Verlag.

Author

T. W. Yee

Note

The confidence intervals are approximate, being based on finite-difference approximations to derivatives.

See also

gevff.

Examples

gdata <- data.frame(y = rgev(n <- 100, scale = 2, shape = -0.1))
fit <- vglm(y ~ 1, gevff, data = gdata, trace = TRUE)
#> Iteration 1: loglikelihood = -215.65335
#> Iteration 2: loglikelihood = -215.58945
#> Iteration 3: loglikelihood = -215.585
#> Iteration 4: loglikelihood = -215.58456
#> Iteration 5: loglikelihood = -215.58452
#> Iteration 6: loglikelihood = -215.58451
#> Iteration 7: loglikelihood = -215.58451

# Identity link for all parameters:
fit2 <- vglm(y ~ 1, gevff(lshape = identitylink, lscale = identitylink,
                          iscale = 10), data = gdata, trace = TRUE)
#> Iteration 1: loglikelihood = -268.72483
#> Iteration 2: loglikelihood = -234.84867
#> Iteration 3: loglikelihood = -218.20071
#> Iteration 4: loglikelihood = -215.7767
#> Iteration 5: loglikelihood = -215.60236
#> Iteration 6: loglikelihood = -215.5863
#> Iteration 7: loglikelihood = -215.5847
#> Iteration 8: loglikelihood = -215.58453
#> Iteration 9: loglikelihood = -215.58451
#> Iteration 10: loglikelihood = -215.58451
coef(fit2, matrix = TRUE)
#>               location    scale       shape
#> (Intercept) -0.2147447 1.865031 -0.08472664
if (FALSE) { # \dontrun{
par(mfrow = c(1, 2))
rlplot(fit) -> i1
rlplot(fit2, pcol = "darkorange", lcol = "blue", log.arg = FALSE,
       scol = "darkgreen", slty = "dashed", las = 1) -> i2
range(i2@post$rlplot$upper - i1@post$rlplot$upper)  # Should be near 0
range(i2@post$rlplot$lower - i1@post$rlplot$lower)  # Should be near 0
} # }