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/datestring when the plot was generated
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39  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, withLab = FALSE, lab.pts = NULL, which.lbs = NULL,
which.Order = NULL, 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.lbl = par("cex"), col.lbl = par("col"), adj.lbl = NULL,
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 
object of class 
n 
numeric; assumed sample size (by default length of 
withIdLine 
logical; shall line 
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

datax 
logical; shall data be plotted on xaxis? 
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 
main 
Main title 
xlab 
xlabel 
ylab 
ylabel 
... 
further parameters for method 
width 
width (in inches) of the graphics device opened 
height 
height (in inches) of the graphics device opened 
withSweave 
logical: if 
mfColRow 
shall default partition in panels be used — defaults to 
n.CI 
numeric; number of points to be used for confidence interval 
withLab 
logical; shall observation labels be plotted in? 
lab.pts 
character or 
which.lbs 
integer or 
which.Order 
integer or 
order.traf 
function or 
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 
col.pch 
color for the plotted symbols 
cex.lbl 
magnification factor for the plotted observation labels 
col.lbl 
color for the plotted observation labels 
adj.lbl 
adj parameter for the plotted observation labels 
alpha.trsp 
alpha transparency to be added ex post to colors

jit.fac 
jittering factor used for discrete distributions. 
jit.tol 
threshold for jittering: if distance between points is smaller
than 
check.NotInSupport 
logical; shall we check if all 
col.NotInSupport 
logical; if preceding check 
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 
withSubst 
logical; if 
Details
 returnlevelplot
signature(x = "ANY", y = "UnivariateDistribution")
: produces a return level plot of a datasetx
against the theoretical quantiles of distributiony
. returnlevelplot
signature(x = "ANY", y = "ProbFamily")
: produces a return level plot of a datasetx
against the theoretical quantiles of the model distribution of modely
. Passed through the...
argument, all arguments valid forsignature(x = "ANY", y = "UnivariateDistribution")
are also valid for this signature. returnlevelplot
signature(x = "ANY", y = "Estimate")
: produces a return level plot of a datasetx
against the theoretical quantiles of the model distribution of the model that can be reconstructed from the estimatory
; 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 tomodifyModel
, and then this shifted model is used in a call to the(x = "ANY", y = "UnivariateDistribution")
method. Passed through the...
argument, all arguments valid forsignature(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 
crit 
A matrix with the lower and upper confidence bounds
(computed by 
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 nonparametric bands, hence also allow for nonparametric 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 peter.ruckdeschel@unioldenburg.de
References
ismev: An Introduction to Statistical Modeling of Extreme Values. R package version 1.39. http://CRAN.Rproject.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
1 2 3  returnlevelplot(r(Norm(15,sqrt(30)))(40), Chisq(df=15))
### more could be seen after installing RobExtremes and ismev
#
