\name{BOD}
\docType{data}
\alias{BOD}
\title{ Biochemical Oxygen Demand }
\description{
  The \code{BOD} data frame has 6 rows and 2 columns giving the
  biochemical oxygen demand versus time in an evaluation of water
  quality.
}
\usage{data(BOD)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{Time}{
      A numeric vector giving the time of the measurement (days).
    }
    \item{demand}{
      A numeric vector giving the biochemical oxygen demand (mg/l).
    }
  }
}
\source{
  Bates, D.M. and Watts, D.G. (1988),
  \emph{Nonlinear Regression Analysis and Its Applications},
  Wiley, Appendix A1.4.

  Originally from Marske (1967), \emph{Biochemical
    Oxygen Demand Data Interpretation Using Sum of Squares Surface}
  M.Sc. Thesis, University of Wisconsin -- Madison.
}
\examples{
data(BOD)
# simplest form of fitting a first-order model to these data
fm1 <- nls(demand ~ A*(1-exp(-exp(lrc)*Time)), data = BOD,
   start = c(A = 20, lrc = log(.35)))
coef(fm1)
print(fm1)
# using the plinear algorithm
fm2 <- nls(demand ~ (1-exp(-exp(lrc)*Time)), data = BOD,
   start = c(lrc = log(.35)), algorithm = "plinear", trace = TRUE)
# using a self-starting model
fm3 <- nls(demand ~ SSasympOrig(Time, A, lrc), data = BOD)
summary( fm3 )
}
\keyword{datasets}
\name{CO2}
\docType{data}
\alias{CO2}
\title{Carbon Dioxide uptake in grass plants}
\description{
  The \code{CO2} data frame has 84 rows and 5 columns of data from an
  experiment on the cold tolerance of the grass species
  \emph{Echinochloa crus-galli}.
}
\usage{data(CO2)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{Plant}{
      an ordered factor with levels
      \code{Qn1} < \code{Qn2} < \code{Qn3} < \dots{} < \code{Mc1}
      giving a unique identifier for each plant.
    }
    \item{Type}{
      a factor with levels
      \code{Quebec} 
      \code{Mississippi}
      giving the origin of the plant
    }
    \item{Treatment}{
      a factor with levels
      \code{nonchilled} 
      \code{chilled}
    }
    \item{conc}{
      a numeric vector of ambient carbon dioxide concentrations (mL/L).
    }
    \item{uptake}{
      a numeric vector of carbon dioxide uptake rates
      (\eqn{\mu\mbox{mol}/m^2}{umol/m^2} sec).
    }
  }
}
\details{
  The \eqn{CO_2}{CO2} uptake of six plants from Quebec and six plants
  from Mississippi was measured at several levels of ambient
  \eqn{CO_2}{CO2} concentration.  Half the plants of each type were
  chilled overnight before the experiment was conducted.
}
\source{
  Potvin, C., Lechowicz, M. J. and Tardif, S. (1990)
  ``The statistical analysis of ecophysiological response curves
  obtained from experiments involving repeated measures'', \emph{Ecology},
  \bold{71}, 1389--1400.

  Pinheiro, J. C. and Bates, D. M. (2000) \emph{Mixed-effects Models in
      S and S-PLUS}, Springer.
}
\examples{
data(CO2)
coplot(uptake ~ conc | Plant, data = CO2, show = FALSE, type = "b")
## fit the data for the first plant
fm1 <- nls(uptake ~ SSasymp(conc, Asym, lrc, c0),
   data = CO2, subset = Plant == 'Qn1')
summary(fm1)
## fit each plant separately
fmlist <- list()
for (pp in levels(CO2$Plant)) {
  fmlist[[pp]] <- nls(uptake ~ SSasymp(conc, Asym, lrc, c0),
      data = CO2, subset = Plant == pp)
}
## check the coefficients by plant
sapply(fmlist, coef)
}
\keyword{datasets}
\keyword{nonlinear}
\name{ChickWeight}
\docType{data}
\alias{ChickWeight}
\title{Weight versus age of chicks on different diets}
\description{
  The \code{ChickWeight} data frame has 578 rows and 4 columns from an
  experiment on the effect of diet on early growth of chicks.
}
\usage{data(ChickWeight)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{weight}{
      a numeric vector giving the body weight of the chick (gm).
    }
    \item{Time}{
      a numeric vector giving the number of days since birth when
      the measurement was made.
    }
    \item{Chick}{
      an ordered factor with levels
      \code{18} < \dots{} < \code{48}
      giving a unique identifier for the chick.  The ordering of
      the levels groups chicks on the same diet together and
      orders them according to their final weight (lightest to
      heaviest) within diet.
    }
    \item{Diet}{
      a factor with levels 1,\dots{},4 indicating which
      experimental diet the chick received.
    }
  }
}
\details{
  The body weights of the chicks were measured at birth and every
  second day thereafter until day 20.  They were also measured on day
  21.  There were four groups on chicks on different protein diets.
}
\source{
  Crowder, M. and Hand, D. (1990), \emph{Analysis of Repeated Measures},
  {Chapman and Hall} (example 5.3)

  Hand, D. and Crowder, M. (1996), \emph{Practical Longitudinal Data
    Analysis}, Chapman and Hall (table A.2)

  Pinheiro, J. C. and Bates, D. M. (2000) \emph{Mixed-effects Models in
    S and S-PLUS}, Springer.
}
\examples{
data(ChickWeight)
coplot(weight ~ Time | Chick, data = ChickWeight,
    type = "b", show = FALSE)
## fit a representative chick
fm1 <- nls(weight ~ SSlogis( Time, Asym, xmid, scal ),
    data = ChickWeight, subset = Chick == 1)
summary( fm1 )
}
\keyword{datasets}
\name{DNase}
\docType{data}
\alias{DNase}
\title{Elisa assay of DNase}
\description{
  The \code{DNase} data frame has 176 rows and 3 columns of data
  obtained during development of an ELISA assay for the recombinant
  protein DNase in rat serum.
}
\usage{data(DNase)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{Run}{
      an ordered factor with levels \code{10} < \dots{} < \code{3}
      indicating the assay run.
    }
    \item{conc}{
      a numeric vector giving the known concentration of the
      protein. 
    }
    \item{density}{
      a numeric vector giving the measured optical density
      (dimensionless) in the assay.  Duplicate optical density
      measurements were obtained. 
    }
  }
}
\source{
  Davidian, M. and Giltinan, D. M. (1995) \emph{Nonlinear Models for
    Repeated Measurement Data}, Chapman & Hall (section 5.2.4, p. 134)

  Pinheiro, J. C. and Bates, D. M. (2000) \emph{Mixed-effects Models in
    S and S-PLUS}, Springer.
}
\examples{
data(DNase)
coplot(density ~ conc | Run, data = DNase,
    show = FALSE, type = "b")
coplot(density ~ log(conc) | Run, data = DNase,
    show = FALSE, type = "b")
## fit a representative run
fm1 <- nls(density ~ SSlogis( log(conc), Asym, xmid, scal ),
    data = DNase, subset = Run == 1)
## compare with a four-parameter logistic
fm2 <- nls(density ~ SSfpl( log(conc), A, B, xmid, scal ),
    data = DNase, subset = Run == 1)
summary(fm2)
anova(fm1, fm2)
}
\keyword{datasets}
\name{Indometh}
\docType{data}
\alias{Indometh}
\title{Pharmacokinetics of Indomethicin}
\description{
  The \code{Indometh} data frame has 66 rows and 3 columns of data on
  the pharmacokinetics of indomethicin.
}
\usage{data(Indometh)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{Subject}{
      an ordered factor with containing the subject codes.  The
      ordering is according to increasing maximum response.
    }
    \item{time}{
      a numeric vector of times at which blood samples were drawn (hr).
    }
    \item{conc}{
      a numeric vector of plasma concentrations of indomethicin (mcg/ml).
    }
  }
}
\details{
  Each of the six subjects were given an intravenous injection of
  indomethicin.
}
\source{
  Kwan, Breault, Umbenhauer, McMahon and Duggan (1976), ``Kinetics of
  Indomethicin absorption, elimination, and enterohepatic circulation in
  man'', \emph{Journal of Pharmacokinetics and Biopharmaceutics}, \bold{4},
  255--280.

  Davidian, M. and Giltinan, D. M. (1995) \emph{Nonlinear Models for
    Repeated Measurement Data}, Chapman & Hall (section 5.2.4, p. 134)

  Pinheiro, J. C. and Bates, D. M. (2000) \emph{Mixed-effects Models in
    S and S-PLUS}, Springer.
}
\examples{
data(Indometh)
fm1 <- nls(conc ~ SSbiexp(time, A1, lrc1, A2, lrc2),
           data = Indometh, subset = Subject == 1)
summary(fm1)
}
\keyword{datasets}
\name{Loblolly}
\docType{data}
\alias{Loblolly}
\title{Growth of Loblolly pine trees}
\description{
  The \code{Loblolly} data frame has 84 rows and 3 columns of records of
  the growth of Loblolly pine trees.
}
\usage{data(Loblolly)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{height}{
      a numeric vector of tree heights (ft).
    }
    \item{age}{
      a numeric vector of tree ages (yr).
    }
    \item{Seed}{
      an ordered factor indicating the seed source for the tree.
      The ordering is according to increasing maximum height.
    }
  }
}
\source{
  Kung, F. H. (1986), ``Fitting logistic growth curve with predetermined
  carrying capacity'', \emph{Proceedings of the Statistical Computing
    Section, American Statistical Association}, 340--343.

  Pinheiro, J. C. and Bates, D. M. (2000) \emph{Mixed-effects Models
    in S and S-PLUS}, Springer.
}
\examples{
data(Loblolly)
plot(height ~ age, data = Loblolly, subset = Seed == 329,
     xlab = "Tree age (yr)", las = 1,
     ylab = "Tree height (ft)",
     main = "Loblolly data and fitted curve (Seed 329 only)")
fm1 <- nls(height ~ SSasymp(age, Asym, R0, lrc),
           data = Loblolly, subset = Seed == 329)
summary(fm1)
age <- seq(0, 30, len = 101)
lines(age, predict(fm1, list(age = age)))
}
\keyword{datasets}
% $Id: NLSstAsymptotic.Rd,v 1.8 2001/03/31 16:07:00 pd Exp $
\name{NLSstAsymptotic}
\title{Fit the Asymptotic Regression Model}
\alias{NLSstAsymptotic}
\alias{NLSstAsymptotic.sortedXyData}
\usage{
NLSstAsymptotic(xy)
}
\arguments{
 \item{xy}{a \code{sortedXyData} object}
}
\description{
  Fits the asymptotic regression model, in the form \code{b0 +
      b1*(1-exp(-exp(lrc) * x)} to the \code{xy} data.  
  This can be used as a building block in determining starting estimates
  for more complicated models.
}
\value{
  A numeric value of length 3 with components labelled \code{b0},
  \code{b1}, and \code{lrc}.  \code{b0} is the estimated intercept on
  the \code{y}-axis, \code{b1} is the estimated difference between the
  asymptote and the \code{y}-intercept, and \code{lrc} is the estimated
  logarithm of the rate constant.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{SSasymp}}}
\examples{
data( Loblolly )
Lob.329 <- Loblolly[ Loblolly$Seed == "329", ]
NLSstAsymptotic(sortedXyData(expression(age), expression(height), Lob.329 ))
}
\keyword{manip}
% $Id: NLSstClosestX.Rd,v 1.4 2001/03/24 06:57:57 ripley Exp $
\name{NLSstClosestX}
\title{Inverse Interpolation}
\alias{NLSstClosestX}
\alias{NLSstClosestX.sortedXyData}
\usage{
NLSstClosestX(xy, yval)
}
\arguments{
 \item{xy}{a \code{sortedXyData} object}
 \item{yval}{a numeric value on the \code{y} scale}
}
\description{
  Use inverse linear interpolation to approximate the \code{x} value at
  which the function represented by \code{xy} is equal to \code{yval}.
}
\value{
  A single numeric value on the \code{x} scale.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{sortedXyData}}, \code{\link{NLSstLfAsymptote}},
  \code{\link{NLSstRtAsymptote}}, \code{\link{selfStart}}}
\examples{
data( DNase )
DNase.2 <- DNase[ DNase$Run == "2", ]
DN.srt <- sortedXyData( expression(log(conc)), expression(density), DNase.2 )
NLSstClosestX( DN.srt, 1.0 )
}
\keyword{manip}
% $Id: NLSstLfAsymptote.Rd,v 1.5 2001/03/24 06:57:57 ripley Exp $
\name{NLSstLfAsymptote}
\title{Horizontal Asymptote on the Left Side}
\alias{NLSstLfAsymptote}
\alias{NLSstLfAsymptote.sortedXyData}
\usage{
NLSstLfAsymptote(xy)
}
\arguments{
 \item{xy}{a \code{sortedXyData} object}
}
\description{
  Provide an initial guess at the horizontal asymptote on
  the left side (i.e. small values of \code{x}) of the graph of \code{y}
  versus \code{x} from the \code{xy} object.  Primarily used within
  \code{initial} functions for self-starting nonlinear regression
  models.
}
\value{
  A single numeric value estimating the horizontal asymptote for small
  \code{x}. 
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{
  \code{\link{sortedXyData}},
  \code{\link{NLSstClosestX}},
  \code{\link{NLSstRtAsymptote}},
  \code{\link{selfStart}}
}
\examples{
data( DNase )
DNase.2 <- DNase[ DNase$Run == "2", ]
DN.srt <- sortedXyData( expression(log(conc)), expression(density), DNase.2 )
NLSstLfAsymptote( DN.srt )
}
\keyword{manip}
% $Id: NLSstRtAsymptote.Rd,v 1.4 2001/03/24 06:57:57 ripley Exp $
\name{NLSstRtAsymptote}
\title{Horizontal Asymptote on the Right Side}
\alias{NLSstRtAsymptote}
\alias{NLSstRtAsymptote.sortedXyData}
\usage{
NLSstRtAsymptote(xy)
}
\arguments{
 \item{xy}{a \code{sortedXyData} object}
}
\description{
  Provide an initial guess at the horizontal asymptote on
  the right side (i.e. large values of \code{x}) of the graph of \code{y}
  versus \code{x} from the \code{xy} object.  Primarily used within
  \code{initial} functions for self-starting nonlinear regression
  models.
}
\value{
  A single numeric value estimating the horizontal asymptote for large \code{x}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{sortedXyData}}, \code{\link{NLSstClosestX}},
  \code{\link{NLSstRtAsymptote}}, \code{\link{selfStart}}}
\examples{
data( DNase )
DNase.2 <- DNase[ DNase$Run == "2", ]
DN.srt <- sortedXyData( expression(log(conc)), expression(density), DNase.2 )
NLSstRtAsymptote( DN.srt )
}
\keyword{manip}
\name{Orange}
\docType{data}
\alias{Orange}
\title{Growth of orange trees}
\description{
  The \code{Orange} data frame has 35 rows and 3 columns of records of
  the growth of orange trees.
}
\usage{data(Orange)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{Tree}{
      an ordered factor indicating the tree on which the measurement is
      made.  The ordering is according to increasing maximum diameter.
    }
    \item{age}{
      a numeric vector giving the age of the tree (days since 1968/12/31)
    }
    \item{circumference}{
      a numeric vector of trunk circumferences (mm).  This is probably
      ``circumference at breast height'', a standard measurement in
      forestry.
    }
  }
}
\source{
  Draper, N. R. and Smith, H. (1998), \emph{Applied Regression Analysis
    (3rd ed)}, Wiley (exercise 24.N).

  Pinheiro, J. C. and Bates, D. M. (2000) \emph{Mixed-effects Models
    in S and S-PLUS}, Springer.
}
\examples{
data(Orange)
coplot(circumference ~ age | Tree, data = Orange, show = FALSE)
fm1 <- nls(circumference ~ SSlogis(age, Asym, xmid, scal),
           data = Orange, subset = Tree == 3)
plot(circumference ~ age, data = Orange, subset = Tree == 3,
     xlab = "Tree age (days since 1968/12/31)",
     ylab = "Tree circumference (mm)", las = 1,
     main = "Orange tree data and fitted model (Tree 3 only)")
age <- seq(0, 1600, len = 101)
lines(age, predict(fm1, list(age = age)))
}
\keyword{datasets}
\name{Puromycin}
\docType{data}
\alias{Puromycin}
\title{Reaction velocity of an enzymatic reaction}
\description{
  The \code{Puromycin} data frame has 23 rows and 3 columns of the
  reaction velocity versus substrate concentration in an enzymatic
  reaction involving untreated cells or cells treated with Puromycin.
}
\usage{data(Puromycin)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{conc}{
      a numeric vector of substrate concentrations (ppm)
    }
    \item{rate}{
      a numeric vector of instantaneous reaction rates (counts/min/min)
    }
    \item{state}{
      a factor with levels
      \code{treated} 
      \code{untreated} 
    }
  }
}
\details{
  Data on the ``velocity'' of an enzymatic reaction were obtained by
  Treloar (1974).  The number of counts per minute of radioactive
  product from the reaction was measured as a function of substrate
  concentration in parts per million (ppm) and from these counts the
  initial rate, or ``velocity,'' of the reaction was calculated
  (counts/min/min).  The experiment was conducted once with the enzyme
  treated with Puromycin, and once with the enzyme untreated.
}
\source{
  Bates, D.M. and Watts, D.G. (1988),
  \emph{Nonlinear Regression Analysis and Its Applications},
  Wiley, Appendix A1.3.

  Treloar, M. A. (1974), \emph{Effects of Puromycin on
    Galactosyltransferase in Golgi Membranes}, M.Sc. Thesis, U. of
  Toronto. 
}
\examples{
data(Puromycin)
plot(rate ~ conc, data = Puromycin, las = 1,
     xlab = "Substrate concentration (ppm)",
     ylab = "Reaction velocity (counts/min/min)",
     pch = as.integer(Puromycin$state),
     col = as.integer(Puromycin$state),
     main = "Puromycin data and fitted Michaelis-Menten curves")
## simplest form of fitting the Michaelis-Menten model to these data
fm1 <- nls(rate ~ Vm * conc/(K + conc), data = Puromycin,
           subset = state == "treated",
           start = c(Vm = 200, K = 0.05), trace = TRUE)
fm2 <- nls(rate ~ Vm * conc/(K + conc), data = Puromycin,
           subset = state == "untreated",
           start = c(Vm = 160, K = 0.05), trace = TRUE)
summary(fm1)
summary(fm2)
## using partial linearity
fm3 <- nls(rate ~ conc/(K + conc), data = Puromycin,
           subset = state == "treated", start = c(K = 0.05),
           algorithm = "plinear", trace = TRUE)
## using a self-starting model
fm4 <- nls(rate ~ SSmicmen(conc, Vm, K), data = Puromycin,
           subset = state == "treated")
summary(fm4)
## add fitted lines to the plot
conc <- seq(0, 1.2, len = 101)
lines(conc, predict(fm1, list(conc = conc)), lty = 1, col = 1)
lines(conc, predict(fm2, list(conc = conc)), lty = 2, col = 2)
legend(0.8, 120, levels(Puromycin$state),
       col = 1:2, lty = 1:2, pch = 1:2)
}
\keyword{datasets}
% $Id: SSasymp.Rd,v 1.3 2001/08/13 19:55:13 ripley Exp $
\name{SSasymp}
\title{Asymptotic Regression Model}
\usage{
SSasymp(input, Asym, R0, lrc)
}
\alias{SSasymp}
\arguments{
 \item{input}{a numeric vector of values at which to evaluate the model.}
 \item{Asym}{a numeric parameter representing the horizontal asymptote on
   the right side (very large values of \code{input}).}
 \item{R0}{a numeric parameter representing the response when
   \code{input} is zero.}
 \item{lrc}{a numeric parameter representing the natural logarithm of
   the rate constant.}
}
\description{
  This \code{selfStart} model evaluates the asymptotic regression
  function and its gradient.  It has an \code{initial} attribute that
  will evaluate initial estimates of the parameters \code{Asym}, \code{R0},
  and \code{lrc} for a given set of data.
}
\value{
  a numeric vector of the same length as \code{input}.  It is the value of
  the expression \code{Asym+(R0-Asym)*exp(-exp(lrc)*input)}.  If all of
  the arguments \code{Asym}, \code{R0}, and \code{lrc} are
  names of objects, the gradient matrix with respect to these names is
  attached as an attribute named \code{gradient}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data( Loblolly )
Lob.329 <- Loblolly[ Loblolly$Seed == "329", ]
SSasymp( Lob.329$age, 100, -8.5, -3.2 )  # response only
Asym <- 100
resp0 <- -8.5
lrc <- -3.2
SSasymp( Lob.329$age, Asym, resp0, lrc ) # response and gradient
getInitial(height ~ SSasymp( age, Asym, resp0, lrc), data = Lob.329)
## Initial values are in fact the converged values
fm1 <- nls(height ~ SSasymp( age, Asym, resp0, lrc), data = Lob.329)
summary(fm1)
\testonly{
  xx <- seq(0, 5, len = 101)
  yy <- 5 - 4 * exp(-xx/(2*log(2)))
  par(mar = c(0, 0, 4.1, 0))
  plot(xx, yy, type = "l", axes = FALSE, ylim = c(0,6), xlim = c(-1, 5),
       xlab = "", ylab = "", lwd = 2,
       main = "Parameters in the SSasymp model")
  usr <- par("usr")
  arrows(usr[1], 0, usr[2], 0, length = 0.1, angle = 25)
  arrows(0, usr[3], 0, usr[4], length = 0.1, angle = 25)
  text(usr[2] - 0.2, 0.1, "x", adj = c(1, 0))
  text(-0.1, usr[4], "y", adj = c(1, 1))
  abline(h = 5, lty = 2, lwd = 0)
  arrows(-0.8, 2.1, -0.8, 0, length = 0.1, angle = 25)
  arrows(-0.8, 2.9, -0.8, 5, length = 0.1, angle = 25)
  text(-0.8, 2.5, expression(phi[1]), adj = c(0.5, 0.5))
  segments(-0.4, 1, 0, 1, lty = 2, lwd = 0.75)
  arrows(-0.3, 0.25, -0.3, 0, length = 0.07, angle = 25)
  arrows(-0.3, 0.75, -0.3, 1, length = 0.07, angle = 25)
  text(-0.3, 0.5, expression(phi[2]), adj = c(0.5, 0.5))
  segments(1, 3.025, 1, 4, lty = 2, lwd = 0.75)
  arrows(0.2, 3.5, 0, 3.5, length = 0.08, angle = 25)
  arrows(0.8, 3.5, 1, 3.5, length = 0.08, angle = 25)
  text(0.5, 3.5, expression(t[0.5]), adj = c(0.5, 0.5))
}
}
\keyword{models}
% $Id: SSasympOff.Rd,v 1.3 2001/08/13 19:55:13 ripley Exp $
\name{SSasympOff}
\title{Asymptotic Regression Model with an Offset}
\usage{
SSasympOff(input, Asym, lrc, c0)
}
\alias{SSasympOff}
\arguments{
 \item{input}{a numeric vector of values at which to evaluate the model.}
 \item{Asym}{a numeric parameter representing the horizontal asymptote on
   the right side (very large values of \code{input}).}
 \item{lrc}{a numeric parameter representing the natural logarithm of
   the rate constant.}
 \item{c0}{a numeric parameter representing the \code{input} for which the
   response is zero.}
}
\description{
  This \code{selfStart} model evaluates an alternative parameterization
  of the asymptotic
  regression function and the gradient with respect to those parameters.
  It has an \code{initial}
  attribute that creates initial estimates of the parameters
  \code{Asym}, \code{lrc}, and \code{c0}.
}
\value{
  a numeric vector of the same length as \code{input}.  It is the value of
  the expression \code{Asym*(1 - exp(-exp(lrc)*(input - c0)))}.  If all of
  the arguments \code{Asym}, \code{lrc}, and \code{c0} are
  names of objects, the gradient matrix with respect to these names is
  attached as an attribute named \code{gradient}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data( CO2 )
CO2.Qn1 <- CO2[CO2$Plant == "Qn1", ]
SSasympOff( CO2.Qn1$conc, 32, -4, 43 )  # response only
Asym <- 32; lrc <- -4; c0 <- 43
SSasympOff( CO2.Qn1$conc, Asym, lrc, c0 ) # response and gradient
getInitial(uptake ~ SSasymp( conc, Asym, lrc, c0), data = CO2.Qn1)
## Initial values are in fact the converged values
fm1 <- nls(uptake ~ SSasymp( conc, Asym, lrc, c0), data = CO2.Qn1)
summary(fm1)
\testonly{
  xx <- seq(0.5, 5, len = 101)
  yy <- 5 * (1 -  exp(-(xx - 0.5)/(2*log(2))))
  par(mar = c(0, 0, 4.0, 0))
  plot(xx, yy, type = "l", axes = FALSE, ylim = c(0,6), xlim = c(-1, 5),
       xlab = "", ylab = "", lwd = 2,
       main = "Parameters in the SSasympOff model")
  usr <- par("usr")
  arrows(usr[1], 0, usr[2], 0, length = 0.1, angle = 25)
  arrows(0, usr[3], 0, usr[4], length = 0.1, angle = 25)
  text(usr[2] - 0.2, 0.1, "x", adj = c(1, 0))
  text(-0.1, usr[4], "y", adj = c(1, 1))
  abline(h = 5, lty = 2, lwd = 0)
  arrows(-0.8, 2.1, -0.8, 0, length = 0.1, angle = 25)
  arrows(-0.8, 2.9, -0.8, 5, length = 0.1, angle = 25)
  text(-0.8, 2.5, expression(phi[1]), adj = c(0.5, 0.5))
  segments(0.5, 0, 0.5, 3, lty = 2, lwd = 0.75)
  text(0.5, 3.1, expression(phi[3]), adj = c(0.5, 0))
  segments(1.5, 2.525, 1.5, 3, lty = 2, lwd = 0.75)
  arrows(0.7, 2.65, 0.5, 2.65, length = 0.08, angle = 25)
  arrows(1.3, 2.65, 1.5, 2.65, length = 0.08, angle = 25)
  text(1.0, 2.65, expression(t[0.5]), adj = c(0.5, 0.5))
}
}
\keyword{models}
% $Id: SSasympOrig.Rd,v 1.3 2001/08/13 19:55:13 ripley Exp $
\name{SSasympOrig}
\title{Asymptotic Regression Model through the Origin}
\usage{
SSasympOrig(input, Asym, lrc)
}
\alias{SSasympOrig}
\arguments{
 \item{input}{a numeric vector of values at which to evaluate the model.}
 \item{Asym}{a numeric parameter representing the horizontal asymptote.}
 \item{lrc}{a numeric parameter representing the natural logarithm of
   the rate constant.}
}
\description{
  This \code{selfStart} model evaluates the asymptotic regression
  function through the origin and its gradient.  It has an
  \code{initial} attribute that will evaluate initial estimates of the
  parameters \code{Asym} and \code{lrc} for a given set of data.
}
\value{
  a numeric vector of the same length as \code{input}.  It is the value of
  the expression \code{Asym*(1 - exp(-exp(lrc)*input))}.  If all of
  the arguments \code{Asym} and \code{lrc} are
  names of objects, the gradient matrix with respect to these names is
  attached as an attribute named \code{gradient}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data( Loblolly )
Lob.329 <- Loblolly[ Loblolly$Seed == "329", ]
SSasympOrig( Lob.329$age, 100, -3.2 )  # response only
Asym <- 100; lrc <- -3.2
SSasympOrig( Lob.329$age, Asym, lrc ) # response and gradient
getInitial(height ~ SSasympOrig(age, Asym, lrc), data = Lob.329)
## Initial values are in fact the converged values
fm1 <- nls(height ~ SSasympOrig( age, Asym, lrc), data = Lob.329)
summary(fm1)
\testonly{
  xx <- seq(0, 5, len = 101)
  yy <- 5 * (1- exp(-xx/(2*log(2))))
  par(mar = c(0, 0, 3.5, 0))
  plot(xx, yy, type = "l", axes = FALSE, ylim = c(0,6), xlim = c(-1, 5),
       xlab = "", ylab = "", lwd = 2,
       main = "Parameters in the SSasympOrig model")
  usr <- par("usr")
  arrows(usr[1], 0, usr[2], 0, length = 0.1, angle = 25)
  arrows(0, usr[3], 0, usr[4], length = 0.1, angle = 25)
  text(usr[2] - 0.2, 0.1, "x", adj = c(1, 0))
  text(-0.1, usr[4], "y", adj = c(1, 1))
  abline(h = 5, lty = 2, lwd = 0)
  arrows(-0.8, 2.1, -0.8, 0, length = 0.1, angle = 25)
  arrows(-0.8, 2.9, -0.8, 5, length = 0.1, angle = 25)
  text(-0.8, 2.5, expression(phi[1]), adj = c(0.5, 0.5))
  segments(1, 2.525, 1, 3.5, lty = 2, lwd = 0.75)
  arrows(0.2, 3.0, 0, 3.0, length = 0.08, angle = 25)
  arrows(0.8, 3.0, 1, 3.0, length = 0.08, angle = 25)
  text(0.5, 3.0, expression(t[0.5]), adj = c(0.5, 0.5))
}
}
\keyword{models}
% $Id: SSbiexp.Rd,v 1.3 2001/08/13 19:55:13 ripley Exp $
\name{SSbiexp}
\title{Biexponential model}
\usage{
SSbiexp(input, A1, lrc1, A2, lrc2)
}
\alias{SSbiexp}
\arguments{
 \item{input}{a numeric vector of values at which to evaluate the model.}
 \item{A1}{a numeric parameter representing the multiplier of the first
   exponential.}
 \item{lrc1}{a numeric parameter representing the natural logarithm of
   the rate constant of the first exponential.}
 \item{A2}{a numeric parameter representing the multiplier of the second
   exponential.}
 \item{lrc2}{a numeric parameter representing the natural logarithm of
   the rate constant of the second exponential.}
}
\description{
  This \code{selfStart} model evaluates the biexponential model function
  and its gradient.  It has an \code{initial} attribute that 
  creates initial estimates of the parameters \code{A1}, \code{lrc1},
  \code{A2}, and \code{lrc2}.
}
\value{
  a numeric vector of the same length as \code{input}.  It is the value of
  the expression
  \code{A1*exp(-exp(lrc1)*input)+A2*exp(-exp(lrc2)*input)}.
  If all of the arguments \code{A1}, \code{lrc1}, \code{A2}, and
  \code{lrc2} are names of objects, the gradient matrix with respect to
  these names is attached as an attribute named \code{gradient}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data( Indometh )
Indo.1 <- Indometh[Indometh$Subject == 1, ]
SSbiexp( Indo.1$time, 3, 1, 0.6, -1.3 )  # response only
A1 <- 3; lrc1 <- 1; A2 <- 0.6; lrc2 <- -1.3
SSbiexp( Indo.1$time, A1, lrc1, A2, lrc2 ) # response and gradient
getInitial(conc ~ SSbiexp(time, A1, lrc1, A2, lrc2), data = Indo.1)
## Initial values are in fact the converged values
fm1 <- nls(conc ~ SSbiexp(time, A1, lrc1, A2, lrc2), data = Indo.1)
summary(fm1)
\testonly{
  xx <- seq(0, 5, len = 101)
  y1 <- 3.5 * exp(-4*xx)
  y2 <- 1.5 * exp(-xx)
  yy <- y1 + y2
  par(mar = c(0, 0, 3.5, 0))
  plot(xx, yy, type = "n", axes = FALSE, ylim = c(-0.2,6), xlim = c(0, 5),
       xlab = "", ylab = "", main = "Components of the SSbiexp model")
  usr <- par("usr")
  lines(xx, y1, lty = 2, lwd = 0.75)
  lines(xx, y2, lty = 3, lwd = 0.75)
  lines(xx, yy, lwd = 2)
  segments(1:5, 0, 1:5, -0.15)
  segments(0, 1:5, -0.06, 1:5)
  text(-0.1, 1:5, 1:5, adj = c(1, 0.25), cex = 0.7)
  text(1:5, -0.15, 1:5, adj = c(0.5, 1), cex = 0.7)
  arrows(usr[1], 0, usr[2], 0, length = 0.1, angle = 25)
  arrows(0, usr[3], 0, usr[4], length = 0.1, angle = 25)
  text(usr[2] - 0.2, 0.1, "x", adj = c(1, 0))
  text(-0.1, usr[4], "y", adj = c(1, 1))
}
}
\keyword{models}
% $Id: SSfol.Rd,v 1.4 2001/08/13 21:41:48 ripley Exp $
\name{SSfol}
\title{First-order Compartment Model}
\usage{
SSfol(Dose, input, lKe, lKa, lCl)
}
\alias{SSfol}
\arguments{
  \item{Dose}{a numeric value representing the initial dose.}
  \item{input}{a numeric vector at which to evaluate the model.}
  \item{lKe}{a numeric parameter representing the natural logarithm of
    the elimination rate constant.}
  \item{lKa}{a numeric parameter representing the natural logarithm of
    the absorption rate constant.}
  \item{lCl}{a numeric parameter representing the natural logarithm of
    the clearance.}
}
\description{
  This \code{selfStart} model evaluates the first-order compartment
  function and its gradient.  It has an \code{initial} attribute that 
  creates initial estimates of the parameters \code{lKe}, \code{lKa},
  and \code{lCl}.
}
\value{
  a numeric vector of the same length as \code{input}, which is the
  value of the expression
  \code{Dose * exp(lKe+lKa-lCl) * (exp(-exp(lKe)*input)-exp(-exp(lKa)*input)) / (exp(lKa)-exp(lKe))}.

  If all of the arguments \code{lKe}, \code{lKa}, and \code{lCl} are
  names of objects, the gradient matrix with respect to these names is
  attached as an attribute named \code{gradient}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data( Theoph )
Theoph.1 <- Theoph[ Theoph$Subject == 1, ]
SSfol( Theoph.1$Dose, Theoph.1$Time, -2.5, 0.5, -3 )  # response only
lKe <- -2.5; lKa <- 0.5; lCl <- -3
SSfol( Theoph.1$Dose, Theoph.1$Time, lKe, lKa, lCl ) # response and gradient
getInitial(conc ~ SSfol(Dose, Time, lKe, lKa, lCl), data = Theoph.1)
## Initial values are in fact the converged values
fm1 <- nls(conc ~ SSfol(Dose, Time, lKe, lKa, lCl), data = Theoph.1)
summary(fm1)
}
\keyword{models}
% $Id: SSfpl.Rd,v 1.3 2001/08/13 19:55:13 ripley Exp $
\name{SSfpl}
\title{Four-parameter Logistic Model}
\usage{
SSfpl(input, A, B, xmid, scal)
}
\alias{SSfpl}
\arguments{
 \item{input}{a numeric vector of values at which to evaluate the model.}
 \item{A}{a numeric parameter representing the horizontal asymptote on
   the left side (very small values of \code{input}).}
 \item{B}{a numeric parameter representing the horizontal asymptote on
   the right side (very large values of \code{input}).}
 \item{xmid}{a numeric parameter representing the \code{input} value at the
   inflection point of the curve.  The value of \code{SSfpl} will be
   midway between \code{A} and \code{B} at \code{xmid}.}
 \item{scal}{a numeric scale parameter on the \code{input} axis.}
}
\description{
  This \code{selfStart} model evaluates the four-parameter logistic
  function and its gradient.  It has an \code{initial} attribute that
  will evaluate initial estimates of the parameters \code{A}, \code{B},
  \code{xmid}, and \code{scal} for a given set of data.
}
\value{
  a numeric vector of the same length as \code{input}.  It is the value of
  the expression \code{A+(B-A)/(1+exp((xmid-input)/scal))}.  If all of
  the arguments \code{A}, \code{B}, \code{xmid}, and \code{scal} are
  names of objects, the gradient matrix with respect to these names is
  attached as an attribute named \code{gradient}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data( ChickWeight )
Chick.1 <- ChickWeight[ChickWeight$Chick == 1, ]
SSfpl( Chick.1$Time, 13, 368, 14, 6 )  # response only
A <- 13; B <- 368; xmid <- 14; scal <- 6
SSfpl( Chick.1$Time, A, B, xmid, scal ) # response and gradient
getInitial(weight ~ SSfpl(Time, A, B, xmid, scal), data = Chick.1)
## Initial values are in fact the converged values
fm1 <- nls(weight ~ SSfpl(Time, A, B, xmid, scal), data = Chick.1)
summary(fm1)
\testonly{
  xx <- seq(-0.5, 5, len = 101)
  yy <- 1 + 4 / ( 1 + exp((2-xx)))
  par(mar = c(0, 0, 3.5, 0))
  plot(xx, yy, type = "l", axes = FALSE, ylim = c(0,6), xlim = c(-1, 5),
       xlab = "", ylab = "", lwd = 2,
       main = "Parameters in the SSfpl model")
  usr <- par("usr")
  arrows(usr[1], 0, usr[2], 0, length = 0.1, angle = 25)
  arrows(0, usr[3], 0, usr[4], length = 0.1, angle = 25)
  text(usr[2] - 0.2, 0.1, "x", adj = c(1, 0))
  text(-0.1, usr[4], "y", adj = c(1, 1))
  abline(h = 5, lty = 2, lwd = 0)
  arrows(-0.8, 2.1, -0.8, 0, length = 0.1, angle = 25)
  arrows(-0.8, 2.9, -0.8, 5, length = 0.1, angle = 25)
  text(-0.8, 2.5, expression(phi[1]), adj = c(0.5, 0.5))
  abline(h = 1, lty = 2, lwd = 0)
  arrows(-0.3, 0.25, -0.3, 0, length = 0.07, angle = 25)
  arrows(-0.3, 0.75, -0.3, 1, length = 0.07, angle = 25)
  text(-0.3, 0.5, expression(phi[2]), adj = c(0.5, 0.5))
  segments(2, 0, 2, 3.3, lty = 2, lwd = 0.75)
  text(2, 3.3, expression(phi[3]), adj = c(0.5, 0))
  segments(3, 1+4/(1+exp(-1)) - 0.025, 3, 2.5, lty = 2, lwd = 0.75)
  arrows(2.3, 2.7, 2.0, 2.7, length = 0.08, angle = 25)
  arrows(2.7, 2.7, 3.0, 2.7, length = 0.08, angle = 25)
  text(2.5, 2.7, expression(phi[4]), adj = c(0.5, 0.5))
}
}
\keyword{models}
% $Id: SSgompertz.Rd,v 1.2 2001/03/24 06:57:57 ripley Exp $
\name{SSgompertz}
\title{Gompertz Growth Model}
\usage{
SSgompertz(x, Asym, b2, b3)
}
\alias{SSgompertz}
\arguments{
 \item{x}{a numeric vector of values at which to evaluate the model.}
 \item{Asym}{a numeric parameter representing the asymptote.}
 \item{b2}{a numeric parameter related to the value of the function at
   \code{x = 0}}
 \item{b3}{a numeric parameter related to the scale the \code{x} axis.}
}
\description{
  This \code{selfStart} model evaluates the Gompertz growth model
  and its gradient.  It has an \code{initial} attribute that
  creates initial estimates of the parameters \code{Asym},
  \code{b2}, and \code{b3}.
}
\value{
  a numeric vector of the same length as \code{input}.  It is the value of
  the expression \code{Asym*exp(-b2*b3^x)}.  If all of
  the arguments \code{Asym}, \code{b2}, and \code{b3} are
  names of objects the gradient matrix with respect to these names is attached as
  an attribute named \code{gradient}.
}
\author{Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data(DNase )
DNase.1 <- subset(DNase, Run == 1)
SSlogis(log(DNase.1$conc), 4.5, 2.3, 0.7)  # response only
Asym <- 4.5; b2 <- 2.3; b3 <- 0.7
SSgompertz(log(DNase.1$conc), Asym, b2, b3 ) # response and gradient
getInitial(density ~ SSgompertz(log(conc), Asym, b2, b3),
           data = DNase.1)
## Initial values are in fact the converged values
fm1 <- nls(density ~ SSgompertz(log(conc), Asym, b2, b3),
           data = DNase.1)
summary(fm1)
}
\keyword{models}
% $Id: SSlogis.Rd,v 1.4 2001/08/13 19:55:13 ripley Exp $
\name{SSlogis}
\title{Logistic Model}
\usage{
SSlogis(input, Asym, xmid, scal)
}
\alias{SSlogis}
\arguments{
 \item{input}{a numeric vector of values at which to evaluate the model.}
 \item{Asym}{a numeric parameter representing the asymptote.}
 \item{xmid}{a numeric parameter representing the \code{x} value at the
   inflection point of the curve.  The value of \code{SSlogis} will be
   \code{Asym/2} at \code{xmid}.}
 \item{scal}{a numeric scale parameter on the \code{input} axis.}
}
\description{
  This \code{selfStart} model evaluates the logistic
  function and its gradient.  It has an \code{initial} attribute that
  creates initial estimates of the parameters \code{Asym},
  \code{xmid}, and \code{scal}.
}
\value{
  a numeric vector of the same length as \code{input}.  It is the value of
  the expression \code{Asym/(1+exp((xmid-input)/scal))}.  If all of
  the arguments \code{Asym}, \code{xmid}, and \code{scal} are
  names of objects the gradient matrix with respect to these names is attached as
  an attribute named \code{gradient}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data( ChickWeight )
Chick.1 <- ChickWeight[ChickWeight$Chick == 1, ]
SSlogis( Chick.1$Time, 368, 14, 6 )  # response only
Asym <- 368; xmid <- 14; scal <- 6
SSlogis( Chick.1$Time, Asym, xmid, scal ) # response and gradient
getInitial(weight ~ SSlogis(Time, Asym, xmid, scal), data = Chick.1)
## Initial values are in fact the converged values
fm1 <- nls(weight ~ SSlogis(Time, Asym, xmid, scal), data = Chick.1)
summary(fm1)
\testonly{
  xx <- seq(-0.5, 5, len = 101)
  yy <- 5 / ( 1 + exp((2-xx)))
  par(mar = c(0, 0, 3.5, 0))
  plot(xx, yy, type = "l", axes = FALSE, ylim = c(0,6), xlim = c(-1, 5),
       xlab = "", ylab = "", lwd = 2,
       main = "Parameters in the SSlogis model")
  usr <- par("usr")
  arrows(usr[1], 0, usr[2], 0, length = 0.1, angle = 25)
  arrows(0, usr[3], 0, usr[4], length = 0.1, angle = 25)
  text(usr[2] - 0.2, 0.1, "x", adj = c(1, 0))
  text(-0.1, usr[4], "y", adj = c(1, 1))
  abline(h = 5, lty = 2, lwd = 0)
  arrows(-0.8, 2.1, -0.8, 0, length = 0.1, angle = 25)
  arrows(-0.8, 2.9, -0.8, 5, length = 0.1, angle = 25)
  text(-0.8, 2.5, expression(phi[1]), adj = c(0.5, 0.5))
  segments(2, 0, 2, 4.0, lty = 2, lwd = 0.75)
  text(2, 4.0, expression(phi[2]), adj = c(0.5, 0))
  segments(3, 5/(1+exp(-1)) + 0.025, 3, 4.0, lty = 2, lwd = 0.75)
  arrows(2.3, 3.8, 2.0, 3.8, length = 0.08, angle = 25)
  arrows(2.7, 3.8, 3.0, 3.8, length = 0.08, angle = 25)
  text(2.5, 3.8, expression(phi[3]), adj = c(0.5, 0.5))
}
}
\keyword{models}
% $Id: SSmicmen.Rd,v 1.4 2001/08/13 19:55:13 ripley Exp $
\name{SSmicmen}
\title{Michaelis-Menten Model}
\usage{
SSmicmen(input, Vm, K)
}
\alias{SSmicmen}
\arguments{
 \item{input}{a numeric vector of values at which to evaluate the model.}
 \item{Vm}{a numeric parameter representing the maximum value of the response.}
 \item{K}{a numeric parameter representing the \code{input} value at
   which half the maximum response is attained.  In the field of enzyme
   kinetics this is called the Michaelis parameter.}
}
\description{
  This \code{selfStart} model evaluates the Michaelis-Menten model and
  its gradient.  It has an \code{initial} attribute that
  will evaluate initial estimates of the parameters \code{Vm} and \code{K}
}
\value{
  a numeric vector of the same length as \code{input}.  It is the value of
  the expression \code{Vm*input/(K+input)}.  If both
  the arguments \code{Vm} and \code{K} are
  names of objects, the gradient matrix with respect to these names is
  attached as an attribute named \code{gradient}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}
}
\examples{
data( Puromycin )
PurTrt <- Puromycin[ Puromycin$state == "treated", ]
SSmicmen( PurTrt$conc, 200, 0.05 )  # response only
Vm <- 200; K <- 0.05
SSmicmen( PurTrt$conc, Vm, K ) # response and gradient
getInitial(rate ~ SSmicmen(conc, Vm, K), data = PurTrt)
## Initial values are in fact the converged values
fm1 <- nls(rate ~ SSmicmen(conc, Vm, K), data = PurTrt)
summary( fm1 )
## Alternative call using the subset argument
fm2 <- nls(rate ~ SSmicmen(conc, Vm, K), data = Puromycin,
           subset = state == "treated")
summary(fm2)
\testonly{
  xx <- seq(0, 5, len = 101)
  yy <- 5 * xx/(1+xx)
  par(mar = c(0, 0, 3.5, 0))
  plot(xx, yy, type = "l", axes = FALSE, ylim = c(0,6), xlim = c(-1, 5),
       xlab = "", ylab = "", lwd = 2,
       main = "Parameters in the SSmicmen model")
  usr <- par("usr")
  arrows(usr[1], 0, usr[2], 0, length = 0.1, angle = 25)
  arrows(0, usr[3], 0, usr[4], length = 0.1, angle = 25)
  text(usr[2] - 0.2, 0.1, "x", adj = c(1, 0))
  text(-0.1, usr[4], "y", adj = c(1, 1))
  abline(h = 5, lty = 2, lwd = 0)
  arrows(-0.8, 2.1, -0.8, 0, length = 0.1, angle = 25)
  arrows(-0.8, 2.9, -0.8, 5, length = 0.1, angle = 25)
  text(-0.8, 2.5, expression(phi[1]), adj = c(0.5, 0.5))
  segments(1, 0, 1, 2.7, lty = 2, lwd = 0.75)
  text(1, 2.7, expression(phi[2]), adj = c(0.5, 0))
}
}
\keyword{models}
% $Id: SSweibull.Rd,v 1.2 2001/03/27 16:12:17 bates Exp $
\name{SSweibull}
\title{Weibull growth curve model}
\usage{
SSweibull(x, Asym, Drop, lrc, pwr)
}
\alias{SSweibull}
\arguments{
 \item{x}{a numeric vector of values at which to evaluate the model.}
 \item{Asym}{a numeric parameter representing the horizontal asymptote on
   the right side (very small values of \code{x}).}
 \item{Drop}{a numeric parameter representing the change from
   \code{Asym} to the \code{y} intercept.}
 \item{lrc}{a numeric parameter representing the natural logarithm of
   the rate constant.}
 \item{pwr}{a numeric parameter representing the power to which \code{x}
   is raised.}
}
\description{
  This \code{selfStart} model evaluates the Weibull model for growth
  curve data and its gradient.  It has an \code{initial} attribute that
  will evaluate initial estimates of the parameters \code{Asym}, \code{Drop},
  \code{lrc}, and \code{pwr} for a given set of data.
}
\value{
  a numeric vector of the same length as \code{x}.  It is the value of
  the expression \code{Asym-Drop*exp(-exp(lrc)*x^pwr)}.  If all of
  the arguments \code{Asym}, \code{Drop}, \code{lrc}, and \code{pwr} are
  names of objects, the gradient matrix with respect to these names is
  attached as an attribute named \code{gradient}.
}
\details{
  This model is a generalization of the \code{\link{SSasymp}} model in
  that it reduces to \code{SSasymp} when \code{pwr} is unity.
  }
\author{Douglas Bates}
\references{
  Ratkowsky, David A. (1983), \emph{Nonlinear Regression Modeling},
  Dekker. (section 4.4.5)
}
\seealso{\code{\link{nls}}, \code{\link{selfStart}}, \code{\link{SSasymp}}
}
\examples{
data(ChickWeight)
Chick.6 <- subset(ChickWeight, (Chick == 6) & (Time > 0))
SSweibull(Chick.6$Time, 160, 115, -5.5, 2.5 )  # response only
Asym <- 160; Drop <- 115; lrc <- -5.5; pwr <- 2.5
SSweibull(Chick.6$Time, Asym, Drop, lrc, pwr)  # response and gradient
getInitial(weight ~ SSweibull(Time, Asym, Drop, lrc, pwr), data = Chick.6)
## Initial values are in fact the converged values
fm1 <- nls(weight ~ SSweibull(Time, Asym, Drop, lrc, pwr), data = Chick.6)
summary(fm1)
}
\keyword{models}
\name{Theoph}
\docType{data}
\alias{Theoph}
\title{Pharmacokinetics of theophylline}
\description{
  The \code{Theoph} data frame has 132 rows and 5 columns of data from
  an experiment on the pharmacokinetics of theophylline.}
\usage{data(Theoph)}
\format{
  This data frame contains the following columns:
  \describe{
    \item{Subject}{
      an ordered factor with levels \code{1}, \dots, \code{12}
      identifying the subject on whom the observation was made.  The
      ordering is by increasing maximum concentration of theophylline
      observed.
    }
    \item{Wt}{
      weight of the subject (kg).
    }
    \item{Dose}{
      dose of theophylline administered orally to the subject (mg/kg).
    }
    \item{Time}{
      time since drug administration when the sample was drawn (hr).
    }
    \item{conc}{
      theophylline concentration in the sample (mg/L).
    }
  }
}
\details{
  Boeckmann, Sheiner and Beal (1994) report data from a study by
  Dr. Robert Upton of the kinetics of the anti-asthmatic drug
  theophylline.  Twelve subjects were given oral doses of theophylline
  then serum concentrations were measured at 11 time points over the
  next 25 hours.

  These data are analyzed in Davidian and Giltinan (1995) and Pinheiro
  and Bates (2000) using a two-compartment open pharmacokinetic model,
  for which a self-starting model function, \code{SSfol}, is available.

}
\source{
  Boeckmann, A. J., Sheiner, L. B. and Beal, S. L. (1994), \emph{NONMEM
    Users Guide: Part V}, NONMEM Project Group, University of
  California, San Francisco.
    
  Davidian, M. and Giltinan, D. M. (1995) \emph{Nonlinear Models for
    Repeated Measurement Data}, Chapman & Hall (section 5.5, p. 145 and
  section 6.6, p. 176)

  Pinheiro, J. C. and Bates, D. M. (2000) \emph{Mixed-effects Models in
    S and S-PLUS}, Springer (Appendix A.29)
}
\seealso{\code{\link{SSfol}}}
\examples{
data(Theoph)
coplot(conc ~ Time | Subject, data = Theoph, show = FALSE)
Theoph.4 <- subset(Theoph, Subject == 4)
fm1 <- nls(conc ~ SSfol(Dose, Time, lKe, lKa, lCl),
           data = Theoph.4)
summary(fm1)
plot(conc ~ Time, data = Theoph.4,
     xlab = "Time since drug administration (hr)",
     ylab = "Theophylline concentration (mg/L)",
     main = "Observed concentrations and fitted model",
     sub  = "Theophylline data - Subject 4 only",
     las = 1, col = 4)
xvals <- seq(0, par("usr")[2], len = 55)
lines(xvals, predict(fm1, newdata = list(Time = xvals)),
      col = 4)
}
\keyword{datasets}
% $Id: asOneSidedFormula.Rd,v 1.3 2001/03/24 06:57:57 ripley Exp $
\name{asOneSidedFormula}
\title{Convert to One-Sided Formula}
\usage{
asOneSidedFormula(object)
}
\alias{asOneSidedFormula}
\arguments{
 \item{object}{a one-sided formula, an expression, a numeric value, or a
   character string.}
}
\description{
  Names, expressions, numeric values, and character strings are converted to
  one-sided formulas. If \code{object} is a formula, it must be
  one-sided, in which case it is returned unaltered.
}
\value{
  a one-sided formula representing \code{object}
}
\author{Jose Pinheiro and Douglas Bates}

\seealso{\code{\link{formula}}}

\examples{
asOneSidedFormula("age")
asOneSidedFormula(~ age)
}
\keyword{models}
\name{clearNames}
\alias{clearNames}
\title{Remove the Names from an Object}
\usage{
clearNames(object)
}
\arguments{
 \item{object}{ an object that may have a \code{names} attribute }
}
\description{
 This function sets the \code{names} attribute of \code{object} to
 \code{NULL} and returns the object.
}
\value{
  An object similar to \code{object} but without names.
}
\author{ Douglas Bates and Saikat DebRoy}
\seealso{\code{\link{setNames}}}
\examples{
data( women )
lapply( women, mean )               # has a names attribute
clearNames( lapply( women, mean ) ) # removes the names
}
\keyword{list}
% $Id: formula.nls.Rd,v 1.5 2001/08/16 09:24:26 ripley Exp $
\name{formula.nls}
\alias{formula.nls}
\title{Extract Model Formula from nls Object}
\usage{
\method{formula}{nls}(x, ...)
}
\arguments{
 \item{x}{an object inheriting from class \code{nls}, representing
   a nonlinear least squares fit.}
 \item{\dots}{further arguments passed to or from other methods.}
}
\description{
  Returns the model used to fit \code{object}. 
}
\value{
  a formula representing the model used to obtain \code{object}.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, \code{\link{formula}}}
\examples{
data(Orange)
fm1 <- nls(circumference ~ A/(1+exp((B-age)/C)), Orange,
  start = list(A=160, B=700, C = 350))
formula(fm1)
}
\keyword{models}
% $Id: getInitial.Rd,v 1.7 2001/03/24 06:57:57 ripley Exp $
\name{getInitial}
\title{Get Initial Parameter Estimates}
\alias{getInitial}
\alias{getInitial.default}
\alias{getInitial.formula}
\alias{getInitial.selfStart}
\usage{
getInitial(object, data, ...)
}
\arguments{
  \item{object}{a formula or a \code{selfStart} model that defines a
    nonlinear regression model}
  \item{data}{a data frame in which the expressions in the formula or
    arguments to the \code{selfStart} model can be evaluated}
  \item{\dots}{optional additional arguments}
}
\description{
  This function evaluates initial parameter estimates for a nonlinear
  regression model.  If \code{data} is a parameterized data frame or
  \code{pframe} object, its \code{parameters} attribute is returned.
  Otherwise the object is examined to see if it contains a call to a
  \code{selfStart} object whose \code{initial} attribute can be
  evaluated.
}
\value{
    A named numeric vector or list of starting estimates for the
    parameters.  The construction of many \code{selfStart} models is such
    that these "starting" estimates are, in fact, the converged parameter
    estimates.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{nls}}, %\code{\link{nlsList}},
    \code{\link{selfStart}},
    \code{\link{selfStart.default}}, \code{\link{selfStart.formula}}
}
\examples{
data(Puromycin)
PurTrt <- Puromycin[ Puromycin$state == "treated", ]
getInitial( rate ~ SSmicmen( conc, Vm, K ), PurTrt )
}
\keyword{models}
\keyword{nonlinear}
\keyword{manip}
\name{nls}
\alias{nls}
\alias{anova.nls}
\alias{anovalist.nls}
\alias{coef.nls}
\alias{deviance.nls}
\alias{df.residual.nls}
\alias{fitted.nls}
\alias{logLik.nls}
\alias{print.nls}
\alias{residuals.nls}
\alias{summary.nls}
\alias{print.summary.nls}
\alias{weights.nls}
\alias{AIC.nls}
\title{Nonlinear Least Squares}
\synopsis{
nls(formula, data = parent.frame(), start, control,
    algorithm = "default", trace = FALSE, subset,
    weights, na.action)
}
\usage{
nls(formula, data = parent.frame(), start, control = nls.control(),
    algorithm = "default", trace = FALSE, subset,
    weights, na.action)
}
\arguments{
 \item{formula}{a nonlinear model formula including variables and parameters}
 \item{data}{an optional data frame in which to evaluate the variables in
     \code{formula}}
 \item{start}{a named list or named numeric vector of starting estimates}
 \item{control}{an optional list of control settings.  See
     \code{nls.control} for the names of the settable control values and
     their effect.}
 \item{algorithm}{character string specifying the algorithm to use.
     The default algorithm is a Gauss-Newton algorithm. The other 
     alternative is "plinear", the Golub-Pereyra algorithm for
     partially linear least-squares models.}
 \item{trace}{logical value indicating if a trace of the iteration
     progress should be printed.  Default is \code{FALSE}.  If
     \code{TRUE} the residual sum-of-squares and the parameter values
     are printed at the conclusion of each iteration.  When the
     \code{"plinear"} algorithm is used, the conditional estimates of
     the linear parameters are printed after the nonlinear parameters.}
 \item{subset}{an optional vector specifying a subset of observations
   to be used in the fitting process.}
 \item{weights}{an optional numeric vector of (fixed) weights.  When
   present, the objective function is weighted least squares. \emph{not
     yet implemented}}
\item{na.action}{a function which indicates what should happen
    when the data contain \code{NA}s.}
}
\description{
  Determine the nonlinear least squares estimates of the nonlinear model
  parameters and return a class \code{nls} object.
}
\details{
  \bold{Do not use \code{nls} on artificial "zero-residual" data.}

  The \code{nls} function uses a relative-offset convergence criterion
  that compares the numerical imprecision at the current parameter
  estimates to the residual sum-of-squares.  This performs well on data of
  the form \deqn{y=f(x,\theta)+\epsilon}{y = f(x, theta) + eps} (with
  \code{var(eps) > 0}).  It
  fails to indicate convergence on data of the form
  \deqn{y=f(x,\theta)}{y = f(x, theta)} because the criterion amounts to
  comparing two components of the round-off error.  If you wish to test
  \code{nls} on artificial data please add a noise component, as shown
  in the example below.
  
  An \code{nls} object is a type of fitted model object.  It has methods
  for the generic functions \code{coef}, \code{formula}, \code{resid},
  \code{print}, \code{summary}, \code{AIC}, and \code{fitted}.
}
\value{
  A list of
  \item{m}{an \code{nlsModel} object incorporating the model}
  \item{data}{the expression that was passed to \code{nls} as the data
    argument.  The actual data values are present in the environment of
    the \code{m} component.}
}
\references{
  Bates, D.M. and Watts, D.G. (1988)
  \emph{Nonlinear Regression Analysis and Its Applications},
  Wiley
}
\author{Douglas M. Bates and Saikat DebRoy}
\seealso{\code{\link{nlsModel}}}
\examples{
data( DNase )
DNase1 <- DNase[ DNase$Run == 1, ]
## using a selfStart model
fm1DNase1 <- nls( density ~ SSlogis( log(conc), Asym, xmid, scal ), DNase1 )
summary( fm1DNase1 )
## using conditional linearity
fm2DNase1 <- nls( density ~ 1/(1 + exp(( xmid - log(conc) )/scal ) ),
                  data = DNase1,
                  start = list( xmid = 0, scal = 1 ),
                  alg = "plinear", trace = TRUE )
summary( fm2DNase1 )
## without conditional linearity
fm3DNase1 <- nls( density ~ Asym/(1 + exp(( xmid - log(conc) )/scal ) ),
                  data = DNase1,
                  start = list( Asym = 3, xmid = 0, scal = 1 ),
                  trace = TRUE )
summary( fm3DNase1 )
## weighted nonlinear regression
data(Puromycin)
Treated <- Puromycin[Puromycin$state == "treated", ]
weighted.MM <- function(resp, conc, Vm, K)
{
    ## Purpose: exactly as white book p.451 -- RHS for nls()
    ##  Weighted version of Michaelis-Menten model
    ## -------------------------------------------------------------------------
    ## Arguments: `y', `x' and the two parameters (see book)
    ## -------------------------------------------------------------------------
    ## Author: Martin Maechler, Date: 23 Mar 2001, 18:48

    pred <- (Vm * conc)/(K + conc)
    (resp - pred) / sqrt(pred)
}

Pur.wt <- nls( ~ weighted.MM(rate, conc, Vm, K), data = Treated,
              start = list(Vm = 200, K = 0.1),
              trace = TRUE)
}
## The two examples below show that you can fit a model to
## artificial data with noise but not to artificial data
## without noise.
x = 1:10
y = x                                  # perfect fit
yeps = y + rnorm(length(y), sd = 0.01) # added noise
nls(yeps ~ a + b*x, start = list(a = 0.12345, b = 0.54321),
     trace = TRUE)
\dontrun{
nls(y ~ a + b*x, start = list(a = 0.12345, b = 0.54321),
     trace = TRUE)
}       
}
\keyword{nonlinear}
\keyword{regression}
\keyword{models}
\name{nls.control}
\alias{nls.control}
\title{Control the Iterations in nls}
\description{
    Allow the user to set some characteristics of the \code{nls}
    nonlinear least squares algorithm.
}
\usage{
nls.control(maxiter=50, tol=1e-05, minFactor=1/1024)
}
\arguments{
  \item{maxiter}{A positive integer specifying the maximum number of
    iterations allowed.}
  \item{tol}{A positive numeric value specifying the tolerance level for
    the relative offset convergence criterion.}
  \item{minFactor}{A positive numeric value specifying the minimum
    step-size factor allowed on any step in the iteration.  The
    increment is calculated with a Gauss-Newton algorithm and
    successively halved until the residual sum of squares has been
    decreased or until the step-size factor has been reduced below this
    limit.}
}
\value{
  A \code{list} with exactly three components:
  \item{maxiter}{}
  \item{tol}{}
  \item{minFactor}{}
}
\references{
  Bates and Watts (1988),
  \emph{Nonlinear Regression Analysis and Its Applications}, Wiley.
}
\author{Douglas Bates and Saikat DebRoy}
\seealso{\code{\link{nls}}}
\examples{
nls.control(minFactor = 1/2048)
}
\keyword{nonlinear}
\keyword{regression}
\keyword{models}
\name{nlsModel}
\alias{nlsModel}
\alias{nlsModel.plinear}
\title{Create an nlsModel Object}
\usage{
nlsModel(form, data, start)
}
\arguments{
 \item{form}{a nonlinear model formula}
 \item{data}{a data frame or a list in which to evaluate the variables
     from the model formula}
 \item{start}{a named list or named numeric vector of starting
   estimates for the parameters in the model}
}
\description{
  This is the constructor for \code{nlsModel} objects, which are
  function closures for several functions in a list.  The closure
  includes a nonlinear model formula, data values for the formula, as
  well as parameters and their values.
}
\details{
  An \code{nlsModel} object is primarily used within the \code{nls}
  function.  It encapsulates the model, the data, and the parameters in
  an environment and provides several methods to access characteristics
  of the model.  It forms an important component of the object returned
  by the \code{nls} function.
}
\value{
    The value is a list of functions that share a common environment.
    \item{resid}{returns the residual vector evaluated at the current
	parameter values}
    \item{fitted}{returns the fitted responses and their gradient at the
	current parameter values}
    \item{formula}{returns the model formula}
    \item{deviance}{returns the residual sum-of-squares at the current
	parameter values}
    \item{gradient}{returns the gradient of the model function at the
	current parameter values}
    \item{conv}{returns the relative-offset convergence criterion
	evaluated at the current parmeter values}
    \item{incr}{returns the parameter increment calculated according to
	the Gauss-Newton formula}
    \item{setPars}{a function with one argument, \code{pars}.  It sets the
	parameter values for the \code{nlsModel} object and returns a
	logical value denoting a singular gradient array.}
    \item{getPars}{returns the current value of the model parameters as a
	numeric vector}
    \item{getAllPars}{returns the current value of the model parameters as a
	numeric vector}
    \item{getEnv}{returns the environment shared by these functions}
    \item{trace}{the function that is called at each iteration if
	tracing is enabled}
    \item{Rmat}{the upper triangular factor of the gradient array at the
	current parameter values}
    \item{predict}{takes as argument \code{newdata},a \code{data.frame} and
	returns the predicted response for \code{newdata}.}
}
\references{Bates, D.M. and Watts, D.G. (1988), \emph{Nonlinear Regression Analysis
    and Its Applications}, Wiley}
\author{Douglas M. Bates and Saikat DebRoy}
\seealso{\code{\link{nls}}}
\examples{
data( DNase )
DNase1 <- DNase[ DNase$Run == 1, ]
mod <-
 nlsModel(density ~ SSlogis( log(conc), Asym, xmid, scal ),
          DNase1, list( Asym = 3, xmid = 0, scal = 1 ))
mod$getPars()     # returns the parameters as a list
mod$deviance()    # returns the residual sum-of-squares
mod$resid()       # returns the residual vector and the gradient
mod$incr()        # returns the suggested increment
mod$setPars( unlist(mod$getPars()) + mod$incr() )  # set new parameter values
mod$getPars()     # check the parameters have changed
mod$deviance()    # see if the parameter increment was successful
mod$trace()       # check the tracing
mod$Rmat()        # R matrix from the QR decomposition of the gradient
}
\keyword{nonlinear}
\keyword{models}
\name{numericDeriv}
\alias{numericDeriv}
\title{Evaluate derivatives numerically}
\description{
    \code{numericDeriv} numerically evaluates the gradient of an expression.
}
\usage{
numericDeriv(expr, theta, rho=parent.frame())
}
\arguments{
  \item{expr}{The expression to be differentiated.  The value of this
      expression should be a numeric vector.}
  \item{theta}{A character vector of names of variables used in \code{expr}}
  \item{rho}{An environment containing all the variables needed to
      evaluate \code{expr}}
}
\details{
    This is a front end to the C function \code{numeric_deriv}, which is
    described in \emph{Writing R Extensions}.
}
\value{
    The value of \code{eval(expr, env = rho)} plus a matrix
    attribute called \code{gradient}.  The columns of this matrix are
    the derivatives of the value with respect to the variables listed in
    \code{theta}.
}
\author{Saikat DebRoy \email{saikat@stat.wisc.edu}}
\examples{
myenv <- new.env()
assign("mean", 0., env = myenv)
assign("sd", 1., env = myenv)
assign("x", seq(-3., 3., len = 31), env = myenv)
numericDeriv(quote(pnorm(x, mean, sd)), c("mean", "sd"), myenv)
}
\keyword{models}

\name{plot.profile.nls}
\alias{plot.profile.nls}
\title{Plot a profile.nls Object}
\description{
  Displays a series of plots of the profile t function and interpolated
  confidence intervals for the parameters in a nonlinear regression
  model that has been fit with \code{nls} and profiled with
  \code{profile.nls}.
}
\usage{
\method{plot}{profile.nls}(x, levels, conf= c(99, 95, 90, 80, 50)/100,
     nseg = 50, absVal =TRUE, ...)
}
\arguments{
 \item{x}{an object of class \code{"profile.nls"} }
 \item{levels}{levels, on the scale of the absolute value of a t
     statistic, at which to interpolate intervals.  Usually \code{conf}
     is used instead of giving \code{levels} explicitly.}
 \item{conf}{a numeric vector of confidence levels for profile-based
     confidence intervals on the parameters.  Defaults to \code{c(0.99,
	 0.95, 0.90, 0.80, 0.50).}}
 \item{nseg}{an integer value giving the number of segments to use in
     the spline interpolation of the profile t curves. Defaults to 50.}
 \item{absVal}{a logical value indicating whether or not the plots
     should be on the scale of the absolute value of the profile t.
     Defaults to \code{TRUE}.} 
 \item{\dots}{other arguments to the \code{plot} function can be passed here.}
}
\references{
  Bates, D.M. and Watts, D.G. (1988),
  \emph{Nonlinear Regression Analysis and Its Applications},
  Wiley (chapter 6)
}
\author{Douglas M. Bates and Saikat DebRoy}
\seealso{
  \code{\link{nls}},
  \code{\link{profile}},
  \code{\link{profile.nls}}
}
\examples{
data( BOD )
# obtain the fitted object
fm1 <- nls(demand ~ SSasympOrig( Time, A, lrc ), data = BOD)
# get the profile for the fitted model
pr1 <- profile( fm1 )
opar <- par(mfrow = c(2,2), oma = c(1.1, 0, 1.1, 0), las = 1)
plot(pr1, conf = c(95, 90, 80, 50)/100)
plot(pr1, conf = c(95, 90, 80, 50)/100, absVal = FALSE)
mtext("Confidence intervals based on the profile sum of squares",
      side = 3, outer = TRUE)
mtext("BOD data - confidence levels of 50\%, 80\%, 90\% and 95\%",
      side = 1, outer = TRUE)
par(opar)
}
\keyword{nonlinear}
\keyword{regression}
\keyword{models}
\name{predict.nls}
\title{Predicting from Nonlinear Least Squares Fits}
\alias{predict.nls}
\usage{
\method{predict}{nls}(object, newdata , se.fit = FALSE, scale = NULL, df = Inf, 
              interval = c("none", "confidence", "prediction"),
              level = 0.95, ...)
}
\description{
  \code{predict.nls} produces predicted values, obtained by evaluating
  the regression function in the frame \code{newdata}.  If the logical
  \code{se.fit} is \code{TRUE}, standard errors of the predictions are
  calculated.  If the numeric argument \code{scale} is set (with
  optional \code{df}), it is used as the residual standard deviation in
  the computation of the standard errors, otherwise this is extracted
  from the model fit.  Setting \code{intervals} specifies computation of
  confidence or prediction (tolerance) intervals at the specified
  \code{level}.

  At present \code{se.fit} and \code{interval} are ignored.
}
\arguments{
 \item{object}{An object that inherits from class \code{nls}.}
 \item{newdata}{A named list or data frame with values of the input
     variables for the model in \code{object}.  If \code{newdata} is
     missing the fitted values at the original data points are returned.}
 \item{se.fit}{A logical value indicating if the standard errors of the
     predictions should be calculated.  Defaults to \code{FALSE}.  At
     present this argument is ignored.}
 \item{scale}{A numeric scalar.  If it is set (with optional
     \code{df}), it is used as the residual standard deviation in the
     computation of the standard errors, otherwise this information is
     extracted from the model fit. At present this argument is ignored.}
 \item{df}{A positive numeric scalar giving the number of degrees of
     freedom for the \code{scale} estimate. At present this argument is
     ignored.}
 \item{interval}{A character string indicating if prediction intervals
     or a confidence interval on the mean responses are to be
     calculated. At present this argument is ignored.}
 \item{level}{A numeric scalar between 0 and 1 giving the confidence
     level for the intervals (if any) to be calculated.  At present
     this argument is ignored.} 
 \item{\dots}{Additional optional arguments.  At present no optional
     arguments are used.}
}
\value{
  \code{predict.nls} produces a vector of predictions or a matrix of
  predictions and bounds with column names \code{fit}, \code{lwr}, and
  \code{upr} if \code{interval} is set.  If \code{se.fit} is
  \code{TRUE}, a list with the following components is returned:

  \item{fit}{vector or matrix as above}
  \item{se.fit}{standard error of predictions}
  \item{residual.scale}{residual standard deviations}
  \item{df}{degrees of freedom for residual}
}
\seealso{
  The model fitting function \code{\link{nls}},
  \code{\link{predict}}.
}
\examples{
data( BOD )
fm <- nls(demand ~ SSasympOrig(Time, A, lrc), data = BOD)
predict(fm)              # fitted values at observed times
## Form data plot and smooth line for the predictions
opar <- par(las = 1)
plot(demand ~ Time, data = BOD, col = 4,
     main = "BOD data and fitted first-order curve",
     xlim = c(0,7), ylim = c(0, 20) )
tt <- seq(0, 8, length = 101)
lines(tt, predict(fm, list(Time = tt)))
par(opar)
}
\keyword{nonlinear}
\keyword{regression}
\keyword{models}
% $Id: profile.nls.Rd,v 1.7 2002/01/17 17:02:25 ripley Exp $
\name{profile.nls}
\alias{profile.nls}
\title{ Method for Profiling nls Objects}
\usage{
\method{profile}{nls}(fitted, which=1:npar, maxpts=100, alphamax=0.01,
        delta.t=cutoff/5, ...)
}
\arguments{
  \item{fitted}{ the original fitted model object.}
  \item{which}{ the original model parameters which should be
    profiled. By default, all parameters are profiled.}
  \item{maxpts}{ maximum number of points to be used for profiling each
    parameter.}
  \item{alphamax}{ maximum significance level allowed for the profile
    t-statistics.}
  \item{delta.t}{ suggested change on the scale of the profile
    t-statistics. Default value chosen to allow profiling at about
    10 parameter values.}
  \item{\dots}{further arguments passed to or from other methods.}
}
\description{
  Investigates behavior of the log-likelihood function near the solution
  represented by \code{fitted}.
}
\value{
  A list with an element for each parameter being profiled. The elements
  are data-frames with two variables 
  \item{par.vals}{ a matrix of parameter values for each fitted model.}
  \item{tau}{ The profile t-statistics.}
}
\details{
  The profile t-statistics is defined as the square root of change in
  sum-of-squares divided by residual standard error with an
  appropriate sign.
}
\references{
  Bates, D.M. and Watts, D.G. (1988), \emph{Nonlinear Regression Analysis
	and Its Applications}, Wiley (chapter 6)}
\author{Douglas M. Bates and Saikat DebRoy}
\seealso{\code{\link{nls}}, \code{\link{profile}},
    \code{\link{profiler.nls}}, \code{\link{plot.profile.nls}}
}
\examples{
data( BOD )
# obtain the fitted object
fm1 <- nls(demand ~ SSasympOrig( Time, A, lrc ), data = BOD)
# get the profile for the fitted model
pr1 <- profile( fm1 )
# profiled values for the two parameters
pr1$A
pr1$lrc
}
\keyword{nonlinear}
\keyword{regression}
\keyword{models}
% $Id: profiler.Rd,v 1.4 2000/06/27 22:26:18 pd Exp $
\name{profiler}
\alias{profiler}
\title{ Constructor for Profiler Objects for Nonlinear Models}
\usage{
profiler(fitted, ...)
}
\arguments{
 \item{fitted}{ the original fitted model object.}
 \item{\dots}{  Additional parameters. See documentation on individual
     methods.}
}
\description{
    Create a profiler object for the model object \code{fitted}.
}
\value{
    An object of class \code{"profiler"} which is a list with function
    elements
    \item{getFittedPars()}{
	the parameters in \code{fitted}
    }
    \item{setDefault(varying, params)}{
	this is used for changing the default settings for
	profiling. In absence of both parameters, the default is set
	to the original fitted parameters with all parameters
	varying. The arguments are

	\code{varying}: a logical, integer or character vector
	giving parameters to be varied.
	\code{params}: the default value at which profiling is to
	take place.
    }
    \item{getProfile(varying, params)}{
	this can be used in conjunction with \code{setDefault}
	without any arguments. Alternatively, the parameters to be
	varied and the values for fixed parameters can be specified
	using the arguments. The arguments are

	\code{varying}: a logical vector giving parameters to be
	varied. This can be omitted if params is a named list or
	numeric vector.

	\code{params}: values for parameters to be held fixed.

        It returns a list with elements
    
	\code{parameters}: the parameter values for the profiled
	optimum.

	\code{fstat}: a profile statistics. See individual methods
	for details.

	\code{varying}: a logical vector indicating parameters
	    which were varied.
    }
}
\author{Douglas M. Bates and Saikat DebRoy}
\seealso{\code{\link{profiler.nls}}, \code{\link{profile}}}
\examples{
# see documentation on individual methods
}
\keyword{nonlinear}
\keyword{models}
% $Id: profiler.nls.Rd,v 1.7 2001/08/25 22:17:32 hornik Exp $
\name{profiler.nls}
\alias{profiler.nls}
\title{ Constructor for Profiler Objects from nls Objects}
\description{
  Create a profiler object for the model object \code{fitted} of class
  \code{\link{nls}}.
}
\usage{
\method{profiler}{nls}(fitted, \dots)
}
\arguments{
  \item{fitted}{the original fitted model object of class
    \code{\link{nls}}.}
  \item{\dots}{  Additional parameters. None are used.}
}
\value{
  An object of class \code{profiler.nls} which is a list with function
  elements
  \item{getFittedModel()}{
    the \code{\link{nlsModel}} object corresponding to \code{fitted}
  }
  \item{getFittedPars()}{
    See documentation for \code{\link{profiler}}
  }
  \item{setDefault(varying, params)}{
    See documentation for \code{\link{profiler}}
  }
  \item{getProfile(varying, params)}{
    In the returned list, \code{fstat} is the ratio of change in
    sum-of-squares and the residual standard error.
    
    For other details, see documentation for \code{\link{profiler}}
  }
}
\section{WARNING}{
  When using setDefault and getProfile together, the internal state of
  the fitted model may get changed. So after completing the profiling
  for a parameter, the internal states should be restored by a call to
  setDefault without any arguments. For example see below or the source
  for \code{\link{profile.nls}}.
}
\references{
  Bates, D.M. and Watts, D.G. (1988),
  \emph{Nonlinear Regression Analysis and Its Applications},
  Wiley
}
\author{Douglas M. Bates and Saikat DebRoy}
\seealso{
  \code{\link{nls}},
  \code{\link{nlsModel}},
  \code{\link{profiler}},
  \code{\link{profile.nls}}
}
\examples{
data( BOD )
## obtain the fitted object
fm1 <- nls(demand ~ SSasympOrig( Time, A, lrc ), data = BOD)
## get the profile for the fitted model
prof1 <- profiler( fm1 )
## profile with A fixed at 16.0
prof1$getProfile(c(FALSE, TRUE), 16.0)
## vary lrc
prof1$setDefault(varying = c(FALSE, TRUE))
## fix A at 14.0 and starting estimate of lrc at -0.2
prof1$setDefault(params = c(14.0, -0.2))
## and get the profile
prof1$getProfile()
## finally, set defaults back to original estimates
prof1$setDefault()
}
\keyword{nonlinear}
\keyword{regression}
\keyword{models}
% $Id: selfStart.Rd,v 1.2 2001/08/13 21:41:48 ripley Exp $
\name{selfStart}
\title{Construct Self-starting Nonlinear Models}
\usage{
selfStart(model, initial, parameters, template)
}
\alias{selfStart}
\description{
  This function is generic; methods functions can be written to handle
  specific classes of objects. Available methods include
  \code{selfStart.default} and \code{selfStart.formula}.
  See the documentation on the appropriate method function.
}
\arguments{
 \item{model}{a function object defining a nonlinear model.}
 \item{initial}{a function object, taking three arguments: \code{mCall},
   \code{data}, and \code{LHS}, 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}.}
 \item{parameters, template}{arguments used by some methods..}
}
\value{
  a function object of the \code{selfStart} class.
}
\author{Jose Pinheiro and Douglas Bates}

\seealso{\code{\link{selfStart.default}}, \code{\link{selfStart.formula}}
}
\examples{
## see documentation for the methods
}    
\keyword{models}
% $Id: selfStart.default.Rd,v 1.2 2001/03/24 06:57:57 ripley Exp $
\name{selfStart.default}
\title{Construct Self-starting Nonlinear Models}
\usage{
selfStart(model, initial, parameters, template)
}
\alias{selfStart.default}
\arguments{
 \item{model}{a function object defining a nonlinear model.}
 \item{initial}{a function object, taking three arguments: \code{mCall},
   \code{data}, and \code{LHS}, 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}.}
 \item{parameters, template}{these arguments are included for
     consistency with the generic function, but are not used
     in the \code{default} method. See the documentation on
   \code{selfStart.formula}.}
}
\description{
  A method for the generic function `selfStart' for formula objects.
}
\value{
  a function object of class \code{selfStart}, corresponding to a
  self-starting nonlinear model function. 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{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{selfStart.formula}}}
\examples{
# `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)
}
}
\keyword{models}


% $Id: selfStart.formula.Rd,v 1.2 2001/03/24 06:57:57 ripley Exp $
\name{selfStart.formula}
\title{Construct Self-starting Nonlinear Models}
\usage{
selfStart(model, initial, parameters, template)
}
\alias{selfStart.formula}
\arguments{
    \item{model}{a nonlinear formula object of the form \code{~expression}.}
    \item{initial}{a function object, taking three arguments: \code{mCall},
	\code{data}, and \code{LHS}, 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}.}
    \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.}
}
\description{
  A method for the generic function `selfStart' for formula objects.
}
\value{
  a function object of class \code{selfStart}, obtained by applying
  \code{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{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{selfStart.default}}, \code{\link{deriv}}
}
\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"))
}

\keyword{models}


\name{setNames}
\alias{setNames}
\title{Set the Names in an Object}
\usage{
setNames(object, nm)
}
\arguments{
 \item{object}{an object for which a \code{names} attribute will be meaningful }
 \item{nm}{a character vector of names to assign to the object}
}
\description{
  This is a convenience function that sets the names on an object and
  returns the object.  It is most useful at the end of a function
  definition where one is creating the object to be returned and would
  prefer not to store it under a name just so the names can be assigned.
}
\value{
  An object of the same sort as \code{object} with the new names assigned.
}
\author{Douglas M. Bates and Saikat DebRoy }
\seealso{\code{\link{clearNames}}}
\examples{
setNames( 1:3, c("foo", "bar", "baz") )
# this is just a short form of
tmp <- 1:3
names(tmp) <-  c("foo", "bar", "baz")
tmp
}
\keyword{list}
% $Id: sortedXyData.Rd,v 1.3 2001/03/24 06:57:57 ripley Exp $
\name{sortedXyData}
\title{Create a sortedXyData object}
\alias{sortedXyData}
\alias{sortedXyData.default}
\usage{
sortedXyData(x, y, data)
}
\arguments{
 \item{x}{ a numeric vector or an expression that will evaluate in
   \code{data} to a numeric vector }
 \item{y}{ a numeric vector or an expression that will evaluate in
   \code{data} to a numeric vector }
 \item{data}{ an optional data frame in which to evaluate expressions
   for \code{x} and \code{y}, if they are given as expressions }
}
\description{
  This is a constructor function for the class of \code{sortedXyData}
  objects.  These objects are mostly used in the \code{initial}
  function for a self-starting nonlinear regression model, which will be
  of the \code{selfStart} class.
}
\value{
  A \code{sortedXyData} object. This is a data frame with exactly
  two numeric columns, named \code{x} and \code{y}.  The rows are
  sorted so the \code{x} column is in increasing order.  Duplicate
  \code{x} values are eliminated by averaging the corresponding \code{y}
  values.
}
\author{Jose Pinheiro and Douglas Bates}
\seealso{\code{\link{selfStart}}, \code{\link{NLSstClosestX}},
  \code{\link{NLSstLfAsymptote}}, \code{\link{NLSstRtAsymptote}}
}
\examples{
data( DNase )
DNase.2 <- DNase[ DNase$Run == "2", ]
sortedXyData( expression(log(conc)), expression(density), DNase.2 )
}
\keyword{manip}
