

   LLiinneeaarr MMiixxeedd--EEffffeeccttss MMooddeellss

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

   AArrgguummeenntts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 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 saying which subset of the
             rows of `data' should  be  used in the fit. This
             can be a logical vector, or a numeric vector indi-
             cating which observation numbers are to be
             included, or a  character  vector of the row names
             to be included.  All observations are included by
             default.

       REML: a logical value.  If `TRUE' the model is fit by
             maximizing the restricted log-likelihood.  If
             `FALSE' the log-likelihood is maximized.  Defaults
             to `FALSE'.

   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.

   DDeessccrriippttiioon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.

   VVaalluue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',
        code{fixed.effects}, and `random.effects'  can be used
        to extract some of its components.

   AAuutthhoorr((ss))::

        Jose Pinheiro and Douglas Bates

   RReeffeerreennccees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.
        (1997), 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. (1997) "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Seeee AAllssoo::

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

   EExxaammpplleess::

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

