

nlme(nlme)                                   R Documentation

_N_o_n_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 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.

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

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

_A_r_g_u_m_e_n_t_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 different parameters. The
          `f1,...,fn' are the names of parameters included
          on the  right hand side of `model' and the
          `x1+...+xm' expressions define linear models 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 sin-
          gle fixed effects for the corresponding parame-
          ter(s).

  random: optionally, any of the following: (i) a two-sided
          formula of the form `r1+...+rn~x1+...+xm |
          g1/.../gQ', with `r1,...,rn' naming parameters
          included on the right hand side of `model',
          `x1+...+xm' specifying the random-effects model
          for these parameters 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 random-
          effects models for different parameters, a `pdMat'
          object with a two-sided formula, or list of two-
          sided formulas (i.e. a non-`NULL' value for `for-
          mula(random)'), or a list of pdMat objects with
          two-sided formulas, or lists of two-sided formu-
          las. In this case, the grouping structure formula
          will be given in `groups', or derived from the
          data used to fit the nonlinear mixed-effects
          model, which should inherit from class  `grouped-
          Data',; (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 documentation 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'. An optional `random' component is 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 group-
          ing levels. 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 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 `"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'.

_V_a_l_u_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',
     `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 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. (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 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. (1996) "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_e_e _A_l_s_o_:

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

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

     library(nlme)
     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),
                 control = list(nlmStepMax = 1.0))
     ## 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))

