R: Construct Self-starting Nonlinear Models

selfStart {stats} | R Documentation

## Construct Self-starting Nonlinear Models

### Description

Construct self-starting nonlinear models to be used in `nls`, 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()`.

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

`nls()` calls `getInitial` and the `initial` function for these self-starting models.

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)

José Pinheiro and Douglas Bates

### See Also

`nls`, `getInitial`.

Each of the following are `"selfStart"` models (with examples) `SSasymp`, `SSasympOff`, `SSasympOrig`, `SSbiexp`, `SSfol`, `SSfpl`, `SSgompertz`, `SSlogis`, `SSmicmen`, `SSweibull`.

Further, package nlme's `nlsList`.

### Examples

    ## self-starting logistic model

    ## The "initializer" (finds initial values for parameters from data):
    initLogis <- function(mCall, data, LHS) {
        xy <- data.frame(sortedXyData(mCall[["input"]], 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")], nm = mCall[c("Asym", "xmid", "scal")])
    }

    SSlogis <- selfStart(~ Asym/(1 + exp((xmid - x)/scal)),
                         initial = initLogis,
                         parameters = 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)

    ## 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 3.5.1 Index]