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 TIBCO 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. TIBCO 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 TIBCO 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.
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:
- coef.nls
- deviance.nls
- df.residual.nls
- fitted.nls
- formula.nls
- logLik.nls
- predict.nls
- print.nls
- residuals.nls
-
summary.nls
- vcov.nls
- weights.nls
All of these are non-visible methods.
Currently, TIBCO 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.
See Also
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))