nlsModel                package:stats                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:

     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

