nls                  package:stats                  R Documentation

Nonlinear Least Squares

Description:

     Determine the nonlinear least-squares estimates of the nonlinear
     model parameters and return a class 'nls' object.

Usage:

     nls(formula, data = parent.frame(), start, control = nls.control(),
         algorithm = "default", trace = FALSE, subset,
         weights, na.action, model = FALSE)

Arguments:

 formula: a nonlinear model formula including variables and parameters

    data: an optional data frame in which to evaluate the variables in
          'formula'

   start: a named list or named numeric vector of starting estimates

 control: an optional list of control settings.  See 'nls.control' for
          the names of the settable control values and their effect.

algorithm: character string specifying the algorithm to use. The
          default algorithm is a Gauss-Newton algorithm. The other 
          alternative is "plinear", the Golub-Pereyra algorithm for
          partially linear least-squares models.

   trace: logical value indicating if a trace of the iteration progress
          should be printed.  Default is 'FALSE'.  If 'TRUE' the
          residual sum-of-squares and the parameter values are printed
          at the conclusion of each iteration.  When the '"plinear"'
          algorithm is used, the conditional estimates of the linear
          parameters are printed after the nonlinear parameters.

  subset: an optional vector specifying a subset of observations to be
          used in the fitting process.

 weights: an optional numeric vector of (fixed) weights.  When present,
          the objective function is weighted least squares. _not yet
          implemented_

na.action: a function which indicates what should happen when the data
          contain 'NA's.

   model: logical.  If true, the model frame is returned as part of the
          object.

Details:

     *Do not use 'nls' on artificial "zero-residual" data.*

     The 'nls' function uses a relative-offset convergence criterion
     that compares the numerical imprecision at the current parameter
     estimates to the residual sum-of-squares.  This performs well on
     data of the form 

                        y = f(x, theta) + eps

     (with 'var(eps) > 0').  It fails to indicate convergence on data
     of the form

                           y = f(x, theta)

     because the criterion amounts to comparing two components of the
     round-off error.  If you wish to test 'nls' on artificial data
     please add a noise component, as shown in the example below.

     An 'nls' object is a type of fitted model object.  It has methods
     for the generic functions 'coef', 'formula', 'resid', 'print',
     'summary', 'AIC', 'fitted' and 'vcov'.

Value:

     A list of 

       m: an 'nlsModel' object incorporating the model

    data: the expression that was passed to 'nls' as the data argument.
           The actual data values are present in the environment of the
          'm' component.

Author(s):

     Douglas M. Bates and Saikat DebRoy

References:

     Bates, D.M. and Watts, D.G. (1988) _Nonlinear Regression Analysis
     and Its Applications_, Wiley

     Bates, D. M. and Chambers, J. M. (1992) _Nonlinear models._
     Chapter 10 of _Statistical Models in S_ eds J. M. Chambers and T.
     J. Hastie, Wadsworth & Brooks/Cole.

See Also:

     'nlsModel'

Examples:

     data( DNase )
     DNase1 <- DNase[ DNase$Run == 1, ]
     ## using a selfStart model
     fm1DNase1 <- nls( density ~ SSlogis( log(conc), Asym, xmid, scal ), DNase1 )
     summary( fm1DNase1 )
     ## using conditional linearity
     fm2DNase1 <- nls( density ~ 1/(1 + exp(( xmid - log(conc) )/scal ) ),
                       data = DNase1,
                       start = list( xmid = 0, scal = 1 ),
                       alg = "plinear", trace = TRUE )
     summary( fm2DNase1 )
     ## without conditional linearity
     fm3DNase1 <- nls( density ~ Asym/(1 + exp(( xmid - log(conc) )/scal ) ),
                       data = DNase1,
                       start = list( Asym = 3, xmid = 0, scal = 1 ),
                       trace = TRUE )
     summary( fm3DNase1 )
     ## weighted nonlinear regression
     data(Puromycin)
     Treated <- Puromycin[Puromycin$state == "treated", ]
     weighted.MM <- function(resp, conc, Vm, K)
     {
         ## Purpose: exactly as white book p.451 -- RHS for nls()
         ##  Weighted version of Michaelis-Menten model
         ## ------------------------------------------------------------
         ## Arguments: 'y', 'x' and the two parameters (see book)
         ## ------------------------------------------------------------
         ## Author: Martin Maechler, Date: 23 Mar 2001, 18:48

         pred <- (Vm * conc)/(K + conc)
         (resp - pred) / sqrt(pred)
     }

     Pur.wt <- nls( ~ weighted.MM(rate, conc, Vm, K), data = Treated,
                   start = list(Vm = 200, K = 0.1),
                   trace = TRUE)

