\Header{step}{Choose a model by AIC in a Stepwise Algorithm}
\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.
This is used as the initial model in the stepwise search.

\item[\code{scope}] defines the range of models examined in the stepwise search.

\item[\code{scale}] used in the definition of the AIC statistic for selecting the models,
currently only for \code{\Link{lm}}, \code{\Link{aov}} and
\code{\Link{glm}} models.

\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{\Link{extractAIC}}.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{step} uses \code{\Link{add1}} and \code{\Link{drop1}}
repeatedly; it will work for any method for which they work, and that
is determined by having a valid method for \code{\Link{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.

There is a potential problem in using \code{\Link{glm}} fits with a variable
\code{scale}, as in that case the deviance is not simply related to the
maximized log-likelihood. The function \code{\Link{extractAIC.glm}} 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 compute the correct AIC.\end{Note}
\begin{Author}\relax
B. D. Ripley\end{Author}
\begin{SeeAlso}\relax
\code{\Link{add1}}, \code{\Link{drop1}}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
example(lm)
step(lm.D9)  

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

