lme4_tidiers: Tidying methods for mixed effects models

In broom.mixed: Tidying Methods for Mixed Models

Tidying methods for mixed effects models

Description

These methods tidy the coefficients of lme4::lmer and lme4::glmer models (i.e., merMod objects). Methods are also provided for allFit objects.

Usage

## S3 method for class 'merMod'
tidy(
  x,
  effects = c("ran_pars", "fixed"),
  scales = NULL,
  exponentiate = FALSE,
  exponentiate_ran_coefs = FALSE,
  ran_prefix = NULL,
  conf.int = FALSE,
  conf.level = 0.95,
  conf.method = "Wald",
  ddf.method = NULL,
  profile = NULL,
  debug = FALSE,
  ...
)

## S3 method for class 'rlmerMod'
tidy(
  x,
  effects = c("ran_pars", "fixed"),
  scales = NULL,
  exponentiate = FALSE,
  exponentiate_ran_coefs = FALSE,
  ran_prefix = NULL,
  conf.int = FALSE,
  conf.level = 0.95,
  conf.method = "Wald",
  ddf.method = NULL,
  profile = NULL,
  debug = FALSE,
  ...
)

## S3 method for class 'merMod'
augment(x, data = stats::model.frame(x), newdata, ...)

## S3 method for class 'merMod'
glance(x, ...)

Arguments

x	An object of class merMod, such as those from lmer, glmer, or nlmer
effects	A character vector including one or more of "fixed" (fixed-effect parameters); "ran_pars" (variances and covariances or standard deviations and correlations of random effect terms); "ran_vals" (conditional modes/BLUPs/latent variable estimates); or "ran_coefs" (predicted parameter values for each group, as returned by coef.merMod)
scales	scales on which to report the variables: for random effects, the choices are ‘"sdcor"’ (standard deviations and correlations: the default if scales is NULL) or ‘"vcov"’ (variances and covariances). NA means no transformation, appropriate e.g. for fixed effects.
exponentiate	whether to exponentiate the fixed-effect coefficient estimates and confidence intervals (common for logistic regression); if TRUE, also scales the standard errors by the exponentiated coefficient, transforming them to the new scale
exponentiate_ran_coefs	whether to exponentiate the predicted paramater values for each group
ran_prefix	a length-2 character vector specifying the strings to use as prefixes for self- (variance/standard deviation) and cross- (covariance/correlation) random effects terms
conf.int	whether to include a confidence interval
conf.level	confidence level for CI
conf.method	method for computing confidence intervals (see lme4::confint.merMod)
ddf.method	the method for computing the degrees of freedom and t-statistics (only applicable when using the lmerTest package: see summary.lmerModLmerTest
profile	pre-computed profile object, for speed when using conf.method="profile"
debug	print debugging output?
...	Additional arguments (passed to confint.merMod for tidy; augment_columns for augment; ignored for glance)
data	original data this was fitted on; if not given this will attempt to be reconstructed
newdata	new data to be used for prediction; optional

Details

When the modeling was performed with na.action = "na.omit" (as is the typical default), rows with NA in the initial data are omitted entirely from the augmented data frame. When the modeling was performed with na.action = "na.exclude", one should provide the original data as a second argument, at which point the augmented data will contain those rows (typically with NAs in place of the new columns). If the original data is not provided to augment and na.action = "na.exclude", a warning is raised and the incomplete rows are dropped.

Value

All tidying methods return a data.frame without rownames. The structure depends on the method chosen.

tidy returns one row for each estimated effect, either with groups depending on the effects parameter. It contains the columns

group	the group within which the random effect is being estimated: "fixed" for fixed effects
level	level within group (NA except for modes)
term	term being estimated
estimate	estimated coefficient
std.error	standard error
statistic	t- or Z-statistic (NA for modes)
p.value	P-value computed from t-statistic (may be missing/NA)

augment returns one row for each original observation, with columns (each prepended by a .) added. Included are the columns

.fitted	predicted values
.resid	residuals
.fixed	predicted values with no random effects

Also added for "merMod" objects, but not for "mer" objects, are values from the response object within the model (of type lmResp, glmResp, nlsResp, etc). These include ".mu", ".offset", ".sqrtXwt", ".sqrtrwt", ".eta".

glance returns one row with the columns

nobs	the number of observations
sigma	the square root of the estimated residual variance
logLik	the data's log-likelihood under the model
AIC	the Akaike Information Criterion
BIC	the Bayesian Information Criterion
deviance	deviance

See Also

na.action

Examples

if (require("lme4")) {
    ## original model
    ## Not run: 
        lmm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
    
## End(Not run)
    ## load stored object
    load(system.file("extdata", "lme4_example.rda", package="broom.mixed"))
    (tt <- tidy(lmm1))
    tidy(lmm1, effects = "fixed")
    tidy(lmm1, effects = "fixed", conf.int=TRUE)
    tidy(lmm1, effects = "fixed", conf.int=TRUE, conf.method="profile")
    ## lmm1_prof <- profile(lmm1) # generated by extdata/runexamples
    tidy(lmm1, conf.int=TRUE, conf.method="profile", profile=lmm1_prof)
    ## conditional modes (group-level deviations from population-level estimate)
    tidy(lmm1, effects = "ran_vals", conf.int=TRUE)
    ## coefficients (group-level estimates)
    (rcoef1 <- tidy(lmm1, effects = "ran_coefs"))
    if (require(tidyr) && require(dplyr)) {
       ## reconstitute standard coefficient-by-level table
       spread(rcoef1,key=term,value=estimate)
       ## split ran_pars into type + term; sort fixed/sd/cor
       (tt %>% separate(term,c("type","term"),sep="__",fill="left")
           %>% arrange(!is.na(type),desc(type)))
    }
    head(augment(lmm1, sleepstudy))
    glance(lmm1)

    glmm1 <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd),
                  data = cbpp, family = binomial)
    tidy(glmm1)
    tidy(glmm1,exponentiate=TRUE)
    tidy(glmm1, effects = "fixed")
    ## suppress warning about influence.merMod
    head(suppressWarnings(augment(glmm1, cbpp)))
    glance(glmm1)

    startvec <- c(Asym = 200, xmid = 725, scal = 350)
    nm1 <- nlmer(circumference ~ SSlogis(age, Asym, xmid, scal) ~ Asym|Tree,
                  Orange, start = startvec)
    ## suppress warnings about var-cov matrix ...
    op <- options(warn=-1)
    tidy(nm1)
    tidy(nm1, effects = "fixed")
    options(op)
    head(augment(nm1, Orange))
    glance(nm1)
    detach("package:lme4")
}
if (require("lmerTest")) {
   lmm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
   tidy(lmm1)
   glance(lmm1)
   detach("package:lmerTest")  # clean up
}

broom.mixed documentation built on Oct. 16, 2024, 1:06 a.m.