R: Return Level Plot for GEV Fits

rlplot.gevff {VGAM} | R Documentation

## 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 zp versus log(yp). 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(zp) = 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 zp is known as the return level associated with the return period 1/p. For many applications, this means zp 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)

[Package VGAM version 1.1-3 Index]