returnlevelplot {distrMod}

Methods for Function returnlevelplot in Package ‘distrMod’

Description

We generalize the return level plot (which is one of the diagnostical plots provided package ismev, e.g., in function gev.diag), see also Coles' book below, to be applicable to distribution and probability model objects. In this context, returnlevelplot produces a rescaled QQ plot of data (argument x) against a (model) distribution. Graphical parameters may be given as arguments to returnlevelplot. In all title and label arguments, if withSubst is TRUE, the following patterns are substituted:

"%C"

class of argument x

"%A"

deparsed argument x

"%D"

time/date-string when the plot was generated

Usage

returnlevelplot(x, y, ...)
## S4 method for signature 'ANY,UnivariateDistribution'
returnlevelplot(x,y,
    n = length(x), withIdLine = TRUE,
    withConf = TRUE, withConf.pw  = withConf, withConf.sim = withConf,
    plot.it = TRUE, datax = FALSE, MaxOrPOT = c("Max","POT"), npy = 365,
    threshold = if(is(y,"GPareto")) NA else 0,    
    xlab = deparse(substitute(x)),
    ylab = deparse(substitute(y)),
    main = "",
    ..., width = 10, height = 5.5, withSweave = getdistrOption("withSweave"),
    mfColRow = TRUE, n.CI = n, with.lab = FALSE, lab.pts = NULL, which.lbs = NULL,
    which.Order = NULL, which.nonlbs = NULL, attr.pre = FALSE, order.traf = NULL,
    col.IdL = "red", lty.IdL = 2, lwd.IdL = 2, alpha.CI = .95,
    exact.pCI = (n<100), exact.sCI = (n<100), nosym.pCI = FALSE,
    col.pCI = "orange", lty.pCI = 3, lwd.pCI = 2, pch.pCI = par("pch"),
    cex.pCI = par("cex"),
    col.sCI = "tomato2", lty.sCI = 4, lwd.sCI = 2, pch.sCI = par("pch"),
    cex.sCI = par("cex"), added.points.CI = TRUE,
    cex.pch = par("cex"), col.pch = par("col"),
    cex.pts = 1, col.pts = par("col"), pch.pts = 19,
    cex.npts = 1, col.npts = grey(.5), pch.npts = 20,
    cex.lbs = par("cex"), col.lbs = par("col"), adj.lbs = par("adj"),
    alpha.trsp = NA, jit.fac = 0,  jit.tol = .Machine$double.eps,
    check.NotInSupport = TRUE, col.NotInSupport = "red",
    with.legend = TRUE, legend.bg = "white",
    legend.pos = "topleft", legend.cex = 0.8,
    legend.pref = "", legend.postf = "",  legend.alpha = alpha.CI,
    debug = FALSE, withSubst = TRUE)
## S4 method for signature 'ANY,ProbFamily'
returnlevelplot(x, y,
   n = length(x), withIdLine = TRUE, withConf = TRUE,
   withConf.pw  = withConf,  withConf.sim = withConf,
    plot.it = TRUE, xlab = deparse(substitute(x)),
    ylab = deparse(substitute(y)), ...)
## S4 method for signature 'ANY,Estimate'
returnlevelplot(x, y,
   n = length(x), withIdLine = TRUE, withConf = TRUE,
   withConf.pw  = withConf,  withConf.sim = withConf,
    plot.it = TRUE, xlab = deparse(substitute(x)),
    ylab = deparse(substitute(y)), ...)

Arguments

x

data to be checked for compatibility with distribution/model y.

y

object of class "UnivariateDistribution" or of class "ProbFamily".

n

numeric; assumed sample size (by default length of x).

withIdLine

logical; shall line y = x be plotted in?

withConf

logical; shall confidence lines be plotted?

withConf.pw

logical; shall pointwise confidence lines be plotted?

withConf.sim

logical; shall simultaneous confidence lines be plotted?

plot.it

logical; shall be plotted at all (inherited from returnlevelplot)?

datax

logical; shall data be plotted on x-axis?

MaxOrPOT

a character string specifying whether it is used for block maxima ("Max") or for points over threshold ("POT"); must be one of "Max" (default) or "POT". You can specify just the initial letter.

npy

number of observations per year/block.

threshold

numerical; in case of MaxOrPot=="POT", this captures the (removed) threshold. If it is NA, it is reconstructed from the distribution y.

main

Main title

xlab

x-label

ylab

y-label

...

further parameters for method returnlevelplot with signature ANY,UnivariateDistribution or with function plot

width

width (in inches) of the graphics device opened

height

height (in inches) of the graphics device opened

withSweave

logical: if TRUE (for working with Sweave) no extra device is opened and height/width are not set

mfColRow

shall default partition in panels be used — defaults to TRUE

n.CI

numeric; number of points to be used for confidence interval

with.lab

logical; shall observation labels be plotted in?

lab.pts

character or NULL; observation labels to be used

attr.pre

logical; do graphical attributes for plotted data refer to indices prior (TRUE) or posterior to selection via arguments which.lbs, which.Order, which.nonlbs (FALSE)?

which.lbs

integer or NULL; which observations shall be labelled

which.nonlbs

indices of the observations which should be plotted but not labelled; either an integer vector with the indices of the observations to be plotted into graph or NULL — then all non-labelled observations are plotted.

which.Order

integer or NULL; which of the ordered (remaining) observations shall be labelled

order.traf

function or NULL; an optional trafo by which the observations are ordered (as order(trafo(obs)).

col.IdL

color for the identity line

lty.IdL

line type for the identity line

lwd.IdL

line width for the identity line

alpha.CI

confidence level

exact.pCI

logical; shall pointwise CIs be determined with exact Binomial distribution?

exact.sCI

logical; shall simultaneous CIs be determined with exact Kolmogorov distribution?

nosym.pCI

logical; shall we use (shortest) asymmetric CIs?

col.pCI

color for the pointwise CI

lty.pCI

line type for the pointwise CI

lwd.pCI

line width for the pointwise CI

pch.pCI

symbol for points (for discrete mass points) in pointwise CI

cex.pCI

magnification factor for points (for discrete mass points) in pointwise CI

col.sCI

color for the simultaneous CI

lty.sCI

line type for the simultaneous CI

lwd.sCI

line width for the simultaneous CI

pch.sCI

symbol for points (for discrete mass points) in simultaneous CI

cex.sCI

magnification factor for points (for discrete mass points) in simultaneous CI

added.points.CI

logical; should CIs be plotted through additional points (and not only through data points)?

cex.pch

magnification factor for the plotted symbols (for backward compatibility); it is ignored once col.pts is specified.

col.pch

color for the plotted symbols (for backward compatibility); it is ignored once col.pts is specified.

cex.pts

size of the points of the second argument plotted, can be a vector; if argument attr.pre is TRUE, it is recycled to the length of all observations and determines the sizes of all plotted symbols, i.e., the selection is done within this argument; in this case argument col.npts is ignored. If attr.pre is FALSE, cex.pts is recycled to the number of the observations selected for labelling and refers to the index ordering after the selection. Then argument cex.npts deteremines the sizes of the shown but non-labelled observations as given in argument which.nonlbs.

col.pts

color of the points of the second argument plotted, can be a vector as in cex.pts (with col.npts as counterpart).

pch.pts

symbol of the points of the second argument plotted, can be a vector as in cex.pts (with pch.npts as counterpart).

col.npts

color of the non-labelled points of the data argument plotted; (may be a vector).

pch.npts

symbol of the non-labelled points of the data argument plotted (may be a vector).

cex.npts

size of the non-labelled points of the data argument plotted (may be a vector).

cex.lbs

magnification factor for the plotted observation labels

col.lbs

color for the plotted observation labels

adj.lbs

adj parameter for the plotted observation labels

alpha.trsp

alpha transparency to be added ex post to colors col.pch and col.lbs; if one-dim and NA all colors are left unchanged. Otherwise, with usual recycling rules alpha.trsp gets shorted/prolongated to length the data-symbols to be plotted. Coordinates of this vector alpha.trsp with NA are left unchanged, while for the remaining ones, the alpha channel in rgb space is set to the respective coordinate value of alpha.trsp. The non-NA entries must be integers in [0,255] (0 invisible, 255 opaque).

jit.fac

jittering factor used for discrete distributions.

jit.tol

threshold for jittering: if distance between points is smaller than jit.tol, points are considered replicates.

check.NotInSupport

logical; shall we check if all x-quantiles lie in support(y)?

col.NotInSupport

logical; if preceding check TRUE color of x-quantiles if not in support(y)

with.legend

logical; shall a legend be plotted?

legend.bg

background color for the legend

legend.pos

position for the legend

legend.cex

magnification factor for the legend

legend.pref

character to be prepended to legend text

legend.postf

character to be appended to legend text

legend.alpha

nominal coverage probability

debug

logical; if TRUE additional output to debug confidence bounds.

withSubst

logical; if TRUE (default) pattern substitution for titles and axis lables is used; otherwise no substitution is used.

Details

returnlevelplot

signature(x = "ANY", y = "UnivariateDistribution"): produces a return level plot of a dataset x against the theoretical quantiles of distribution y.

returnlevelplot

signature(x = "ANY", y = "ProbFamily"): produces a return level plot of a dataset x against the theoretical quantiles of the model distribution of model y. Passed through the ... argument, all arguments valid for signature(x = "ANY", y = "UnivariateDistribution") are also valid for this signature.

returnlevelplot

signature(x = "ANY", y = "Estimate"): produces a return level plot of a dataset x against the theoretical quantiles of the model distribution of the model that can be reconstructed from the estimator y; more specifically, it tries to get hand at the argument 'ParamFamily' of the esimator's call; if this is available, internally this model is shifted to the estimated parameter by a call to modifyModel, and then this shifted model is used in a call to the (x = "ANY", y = "UnivariateDistribution")-method. Passed through the ... argument, all arguments valid for signature(x = "ANY", y = "UnivariateDistribution") are also valid for this signature.

Value

As for function returnlevelplot from package stats: a list with components

x

The x coordinates of the points that were/would be plotted

y

The corresponding quantiles of the second distribution, including NAs.

crit

A matrix with the lower and upper confidence bounds (computed by qqbounds).

err

logical vector of length 2.

(elements crit and err are taken from the return value(s) of qqbounds).

Note

The confidence bands given in our version of the return level plot differ from the ones given in package ismev. We use non-parametric bands, hence also allow for non-parametric deviances from the model, whereas in in package ismev they are based on profiling, hence only check for variability within the parametric class.

Author(s)

Peter Ruckdeschel [e-mail]

References

ismev: An Introduction to Statistical Modeling of Extreme Values. R package version 1.39. https://CRAN.R-project.org/package=ismev; original S functions written by Janet E. Heffernan with R port and R documentation provided by Alec G. Stephenson. (2012).

Coles, S. (2001). An introduction to statistical modeling of extreme values. London: Springer.

See Also

qqplot from package stats – the standard QQ plot function, qqplot from package distr for comparisons of distributions, qqplot from this package and qqbounds, used by returnlevelplot to produce confidence intervals.

Examples

set.seed(20190331)
returnlevelplot(r(Norm(15,sqrt(30)))(40), Chisq(df=15))
### more could be seen after installing RobExtremes and ismev
#

## IGNORE_RDIFF_BEGIN
 ## at R CMD check --as-cran, it does not find package cluster
           ## when trying to attach package rrcov
           ## so remove this from testing
if(require(RobExtremes) && require(ismev)){

 data(portpirie)
 gevfit <- gev.fit(portpirie[,2]) ## taken from example from ismev::gev.fit
 GEVF <- GEVFamily(scale=gevfit$mle[2],shape=gevfit$mle[3],loc=gevfit$mle[1])
 erg <- returnlevelplot(portpirie[,2], GEVF)
 print(names(erg))
 print(names(erg$plotArgs))
 print(names(erg$IdLineArgs))
 returnlevelplot(portpirie[,2], GEVF, datax=TRUE)

 data(rain)
 gpdfit <- gpd.fit(rain,10) ## taken from example from ismev::gpd.fit
 GPDF <- GParetoFamily(scale=gpdfit$mle[1],shape=gpdfit$mle[2],loc=10)
 returnlevelplot(rain, GPDF, MaxOrPOT="POT", xlim=c(1e-1,1e3))
}

## IGNORE_RDIFF_END