# lmer {lme4}

Fit Linear Mixed-Effects Models

### Description

Fit a linear mixed-effects model (LMM) to data, via REML or maximum likelihood.

### Usage

lmer(formula, data = NULL, REML = TRUE, control = lmerControl(), start = NULL, verbose = 0L, subset, weights, na.action, offset, contrasts = NULL, devFunOnly = FALSE, ...)

### Arguments

- formula
- a two-sided linear formula object describing both the fixed-effects and random-effects part of the model, with the response on the left of a
`~`

operator and the terms, separated by`+`

operators, on the right. Random-effects terms are distinguished by vertical bars (`|`

) separating expressions for design matrices from grouping factors. Two vertical bars (`||`

) can be used to specify multiple uncorrelated random effects for the same grouping variable. (Because of the way it is implemented, the`||`

-syntax*works only for design matrices containing numeric (continuous) predictors*; to fit models with independent categorical effects, see`dummy`

or the`lmer_alt`

function from the`afex`

package.) - 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. While`data`

is optional, the package authors*strongly*recommend its use, especially when later applying methods such as`update`

and`drop1`

to the fitted model (*such methods are not guaranteed to work properly if*). If`data`

is omitted`data`

is omitted, variables will be taken from the environment of`formula`

(if specified as a formula) or from the parent frame (if specified as a character vector). - REML
- logical scalar - Should the estimates be chosen to optimize the REML criterion (as opposed to the log-likelihood)?
- control
- a list (of correct class, resulting from
`lmerControl()`

or`glmerControl()`

respectively) containing control parameters, including the nonlinear optimizer to be used and parameters to be passed through to the nonlinear optimizer, see the`*lmerControl`

documentation for details. - start
- a named
`list`

of starting values for the parameters in the model. For`lmer`

this can be a numeric vector or a list with one component named`"theta"`

. - verbose
- integer scalar. If
`> 0`

verbose output is generated during the optimization of the parameter estimates. If`> 1`

verbose output is generated during the individual PIRLS steps. - 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. - weights
- an optional vector of ‘prior weights’ to be used in the fitting process. Should be
`NULL`

or a numeric vector. Prior`weights`

are*not*normalized or standardized in any way. In particular, the diagonal of the residual covariance matrix is the squared residual standard deviation parameter`sigma`

times the vector of inverse`weights`

. Therefore, if the`weights`

have relatively large magnitudes, then in order to compensate, the`sigma`

parameter will also need to have a relatively large magnitude. - na.action
- a function that indicates what should happen when the data contain
`NA`

s. The default action (`na.omit`

, inherited from the 'factory fresh' value of`getOption("na.action")`

) strips any observations with any missing values in any variables. - offset
- this can be used to specify an
*a priori*known component to be included in the linear predictor during fitting. This should be`NULL`

or a numeric vector of length equal to the number of cases. One or more`offset`

terms can be included in the formula instead or as well, and if more than one is specified their sum is used. See`model.offset`

. - contrasts
- an optional list. See the
`contrasts.arg`

of`model.matrix.default`

. - devFunOnly
- logical - return only the deviance evaluation function. Note that because the deviance function operates on variables stored in its environment, it may not return
*exactly*the same values on subsequent calls (but the results should always be within machine tolerance). - ...
- other potential arguments. A
`method`

argument was used in earlier versions of the package. Its functionality has been replaced by the`REML`

argument.

### Details

- If the
`formula`

argument is specified as a character vector, the function will attempt to coerce it to a formula. However, this is not recommended (users who want to construct formulas by pasting together components are advised to use`as.formula`

or`reformulate`

); model fits will work but subsequent methods such as`drop1`

,`update`

may fail. - When handling perfectly collinear predictor variables (i.e. design matrices of less than full rank),
`[gn]lmer`

is not quite as sophisticated as some simpler modeling frameworks such as`lm`

and`glm`

. While it does automatically drop collinear variables (with a message rather than a warning), it does not automatically fill in`NA`

values for the dropped coefficients; these can be added via`fixef(fitted.model,add.dropped=TRUE)`

. This information can also be retrieved via`attr(getME(fitted.model,"X"),"col.dropped")`

. - the deviance function returned when
`devFunOnly`

is`TRUE`

takes a single numeric vector argument, representing the`theta`

vector. This vector defines the scaled variance-covariance matrices of the random effects, in the Cholesky parameterization. For models with only simple (intercept-only) random effects,`theta`

is a vector of the standard deviations of the random effects. For more complex or multiple random effects, running`getME(.,"theta")`

to retrieve the`theta`

vector for a fitted model and examining the names of the vector is probably the easiest way to determine the correspondence between the elements of the`theta`

vector and elements of the lower triangles of the Cholesky factors of the random effects.

### Values

An object of class `merMod`

(more specifically, an object of *subclass* `lmerMod`

), for which many methods are available (e.g. `methods(class="merMod")`

)

### See Also

`lm`

for linear models; `glmer`

for generalized linear; and `nlmer`

for nonlinear mixed models.

### Examples

## linear mixed models - reference values from older code (fm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)) summary(fm1)# (with its own print method; see class?merMod % ./merMod-class.Rd str(terms(fm1)) stopifnot(identical(terms(fm1, fixed.only=FALSE), terms(model.frame(fm1)))) attr(terms(fm1, FALSE), "dataClasses") # fixed.only=FALSE needed for dataCl. fm1_ML <- update(fm1,REML=FALSE) (fm2 <- lmer(Reaction ~ Days + (Days || Subject), sleepstudy)) anova(fm1, fm2) sm2 <- summary(fm2) print(fm2, digits=7, ranef.comp="Var") # the print.merMod() method print(sm2, digits=3, corr=FALSE) # the print.summary.merMod() method (vv <- vcov.merMod(fm2, corr=TRUE)) as(vv, "corMatrix")# extracts the ("hidden") 'correlation' entry in @factors ## Fit sex-specific variances by constructing numeric dummy variables ## for sex and sex:age; in this case the estimated variance differences ## between groups in both intercept and slope are zero ... data(Orthodont,package="nlme") Orthodont$nsex <- as.numeric(Orthodont$Sex=="Male") Orthodont$nsexage <- with(Orthodont, nsex*age) lmer(distance ~ age + (age|Subject) + (0+nsex|Subject) + (0 + nsexage|Subject), data=Orthodont)

Documentation reproduced from package lme4, version 1.1-12. License: GPL (>= 2)