nls {stats} | R Documentation

## Nonlinear Least Squares

### Description

Determine the nonlinear (weighted) least-squares estimates of the parameters of a nonlinear model.

### 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`. Can also be a list or an environment, but not a matrix.
`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 (weighted) 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"` algorithm is used the objective function value printed is half the residual (weighted) 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.
`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` | vectors 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

An `nls` object is a type of fitted model object. It has methods for the generic functions `anova`, `coef`, `confint`, `deviance`, `df.residual`, `fitted`, `formula`, `logLik`, `predict`, `print`, `profile`, `residuals`, `summary`, `vcov` and `weights`.

Variables in `formula` are looked for first in `data`, then the environment of `formula` and finally along the search path. Functions in `formula` are searched for first in the environment of `formula` 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.
`call` | the matched call.
`na.action` | the `"na.action"` attribute (if any) of the model frame.
`dataClasses` | the `"dataClasses"` attribute (if any) of the `"terms"` attribute of the model frame.
`model` | if `model = TRUE`, the model frame.
`weights` | if `weights` is supplied, the weights.
`convergence, message` | for an `algorithm = "port"` fit only, a convergence code (always 0) and message.

### Warning

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.

The `algorithm = "port"` code appears unfinished, and does not even check that the starting value is within the bounds. Use with caution, especially where bounds are supplied.

### 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 documentation.

### See Also

`summary.nls`, `predict.nls`, `profile.nls`.

### 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 Port's 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)
    summary(Pur.wt)

    ## 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.3.1 Index]