R: Construct Self-starting Nonlinear Models (original) (raw)

selfStart {stats}	R Documentation

Description

Construct self-starting nonlinear models to be used in[nls](../../stats/help/nls.html), etc. Via function initial to compute approximate parameter values from data, such models are “self-starting”, i.e., do not need a start argument in, e.g., [nls](../../stats/help/nls.html)().

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 arguments mCall,data, and LHS, and ..., 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 inmodel. The ... is used by nls() to pass itscontrol and trace arguments for the cases whereinitial() itself calls nls() as it does for the ten self-starting nonlinear models in R's stats package.
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 thederiv function.
template	an optional prototype for the calling sequence of the returned object, passed as the function.arg argument to thederiv function. By default, a template is generated with the covariates in model coming first and the parameters inmodel coming last in the calling sequence.

Details

[nls](../../stats/help/nls.html)() calls [getInitial](../../stats/help/getInitial.html) and theinitial function for these self-starting models.

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

Value

a [function](../../base/html/function.html) object of class "selfStart", for theformula method obtained by applying [deriv](../../stats/help/deriv.html)to the right hand side of the model formula. Aninitial attribute (defined by the initial argument) is added to the function to calculate starting estimates for the parameters in the model automatically.

Author(s)

José Pinheiro and Douglas Bates

Examples

## self-starting logistic model

## The "initializer" (finds initial values for parameters from data):
initLogis <- function(mCall, data, LHS, ...) {
    xy <- sortedXyData(mCall[["x"]], LHS, data)
    if(nrow(xy) < 4)
        stop("too few distinct input values to fit a logistic model")
    z <- xy[["y"]]
    ## transform to proportion, i.e. in (0,1) :
    rng <- range(z); dz <- diff(rng)
    z <- (z - rng[1L] + 0.05 * dz)/(1.1 * dz)
    xy[["z"]] <- log(z/(1 - z))		# logit transformation
    aux <- coef(lm(x ~ z, xy))
    pars <- coef(nls(y ~ 1/(1 + exp((xmid - x)/scal)),
                     data = xy,
                     start = list(xmid = aux[[1L]], scal = aux[[2L]]),
                     algorithm = "plinear", ...))
    setNames(pars [c(".lin", "xmid", "scal")],
             mCall[c("Asym", "xmid", "scal")])
}

mySSlogis <- selfStart(~ Asym/(1 + exp((xmid - x)/scal)),
                       initial = initLogis,
                       parameters = c("Asym", "xmid", "scal"))

getInitial(weight ~ mySSlogis(Time, Asym, xmid, scal),
           data = subset(ChickWeight, Chick == 1))


# '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)

## Explore the self-starting models already available in R's  "stats":
pos.st <- which("package:stats" == search())
mSS <- apropos("^SS..", where = TRUE, ignore.case = FALSE)
(mSS <- unname(mSS[names(mSS) == pos.st]))
fSS <- sapply(mSS, get, pos = pos.st, mode = "function")
all(sapply(fSS, inherits, "selfStart"))  # -> TRUE

## Show the argument list of each self-starting function:
str(fSS, give.attr = FALSE)

[Package _stats_ version 4.6.0 Index]