\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, data, na.action, ...)

## S3 method for class 'lm':
model.frame(formula, data, na.action, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] a model formula
\item[\code{data}] \code{data.frame}, list, \code{environment} or object
coercible to \code{data.frame} containing the variables in
\code{formula}.
\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{subset}, \code{offset} and
\code{weights}. \code{NULL} arguments are treated as missing.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Variables in the 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.

First all the variables needed are collected into a data frame.
Then \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}

