selfStart               package:stats               R Documentation

Construct Self-starting Nonlinear Models

Description:

     Construct self-starting nonlinear models.

Usage:

     selfStart(model, initial, parameters, template)

Arguments:

   model: a function object defining a nonlinear model or a nonlinear
          formula object of the form '~expression'.

 initial: a function object, taking three arguments: 'mCall', 'data',
          and 'LHS', representing, respectively, a matched call to the
          function 'model', a data frame in which to interpret the
          variables in 'mCall', and the expression from the left-hand
          side of the model formula in the call to 'nls'. This function
          should return initial values for the parameters in 'model'.

parameters: a character vector specifying the terms on the right hand
          side of 'model' for which initial estimates should be
          calculated.  Passed as the 'namevec' argument to the 'deriv'
          function.

template: an optional prototype for the calling sequence of the
          returned object, passed as the 'function.arg' argument to the
          'deriv' function.  By default, a template is generated with
          the covariates in 'model' coming first and the parameters in
          'model' coming last in the calling sequence.

Details:

     This function is generic; methods functions can be written to
     handle specific classes of objects.

Value:

     a function object of class '"selfStart"', for the 'formula' method
     obtained by applying 'deriv' to the right hand side of the 'model'
     formula.  An 'initial' attribute (defined by the 'initial'
     argument) is added to the function to calculate starting estimates
     for the parameters in the model automatically.

Author(s):

     Jose Pinheiro and Douglas Bates

See Also:

     'nls'

Examples:

     ## self-starting logistic model

     SSlogis <- selfStart(~ Asym/(1 + exp((xmid - x)/scal)),
       function(mCall, data, LHS)
       {
         xy <- sortedXyData(mCall[["x"]], LHS, data)
         if(nrow(xy) < 4) {
           stop("Too few distinct x values to fit a logistic")
         }
         z <- xy[["y"]]
         if (min(z) <= 0) { z <- z + 0.05 * max(z) } # avoid zeroes
         z <- z/(1.05 * max(z))              # scale to within unit height
         xy[["z"]] <- log(z/(1 - z))         # logit transformation
         aux <- coef(lm(x ~ z, xy))
         parameters(xy) <- list(xmid = aux[1], scal = aux[2])
         pars <- as.vector(coef(nls(y ~ 1/(1 + exp((xmid - x)/scal)), 
                                  data = xy, algorithm = "plinear")))
         value <- c(pars[3], pars[1], pars[2])
         names(value) <- mCall[c("Asym", "xmid", "scal")]
         value
       }, c("Asym", "xmid", "scal"))

     # 'first.order.log.model' is a function object defining a first order
     # compartment model 
     # 'first.order.log.initial' is a function object which calculates initial
     # values for the parameters in 'first.order.log.model'

     # self-starting first order compartment model
     ## Not run: 
     SSfol <- selfStart(first.order.log.model, first.order.log.initial)
     ## End(Not run)

