lmer {lme4}R Documentation

Fit (Generalized) Linear Mixed-Effects Models

Description

This generic function fits a linear mixed-effects model with nested or crossed grouping factors for the random effects.

Usage

lmer(formula, data, family, method, control, start,
     subset, weights, na.action, offset, contrasts,
     model, ...)

## S4 method for signature 'formula':
lmer(formula, data, family, method,
    control, start, subset, weights, na.action, offset, contrasts,
    model, ...)

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. If family is missing then a linear mixed model is fit; otherwise a generalized linear mixed model is fit.
method a character string. For a linear mixed model the default is "REML" indicating that the model should be fit by maximizing the restricted log-likelihood. The alternative is "ML" indicating that the log-likelihood should be maximized. (This method is sometimes called "full" maximum likelihood.) For a generalized linear mixed model the criterion is always the log-likelihood but this criterion does not have a closed form expression and must be approximated. The default approximation is "PQL" or penalized quasi-likelihood. Alternatives are "Laplace" or "AGQ" indicating the Laplacian and adaptive Gaussian quadrature approximations respectively. The "PQL" method is fastest but least accurate. The "Laplace" method is intermediate in speed and accuracy. The "AGQ" method is the most accurate but can be considerably slower than the others.
control a list of control parameters. See below for details.
start a list of relative precision matrices for the random effects. This has the same form as the slot "Omega" in a fitted model. Only the upper triangle of these symmetric matrices should be stored.
subset, weights, na.action, offset, contrasts further model specification arguments as in lm; see there for details.
model logical indicating if the model component should be returned (in slot frame).
... potentially further arguments for methods. Currently none are used.

Details

This is a revised version of the lme function from the nlme package. This version uses a different method of specifying random-effects terms and allows for fitting generalized linear mixed models as well as linear mixed models.

Additional standard arguments to model-fitting functions can be passed to lmer.

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) causes lme to print 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:
maxIter:
maximum number of iterations for the lme optimization algorithm. Default is 50.
tolerance:
relative convergence tolerance for the lme optimization algorithm. Default is sqrt(.Machine$double.eps).
msMaxIter:
maximum number of iterations for the nlminb optimization step inside the lme optimization. Default is 200.
msVerbose:
a logical value passed as the trace argument to nlminb (see documentation on that function). Default is getOption("verbose").
niterEM:
number of iterations for the EM algorithm used to refine the initial estimates of the random effects variance-covariance coefficients. Default is 15.
EMverbose:
a logical value indicating if verbose output should be produced during the EM iterations. Default is getOption("verbose").
PQLmaxIt:
maximum number of iterations for the PQL algorithm when fitting generalized linear mixed models. Default is 30.
usePQL:
Should the PQL method be used before switching to general optimization when fitting generalized linear mixed models using method = "Laplace"? Default is FALSE.
gradient:
a logical value indicating if the analytic gradient of the objective should be used. Use of an analytic gradient results in more stable convergence but can take longer. For models with multiple grouping factors the difference in time can be substantial. Default is TRUE.
Hessian:
a logical value indicating if the analytic Hessian of the objective should be calculated. This is an experimental feature and at present the default is FALSE. In the future we may use the analytic Hessian in the optimization.
model, x
logicals. If TRUE the corresponding components of the fit (the model frame, the model matrices) are returned.

Value

An object of class "lmer". There are many methods applicable to "lmer" objects, see the above help page.

See Also

The lmer class, lm

Examples

(fm1 <- lmer(Reaction ~ Days + (Days|Subject), sleepstudy))
(fm2 <- lmer(Reaction ~ Days + (1|Subject) + (0+Days|Subject), sleepstudy))
anova(fm1, fm2)

[Package lme4 version 0.9975-10 Index]