nlsModel {nls} | R Documentation

## Create an nlsModel Object

### Description

This is the constructor for `nlsModel` objects, which are function closures for several functions in a list. The closure includes a nonlinear model formula, data values for the formula, as well as parameters and their values.

### Usage

    nlsModel(form, data, start)

### Arguments

`form` | a nonlinear model formula
`data` | a data frame or a list in which to evaluate the variables from the model formula
`start` | a named list or named numeric vector of starting estimates for the parameters in the model

### Details

An `nlsModel` object is primarily used within the `nls` function. It encapsulates the model, the data, and the parameters in an environment and provides several methods to access characteristics of the model. It forms an important component of the object returned by the `nls` function.

### Value

The value is a list of functions that share a common environment.

`resid` | returns the residual vector evaluated at the current parameter values
`fitted` | returns the fitted responses and their gradient at the current parameter values
`formula` | returns the model formula
`deviance` | returns the residual sum-of-squares at the current parameter values
`gradient` | returns the gradient of the model function at the current parameter values
`conv` | returns the relative-offset convergence criterion evaluated at the current parmeter values
`incr` | returns the parameter increment calculated according to the Gauss-Newton formula
`setPars` | a function with one argument, `pars`. It sets the parameter values for the `nlsModel` object and returns a logical value denoting a singular gradient array.
`getPars` | returns the current value of the model parameters as a numeric vector
`getAllPars` | returns the current value of the model parameters as a numeric vector
`getEnv` | returns the environment shared by these functions
`trace` | the function that is called at each iteration if tracing is enabled
`Rmat` | the upper triangular factor of the gradient array at the current parameter values
`predict` | takes as argument `newdata`,a `data.frame` and returns the predicted response for `newdata`.

### Author(s)

Douglas M. Bates and Saikat DebRoy

### References

Bates, D.M. and Watts, D.G. (1988), Nonlinear Regression Analysis and Its Applications, Wiley

### See Also

`nls`

### Examples

    library( nls )
    data( DNase )
    DNase1 <- DNase[ DNase$Run == 1, ]
    mod <-
     nlsModel(density ~ SSlogis( log(conc), Asym, xmid, scal ),
              DNase1, list( Asym = 3, xmid = 0, scal = 1 ))
    mod$getPars()     # returns the parameters as a list
    mod$deviance()    # returns the residual sum-of-squares
    mod$resid()       # returns the residual vector and the gradient
    mod$incr()        # returns the suggested increment
    mod$setPars( unlist(mod$getPars()) + mod$incr() )  # set new parameter values
    mod$getPars()     # check the parameters have changed
    mod$deviance()    # see if the parameter increment was successful
    mod$trace()       # check the tracing
    mod$Rmat()        # R matrix from the QR decomposition of the gradient