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 = 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`.

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.

### 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)

    ## 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 Contents]