Nonlinear Least Squares Regression

DESCRIPTION:

Fits a nonlinear regression model via least squares. The errors are assumed Gaussian and independent with constant variance.

USAGE:

nls(formula, data, start=getInitial(formula, data), control=<<see below>>,
    algorithm="default", trace=F)

REQUIRED ARGUMENTS:

formula
a formula which specifies the nonlinear regression model. The right-hand side of the formula could be a self-starting function, see the DETAILS section below for a definition and a list of available self-starting functions in S-PLUS. See the DETAILS section also on using the plinear algorithm on the right hand side of the formula as another option for model specification.
data
data frame in which to do the computations. In addition to the usual data variables, the data frame may contain parameters. These are typically set by using the assignment form of the parameters or param functions. The parameters in a data frame are used to establish initial values for the parameters in the model.

OPTIONAL ARGUMENTS:

start
a list with named components or a numeric vector containing the starting values for the model parameters. Although start is optional, it is highly recommended for unambiguous specification of the parameters, unless the right-hand side of formula is a self-starting function. If start is omitted, S-PLUS assumes that any names in the model formula that are not variables in the data frame are parameters. For partial linear models (i.e., when algorithm="plinear"), initial values for only the nonlinear parameters should be supplied.

If the start argument includes a single initial value for each model parameter, it can be given as either a list or a numeric vector. To associate more than one initial value with each parameter, specify start as a list: for example, start = list(A = 2:22, B = 95, C = c(50,60)).

If a self-starting function, i.e. a function of class "selfStart", is given in formula, then its initial attribute is used to determine starting values. See the DETAILS section for more information on self-starting functions.
control
list of control values to be used in the iteration. See nls.control for the available control options, their default settings, and their effects on the fitting algorithm.
algorithm
character string naming the algorithm to use. The default is a Gauss-Newton algorithm. If algorithm="plinear", the Golub-Pereyra algorithm for partially linear least-squares models is used.
trace
logical flag or character string naming a tracing function. By default, trace=FALSE and no tracing is performed. If trace=TRUE, then the trace.nls function is used to trace. It is also possible to write and use your own tracing function; see trace.nls for the relevant arguments. Note, however, that trace.nls uses a special accumulation technique that depends on cooperation with nls. The accumulation technique is switched on only by setting trace=TRUE, and not by calling trace=trace.nls directly. For more details, see the SIDE EFFECTS section below.

VALUE:

object of class "nls", containing the parameters, residuals, fitted values, and other components of the model. See nls.object for details.

SIDE EFFECTS:

If trace=TRUE, the trace.nls function prints the convergence criterion and parameters at each iteration in the fitting algorithm. It also accumulates the corresponding information in a matrix, which is added to the fitted nls object as a "trace" component.

DETAILS:

The nls function tries to estimate parameters for a nonlinear model that minimize the sum of squared residuals.

For the default algorithm, the left side of formula is the response to be fitted, and the right side should evaluate to a numeric vector the same length as the response. If the value of the right side of the formula does not include a "gradient" attribute, numerical derivatives are used in the fitting algorithm. You can increase the computational speed and numerical accuracy of the algorithm by providing analytical derivatives instead, which is usually accomplished with the deriv function. If the value of the right side of formula has a "gradient" attribute, it should be a matrix in which the number of rows equals the length of the response, and there is one column for each of the parameters.

For certain types of models, the right side of the formula can also be a self-starting function, which algorithmically derives initial values for the parameters. Several self-starting functions are provided with S-PLUS. The user can also build a customized self-starting function by using the S-PLUS function selfStart. For more details, see the help files for the following functions: SSasymp , Asymptotic Regression, SSasympOff , Asymptotic Regression with an Offset, SSasympOrig , Asymptotic Regression through the Origin, SSbiexp , Bi-Exponential model, SSfol , First-order Compartment Model, SSfpl , Four-Parameter Logistic Model, SSlogis , Logistic Model, SSmicmen , Michaelis-Menten Model.

When there are linear and nonlinear parameters in the model, the "plinear" algorithm can be used. In this case, the right side of formula should evaluate to the derivative matrix for the linear parameters only, conditional on the nonlinear parameters. Alternatively, the derivative matrix can be given as a vector whose length is some multiple of the length of the response. If the value of the right side of the formula includes a "gradient" attribute, it should be a multidimensional array; the dimensions of the array are the number of observations, by number of linear parameters, by number of nonlinear parameters.

Caution is advised when calling nls with analytic gradients when only the right side of a formula is supplied. Although it might seem reasonable to define the gradient in this case as if the response was a vector of zeros, this assumption leads to incorrect results. The nls function assumes that the analytic gradient is that of the predictions, and is thus the negative gradient of the residuals.

REFERENCES:

Chambers, J.M. and Hastie, T.J. (Eds.) (1992). Statistical Models in S. Pacific Grove, CA.: Wadsworth & Brooks/Cole.

Pinheiro, J.C., and Bates, D.M. (2000). Mixed-Effects Models in S and S-PLUS. New York: Springer-Verlag.

Venables, W.N., and Ripley, B.D. (1999). Modern Applied Statistics with S-PLUS. New York: Springer-Verlag.

SEE ALSO:

, , , , , , , .

EXAMPLES:

# fit Michaelis and Menten's original data.
conc <- c(0.3330, 0.1670, 0.0833, 0.0416,
    0.0208, 0.0104, 0.0052)
vel <- c(3.636, 3.636, 3.236, 2.666, 2.114, 1.466, 0.866)
Micmen <- data.frame(conc=conc, vel=vel)
param(Micmen,"K") <- 0.02; param(Micmen,"Vm") <- 3.7
fit <- nls(vel~Vm*conc/(K+conc), data = Micmen)

# specify starting parameters for the Orange data.
nls(circumference ~ A/(1 + exp(-(age-B)/C)), data = Orange,
    start = list(A=150, B=600, C=400))

# use the logistic self-starting function instead.
nls(circumference ~ SSlogis(age, A, B, C), data = Orange)