lmer                  package:lme4                  R Documentation

_F_i_t _M_i_x_e_d-_E_f_f_e_c_t_s _M_o_d_e_l_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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(), ...)

_A_r_g_u_m_e_n_t_s:

 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.

_D_e_t_a_i_l_s:

     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':

     _s_u_b_s_e_t 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.

     _n_a._a_c_t_i_o_n a function that indicates what should happen when the
          data contain 'NA's.  The default action ('na.fail') prints an
          error message and terminate if there are any incomplete
          observations.

     _c_o_n_t_r_o_l 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:

          '_m_s_V_e_r_b_o_s_e': a logical value passed as the 'trace' argument
               to 'nlminb' (see documentation on that function). 
               Default is 'getOption("verbose")'.

          '_m_a_x_I_t_e_r': a positive integer passed as the 'maxIter'
               argument to 'nlminb' (see documentation on that
               function).  Default is '300'.

          '_m_a_x_F_N': a positive integer specifying the maximum number of
               evaluations of the deviance function allowed during the
               optimization. Default is '900'.


     _m_o_d_e_l, _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'.

_V_a_l_u_e:

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

_S_e_e _A_l_s_o:

     The 'mer' class, 'lm'

_E_x_a_m_p_l_e_s:

     ## 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))
     ## nonlinear mixed models
     (nm1 <- nlmer(circumference ~ SSlogis(age, Asym, xmid, scal) ~ Asym|Tree,
                   Orange, start = c(Asym = 200, xmid = 725, scal = 350)))

