Worm plot of randomized quantile residuals

worm_plot() draws a detrended QQ plot (van Buuren & Fredriks-style worm plot) of drm_quantile_residuals() against their N(0,1) order-statistic theoretical quantiles: deviation = sorted residual - theoretical quantile. A flat scatter around the dotted zero reference line is no detectable departure from N(0,1); a systematic bend flags a mis-specification of the fitted distributional form (see the GAMLSS-Primer Fig-4c contrast: a location-only fit to heteroscedastic data bends, the matching location-scale fit is flat).

Usage

worm_plot(object, seed = NULL, nsim = 1L, response = NULL, ...)

Arguments

object: A drmTMB fit.
seed: Optional single integer seed, passed to drm_quantile_residuals().
nsim: Number of Dunn-Smyth realizations to overplot as an envelope; passed to drm_quantile_residuals().
response: For a bivariate biv_gaussian fit, 1 or 2, selecting which response's marginal residuals to plot; see fitted_distribution(). Must be NULL (the default) for univariate model types.
...: Reserved for future options.

Value

A ggplot object.

Details

When nsim > 1, a pale grey envelope (with a darker outline) overplots the per-rank range across the nsim Dunn-Smyth realizations, so a single randomized draw is not over-read; the first realization's points and fitted trend are drawn on top.

This is fixed-effect adequacy only – see drm_quantile_residuals(). A flat worm plot is "no detectable departure" evidence about the fixed-effect distributional form, never a general validity or calibration claim.

What this detects – and does not. A worm plot bends when the underlying quantile residuals depart from N(0,1); see residuals.drmTMB()'s Details for the full gated-campaign breakdown (400 seeds x 18 families, tweedie: 99 of 400 seeds locally, full run deferred to Totoro; docs/dev-log/simulation-artifacts/2026-07-12-dg3-power-arm-gated/). In short: it flags shape/atom mis-specification a family cannot reabsorb through its own free parameters (heavy tails, ignored overdispersion or zero-inflation in a no-free-dispersion family, ignored truncation, a missing zero/one atom – gated power >= 0.8), but it stays flat – a genuine structural blind spot, not evidence of adequacy – when a free nuisance/dispersion/inflation parameter absorbs the mis-specification (e.g. heteroscedasticity absorbed by Student-t nu, missing zero-inflation absorbed by nbinom2 sigma, or a constant-vs-covariate zero-inflation/hurdle mechanism mis-set for hurdle_nbinom2/ zero_one_beta). For zi_poisson/zi_nbinom2, the same constant-vs-covariate mechanism mis-spec is NOT flat – power rises with n – but stays far below 0.8 even at n = 3000, so it is sample-size-limited in principle but impractical to detect at realistic sample sizes. A mean-structure diagnostic, not this one, is what catches an absorbed mis-specification.

Examples

set.seed(20260712)
n <- 60
x <- stats::rnorm(n)
dat <- data.frame(y = 0.5 + 0.8 * x + stats::rnorm(n), x = x)
fit <- drmTMB(bf(y ~ x, sigma ~ 1), family = gaussian(), data = dat)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  worm_plot(fit)
}