R: Standard 'nls' framework that uses 'nls.lm' for fitting

nlsLM {minpack.lm} | R Documentation

## Standard 'nls' framework that uses 'nls.lm' for fitting

### Description

`nlsLM` is a modified version of `nls` that uses `nls.lm` for fitting. Since an object of class 'nls' is returned, all generic functions such as `anova`, `coef`, `confint`, `deviance`, `df.residual`, `fitted`, `formula`, `logLik`, `predict`, `print`, `profile`, `residuals`, `summary`, `update`, `vcov` and `weights` are applicable.

### Usage

    nlsLM(formula, data = parent.frame(), start, jac = NULL,
          algorithm = "LM", control = nls.lm.control(),
          lower = NULL, upper = NULL, trace = FALSE, subset,
          weights, na.action, model = FALSE, ...)

### 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.
`jac` | A function to return the Jacobian.
`algorithm` | only method `"LM"` (Levenberg-Marquardt) is implemented.
`control` | an optional list of control settings. See `nls.lm.control` for the names of the settable control values and their effect.
`lower` | A numeric vector of lower bounds on each parameter. If not given, the default lower bound for each parameter is set to `-Inf`.
`upper` | A numeric vector of upper bounds on each parameter. If not given, the default upper bound for each parameter is set to `Inf`.
`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.
`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. See the `wfct` function for options for easy specification of weighting schemes.
`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. The ‘factory-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`.
`...` | Additional optional arguments. None are used at present.

### Details

The standard `nls` function was modified in several ways to incorporate the Levenberg-Marquardt type `nls.lm` fitting algorithm. The `formula` is transformed into a function that returns a vector of (weighted) residuals whose sum square is minimized by `nls.lm`. The optimized parameters are then transferred to `nlsModel` in order to obtain an object of class 'nlsModel'. The internal C function `C_nls_iter` and `nls_port_fit` were removed to avoid subsequent "Gauss-Newton", "port" or "plinear" types of optimization of `nlsModel`. Several other small modifications were made in order to make all generic functions work on the output.

### 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.
`convInfo` | a list with convergence information.
`control` | the control `list` used, see the `control` argument.
`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.

### Author(s)

Andrej-Nikolai Spiess and Katharine M. Mullen

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

J.J. More, "The Levenberg-Marquardt algorithm: implementation and theory," in Lecture Notes in Mathematics 630: Numerical Analysis, G.A. Watson (Ed.), Springer-Verlag: Berlin, 1978, pp. 105-116.

### See Also

`nls.lm`, `nls`, `nls.lm.control`, `optim`

### Examples

    ### Examples from 'nls' doc ###
    DNase1 <- subset(DNase, Run == 1)
    ## using a selfStart model
    fm1DNase1 <- nlsLM(density ~ SSlogis(log(conc), Asym, xmid, scal), DNase1)
    ## using logistic formula
    fm2DNase1 <- nlsLM(density ~ Asym/(1 + exp((xmid - log(conc))/scal)),
                     data = DNase1,
                     start = list(Asym = 3, xmid = 0, scal = 1))

    ## all generics are applicable
    coef(fm1DNase1)
    confint(fm1DNase1)
    deviance(fm1DNase1)
    df.residual(fm1DNase1)
    fitted(fm1DNase1)
    formula(fm1DNase1)
    logLik(fm1DNase1)
    predict(fm1DNase1)
    print(fm1DNase1)
    profile(fm1DNase1)
    residuals(fm1DNase1)
    summary(fm1DNase1)
    update(fm1DNase1)
    vcov(fm1DNase1)
    weights(fm1DNase1)

    ## weighted nonlinear regression using
    ## inverse squared variance of the response
    ## gives same results as original 'nls' function
    Treated <- Puromycin[Puromycin$state == "treated", ]
    var.Treated <- tapply(Treated$rate, Treated$conc, var)
    var.Treated <- rep(var.Treated, each = 2)
    Pur.wt1 <- nls(rate ~ (Vm * conc)/(K + conc), data = Treated,
                   start = list(Vm = 200, K = 0.1), weights = 1/var.Treated^2)
    Pur.wt2 <- nlsLM(rate ~ (Vm * conc)/(K + conc), data = Treated,
                   start = list(Vm = 200, K = 0.1), weights = 1/var.Treated^2)
    all.equal(coef(Pur.wt1), coef(Pur.wt2))

    ## 'nlsLM' can fit zero-noise data
    ## in contrast to 'nls'
    x <- 1:10
    y <- 2*x + 3
    ## Not run:
    nls(y ~ a + b * x, start = list(a = 0.12345, b = 0.54321))

    ## End(Not run)
    nlsLM(y ~ a + b * x, start = list(a = 0.12345, b = 0.54321))

    ### Examples from 'nls.lm' doc
    ## values over which to simulate data
    x <- seq(0,5, length = 100)
    ## model based on a list of parameters
    getPred <- function(parS, xx) parS$a * exp(xx * parS$b) + parS$c
    ## parameter values used to simulate data
    pp <- list(a = 9,b = -1, c = 6)
    ## simulated data with noise
    simDNoisy <- getPred(pp, x) + rnorm(length(x), sd = .1)
    ## make model
    mod <- nlsLM(simDNoisy ~ a * exp(b * x) + c,
                 start = c(a = 3, b = -0.001, c = 1),
                 trace = TRUE)
    ## plot data
    plot(x, simDNoisy, main = "data")
    ## plot fitted values
    lines(x, fitted(mod), col = 2, lwd = 2)

    ## create declining cosine
    ## with noise
    TT <- seq(0, 8, length = 501)
    tau <- 2.2
    N0 <- 1000
    a <- 0.25
    f0 <- 8
    Ndet <- N0 * exp(-TT/tau) * (1 + a * cos(f0 * TT))
    N <- Ndet +  rnorm(length(Ndet), mean = Ndet, sd = .01 * max(Ndet))
    ## make model
    mod <- nlsLM(N ~ N0 * exp(-TT/tau) * (1 + a * cos(f0 * TT)),
                 start = c(tau = 2.2, N0 = 1500, a = 0.25, f0 = 10),
                 trace = TRUE)

    ## plot data
    plot(TT, N, main = "data")
    ## plot fitted values
    lines(TT, fitted(mod), col = 2, lwd = 2)

[Package minpack.lm version 1.2-1 Index]