gnls                  package:nlme                  R Documentation

Fit Nonlinear Model Using Generalized Least Squares

Description:

     This function fits a nonlinear model using generalized least
     squares. The errors are allowed to be correlated and/or have
     unequal variances.

Usage:

     gnls(model, data, params, start, correlation, weights, subset,
          na.action, naPattern, control, verbose)

Arguments:

   model: a two-sided formula object describing the model, with the
          response on the left of a '~' operator and  a nonlinear
          expression involving parameters and covariates on the right.
          If 'data' is given, all names used in the formula should be
          defined as parameters or variables in the data frame.

    data: an optional data frame containing the variables named in
          'model', 'correlation', 'weights',  'subset', and
          'naPattern'. By default the variables are  taken from the
          environment from which 'gnls' is called.

  params: an optional two-sided linear formula of the form
          'p1+...+pn~x1+...+xm', or list of two-sided formulas of the
          form 'p1~x1+...+xm', with possibly different models for each
          parameter. The 'p1,...,pn' represent parameters included on
          the right hand side of 'model' and 'x1+...+xm' define a
          linear model for the parameters (when the left hand side of
          the formula contains several parameters, they are all 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). By default, the parameters are
          obtained from the names of 'start'.

   start: an optional named list, or numeric vector, with the initial
          values for the parameters in 'model'. It can be omitted when
          a 'selfStarting' function is used in 'model', in which case
          the starting estimates will be obtained from a single call to
          the 'nls' function.

correlation: an optional 'corStruct' object describing the within-group
          correlation structure. See the documentation of 'corClasses'
          for a description of the available 'corStruct' classes. If a
          grouping variable is to be used, it must be specified in the
          'form' argument to the 'corStruct' constructor. Defaults to
          'NULL', corresponding to uncorrelated  errors.

 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 'varClasses' for a description of the
          available 'varFunc' classes. Defaults to 'NULL',
          corresponding to homoscesdatic errors.

  subset: an optional expression indicating which subset of the rows of
          'data' 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.

na.action: a function that indicates what should happen when the data
          contain 'NA's.  The default action ('na.fail') causes 'gnls'
          to print an error message 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 algorithm to
          replace the default values returned by the function
          'gnlsControl'. 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'.

     ...: some methods for this generic require additional arguments. 
          None are used in this method.

Value:

     an object of class 'gnls', also inheriting from class 'gls',
     representing the nonlinear model fit. Generic functions such as
     'print', 'plot' and  'summary' have methods to show the results of
     the fit. See 'gnlsObject' for the components of the fit. The
     functions 'resid', 'coef', and 'fitted' can be used to extract
     some of its components.

Author(s):

     Jose Pinheiro jose.pinheiro@pharma.novartis.com and Douglas Bates
     bates@stat.wisc.edu

References:

     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 models is presented in detail in Carrol, R.J. and
     Rupert, D. (1988) and 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. 

     Carrol, R.J. and Rupert, D. (1988) "Transformation and Weighting
     in Regression", Chapman and Hall.

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

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

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

     Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models in S
     and S-PLUS", Springer.

See Also:

     'corClasses', 'gnlsControl', 'gnlsObject', 'gnlsStruct',
     'predict.gnls', 'varClasses', 'varFunc'

Examples:

     # variance increases with a power of the absolute fitted values
     fm1 <- gnls(weight ~ SSlogis(Time, Asym, xmid, scal), Soybean,
                 weights = varPower())
     summary(fm1)

