

   NNoonnl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

        nlme(model, data, fixed, random, groups, start, correlation, weights,
             subset, method, na.action, naPattern, control, verbose)

   AArrgguummeennttss::

      model: a nonlinear model formula, with the response on
             the left of a `~' operator and an expression
             involving parameters and covariates on the right,
             or an `nlsList' object.  If `data' is given, all
             names used in the formula should be defined as
             parameters or variables in the data frame. The
             method function `nlme.nlsList' is documented sepa-
             rately.

       data: an optional data frame containing the variables
             named in `model', `fixed', `random', `correla-
             tion', `weights', `subset', and `naPattern'.  By
             default the variables are taken from the environ-
             ment from which `nlme' is called.

      fixed: a two-sided linear formula of the form
             `f1+...+fn~x1+...+xm', or a list of two-sided for-
             mulas of the form `f1~x1+...+xm', with possibly
             different models for each fixed effect. The
             `f1,...,fn' represent fixed effects included on
             the right hand side of `model' and `x1+...+xm'
             define a linear model for these parameters (when
             the left hand side of the formula contains several
             parameters, they all are assumed to follow the
             same linear model, described by the right hand
             side expression). A `1' on the right hand side of
             the formula(s) indicates a single fixed effects
             for the corresponding parameter(s).

     random: optionally, any of the following: (i) a two-sided
             formula of the form `r1+...+rn~x1+...+xm |
             g1/.../gQ', with `r1,...,rn' representing random
             effects included on the right hand side of
             `model', `x1+...+xm' specifying the model for
             these random effects and `g1/.../gQ' the grouping
             structure (`Q' 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 two-
             sided formula of the form `r1+...+rn~x1+..+xm', a
             list of two-sided formulas of the form
             `r1~x1+...+xm', with possibly different models for
             each random effect, a `pdMat' object with a two-
             sided formula, or list of two-sided formulas (i.e.
             a non-`NULL' value for `formula(random)'), or a
             list of pdMat objects with two-sided formulas, or
             lists of two-sided formulas. In this case, the
             grouping structure formula will be given in
             `groups', or derived from the data used to to fit
             the nonlinear mixed-effects model, which should
             inherit from class  `groupedData',; (iii) a named
             list of formulas, lists of formulas, or `pdMat'
             objects as in (ii), 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; (iv) an `reStruct' object. See the docu-
             mentation on `pdClasses' for a description of the
             available `pdMat' classes. Defaults to `fixed',
             resulting in all fixed effects having also random
             effects.

     groups: an optional one-sided formula of the form `~g1'
             (single level of nesting) or `~g1/.../gQ' (multi-
             ple levels of nesting), specifying the partitions
             of the data over which the random effects vary.
             `g1,...,gQ' must evaluate to factors in `data'.
             The order of nesting, when multiple levels are
             present, is taken from left to right (i.e. `g1' is
             the first level, `g2' the second, etc.).

      start: an optional numeric vector, or list of initial
             estimates for the fixed effects and random
             effects. If declared as a numeric vector, it is
             converted internally to a list with a single com-
             ponent `fixed', given by the vector. The `fixed'
             component is required, unless the model function
             inherits from class `selfStart', in which case
             initial values will be derived from a call to
             `nlsList'. The `random' is optionally used to
             specify initial values for the random effects and
             should consist of a matrix, or a list of matrices
             with length equal to the number of grouping lev-
             els. Each matrix should have as many rows as the
             number of groups at the corresponding level and as
             many columns as the number of random effects in
             that level.

   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 homoscesdatic 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.

     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 `"ML"'.

   na.action: a function that indicates what should happen when
             the data contain `NA's.  The default action
             (`na.fail') causes `nlme' to print an error mes-
             sage and terminate if there are any incomplete
             observations.

   naPattern: an expression or formula object, specifying which
             returned values are to be regarded as missing.

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

    verbose: an optional logical value. If `TRUE' information
             on the evolution of the iterative algorithm is
             printed. Default is `FALSE'.

   DDeessccrriippttiioonn::

        This generic function fits a nonlinear mixed-effects
        model in the formulation described in Lindstrom and
        Bates (1990) 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 `nlme' representing the nonlinear
        mixed-effects model fit. Generic functions such as
        `print', `plot' and `summary' have methods to show the
        results of the fit. See `nlmeObject' 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 model formulation and computational methods are
        described in Lindstrom, M.J. and Bates, D.M. (1990).
        The variance-covariance parametrizations are described
        in Pinheiro, J.C. and Bates., D.M.  (1996).   The dif-
        ferent correlation structures available for the `corre-
        lation' 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 Davidian, M.
        and Giltinan, D.M. (1995).

        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.

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

        Lindstrom, M.J. and Bates, D.M. (1990) "Nonlinear Mixed
        Effects Models for Repeated Measures Data", Biometrics,
        46, 673-687.

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

        `nlmeControl', `nlme.nlsList', `nlmeObject', `nlsList',
        `reStruct', `varFunc', `pdClasses', `corClasses', `var-
        Classes'

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

        library(lme)
        data(Soybean)

        ## all parameters as fixed and random effects
        fm1 <- nlme(weight ~ SSlogis(Time, Asym, xmid, scal), data = Soybean,
                    fixed = Asym + xmid + scal ~ 1, start = c(18, 52, 7.5))
        ## only Asym and xmid as random, with a diagonal covariance
        fm2 <- nlme(weight ~ SSlogis(Time, Asym, xmid, scal), data = Soybean,
                    fixed = Asym + xmid + scal ~ 1, random = pdDiag(Asym + xmid ~ 1),
                    start = c(18, 52, 7.5))

