augment_quantile: Augment data with randomized quantile residuals

In regressinator: Simulate and Diagnose (Generalized) Linear Models

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

Arguments

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

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.

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.

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. \Sexpr[results=rd]{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()

regressinator documentation built on Sept. 11, 2024, 6:50 p.m.