\HeaderA{model.frame}{Extracting the ``Environment'' of a Model Formula}{model.frame}
\methaliasA{model.frame.aovlist}{model.frame}{model.frame.aovlist}
\methaliasA{model.frame.default}{model.frame}{model.frame.default}
\methaliasA{model.frame.glm}{model.frame}{model.frame.glm}
\methaliasA{model.frame.lm}{model.frame}{model.frame.lm}
\keyword{models}{model.frame}
\begin{Description}\relax
\code{model.frame} (a generic function) and its methods return a
\code{\LinkA{data.frame}{data.frame}} with the variables needed to use
\code{formula} and any \code{...} arguments.
\end{Description}
\begin{Usage}
\begin{verbatim}
model.frame(formula, ...)

## Default S3 method:
model.frame(formula, data = NULL,
           subset = NULL, na.action = na.fail,
           drop.unused.levels = FALSE, xlev = NULL, ...)

## S3 method for class 'aovlist':
model.frame(formula, data = NULL, ...)

## S3 method for class 'glm':
model.frame(formula, ...)

## S3 method for class 'lm':
model.frame(formula, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] a model \code{\LinkA{formula}{formula}} or \code{\LinkA{terms}{terms}}
object or an \R{} object.
\item[\code{data}] a data.frame, list or environment (or object
coercible by \code{\LinkA{as.data.frame}{as.data.frame}} to a data.frame),
containing the variables in \code{formula}.  Neither a matrix nor an
array will be accepted.
\item[\code{subset}] a specification of the rows to be used: defaults to all
rows. This can be any valid indexing vector (see
\code{\LinkA{[.data.frame}{[.data.frame}}) for the rows of \code{data} or if that is not
supplied, a data frame made up of the variables used in \code{formula}.
\item[\code{na.action}] how \code{NA}s are treated.  The default is first,
any \code{na.action} attribute of \code{data}, second
a \code{na.action} setting of \code{\LinkA{options}{options}}, and third
\code{\LinkA{na.fail}{na.fail}} if that is unset.  The \dQuote{factory-fresh}
default is \code{\LinkA{na.omit}{na.omit}}.  Another possible value is \code{NULL}.
\item[\code{drop.unused.levels}] should factors have unused levels dropped?
Defaults to \code{FALSE}.
\item[\code{xlev}] a named list of character vectors giving the full set of levels
to be assumed for each factor.
\item[\code{...}] further arguments such as \code{data}, \code{na.action},
\code{subset}.  Any additional arguments such as \code{offset} and
\code{weights} which reach the default method are used to create
further columns in the model frame, with parenthesised names such as
\code{"(offset)"}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Exactly what happens depends on the class and attributes of the object
\code{formula}.  If this is an object of fitted-model class such as
\code{"lm"}, the method will either returned the saved model frame
used when fitting the model (if any, often selected by argument
\code{model = TRUE}) or pass the call used when fitting on to the
default method.  The default method itself can cope with rather
standard model objects such as those of classes
\code{"\LinkA{lqs}{lqs}"} and \code{"\LinkA{ppr}{ppr}"} from
package \pkg{MASS} if no other arguments are supplied.

The rest of this section applies only to the default method.

If either \code{formula} or \code{data} is already a model frame (a
data frame with a \code{"terms"} attribute and the other is missing,
the model frame is returned.  Unless \code{formula} is a terms object,
\code{terms} is called on it.  (If you wish to use the
\code{keep.order} argument of \code{terms.formula}, pass a terms
object rather than a formula.)

Row names for the model frame are taken from the \code{data} argument
if present, then from the names of the response in the formula (or
rownames if it is a matrix), if there is one.

All the variables in \code{formula}, \code{subset} and in \code{...}
are looked for first in \code{data} and then in the environment of
\code{formula} (see the help for \code{\LinkA{formula}{formula}()} for further
details) and collected into a data frame.  Then the \code{subset}
expression is evaluated, and it is is used as a row index to the data
frame.  Then the \code{na.action} function is applied to the data frame
(and may well add attributes).  The levels of any factors in the data
frame are adjusted according to the \code{drop.unused.levels} and
\code{xlev} arguments.

Unless \code{na.action = NULL}, time-series attributes will be removed
from the variables found (since they will be wrong if \code{NA}s are
removed).

Note that \emph{all} the variables in the formula are included in the
data frame, even those preceded by \code{-}.
\end{Details}
\begin{Value}
A \code{\LinkA{data.frame}{data.frame}} containing the variables used in
\code{formula} plus those specified \code{...}.
\end{Value}
\begin{References}\relax
Chambers, J. M. (1992)
\emph{Data for models.}
Chapter 3 of \emph{Statistical Models in S}
eds J. M. Chambers and T. J. Hastie, Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{model.matrix}{model.matrix}} for the \dQuote{design matrix},
\code{\LinkA{formula}{formula}} for formulas  and
\code{\LinkA{expand.model.frame}{expand.model.frame}} for model.frame manipulation.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data.class(model.frame(dist ~ speed, data = cars))
\end{ExampleCode}
\end{Examples}

