qqnorm.brma creates a normal QQ plot for a fitted brma
object. The plot displays sorted standardized residuals on the vertical axis
against the theoretical quantiles of a standard normal distribution on the
horizontal axis. Under a correctly specified model, the points should fall
approximately along the diagonal reference line.
Usage
# S3 method for class 'brma'
qqnorm(
y,
type = "rstudent",
unit = "estimate",
conditioning_depth = "marginal",
envelope = TRUE,
conf_level = 95,
bonferroni = FALSE,
reps = 1000,
smooth = TRUE,
xlim,
ylim,
xlab,
ylab,
plot_type = "base",
max_samples = Inf,
...
)Arguments
- y
a fitted brma object.
- type
the type of standardized residuals to use. Options are:
"rstudent"(alias:"LOO-PIT"; default): Leave-one-out probability integral transform residuals. Works for normal outcome models, including selection models, and, as a descriptive normal approximation, for binomial and Poisson GLMMs. This is the recommended type for Bayesian models as it properly accounts for estimation uncertainty and leverage. Note: requires that loo has been computed (seeadd_loo)."rstandard": Internally standardized residuals using the hat matrix. Only available for normal outcome models without selection (weightfunction) bias adjustment.
- unit
output unit. Only
"estimate"is implemented currently.- conditioning_depth
residual conditioning depth. Options are
"marginal","cluster", and"estimate". It does not apply to LOO-PIT residuals, whose metadata record the deletion unit and retained context instead; leave it omitted for those residuals.- envelope
logical indicating whether to add a pseudo confidence envelope to the plot. The deterministic envelope uses Beta order-statistic quantiles transformed to the standard normal scale, providing a reference under a correctly specified model. Defaults to
TRUE.- conf_level
finite numeric value strictly between 0 and 100 specifying the confidence level for the envelope bounds. Defaults to
95.- bonferroni
logical indicating whether to apply Bonferroni correction to the envelope, so it can be regarded as a simultaneous confidence region for all \(k\) residuals. Defaults to
FALSE.- reps
retained for compatibility with earlier simulation-based envelopes. The current envelope is deterministic and does not use this argument.
- smooth
logical indicating whether to smooth the envelope bounds using Friedman's SuperSmoother (
supsmu). Defaults toTRUE.- xlim
x-axis limits. If not specified, limits are computed from data.
- ylim
y-axis limits. If not specified, limits are computed from data.
- xlab
title for the x-axis. If not specified, defaults to
"Theoretical Quantiles".- ylab
title for the y-axis. If not specified, defaults to
"Sample Quantiles".- plot_type
whether to use a base plot
"base"or ggplot2"ggplot"for plotting. Defaults to"base".- max_samples
maximum posterior draws used to compute known-
Vinternally standardized residuals. Defaults toInf. Finite values select draws deterministically and are ignored for other residual types.- ...
additional graphical arguments to customize the plot appearance:
- pch
point symbol (default: 21, filled circle)
- col
point border color (default: "black")
- bg
point fill/background color (default: "#A6A6A6")
- cex
point size multiplier for base graphics (default: 1)
- size
point size for ggplot2 (default: 2)
- shade
fill color for the envelope region (default: "grey90"). Set to
NAto suppress shading.- col.envelope
color for envelope boundary lines (default: "grey50")
- col.refline
color of the diagonal reference line (default: "black")
- main
character string for plot title (default: no title)
- as_data
if
TRUE, returns plot data instead of creating the plot
Value
For plot_type = "base", returns an invisible list with
components x (theoretical quantiles) and y (sorted
residuals). For plot_type = "ggplot", returns a ggplot object.
If as_data = TRUE, returns a list with all computed plot data
including: x, y, points, refline,
envelope, xlim, ylim, xlab, and ylab.
Details
The normal QQ plot is a diagnostic tool for assessing whether the standardized residuals follow a standard normal distribution, as expected under a correctly specified model. Each point represents one estimate, plotted at coordinates \((\Phi^{-1}(p_i), z_{(i)})\) where \(p_i\) are the plotting positions and \(z_{(i)}\) are the sorted standardized residuals. Each retained input row contributes one point, irrespective of its likelihood weight. Weights affect fitting and the residual calculation; they do not replicate points or multiply residual values in this plot.
The default residual type is "rstudent" (LOO-PIT), which differs
from metafor::qqnorm (which defaults to "rstandard").
LOO-PIT residuals are preferred for normal outcome models because they
properly account for
estimation uncertainty via leave-one-out cross-validation.
The confidence envelope is computed in closed form from the distribution of
normal order statistics. For the \(i\)-th sorted residual,
\(\Phi(Z_{(i)})\) follows a beta distribution with shape parameters
\(i\) and \(k + 1 - i\). Pointwise quantile bounds are transformed back
with \(\Phi^{-1}\). When smooth = TRUE, bounds are smoothed using
Friedman's SuperSmoother. When bonferroni = TRUE, the confidence
level is adjusted for simultaneous inference across all \(k\) comparisons.
For correlated known-V brma.mv() "rstandard" residuals,
this envelope remains an independent order-statistic reference band. It is
descriptive and does not model residual correlation induced by known sampling
covariance.
For binomial and Poisson GLMMs the LOO-PIT residuals are a descriptive normal
approximation on the effect-size scale rather than a PIT of the fitted
discrete likelihood (see residuals.brma); the default
y-axis label says so.
Examples
if (FALSE) { # \dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
data(dat.lehmann2018, package = "metadat")
fit <- brma(
yi = yi,
vi = vi,
data = dat.lehmann2018,
measure = "SMD",
seed = 1,
silent = TRUE
)
fit <- add_loo(fit)
qqnorm(fit)
qqnorm(fit, type = "rstandard")
qqnorm(fit, envelope = FALSE)
qqnorm(fit, plot_type = "ggplot")
qqnorm(fit, pch = 19, col = "blue", shade = "lightblue")
}
} # }