R: Fit Mixed-Effects Models

lmer {lme4}

R Documentation

Fit Mixed-Effects Models

Description

Fit a linear mixed model or a generalized linear mixed model or a nonlinear mixed model.

Usage

lmer(formula, data, family = NULL, REML = TRUE,
     control = list(), start = NULL, verbose = FALSE,
     doFit = TRUE, subset, weights, na.action, offset,
     contrasts = NULL, model = TRUE, x = TRUE, ...)
lmer2(formula, data, family = NULL, REML = TRUE,
      control = list(), start = NULL, verbose = FALSE,
      subset, weights, na.action, offset,
      contrasts = NULL, model = TRUE, x = TRUE, ...)
glmer(formula, data, family = gaussian, start = NULL,
      verbose = FALSE, nAGQ = 1, doFit = TRUE, subset, weights,
      na.action, offset, contrasts = NULL, model = TRUE,
      control = list(), ...)
nlmer(formula, data, start = NULL, verbose = FALSE, nAGQ = 1,
      doFit = TRUE, subset, weights, na.action,
      contrasts = NULL, model = TRUE, control = list(), ...)

Arguments

`formula`	a two-sided linear formula object describing the fixed-effects part of the model, with the response on the left of a `~` operator and the terms, separated by `+` operators, on the right. The vertical bar character `"\|"` separates an expression for a model matrix and a grouping factor.
`data`	an optional data frame containing the variables named in `formula`. By default the variables are taken from the environment from which `lmer` is called.
`family`	a GLM family, see `glm` and `family`. If `family` is missing then a linear mixed model is fit; otherwise a generalized linear mixed model is fit.
`REML`	logical argument to `lmer` only. Should the estimates be chosen to optimize the REML criterion (as opposed to the log-likelihood)? Defaults to `TRUE`.
`nAGQ`	a positive integer - the number of points per axis for evaluating the adaptive Gauss-Hermite approximation to the log-likelihood. This defaults to 1, corresponding to the Laplacian approximation. Values greater than 1 produce greater accuracy in the evaluation of the log-likelihood at the expense of speed.
`control`	a list of control parameters. See below for details.
`start`	a named list of starting values for the parameters in the model. If the list is of the same form as the `ST` slot, it is becomes the starting values of the `ST` slot. If the list contains components named `fixef` and/or `ST`, these are used as the starting values for those slots. (Setting starting values for `fixef` has no effect for a linear mixed model because the fixed-effects parameters do not appear in the profiled deviance.) In `lmer` and `glmer` a numeric `start` argument of the appropriate length is used as the starting value of the parameter vector that determines the `ST` slot. In `nlmer` a numeric `start` argument is used as the starting values of the `fixef` slot.
`doFit`	logical scalar. When `doFit = FALSE` the model is not fit but instead a structure with the model matrices for the random-effects terms is returned, so they can be modified for special model forms. When `doFit = TRUE`, the default, the model is fit immediately.
`subset, weights, na.action, offset, contrasts`	further model specification arguments as in `lm`; see there for details.
`model`	logical scalar. If `FALSE` the model frame in slot `frame` is truncated to zero rows.
`x`	logical scalar. If `FALSE` the model matrix in slot `X` is truncated to zero rows.
`verbose`	logical scalar. If `TRUE` verbose output is generated during the optimization of the parameter estimates.
`...`	other potential arguments. A `method` argument was used in earlier versions of the package. Its functionality has been replaced by the `REML` and `nAGQ` arguments.

Details

The lmer and glmer functions are nearly interchangeable. If lmer is called with a non-default family argument the call is replaced by a call to glmer with the current arguments. If glmer is called with the default family, namely the gaussian family with the identity link, then the call is replaced by a call to lmer with the current arguments. (They are described as “nearly” interchangeable because the REML argument only applies to calls to lmer and the nAGQ argument only applies to calls to glmer.)

Additional standard arguments to model-fitting functions can be passed to lmer or glmer or nlmer:

subset

an optional expression indicating the subset of the rows of data that should be used in the fit. This can be a logical vector, or a numeric vector indicating which observation numbers are to be included, or a character vector of the row names to be included. All observations are included by default.

na.action

a function that indicates what should happen when the data contain NAs. The default action (na.fail) prints an error message and terminate if there are any incomplete observations.

control

a named list of control parameters for the estimation algorithm, specifying only the ones to be changed from their default values. Hence defaults to an empty list.
Possible control options and their default values are:

msVerbose:: a logical value passed as the trace argument to nlminb (see documentation on that function). Default is getOption("verbose").
maxIter:: a positive integer passed as the maxIter argument to nlminb (see documentation on that function). Default is 300.
maxFN:: a positive integer specifying the maximum number of evaluations of the deviance function allowed during the optimization. Default is 900

model, x

logicals. If TRUE the corresponding components of the fit (the model frame, the model matrices) are returned.

The lmer2 name exists only for backwards compatibility. Calling this function simply produces an equivalent call to lmer.

Value

An object of class "mer", for which many methods are available. See there for details.

Examples

## linear mixed models
(fm1 <- lmer(Reaction ~ Days + (Days|Subject), sleepstudy))
(fm2 <- lmer(Reaction ~ Days + (1|Subject) + (0+Days|Subject), sleepstudy))
anova(fm1, fm2)
## generalized linear mixed model
(gm1 <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd),
              family = binomial, data = cbpp))
## GLMM with individual-level variability (accounting for overdispersion)
cbpp$obs <- 1:nrow(cbpp)
(gm2 <- glmer(cbind(incidence, size - incidence) ~ period +
    (1 | herd) +  (1|obs),
              family = binomial, data = cbpp))
anova(gm1,gm2)
## nonlinear mixed models
(nm1 <- nlmer(circumference ~ SSlogis(age, Asym, xmid, scal) ~ Asym|Tree,
              Orange, start = c(Asym = 200, xmid = 725, scal = 350)))

[Package lme4 version 0.999375-42 Index]