| % File src/library/stats/man/selfStart.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2020 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{selfStart} |
| \title{Construct Self-starting Nonlinear Models} |
| \encoding{UTF-8} |
| \alias{selfStart} |
| \alias{selfStart.default} |
| \alias{selfStart.formula} |
| \description{ |
| Construct self-starting nonlinear models to be used in |
| \code{\link{nls}}, etc. Via function \code{initial} to compute |
| approximate parameter values from data, such models are |
| \dQuote{self-starting}, i.e., do not need a \code{start} argument in, |
| e.g., \code{\link{nls}()}. |
| } |
| \usage{ |
| selfStart(model, initial, parameters, template) |
| } |
| \arguments{ |
| \item{model}{a function object defining a nonlinear model or |
| a nonlinear \code{\link{formula}} object of the form \code{~ expression}.} |
| \item{initial}{a function object, taking arguments \code{mCall}, |
| \code{data}, and \code{LHS}, \emph{and} \code{...}, representing, |
| respectively, a matched call to the function \code{model}, a data frame in |
| which to interpret the variables in \code{mCall}, and the expression |
| from the left-hand side of the model formula in the call to \code{nls}. |
| This function should return initial values for the parameters in |
| \code{model}. The \code{...} is used by \code{\link{nls}()} to pass its |
| \code{control} and \code{trace} arguments for the cases where |
| \code{initial()} itself calls \code{nls()} as it does for the ten |
| self-starting nonlinear models in \R's \pkg{stats} package.} |
| \item{parameters}{a character vector specifying the terms on the right |
| hand side of \code{model} for which initial estimates should be |
| calculated. Passed as the \code{namevec} argument to the |
| \code{deriv} function.} |
| \item{template}{an optional prototype for the calling sequence of the |
| returned object, passed as the \code{function.arg} argument to the |
| \code{deriv} function. By default, a template is generated with the |
| covariates in \code{model} coming first and the parameters in |
| \code{model} coming last in the calling sequence.} |
| } |
| \details{ |
| \code{\link{nls}()} calls \code{\link{getInitial}} and the |
| \code{initial} function for these self-starting models. |
| |
| This function is generic; methods functions can be written to handle |
| specific classes of objects. |
| } |
| \value{ |
| a \code{\link{function}} object of class \code{"selfStart"}, for the |
| \code{formula} method obtained by applying \code{\link{deriv}} |
| to the right hand side of the \code{model} formula. An |
| \code{initial} attribute (defined by the \code{initial} argument) is |
| added to the function to calculate starting estimates for the |
| parameters in the model automatically. |
| } |
| \author{\enc{José}{Jose} Pinheiro and Douglas Bates} |
| |
| \seealso{ |
| \code{\link{nls}}, \code{\link{getInitial}}. |
| |
| Each of the following are \code{"selfStart"} models (with examples) |
| \code{\link{SSasymp}}, \code{\link{SSasympOff}}, \code{\link{SSasympOrig}}, |
| \code{\link{SSbiexp}}, \code{\link{SSfol}}, \code{\link{SSfpl}}, |
| \code{\link{SSgompertz}}, \code{\link{SSlogis}}, \code{\link{SSmicmen}}, |
| \code{\link{SSweibull}}. |
| |
| Further, package \CRANpkg{nlme}'s \code{\link[nlme]{nlsList}}. |
| } |
| \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")) |
| \dontshow{## IGNORE_RDIFF_BEGIN} |
| getInitial(weight ~ mySSlogis(Time, Asym, xmid, scal), |
| data = subset(ChickWeight, Chick == 1)) |
| \dontshow{## IGNORE_RDIFF_END} |
| |
| # '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 |
| \dontrun{ |
| SSfol <- selfStart(first.order.log.model, first.order.log.initial) |
| } |
| |
| ## 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) |
| } |
| \keyword{models} |