\HeaderA{add1}{Add or Drop All Possible Single Terms to a Model}{add1}
\methaliasA{add1.default}{add1}{add1.default}
\methaliasA{add1.glm}{add1}{add1.glm}
\methaliasA{add1.lm}{add1}{add1.lm}
\aliasA{drop1}{add1}{drop1}
\methaliasA{drop1.default}{add1}{drop1.default}
\methaliasA{drop1.glm}{add1}{drop1.glm}
\methaliasA{drop1.lm}{add1}{drop1.lm}
\keyword{models}{add1}
\begin{Description}\relax
Compute all the single terms in the \code{scope} argument that can be
added to or dropped from the model, fit those models and compute a
table of the changes in fit.
\end{Description}
\begin{Usage}
\begin{verbatim}
add1(object, scope, ...)

## Default S3 method:
add1(object, scope, scale = 0, test = c("none", "Chisq"),
     k = 2, trace = FALSE, ...)

## S3 method for class 'lm':
add1(object, scope, scale = 0, test = c("none", "Chisq", "F"),
     x = NULL, k = 2, ...)

## S3 method for class 'glm':
add1(object, scope, scale = 0, test = c("none", "Chisq", "F"),
     x = NULL, k = 2, ...)

drop1(object, scope, ...)

## Default S3 method:
drop1(object, scope, scale = 0, test = c("none", "Chisq"),
      k = 2, trace = FALSE, ...)

## S3 method for class 'lm':
drop1(object, scope, scale = 0, all.cols = TRUE,
      test = c("none", "Chisq", "F"), k = 2, ...)

## S3 method for class 'glm':
drop1(object, scope, scale = 0, test = c("none", "Chisq", "F"),
      k = 2, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] a fitted model object.
\item[\code{scope}] a formula giving the terms to be considered for adding or
dropping.
\item[\code{scale}] an estimate of the residual mean square to be
used in computing \eqn{C_p}{}. Ignored if \code{0} or \code{NULL}.
\item[\code{test}] should the results include a test statistic relative to the
original model?  The F test is only appropriate for \code{\LinkA{lm}{lm}} and
\code{\LinkA{aov}{aov}} models or perhaps for \code{\LinkA{glm}{glm}} fits with
estimated dispersion.
The \eqn{\chi^2}{} test can be an exact test
(\code{lm} models with known scale) or a likelihood-ratio test or a
test of the reduction in scaled deviance depending on the method.
\item[\code{k}] the penalty constant in AIC / \eqn{C_p}{}.
\item[\code{trace}] if \code{TRUE}, print out progress reports.
\item[\code{x}] a model matrix containing columns for the fitted model and all
terms in the upper scope.  Useful if \code{add1} is to be called
repeatedly.  \bold{Warning:} no checks are done on its validity.
\item[\code{all.cols}] (Provided for compatibility with S.)  Logical to specify
whether all columns of the design matrix should be used.  If
\code{FALSE} then non-estimable columns are dropped, but the result
is not usually statistically meaningful.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
For \code{drop1} methods, a missing \code{scope} is taken to be all
terms in the model. The hierarchy is respected when considering terms
to be added or dropped: all main effects contained in a second-order
interaction must remain, and so on.

In a \code{scope} formula \code{.} means \sQuote{what is already there}.

The methods for \code{\LinkA{lm}{lm}} and \code{\LinkA{glm}{glm}} are more
efficient in that they do not recompute the model matrix and call the
\code{fit} methods directly.

The default output table gives AIC, defined as minus twice log
likelihood plus \eqn{2p}{} where \eqn{p}{} is the rank of the model (the
number of effective parameters).  This is only defined up to an
additive constant (like log-likelihoods).  For linear Gaussian models
with fixed scale, the constant is chosen to give Mallows' \eqn{C_p}{},
\eqn{RSS/scale + 2p - n}{}.  Where \eqn{C_p}{} is used,
the column is labelled as \code{Cp} rather than \code{AIC}.

The F tests for the \code{"glm"} methods are based on analysis of
deviance tests, so if the dispersion is estimated it is based on the
residual deviance, unlike the F tests of \code{\LinkA{anova.glm}{anova.glm}}.
\end{Details}
\begin{Value}
An object of class \code{"anova"} summarizing the differences in fit
between the models.
\end{Value}
\begin{Section}{Warning}
The model fitting must apply the models to the same dataset. Most
methods will attempt to use a subset of the data with no missing
values for any of the variables if \code{na.action=na.omit}, but
this may give biased results.  Only use these functions with data
containing missing values with great care.
\end{Section}
\begin{Note}\relax
These are not fully equivalent to the functions in S.  There is no
\code{keep} argument, and the methods used are not quite so
computationally efficient.

Their authors' definitions of Mallows' \eqn{C_p}{} and Akaike's AIC
are used, not those of the authors of the models chapter of S.
\end{Note}
\begin{Author}\relax
The design was inspired by the S functions of the same names described
in Chambers (1992).
\end{Author}
\begin{References}\relax
Chambers, J. M. (1992)
\emph{Linear models.}
Chapter 4 of \emph{Statistical Models in S}
eds J. M. Chambers and T. J. Hastie, Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{step}{step}}, \code{\LinkA{aov}{aov}}, \code{\LinkA{lm}{lm}},
\code{\LinkA{extractAIC}{extractAIC}}, \code{\LinkA{anova}{anova}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(graphics); require(utils)
example(step)#-> swiss
add1(lm1, ~ I(Education^2) + .^2)
drop1(lm1, test="F")  # So called 'type II' anova

example(glm)
drop1(glm.D93, test="Chisq")
drop1(glm.D93, test="F")
\end{ExampleCode}
\end{Examples}

