

lme(nlme)                                    R Documentation

_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_:

     This generic function fits a linear mixed-effects model
     in the formulation described in Laird and Ware (1982)
     but allowing for nested random effects. The within-
     group errors are allowed to be correlated and/or have
     unequal variances.

_U_s_a_g_e_:

     lme(fixed, data, random, correlation, weights, subset, method,
         na.action, control)

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

   fixed: 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, sepa-
          rated by `+' operators, on the right, an `lmList'
          object, or a `groupedData' object. The method
          functions `lme.lmList' and `lme.groupedData' are
          documented separately.

    data: an optional data frame containing the variables
          named in `fixed', `random', `correlation',
          `weights', and `subset'.  By default the variables
          are taken from the environment from which `lme' is
          called.

  random: optionally, any of the following: (i) a one-sided
          formula of the form `~x1+...+xn | g1/.../gm', with
          `x1+...+xn' specifying the model for the random
          effects and `g1/.../gm' the grouping structure
          (`m' may be equal to 1, in which case no `/' is
          required). The random effects formula will be
          repeated for all levels of grouping, in the case
          of multiple levels of grouping; (ii) a list of
          one-sided formulas of the form `~x1+...+xn | g',
          with possibly different random effects models for
          each grouping level. The order of nesting will be
          assumed the same as the order of the elements in
          the list; (iii) a one-sided formula of the form
          `~x1+...+xn', or a `pdMat' object with a formula
          (i.e. a non-`NULL' value for `formula(object)'),
          or a list of such formulas or `pdMat' objects. In
          this case, the grouping structure formula will be
          derived from the data used to fit the linear
          mixed-effects model, which should inherit from
          class `groupedData'; (iv) a named list of formulas
          or `pdMat' objects as in (iii), with the grouping
          factors as names. The order of nesting will be
          assumed the same as the order of the order of the
          elements in the list; (v) an `reStruct' object.
          See the documentation on `pdClasses' for a
          description of the available `pdMat' classes.
          Defaults to a formula consisting of the right hand
          side of `fixed'.

correlation: an optional `corStruct' object describing the
          within-group correlation structure. See the docu-
          mentation of `corClasses' for a description of the
          available `corStruct' classes. Defaults to `NULL',
          corresponding to no within-group correlations.

 weights: an optional `varFunc' object or one-sided formula
          describing the within-group heteroscedasticity
          structure. If given as a formula, it is used as
          the argument to `varFixed', corresponding to fixed
          variance weights. See the documentation on `var-
          Classes' for a description of the available `var-
          Func' classes. Defaults to `NULL', corresponding
          to homocesdatic within-group errors.

  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.

  method: a character string.  If `"REML"' the model is fit
          by maximizing the restricted log-likelihood.  If
          `"ML"' the log-likelihood is maximized.  Defaults
          to `"REML"'.

na.action: 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 observa-
          tions.

 control: a list of control values for the estimation algo-
          rithm to replace the default values returned by
          the function `lmeControl'.  Defaults to an empty
          list.

_V_a_l_u_e_:

     an object of class `lme' representing the linear mixed-
     effects model fit. Generic functions such as `print',
     `plot' and `summary' have methods to show the results
     of the fit. See `lmeObject' for the components of the
     fit. The functions `resid', `coef', `fitted',
     `fixed.effects', and `random.effects'  can be used to
     extract some of its components.

_A_u_t_h_o_r_(_s_)_:

     Jose Pinheiro and Douglas Bates

_R_e_f_e_r_e_n_c_e_s_:

     The computational methods are described in Bates, D.M.
     and Pinheiro (1998) and follow on the general framework
     of Lindstrom, M.J. and Bates, D.M. (1988). The model
     formulation is described in Laird, N.M. and Ware, J.H.
     (1982).  The variance-covariance parametrizations are
     described in <Pinheiro, J.C. and Bates., D.M.  (1996).
     The different correlation structures available for the
     `correlation' argument are described in Box, G.E.P.,
     Jenkins, G.M., and Reinsel G.C. (1994), Littel, R.C.,
     Milliken, G.A., Stroup, W.W., and Wolfinger, R.D.
     (1996), and Venables, W.N. and Ripley, B.D. (1997). The
     use of variance functions for linear and nonlinear
     mixed effects models is presented in detail in David-
     ian, M. and Giltinan, D.M. (1995).

     Bates, D.M. and Pinheiro, J.C. (1998) "Computational
     methods for multilevel models" available in PostScript
     or PDF formats at http://franz.stat.wisc.edu/pub/NLME/

     Box, G.E.P., Jenkins, G.M., and Reinsel G.C. (1994)
     "Time Series Analysis: Forecasting and Control", 3rd
     Edition, Holden-Day.

     Davidian, M. and Giltinan, D.M. (1995) "Nonlinear Mixed
     Effects Models for Repeated Measurement Data", Chapman
     and Hall.

     Laird, N.M. and Ware, J.H. (1982) "Random-Effects Mod-
     els for Longitudinal Data", Biometrics, 38, 963-974.

     Lindstrom, M.J. and Bates, D.M. (1988) "Newton-Raphson
     and EM Algorithms for Linear Mixed-Effects Models for
     Repeated-Measures Data", Journal of the American Sta-
     tistical Association, 83, 1014-1022.

     Littel, R.C., Milliken, G.A., Stroup, W.W., and Wolfin-
     ger, R.D. (1996) "SAS Systems for Mixed Models", SAS
     Institute.

     Pinheiro, J.C. and Bates., D.M.  (1996) "Unconstrained
     Parametrizations for Variance-Covariance Matrices",
     Statistics and Computing, 6, 289-296.

     Venables, W.N. and Ripley, B.D. (1997) "Modern Applied
     Statistics with S-plus", 2nd Edition, Springer-Verlag.

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

     `lmeControl', `lme.lmList', `lme.groupedData', `lmeOb-
     ject', `lmList', `reStruct', `reStruct', `varFunc',
     `pdClasses', `corClasses', `varClasses'

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

     library(nlme)
     data(Orthodont)
     fm1 <- lme(distance ~ age, data = Orthodont) # random is ~ age
     fm2 <- lme(distance ~ age + Sex, data = Orthodont, random = ~ 1)

