regressinator (version 0.3.0)

augment_quantile: Augment data with randomized quantile residuals

Description

Generates a data frame containing a model's predictors, the residuals, and the randomized quantile residuals as additional columns.

Usage

augment_quantile(x, ...)
augment_quantile_longer(x, ...)

Value

Data frame with one row per observation used to fit x, including a .quantile.resid column containing the quantile residuals. See broom::augment() and its methods for details of other columns.

For augment_quantile_longer(), the output is in "long" format with one row per predictor per observation. Columns .predictor_name and .predictor_value identify the predictor and its value. An additional column .obs records the original observation numbers so results can be matched to observations in the original model data. See Limitations in augment_longer() for limitations on factor predictors.

Arguments

x

Fitted model to obtain randomized quantile residuals from

...

Additional arguments to pass to broom::augment()

Implementation details

Uses broom::augment() to generate the data frame, then uses the DHARMa package to generate randomized quantile residuals for the model.

Details

Randomized quantile residuals provide more interpretable residuals for generalized linear models (GLMs), such as logistic regression. See Dunn and Smyth (1996) for details, or review the examples provided in vignette("DHARMa", package="DHARMa").

Let \(F_Y(y; x, \beta)\) be the predicted cumulative distribution function for \(Y\) when \(X = x\), using the fitted GLM. When the response is continuous, the randomized quantile residual for observation \(i\) is

$$r_{q,i} = F_Y(y_i; x_i, \hat \beta).$$

When the response is discrete, let

$$a_i = \lim_{y \uparrow y_i} F_Y(y; x_i, \hat \beta)$$

and

$$b_i = F_Y(y_i; x_i, \hat \beta),$$

then draw the randomized quantile residual as

$$r_{q,i} \sim \text{Uniform}(a_i, b_i).$$

As cumulative distributions are left-continuous, this "jitters" the values between the discrete steps, resulting in a residual that is uniformly distributed when the model is correct.

Some definitions of randomized quantile residuals transform the resulting values using the standard normal inverse cdf, so they are normally distributed. That step is omitted here, as uniform residuals are easy to work with.

References

Dunn, Peter K., and Gordon K. Smyth (1996). "Randomized Quantile Residuals." Journal of Computational and Graphical Statistics 5 (3): 236–44. tools:::Rd_expr_doi("10.2307/1390802")

See Also

vignette("logistic-regression-diagnostics") and vignette("other-glm-diagnostics") for examples of plotting and interpreting randomized quantile residuals; augment_longer(); broom::augment()

Examples

# A simple bivariate setting where the model is misspecified:
logistic_pop <- population(
  x1 = predictor(rnorm, mean = 0, sd = 10),
  x2 = predictor(runif, min = 0, max = 10),
  y = response(0.7 + 0.2 * x1 + x1^2 / 100 - 0.2 * x2,
               family = binomial(link = "logit"))
)

logistic_data <- sample_x(logistic_pop, n = 100) |>
  sample_y()

# Note the true relationship with x1 is quadratic, but only a linear
# model (in the log-odds) is fit:
fit <- glm(y ~ x1 + x2, data = logistic_data, family = binomial)

# Randomized quantile residuals:
augment_quantile(fit)

# In long format, they can be plotted against both predictors,
# revealing a quadratic trend in x1:
library(ggplot2)
augment_quantile_longer(fit) |>
  ggplot(aes(x = .predictor_value, y = .quantile.resid)) +
  geom_point() +
  geom_smooth() +
  facet_wrap(vars(.predictor_name), scales = "free_x") +
  labs(x = "Predictor value", y = "Randomized quantile residual")