HLMdiag (version 0.5.0)

hlm_resid.default: Calculating residuals from HLMs

Description

hlm_resid takes a hierarchical linear model fit as a lmerMod or lme object and extracts residuals and predicted values from the model, using Least Squares (LS) and Empirical Bayes (EB) methods. It then appends them to the model data frame in the form of a tibble inspired by the augment function in broom. This unified framework enables the analyst to more easily conduct an upward residual analysis during model exploration/checking.

Usage

# S3 method for default
hlm_resid(object, ...)
# S3 method for lmerMod
hlm_resid(
  object,
  level = 1,
  standardize = FALSE,
  include.ls = TRUE,
  data = NULL,
  ...
)
# S3 method for lme
hlm_resid(
  object,
  level = 1,
  standardize = FALSE,
  include.ls = TRUE,
  data = NULL,
  ...
)

Arguments

object

an object of class lmerMod or lme.

...

do not use

level

which residuals should be extracted: 1 for within-group (case-level) residuals, the name of a grouping factor for between-group residuals (as defined in flist in lmerMod objects or in groups in lme objects)

standardize

for any level, if standardize = TRUE the standardized residuals will be returned for any group; for level-1 only, if standardize = "semi" then the semi-standardized level-1 residuals will be returned

include.ls

a logical indicating if LS residuals be included in the return tibble. include.ls = FALSE decreases runtime substantially.

data

if na.action = na.exclude, the user must provide the data set used to fit the model, otherwise NULL.

Details

The hlm_resid function provides a wrapper that will extract residuals and predicted values from a fitted lmerMod or lme object. The function provides access to residual quantities already made available by the functions resid, predict, and ranef, but adds additional functionality. Below is a list of types of residuals and predicted values that are extracted and appended to the model data.

level-1 residuals

.resid and .fitted

Residuals calculated using the EB method (using maximum likelihood). Level-1 EB residuals are interrelated with higher level residuals. Equivalent to the residuals extracted by resid(object) and predict(object) respectively. When standardize = TRUE, residuals are standardized by sigma components of the model object.

.ls.resid and .ls.fitted

Residuals calculated calculated by fitting separate LS regression models for each group. Level-1 LS residuals are unconfounded by higher level residuals, but unreliable for small within-group sample sizes.

.mar.resid and .mar.fitted

Marginal residuals only consider the fixed effect portion of the estimates. Equivalent to resid(object, level=0) in nlme, not currently implemented within the lme4::resid function. When standardize = TRUE, Cholesky marginal residuals are returned.

higher-level residuals (random effects)

.ranef.var_name

The group level random effects using the EB method of estimating parameters. Equivalent to ranef(object) on the specified level. EB residuals are preferred at higher levels as LS residuals are dependent on a large sample size.

.ls.var_name

The group level random effects using the LS method of estimating parameters. Calculated using ranef on a lmList object to compare the random effects of individual models to the global model.

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.

David Robinson and Alex Hayes (2020). broom: Convert Statistical Analysis Objects into Tidy Tibbles. R package version 0.5.6. https://CRAN.R-project.org/package=broom

See Also

hlm_augment, resid, ranef

Examples

# NOT RUN {
data(sleepstudy, package = "lme4")
fm.lmer <- lme4::lmer(Reaction ~ Days + (Days|Subject), sleepstudy)
fm.lme <- nlme::lme(Reaction ~ Days, random = ~Days|Subject, sleepstudy)

# level-1 and marginal residuals
fm.lmer.res1 <- hlm_resid(fm.lmer) ## raw level-1 and mar resids
fm.lmer.res1
fm.lme.std1 <- hlm_resid(fm.lme, standardize = TRUE) ## std level-1 and mar resids
fm.lme.std1

# level-2 residuals
fm.lmer.res2 <- hlm_resid(fm.lmer, level = "Subject") ## level-2 ranefs
fm.lmer.res2
fm.lme.res2 <- hlm_resid(fm.lme, level = "Subject", include.ls = FALSE) ##level-2 ranef, no LS
fm.lme.res2
# }