lmerTest (version 3.1-3)

lmerTest-package: lmerTest: Tests in Linear Mixed Effects Models

Description

The lmerTest package provides p-values in type I, II or III anova and summary tables for linear mixed models (lmer model fits cf. lme4) via Satterthwaite's degrees of freedom method; a Kenward-Roger method is also available via the pbkrtest package. Model selection and assessment methods include step, drop1, anova-like tables for random effects (ranova), least-square means (LS-means; ls_means) and tests of linear contrasts of fixed effects (contest).

Key Functions and Methods

lmer

overloads lme4::lmer and produced an object of class lmerModLmerTest which inherits from lmerMod. In addition to computing the model (using lme4::lmer), lmerTest::lmer computes a couple of components needed for the evaluation of Satterthwaite's denominator degrees of freedom.

anova

anova method for lmer model fits produces type I, II, and III anova tables for fixed-effect terms with Satterthwaite and Kenward-Roger methods for denominator degrees of freedom for F-tests.

summary

summary method for lmer model fits adds denominator degrees of freedom and p-values to the coefficient table.

ranova

anova-like table of random effects via likelihood ratio tests with methods for both lmerMod and lmerModLmerTest objects. ranova can either test reduction of random-effect terms to simpler structures or it can test removal of entire random-effect terms.

drop1

F-tests of fixed-effect terms using Satterthwaite or Kenward-Roger methods for denominator degrees of freedom. These 'single term deletion' tables are useful for model selection and tests of marginal terms. Compared to the likelihood ratio tests of lme4::drop1 the F-tests and p-values of lmerTest::drop1 are more accurate and considerably faster since no additional model fitting is required.

contest

tests of contrasts, i.e. tests of linear functions of the fixed-effect coefficients. A user-friendly interface for tests of contrasts with outputs either as a summary-like table of t-tests or an anova-like table of F-tests (or a list of either). Contrasts can optionally be tested for estimability. Contrasts are allowed to be rank-deficient as the rank is automatically detected and appropriate adjustments made. Methods for lmerModLmerTest as well as lmerMod objects -- the latter avoids the Satterthwaite specific computations when the Kenward-Roger method is used.

show_test

a function which operates on anova tables and LS-means tables makes it possible to see exactly which functions of the coefficients are being tested. This is helpful when differences between type I, II and III anova tables are being considered and discussed.

ls_means

computes the so-called least-squares means (classical Yates contrasts) as well as pairwise differences of these.

step

performs automatic backward model selection of fixed and random parts of the linear mixed model.

as_lmerModLmerTest

an explicit coerce function from class lmerMod to lmerModLmerTest.

Details

The computational approach is to let lmerTest::lmer compute the Hessian and derivatives needed for evaluation of degrees of freedom and t- and F-tests and to store these in the model object. The Hessian and derivatives are therefore computed only once per model fit and reused with each call to anova, summary, etc. Evaluation of t and F-tests does not involve model re-fitting.

lmerTest::lmer roughly amounts to calling lme4::lmer followed by lmerTest::as_lmerModLmerTest, so for computationally intensive model fits it can make sense to use lme4::lmer rather than lmerTest::lmer if computational time is an issue and summary tables and anova tables will not be needed.

References

Alexandra Kuznetsova, Per B. Brockhoff and Rune H. B. Christensen (2017) lmerTest Package: Tests in Linear Mixed Effects Models. Journal of Statistical Software, 82(13), 1--26. doi:10.18637/jss.v082.i13

Examples

# NOT RUN {
## load lmerTest package
library(lmerTest)

## Fit linear mixed model to the ham data:
fm <- lmer(Informed.liking ~ Gender + Information * Product + (1 | Consumer) +
             (1 | Consumer:Product), data=ham)

## Summary including coefficient table with p-values for t-statistics using
## Satterthwaite's method for denominator degrees of freedom:
summary(fm)

## Type III anova table with p-values for F-tests based on Satterthwaite's
## method:
(aov <- anova(fm))

## Inspect the contrast matrix for the Type III test of Product:
show_tests(aov, fractions = TRUE)$Product

## Choose type II anova table with Kenward-Roger method for the F-test:
# }
# NOT RUN {
if(requireNamespace("pbkrtest", quietly = TRUE))
  anova(fm, type=2, ddf="Kenward-Roger")
# }
# NOT RUN {
## Anova-like table of random-effect terms using likelihood ratio tests:
ranova(fm)

## F-tests of 'single term deletions' for all marginal terms:
drop1(fm)

## Least-Square means and pairwise differences:
(lsm <- ls_means(fm))
ls_means(fm, which = "Product", pairwise = TRUE)

## ls_means also have plot and as.data.frame methods:
# }
# NOT RUN {
plot(lsm, which=c("Product", "Information"))
as.data.frame(lsm)
## Inspect the LS-means contrasts:
show_tests(lsm, fractions=TRUE)$Product
# }
# NOT RUN {
## Contrast test (contest) using a custom contrast:
## Here we make the 2-df joint test of the main effects of Gender and Information
(L <- diag(length(fixef(fm)))[2:3, ])
contest(fm, L = L)

## backward elimination of non-significant effects:
step_result <- step(fm)

## Elimination tables for random- and fixed-effect terms:
step_result

# Extract the model that step found:
final_model <- get_model(step_result)

# }