nlsModel                package:stats                R Documentation

_C_r_e_a_t_e _a_n _n_l_s_M_o_d_e_l _O_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     nlsModel(form, data, start)

_A_r_g_u_m_e_n_t_s:

    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

_D_e_t_a_i_l_s:

     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.

     See 'nls' for where elements of the formula 'form' are looked for.
      In normal use all the variables will be in 'data'.

_V_a_l_u_e:

     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, which
          contains copies of all the variables in 'data' and has as
          parent the environment of 'form'.

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

_A_u_t_h_o_r(_s):

     Douglas M. Bates and Saikat DebRoy

_R_e_f_e_r_e_n_c_e_s:

     Bates, D.M. and Watts, D.G. (1988), _Nonlinear Regression Analysis
     and Its Applications_, Wiley

_S_e_e _A_l_s_o:

     'nls'

_E_x_a_m_p_l_e_s:

     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

