# nls

##### Nonlinear Least Squares

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

- Keywords
- models, regression, nonlinear

##### 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. Will be coerced to a formula if necessary.
- data
- an optional data frame in which to evaluate the variables in
`formula`

and`weights`

. Can also be a list or an environment, but not a matrix. - start
- a named list or named numeric vector of starting
estimates. When
`start`

is missing, a very cheap guess for`start`

is tried (if`algorithm != "plinear"`

). - 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 thenl2sol algorithm from the Port library -- see the references. Can be abbreviated. - 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. Thefactory-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`

(and `weights`

if not missing) 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.

Arguments `subset`

and `na.action`

are supported only when
all the variables in the formula taken from `data`

are of the
same length: other cases give a warning.

Note that the `anova`

method does not check that the
models are nested: this cannot easily be done automatically, so use
with care.

##### 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 with several components, notably `algorithm`

.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.convInfo a list with convergence information. control the control `list`

used, see the`control`

argument.convergence, message for an `algorithm = "port"`

fit only, a convergence code (`0`

for convergence) and message.To use these is

*deprecated*, as they are available from`convInfo`

now.

##### Note

Setting `warnOnly = TRUE`

in the `control`

argument (see `nls.control`

) returns a non-converged
object (since Rversion 2.5.0) which might be useful for further
convergence analysis, *but not for inference*.

##### 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) + \epsilon$$ (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.

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

`summary.nls`

, `predict.nls`

,
`profile.nls`

.

Self starting models (with `selfStart`

.

##### Examples

`library(stats)`

```
<testonly>od <- options(digits=5)</testonly>
require(graphics)
DNase1 <- subset(DNase, Run == 1)
## using a selfStart model
fm1DNase1 <- nls(density ~ SSlogis(log(conc), Asym, xmid, scal), DNase1)
summary(fm1DNase1)
## the coefficients only:
coef(fm1DNase1)
## including their SE, etc:
coef(summary(fm1DNase1))
## using conditional linearity
fm2DNase1 <- nls(density ~ 1/(1 + exp((xmid - log(conc))/scal)),
data = DNase1,
start = list(xmid = 0, scal = 1),
algorithm = "plinear")
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))
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),
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
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))
summary(Pur.wt)
## Passing arguments using a list that can not be coerced to a data.frame
lisTreat <- with(Treated,
list(conc1 = conc[1], conc.1 = conc[-1], rate = rate))
weighted.MM1 <- function(resp, conc1, conc.1, Vm, K)
{
conc <- c(conc1, conc.1)
pred <- (Vm * conc)/(K + conc)
(resp - pred) / sqrt(pred)
}
Pur.wt1 <- nls( ~ weighted.MM1(rate, conc1, conc.1, Vm, K),
data = lisTreat, start = list(Vm = 200, K = 0.1))
stopifnot(all.equal(coef(Pur.wt), coef(Pur.wt1)))
## Chambers and Hastie (1992) Statistical Models in S (p. 537):
## If the value of the right side [of formula] has an attribute called
## 'gradient' this should be a matrix with the number of rows equal
## to the length of the response and one column for each parameter.
weighted.MM.grad <- function(resp, conc1, conc.1, Vm, K)
{
conc <- c(conc1, conc.1)
K.conc <- K+conc
dy.dV <- conc/K.conc
dy.dK <- -Vm*dy.dV/K.conc
pred <- Vm*dy.dV
pred.5 <- sqrt(pred)
dev <- (resp - pred) / pred.5
Ddev <- -0.5*(resp+pred)/(pred.5*pred)
attr(dev, "gradient") <- Ddev * cbind(Vm = dy.dV, K = dy.dK)
dev
}
Pur.wt.grad <- nls( ~ weighted.MM.grad(rate, conc1, conc.1, Vm, K),
data = lisTreat, start = list(Vm = 200, K = 0.1))
rbind(coef(Pur.wt), coef(Pur.wt1), coef(Pur.wt.grad))
## In this example, there seems no advantage to providing the gradient.
## In other cases, there might be.
## 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 <- 2*x + 3 # 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))
## terminates in an error, because convergence cannot be confirmed:
try(nls(y ~ a + b*x, start = list(a = 0.12345, b = 0.54321)))
## the nls() internal cheap guess for starting values can be sufficient:
x <- -(1:100)/10
y <- 100 + 10 * exp(x / 2) + rnorm(x)/10
nlmod <- nls(y ~ Const + A * exp(B * x))
plot(x,y, main = "nls(*), data, true function and fit, n=100")
curve(100 + 10 * exp(x / 2), col = 4, add = TRUE)
lines(x, predict(nlmod), col = 2)
## The muscle dataset in MASS is from an experiment on muscle
## contraction on 21 animals. The observed variables are Strip
## (identifier of muscle), Conc (Cacl concentration) and Length
## (resulting length of muscle section).
utils::data(muscle, package = "MASS")
## The non linear model considered is
## Length = alpha + beta*exp(-Conc/theta) + error
## where theta is constant but alpha and beta may vary with Strip.
with(muscle, table(Strip)) # 2, 3 or 4 obs per strip
## We first use the plinear algorithm to fit an overall model,
## ignoring that alpha and beta might vary with Strip.
musc.1 <- nls(Length ~ cbind(1, exp(-Conc/th)), muscle,
start = list(th = 1), algorithm = "plinear")
summary(musc.1)
## Then we use nls' indexing feature for parameters in non-linear
## models to use the conventional algorithm to fit a model in which
## alpha and beta vary with Strip. The starting values are provided
## by the previously fitted model.
## Note that with indexed parameters, the starting values must be
## given in a list (with names):
b <- coef(musc.1)
musc.2 <- nls(Length ~ a[Strip] + b[Strip]*exp(-Conc/th), muscle,
start = list(a = rep(b[2], 21), b = rep(b[3], 21), th = b[1]))
summary(musc.2)
<testonly>options(od)</testonly>
```

*Documentation reproduced from package stats, version 3.3, License: Part of R 3.3*