nls
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 = parent.frame(), start, control = nls.control(), 
    algorithm = c("default", "plinear", "port"), trace = FALSE, 
    subset, weights, na.action, model = FALSE, lower = -Inf, 
    upper = Inf, ...)

Arguments

formula a formula that specifies the nonlinear regression model. The right-hand side of the formula can be a self-starting function. See the DETAILS section for a definition and a list of available self-starting functions. 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 a data frame in which to do the computations. Alternatively, it can be a list or an environment.
start a list with named components or a numeric vector containing the starting values for the model parameters. Although start is optional, we highly recommend using it for unambiguous specification of the parameters, unless the right-hand side of formula is a self-starting function.
  • If you omit start, then the engine assumes that any names in the model formula that are not variables in the data frame are parameters. For partial linear models (that is, 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 formula is a self-starting function (that is, a function of class "selfStart"), then its initial attribute is used to determine starting values. See the DETAILS section for more information on self-starting functions.
control a list of control values to use in the iteration. See nls.control for the available control options, their default settings, and their effects on the fitting algorithm.
algorithm a character string naming the algorithm to use. It can be "default", "plinear", or "port". The default is a Gauss-Newton algorithm.
  • If algorithm is "plinear", the Golub-Pereyra algorithm for partially linear least-squares models is used.
  • If algorithm is "port", the Port algorithm from the Port library is used. See the references for more details about the Port library. Currently Spotfire Enterprise Runtime for R does not support the "port" algorithm, and a warning is generated if algorithm is "port".
trace a logical flag. If TRUE, tracing is performed, and some trace information is printed out. The default is FALSE.
subset an optional vector defining which subset of the data to use in the fitting process.
weights a numeric vector of weights for the fitting criterion. By default, all observations are weighted equally.
na.action a function to filter missing data (NAs).
model a logical flag. If TRUE, indicates that the model.frame is returned as the "model" component of the nls object. The default is FALSE. Spotfire Enterprise Runtime for R does not currently implement this argument.
lower, upper the vectors of lower and upper bounds for the parameters. Used only in the "port" algorithm. The default is "-Inf" and "+Inf", which means the parameters have no bounds and are not constrained. Currently Spotfire Enterprise Runtime for R does not support the "port" algorithm, and a warning is generated if these arguments are given.
... other arguments.

Details

The nls function tries to estimate the 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.
The following self-starting functions are provided; however, you can build a customized self-starting function by using the selfStart function.
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
For more details, see the help files for the above functions.
When the model has linear and nonlinear parameters, you can use the "plinear" algorithm. 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.
The nls class object has methods for the following generic functions: All of these are non-visible methods.
Currently, Spotfire Enterprise Runtime for R does not have methods for the generic functions anova.nls, confint.nls, and profile.nls.
Value
returns an object of class "nls" containing the following components:

m an object of class "nlsModel". This object contains a list of functions that can be called to extract residuals, fitted values, formula, and so on.
convInfo a list of convergence information, containing:
isConv a logical flag specifying if the algorithm converged.
finIter the final iteration number.
finTol the final tolerance.
stopCode the integer stop code.
stopMessage a character string containing the stop message.
data a substitution of the input argument data.
call the matched call and other components.
na.action the na.action attribute of the model frame.
weights optional. The weights if the input argument weights is specified.
control the control list of argument control.
References
Bates, D. M. and Watts, D. G. 1988. Nonlinear Regression Analysis and Its Applications. New York, NY: John Wiley & Sons.
Bates, D. M. and Chambers, J. M. 1992. Statistical Models in S. Pacific Grove, CA.: Wadsworth & Brooks/Cole.
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, NY: Springer.
Venables, W. N. and Ripley, B. D. 1999. Modern Applied Statistics with S-PLUS. Third Edition. New York, NY: Springer.
http://www.netlib.org/port/. for the Port library documentation.
See Also
lm, nls.control, deriv, selfStart
Examples
library(Sdatasets) # access Orange dataset used below

# 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)
fit <- nls(vel~Vm*conc/(K+conc), data = Micmen,
           start = list(K = 0.02, Vm = 3.7), 
           trace = TRUE, model = TRUE, weights = rep(1/7, 7))
names(fit$m)  # list elements of the nlsModel component

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

# use "plinear" algorithm
tDat <- data.frame(
    x = c(2.3, 3.2, 4.3, 5.3, 5.7, 6.3, 6.8, 9.6, 9.8, 10.7,
          12.7, 13.2, 13.4, 13.7, 14.5, 15.4, 16.5, 17, 17.1, 17.9),
    y = c(8.8, 9.6, 8, 4.2, 2.5, 0, -2, -7.1, -6.9, -4.9, 
          1.6, 2.8, 3.4, 3.8, 4.6, 4.1, 1.9, 0.7, 0.2, -1.8))
nls(y ~ cbind(sin(x * freq1), sin(x * freq2)), data=tDat,
    algorithm="plinear", start=list(freq1=0.5, freq2=0.3))
Package stats version 6.1.1-7
Package Index