nlmer                  package:lme4                  R Documentation

_F_i_t _N_o_n_l_i_n_e_a_r _M_i_x_e_d _M_o_d_e_l_s

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

     Fit a nonlinear mixed model with nested or crossed grouping
     factors for the random effects.

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

     nlmer(formula, data, control, start, verbose,
          subset, weights, na.action, contrasts,
          model, ...)

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

 formula: a three part formula object describing the response, the
          nonlinear model and the fixed and random effects in the
          model. In the fixed and random effects specification the
          vertical bar character '"|"' separates an expression for a
          model matrix and a grouping factor.  At present evaluation of
          the nonlinear model function must return a gradient
          attribute.

    data: an optional data frame containing the variables named in
          'formula'.  By default the variables are taken from the
          environment from which 'nlmer' is called.

 control: a list of control parameters. See below for details.

   start: a named numeric vector of starting values for the fixed
          effects parameters or a list that contains an element called
          '"fixef"' that has this form.  Optionally the list may
          contain an element called '"ST"' providing a starting value
          for the 'ST' slot.

 verbose: logical scalar - 'TRUE' indicates verbose output from the
          iterations during the optimization process (highly
          recommended when difficulties are encountered).  Default is
          'FALSE'.

subset, weights, na.action, 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 'nlme' 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'.

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


     _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 '"nlmer"'. There are many methods applicable to
     '"nlmer"' objects, see the above help page.

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

     The 'nlmer' class

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

     (fm1 <- lme4:::nlmer(circumference ~ SSlogis(age, Asym, xmid, scal) ~ Asym|Tree,
                         Orange, verb = 1,
                         start = c(Asym = 192.6872, xmid = 728.7544, scal = 353.5320)))
     (fm2 <- lme4:::nlmer(conc ~ SSfol(Dose, Time,lKe, lKa, lCl) ~ (lKe+lKa+lCl|Subject),
                         Theoph, start = c(lKe = -2.5, lKa = 0.5, lCl = -3), verb = 1))
     (fm3 <- lme4:::nlmer(conc ~ SSfol(Dose, Time,lKe, lKa, lCl) ~
                          (lKe|Subject) + (lKa|Subject) + (lCl|Subject), Theoph,
                          start = c(lKe = -2.5, lKa = 0.5, lCl = -3), verb = 1))
     (fm4 <- lme4:::nlmer(conc ~ SSfol(Dose, Time,lKe, lKa, lCl) ~
                          (lKa+lCl|Subject), Theoph,
                          start = c(lKe = -2.5, lKa = 0.5, lCl = -3), verb = 1))
     (fm5 <- lme4:::nlmer(conc ~ SSfol(Dose, Time,lKe, lKa, lCl) ~
                         (lKa|Subject) + (lCl|Subject), Theoph,
                         start = c(lKe = -2.5, lKa = 0.5, lCl = -3), verb = 1))

