nls {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

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

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

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

[Package Contents]