Calculating residuals from HLMs

HLMresid is a function that extracts residuals from a hierarchical linear model fit using lmer. That is, it is a unified framework that extracts/calculates residuals from mer or lmerMod objects.

# S3 method for default
HLMresid(object, ...)

# S3 method for mer
HLMresid(object, level, type = "EB", sim = NULL, standardize = FALSE, ...)

# S3 method for lmerMod
HLMresid(object, level, type = "EB", sim = NULL, standardize = FALSE, ...)

Arguments

object	an object of class mer or lmerMod.
...	do not use
level	which residuals should be extracted: 1 for within-group (case-level) residuals, the name of a grouping factor (as defined in flist of the mer object) for between-group residuals, or marginal.
type	how are the residuals predicted: either "EB" or "LS" (the default is "EB").
sim	optional argument giving the data frame used for LS residuals. This is used mainly for dealing with simulations.
standardize	if standardize = TRUE the standardized residuals will be returned; if standardize = "semi" then the semi-standardized level-1 residuals will be returned. Note that for higher-level residuals of type = "LS", standardize = TRUE does not result in standardized residuals as they have not been implemented.

Details

This function extracts residuals from the model, and can extract residuals estimated using least squares (LS) or Empirical Bayes (EB). This unified framework enables the analyst to more easily conduct an upward residual analysis during model exploration/checking.

The HLMresid function provides a wrapper that will extract residuals from a fitted mer or lmerMod object. The function provides access to residual quantities already made available by the functions resid and ranef, but adds additional functionality. Below is a list of types of residuals that can be extracted.

raw level-1 residuals

These are equivalent to the residuals extracted by resid if level = 1, type = "EB", and standardize = FALSE is specified. You can also specify type = "LS" for LS residuals that are not equivalent to those from resid.

standardized level-1 residuals

Specify level = 1, and standardize = TRUE. This works with both type = "EB" or "LS".

semi-standardized level-1 residuals

Specify level = 1, type = "LS" and standardize = "semi".

raw group level residuals

These are equivalent to extracting the predicted random effects for a given group using ranef. Set level to a grouping factor name and type = "EB". type = "LS" can also be specified, though this is less common.

standardized group level residuals

Set level to a grouping factor name, type = "EB", and standardized = TRUE. This will not produce standardized residuals for type = "LS".

marginal residuals

The marginal residuals can be obtained by setting level = "marginal". Only type = "EB" is implemented.

cholesky residuals

These are essentially standardized marginal residuals. To obtain cholesky residuals set level = "marginal", type = "EB", and standardize = TRUE.

Note that standardize = "semi" is only implemented for level-1 LS residuals.

References

Hilden-Minton, J. (1995) Multilevel diagnostics for mixed and hierarchical linear models. University of California Los Angeles.

Houseman, E. A., Ryan, L. M., & Coull, B. A. (2004) Cholesky Residuals for Assessing Normal Errors in a Linear Model With Correlated Outcomes. Journal of the American Statistical Association, 99(466), 383--394.

See also

LSresids, resid, ranef

Author

Adam Loy loyad01@gmail.com

Examples

if (FALSE) {
data(sleepstudy, package = "lme4")
fm1 <- lme4::lmer(Reaction ~ Days + (Days|Subject), sleepstudy)

# level-1 residuals
all.equal(HLMresid(object = fm1, level = 1, type = "EB"), resid(fm1)) ## EB
r1LS <- HLMresid(object = fm1, level = 1, type = "LS") ## raw LS resids
head(r1LS)
r1LS.std <- HLMresid(object = fm1, level = 1, type = "LS", standardize = TRUE) ## std. LS resids
head(r1LS.std)

# level-2 residuals
all.equal(r2EB <- HLMresid(object = fm1, level = "Subject", type = "EB"), 
                           lme4::ranef(fm1)[["Subject"]])
r2EB.std <- HLMresid(object = fm1, level = "Subject", type = "EB", standardize = TRUE)
head(r2EB)
head(r2EB.std)

# marginal residuals
mr <- HLMresid(object = fm1, level = "marginal")
cholr <- HLMresid(object = fm1, level = "marginal", standardize = TRUE) # Cholesky residuals
}