returnlevelplot: Methods for Function returnlevelplot in Package 'distrMod'

In distrMod: Object Oriented Implementation of Probability Models

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

distrMod documentation built on Nov. 16, 2022, 9:07 a.m.