\Header{model.frame}{Extracting the ``Environment'' of a Model Formula}
\methalias{model.frame.aovlist}{model.frame}
\methalias{model.frame.default}{model.frame}
\methalias{model.frame.glm}{model.frame}
\methalias{model.frame.lm}{model.frame}
\keyword{models}{model.frame}
\begin{Description}\relax
\code{model.frame} (a generic function) and its methods return a
\code{\Link{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{\Link{formula}} or \code{\Link{terms}}
object or an \R{} object.
\item[\code{data}] \code{data.frame}, list, \code{environment} or object
coercible to \code{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{\Link{[.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{\Link{options}}, and third
\code{\Link{na.fail}} if that is unset.  The \dQuote{factory-fresh}
default is \code{\Link{na.omit}}.
\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{"\Link{lqs}"} and \code{"\Link{ppr}"} 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.)

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{\Link{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.
\end{Details}
\begin{Value}
A \code{\Link{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{\Link{model.matrix}} for the \dQuote{design matrix},
\code{\Link{formula}} for formulas  and
\code{\Link{expand.model.frame}} for model.frame manipulation.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(cars)
data.class(model.frame(dist ~ speed, data = cars))
\end{ExampleCode}
\end{Examples}

