\HeaderA{step}{Choose a model by AIC in a Stepwise Algorithm}{step}
\keyword{models}{step}
\begin{Description}\relax
Select a formula-based model by AIC.
\end{Description}
\begin{Usage}
\begin{verbatim}
step(object, scope, scale = 0,
     direction = c("both", "backward", "forward"), 
     trace = 1, keep = NULL, steps = 1000, k = 2, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] an object representing a model of an appropriate class (mainly
\code{"lm"} and \code{"glm"}).
This is used as the initial model in the stepwise search.

\item[\code{scope}] defines the range of models examined in the stepwise search.
This should be either a single formula, or a list containing
components \code{upper} and \code{lower}, both formulae.  See the
details for how to specify the formulae and how they are used.

\item[\code{scale}] used in the definition of the AIC statistic for selecting the models,
currently only for \code{\LinkA{lm}{lm}}, \code{\LinkA{aov}{aov}} and
\code{\LinkA{glm}{glm}} models.  The default value, \code{0}, indicates
the scale should be estimated: see \code{\LinkA{extractAIC}{extractAIC}}.

\item[\code{direction}] the mode of stepwise search, can be one of \code{"both"},
\code{"backward"}, or \code{"forward"}, with a default of \code{"both"}. 
If the \code{scope} argument is missing the default for
\code{direction} is \code{"backward"}.

\item[\code{trace}] if positive, information is printed during the running of \code{step}.
Larger values may give more detailed information.

\item[\code{keep}] a filter function whose input is a fitted model object and the 
associated \code{AIC} statistic, and whose output is arbitrary. 
Typically \code{keep} will select a subset of the components of 
the object and return them. The default is not to keep anything.

\item[\code{steps}] the maximum number of steps to be considered.  The default is 1000
(essentially as many as required).  It is typically used to stop the
process early.

\item[\code{k}] the multiple of the number of degrees of freedom used for the penalty.
Only \code{k = 2} gives the genuine AIC: \code{k = log(n)} is sometimes
referred to as BIC or SBC.

\item[\code{...}] any additional arguments to \code{\LinkA{extractAIC}{extractAIC}}.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{step} uses \code{\LinkA{add1}{add1}} and \code{\LinkA{drop1}{drop1}}
repeatedly; it will work for any method for which they work, and that
is determined by having a valid method for \code{\LinkA{extractAIC}{extractAIC}}.
When the additive constant can be chosen so that AIC is equal to
Mallows' \eqn{C_p}{Cp}, this is done and the tables are labelled
appropriately.

The set of models searched is determined by the \code{scope} argument.
The right-hand-side of its \code{lower} component is always included
in the model, and right-hand-side of the model is included in the
\code{upper} component.  If \code{scope} is a single formula, it
specifies the \code{upper} component, and the \code{lower} model is
empty.  If \code{scope} is missing, the initial model is used as the
\code{upper} model.

Models specified by \code{scope} can be templates to update
\code{object} as used by \code{\LinkA{update.formula}{update.formula}}.  So using
\code{.} in a \code{scope} formula means \sQuote{what is
already there}, with \code{.\textasciicircum{}2} indicating all interactions of
existing terms.

There is a potential problem in using \code{\LinkA{glm}{glm}} fits with a
variable \code{scale}, as in that case the deviance is not simply
related to the maximized log-likelihood.  The \code{"glm"} method for
function \code{\LinkA{extractAIC}{extractAIC}} makes the
appropriate adjustment for a \code{gaussian} family, but may need to be
amended for other cases.  (The \code{binomial} and \code{poisson}
families have fixed \code{scale} by default and do not correspond
to a particular maximum-likelihood problem for variable \code{scale}.)
\end{Details}
\begin{Value}
the stepwise-selected model is returned, with up to two additional
components.  There is an \code{"anova"} component corresponding to the
steps taken in the search, as well as a \code{"keep"} component if the
\code{keep=} argument was supplied in the call. The
\code{"Resid. Dev"} column of the analysis of deviance table refers
to a constant minus twice the maximized log likelihood: it will be a
deviance only in cases where a saturated model is well-defined
(thus excluding \code{lm}, \code{aov} and \code{survreg} fits,
for example).
\end{Value}
\begin{Section}{Warning}
The model fitting must apply the models to the same dataset. This
may be a problem if there are missing values and \R's default of
\code{na.action = na.omit} is used.  We suggest you remove the
missing values first.
\end{Section}
\begin{Note}\relax
This function differs considerably from the function in S, which uses a
number of approximations and does not in general compute the correct AIC.

This is a minimal implementation.  Use \code{\LinkA{stepAIC}{stepAIC}}
in package \pkg{MASS} for a wider range of object classes.
\end{Note}
\begin{Author}\relax
B. D. Ripley: \code{step} is a slightly simplified version of
\code{\LinkA{stepAIC}{stepAIC}} in package \pkg{MASS} (Venables \&
Ripley, 2002 and earlier editions).

The idea of a \code{step} function follows that described in Hastie \&
Pregibon (1992); but the implementation in \R{} is more general.
\end{Author}
\begin{References}\relax
Hastie, T. J. and Pregibon, D. (1992)
\emph{Generalized linear models.}
Chapter 6 of \emph{Statistical Models in S}
eds J. M. Chambers and T. J. Hastie, Wadsworth \& Brooks/Cole.

Venables, W. N. and Ripley, B. D. (2002)
\emph{Modern Applied Statistics with S.}
New York: Springer (4th ed).
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{stepAIC}{stepAIC}} in \pkg{MASS}, \code{\LinkA{add1}{add1}},
\code{\LinkA{drop1}{drop1}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
utils::example(lm)
step(lm.D9)  

summary(lm1 <- lm(Fertility ~ ., data = swiss))
slm1 <- step(lm1)
summary(slm1)
slm1$anova
\end{ExampleCode}
\end{Examples}

