Augment data with randomized quantile residuals

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, ...)

Arguments

x: Fitted model to obtain randomized quantile residuals from
...: Additional arguments to pass to broom::augment()

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.

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.

Implementation details

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

References

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