\HeaderA{nls}{Nonlinear Least Squares}{nls}
\keyword{nonlinear}{nls}
\keyword{regression}{nls}
\keyword{models}{nls}
\begin{Description}\relax
Determine the nonlinear (weighted) least-squares estimates of the
parameters of a nonlinear model.
\end{Description}
\begin{Usage}
\begin{verbatim}
nls(formula, data, start, control, algorithm,
    trace, subset, weights, na.action, model,
    lower, upper, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] a nonlinear model \LinkA{formula}{formula} including variables and
parameters.  Will be coerced to a formula if necessary.
\item[\code{data}] an optional data frame in which to evaluate the variables in
\code{formula}.  Can also be a list or an environment, but not a matrix.
\item[\code{start}] a named list or named numeric vector of starting
estimates.  Since R 2.4.0, when \code{start} is missing, a very
cheap guess for \code{start} is tried (if \code{algorithm != "plinear"}).

\item[\code{control}] an optional list of control settings.  See
\code{\LinkA{nls.control}{nls.control}} for the names of the settable control
values and their effect.
\item[\code{algorithm}] character string specifying the algorithm to use.
The default algorithm is a Gauss-Newton algorithm.  Other possible
values are \code{"plinear"} for the Golub-Pereyra algorithm for
partially linear least-squares models and \code{"port"} for the
\sQuote{nl2sol} algorithm from the Port package.
\item[\code{trace}] logical value indicating if a trace of the iteration
progress should be printed.  Default is \code{FALSE}.  If
\code{TRUE} the residual (weighted) sum-of-squares and the
parameter values are printed at the conclusion of each iteration.
When the \code{"plinear"} algorithm is used, the conditional
estimates of the linear parameters are printed after the nonlinear
parameters.  When the \code{"port"} algorithm is used the
objective function value printed is half the residual (weighted)
sum-of-squares.
\item[\code{subset}] an optional vector specifying a subset of observations
to be used in the fitting process.
\item[\code{weights}] an optional numeric vector of (fixed) weights.  When
present, the objective function is weighted least squares.
\item[\code{na.action}] a function which indicates what should happen
when the data contain \code{NA}s.  The default is set by
the \code{na.action} setting of \code{\LinkA{options}{options}}, and is
\code{\LinkA{na.fail}{na.fail}} if that is unset.  The \dQuote{factory-fresh}
default is \code{\LinkA{na.omit}{na.omit}}.  Value \code{\LinkA{na.exclude}{na.exclude}}
can be useful.
\item[\code{model}] logical.  If true, the model frame is returned as part of
the object. Default is \code{FALSE}.
\item[\code{lower, upper}] vectors of lower and upper bounds, replicated to
be as long as \code{start}.  If unspecified, all parameters are
assumed to be unconstrained.  Bounds can only be used with the
\code{"port"} algorithm.  They are ignored, with a warning, if given
for other algorithms.
\item[\code{...}] Additional optional arguments.  None are used at present.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
An \code{nls} object is a type of fitted model object.  It has methods
for the generic functions \code{\LinkA{anova}{anova}}, \code{\LinkA{coef}{coef}},
\code{\LinkA{confint}{confint}}, \code{\LinkA{deviance}{deviance}},
\code{\LinkA{df.residual}{df.residual}}, \code{\LinkA{fitted}{fitted}},
\code{\LinkA{formula}{formula}}, \code{\LinkA{logLik}{logLik}}, \code{\LinkA{predict}{predict}},
\code{\LinkA{print}{print}}, \code{\LinkA{profile}{profile}}, \code{\LinkA{residuals}{residuals}},
\code{\LinkA{summary}{summary}}, \code{\LinkA{vcov}{vcov}} and \code{\LinkA{weights}{weights}}.

Variables in \code{formula} are looked for first in \code{data}, then
the environment of \code{formula} and finally along the search path.
Functions in \code{formula} are searched for first in the environment
of \code{formula} and then along the search path.
\end{Details}
\begin{Value}
A list of
\begin{ldescription}
\item[\code{m}] an \code{nlsModel} object incorporating the model.
\item[\code{data}] the expression that was passed to \code{nls} as the data
argument.  The actual data values are present in the environment of
the \code{m} component.
\item[\code{call}] the matched call with several components, notably
\code{algorithm}.
\item[\code{na.action}] the \code{"na.action"} attribute (if any) of the
model frame.
\item[\code{dataClasses}] the \code{"dataClasses"} attribute (if any) of the
\code{"terms"} attribute of the model frame.
\item[\code{model}] if \code{model = TRUE}, the model frame.
\item[\code{weights}] if \code{weights} is supplied, the weights.
\item[\code{convInfo}] when \code{algorithm} is not "port", a list with
convergence information.
\item[\code{control}] the control \code{list} used, see the \code{control}
argument.
\item[\code{convergence, message}] for an \code{algorithm = "port"} fit only,
a convergence code (\code{0} for convergence) and message.

\end{ldescription}


\bold{Note} that setting \code{warnOnly = TRUE} in the \code{control}
argument (see \code{\LinkA{nls.control}{nls.control}}) returns a non-converged
object (since \R{} version 2.5.0) which might be useful for further
convergence analysis, \emph{but \bold{not} for inference}.
\end{Value}
\begin{Section}{Warning}
\bold{Do not use \code{nls} on artificial "zero-residual" data.}

The \code{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 \deqn{y=f(x,\theta)+\epsilon}{y = f(x, theta) + eps} (with
\code{var(eps) > 0}).  It fails to indicate convergence on data of the form
\deqn{y=f(x,\theta)}{y = f(x, theta)} because the criterion amounts to
comparing two components of the round-off error.  If you wish to test
\code{nls} on artificial data please add a noise component, as shown
in the example below.

The \code{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.
\end{Section}
\begin{Author}\relax
Douglas M. Bates and Saikat DebRoy
\end{Author}
\begin{References}\relax
Bates, D. M. and Watts, D. G. (1988)
\emph{Nonlinear Regression Analysis and Its Applications},
Wiley

Bates, D. M. and Chambers, J. M. (1992)
\emph{Nonlinear models.}
Chapter 10 of \emph{Statistical Models in S}
eds J. M. Chambers and T. J. Hastie, Wadsworth \& Brooks/Cole.

\url{http://netlib.bell-labs.com/netlib/port/} for the Port library
documentation.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{summary.nls}{summary.nls}}, \code{\LinkA{predict.nls}{predict.nls}},
\code{\LinkA{profile.nls}{profile.nls}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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),
                 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

    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 <- 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),
    trace = TRUE)
## Not run: 
## terminates in an error, because convergence cannot be confirmed:
nls(y ~ a + b*x, start = list(a = 0.12345, b = 0.54321),
     trace = TRUE)
## End(Not run)

## nls() internal very 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), trace=TRUE)

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)
\end{ExampleCode}
\end{Examples}

