nls                   package:nls                   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)

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.

Details:

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

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

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)

