nls {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, start, control, algorithm,
    trace, subset, weights, na.action, model,
    lower, upper, ...)

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. 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 NAs. 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.

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.

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.

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.

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

See Also

nlsModel

Examples

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)       

[Package stats version 2.2.1 Index]