rlplot.gevff {VGAM}

Return Level Plot for GEV Fits

Description

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

Note

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

Author(s)

T. W. Yee

References

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

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)

# Identity link for all parameters:
fit2 <- vglm(y ~ 1, gevff(lshape = identitylink, lscale = identitylink,
                          iscale = 10), data = gdata, trace = TRUE)
coef(fit2, matrix = TRUE)
## Not run: 
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

## End(Not run)