R: Construct Self-starting Nonlinear Models

selfStart {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)

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`

### 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")))
        setNames(c(pars[3], pars[1], pars[2]),
                 mCall[c("Asym", "xmid", "scal")])
      }, 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.1.2 Index]