Worm Plots for Quantile Residuals

Visualize goodness of fit of regression models by worm plots using quantile residuals. If plot = TRUE, the resulting object of class "wormplot" is plotted by plot.qqrplot or autoplot.qqrplot before it is returned, depending on whether the package ggplot2 is loaded.

wormplot(object, ...)

# S3 method for default
wormplot(
  object,
  newdata = NULL,
  plot = TRUE,
  class = NULL,
  detrend = TRUE,
  scale = c("normal", "uniform"),
  nsim = 1L,
  delta = NULL,
  confint = TRUE,
  simint = TRUE,
  simint_level = 0.95,
  simint_nrep = 250,
  single_graph = FALSE,
  xlab = "Theoretical quantiles",
  ylab = "Deviation",
  main = NULL,
  ...
)

Arguments

object

an object from which probability integral transforms can be extracted using the generic function procast.

newdata

optionally, a data frame in which to look for variables with which to predict. If omitted, the original observations are used.

plot

Should the plot or autoplot method be called to draw the computed Q-Q plot? Either set plot expicitly to "base" vs. "ggplot2" to choose the type of plot, or for a logical plot argument it's chosen conditional if the package ggplot2 is loaded.

class

Should the invisible return value be either a data.frame or a tibble. Either set class expicitly to "data.frame" vs. "tibble", or for NULL it's chosen automatically conditional if the package tibble is loaded.

detrend

logical. Should the qqrplot be detrended, i.e, plotted as a `wormplot()`?

scale

On which scale should the quantile residuals be shown: on the probability scale ("uniform") or on the normal scale ("normal").

nsim, delta

arguments passed to proresiduals.

confint

logical or character string describing the type for plotting `c("polygon", "line")`. If not set to `FALSE`, the pointwise confidence interval of the (randomized) quantile residuals are visualized.

simint

logical. In case of discrete distributions, should the simulation (confidence) interval due to the randomization be visualized?

simint_level

numeric. The confidence level required for calculating the simulation (confidence) interval due to the randomization.

simint_nrep

numeric. The repetition number of simulated quantiles for calculating the simulation (confidence) interval due to the randomization.

single_graph

logical. Should all computed extended reliability diagrams be plotted in a single graph?

xlab, ylab, main, ...

graphical parameters passed to plot.qqrplot or autoplot.qqrplot.

Value

An object of class "qqrplot" inheriting from "data.frame" or "tibble" conditional on the argument class

with the following variables:

x

theoretical quantiles,

y

deviations between theoretical and empirical quantiles.

In case of randomized residuals, nsim different x and y values, and lower and upper confidence interval bounds (x_rg_lwr, y_rg_lwr, x_rg_upr, y_rg_upr) can optionally be returned. Additionally, xlab, ylab, main, and simint_level, as well as the the (scale) and wether a detrended Q-Q residuals plot was computed are stored as attributes.

Details

Worm plots (de-trended Q-Q plots) draw deviations of quantile residuals (by default: transformed to standard normal scale) and theoretical quantiles from the same distribution against the same theoretical quantiles. For computation, wormplot leverages the function proresiduals employing the procast.

Additional options are offered for models with discrete responses where randomization of quantiles is needed.

In addition to the plot and autoplot method for wormplot objects, it is also possible to combine two (or more) worm plots by c/rbind, which creates a set of worm plots that can then be plotted in one go.

References

van Buuren S and Fredriks M (2001). “Worm plot: simple diagnostic device for modelling growth reference curves”. Statistics in Medicine, 20, 1259--1277. doi:10.1002/sim.746

Examples


## speed and stopping distances of cars
m1_lm <- lm(dist ~ speed, data = cars)

## compute and plot wormplot
wormplot(m1_lm)


#-------------------------------------------------------------------------------
## determinants for male satellites to nesting horseshoe crabs
data("CrabSatellites", package = "countreg")

## linear poisson model
m1_pois <- glm(satellites ~ width + color, data = CrabSatellites, family = poisson)
m2_pois <- glm(satellites ~ color, data = CrabSatellites, family = poisson)

## compute and plot wormplot as base graphic
w1 <- wormplot(m1_pois, plot = FALSE)
w2 <- wormplot(m2_pois, plot = FALSE)

## plot combined wormplot as "ggplot2" graphic
ggplot2::autoplot(c(w1, w2), single_graph = TRUE, col = c(1, 2), fill = c(1, 2))