lmer                  package:lme4                  R Documentation

_F_i_t (_G_e_n_e_r_a_l_i_z_e_d) _L_i_n_e_a_r _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 or generalized linear mixed-effects model with nested
     or crossed grouping factors for the random effects.

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

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

_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'.  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.

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

     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.

     The 'lmer2' function is a development version of 'lmer' that uses
     a modified internal representation of the model.  Typically
     'lmer2' is faster and more reliable than 'lmer'.  At present
     'lmer2' can only fit linear mixed-effects models (that is, the
     'family' argument must be left unspecified) and not all the
     methods for '"lmer"' objects are defined for '"lmer2"' objects. 
     In particular, there is no 'mcmcsamp' method for '"lmer2"'
     objects.

     When all the methods for the '"lmer"' objects and all the options
     for the 'lmer' function have been duplicated for the new
     representation, the new representation will replace the old one
     and the '"2"' will be dropped from the name.

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

     _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') causes
          'lme' to print 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_a_x_I_t_e_r': maximum number of iterations for the 'lme'
               optimization algorithm.  Default is 50.

          '_t_o_l_e_r_a_n_c_e': relative convergence tolerance for the 'lme'
               optimization algorithm.  Default is
               'sqrt(.Machine$double.eps)'.

          '_m_s_M_a_x_I_t_e_r': maximum number of iterations for the 'nlminb'
               optimization step inside the 'lme' optimization. 
               Default is 200.

          '_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")'.

          '_n_i_t_e_r_E_M': number of iterations for the EM algorithm used to
               refine the initial estimates of the random effects
               variance-covariance coefficients.  Default is 15.

          '_E_M_v_e_r_b_o_s_e': a logical value indicating if verbose output
               should be produced during the EM iterations.  Default is
               'getOption("verbose")'.

          '_P_Q_L_m_a_x_I_t': maximum number of iterations for the PQL
               algorithm when fitting generalized linear mixed models.
               Default is 30.

          '_u_s_e_P_Q_L': Should the PQL method be used before switching to
               general optimization when fitting generalized linear
               mixed models using 'method = "Laplace"'?  Default is
               'FALSE'.

          '_g_r_a_d_i_e_n_t': 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'.

          '_H_e_s_s_i_a_n': 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.


     _m_o_d_e_l, _x logicals.  If 'TRUE' the corresponding components of the
          fit (the model frame, the model matrices) are returned.

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

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

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

     The 'lmer' class, 'lm'

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

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

