nls                  package:stats                  R Documentation

_N_o_n_l_i_n_e_a_r _L_e_a_s_t _S_q_u_a_r_e_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     nls(formula, data, start, control, algorithm,
         trace, subset, weights, na.action, model,
         lower, upper, ...)

_A_r_g_u_m_e_n_t_s:

 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. Other possible
          values are '"plinear"' for the Golub-Pereyra algorithm for
          partially linear least-squares models and '"port"' for the
          "nl2sol" algorithm from the Port package.

   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.  When
          the '"port"' algorithms are used the objective function value
          printed is half the residual sum-of-squares.

  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.  The default is set by the 'na.action' setting
          of 'options', and is 'na.fail' if that is unset.  The
          "factory-fresh" default is 'na.omit'.  Value 'na.exclude' can
          be useful.

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

lower, upper: vector of lower and upper bounds, replicated to be as
          long as 'start'.  If unspecified, all parameters are assumed
          to be unconstrained.  Bounds can only be used with the
          '"port"' algorithm.  They are ignored, with a warning, if
          given for other algorithms.

     ...: Additional optional arguments.  None are used at present.

_D_e_t_a_i_l_s:

     *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'.

     Variables in 'formula' are looked for first in 'data', then the
     environment of 'formula' (added in 1.9.1) and finally along the
     search path.  Functions in 'formula' are searched for first in the
     environment of 'formula' (added in 1.9.1) and then along the
     search path.

_V_a_l_u_e:

     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.

_A_u_t_h_o_r(_s):

     Douglas M. Bates and Saikat DebRoy

_R_e_f_e_r_e_n_c_e_s:

     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.

     <URL: http://netlib.bell-labs.com/netlib/port/> for the Port
     library

_S_e_e _A_l_s_o:

     'nlsModel'

_E_x_a_m_p_l_e_s:

     DNase1 <- subset(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 )
     ## using the nl2sol algorithm
     fm4DNase1 <- nls( density ~ Asym/(1 + exp((xmid - log(conc))/scal)),
                       data = DNase1,
                       start = list(Asym = 3, xmid = 0, scal = 1),
                       trace = TRUE, algorithm = "port")
     summary(fm4DNase1)

     ## weighted nonlinear regression
     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)

     ## The two examples below show that you can fit a model to
     ## artificial data with noise but not to artificial data
     ## without noise.
     x = 1:10
     y = x                                  # perfect fit
     yeps = y + rnorm(length(y), sd = 0.01) # added noise
     nls(yeps ~ a + b*x, start = list(a = 0.12345, b = 0.54321),
          trace = TRUE)
     ## Not run: 
     nls(y ~ a + b*x, start = list(a = 0.12345, b = 0.54321),
          trace = TRUE)
     ## End(Not run)       

