

   nlsModel {nls}                               R Documentation

   CCrreeaattee aann nnllssMMooddeell OObbjjeecctt

   DDeessccrriippttiioon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Ussaaggee::

        nlsModel(form, data, start)

   AArrgguummeenntts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Deettaaiills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 meth-
        ods to access characteristics of the model.  It forms
        an important component of the object returned by the
        `nls' function.

   VVaalluuee::

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

      resid: returns the residual vector evaluated at the cur-
             rent 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 accord-
             ing 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 gradi-
             ent array.

    getPars: returns the current value of the model parameters
             as a numeric vector

   getAllPars: returns the current value of the model parame-
             ters 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'.

   AAuutthhoorr((ss))::

        Douglas M. Bates and Saikat DebRoy

   RReeffeerreenncceess::

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

   SSeeee AAllssoo::

        `nls'

   EExxaammpplleess::

        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

