Construct a Model Frame - Generic function

DESCRIPTION:

Returns a data frame representing the model.
This function is an S Version 3 generic (see Methods); method functions can be written to handle specific S Version 3 classes of data. Classes that already have methods for this function include aovlist, lm, bdLm, loess, tree.

USAGE:

model.frame(formula, data, na.action = na.fail, ...) 
model.frame.default(formula, data = NULL, na.action = na.fail,  
                    drop.unused.levels = F, xlevels = NULL, ...) 

REQUIRED ARGUMENTS:

formula
the formula or other object defining what terms should be included in the model frame. Besides being a formula object, this can be a fitted model of various kinds, in which case the formula used in fitting the model defines the terms.

OPTIONAL ARGUMENTS:

data
data frame or bdFrame from which the model frame is to be constructed.
na.action
a function to filter missing data. The default ( na.fail) is to report an error if any missing values are found. One possible alternative is na.omit, which deletes observations that contain one or more missing values.
drop.unused.levels
If TRUE (the default) then unused levels in any factor will be omitted from the "levels" attribute of the factor in the resulting model frame. If FALSE, unused levels will not be dropped and the model frame will contain factors with all of the original levels, used or not. This will produce a singular model matrix whenever unused levels are present.
xlevels
an optional named list with names specifying factors contained in "data" and values corresponding to levels to retain in the resulting model frame. Note that levels may not dropped if they occur in "data". However, if some levels are not contained in "data" but it is desired to retain those levels in the resulting model frame, "xlevels" allows you to do so. If "xlevels" is provided "drop.unused.levels" will be ignored.
...
other arguments to the model fitting functions, such as weights= and subset=, are passed on to model.frame.

Typically, model.frame is called less often by users than by functions that are either fitting a model or summarizing one. The default method for model.frame constructs the model frame from the terms (usually inferred from the formula), the data if any, and any special expressions such as subsets, weights, or whatever the particular fitting method needs.

VALUE:

a data frame or bdFrame representing all the terms in the model (precisely, all those terms of order 1; i.e., main effects), plus the response if any, and any special extra variables (such as weight arguments to fitting functions). One such argument is handled specially---namely, subset=. If this argument is present, it is used to compute a subset of the rows of the data. It is this subset that is returned. The returned data frame or bdFrame has an attribute terms containing the terms object defined by the formula.

DETAILS:

The response and any extra variables other than subset are stored in the data frame or bdFrame. They should be retrieved from the frame by using

model.extract(fr, response) # for response
model.extract(fr, weights) # for weights=


and so on for whatever names were used in the arguments to model.frame . Other than subset, the names of such extras are arbitrary; they only need to evaluate to a legitimate variable for the data frame or bdFrame (e.g., a numeric vector, a bdNumeric, a matrix, or a factor).

The names of such variables are specially coded in the model frame so as not to conflict with variable names occurring in the terms. You should always use model.extract, which shares the knowledge of the coded names with model.frame, rather than assuming a specific coding.

NOTE:

Model frames are more typically produced as a side-effect of fitting a model rather than directly by calling model.frame. Functions like lm take an option model=T, that produces the model frame as a component of the fit.

Note also that model.frame methods for model objects, such as model.frame.lm, compute a model frame using the data object name stored within the model object. For example, the object name is extracted from the call component of a lm object. Therefore, the data object must exist when calling these methods or it will fail. If the contents of the data object have been modified after the construction of the model object, the contents of the model frame will not be the same as the one used in constructing the model object.

SEE ALSO:

, .

EXAMPLES:

fuel.fit <- lm(Fuel ~ Weight + Disp., fuel.frame) 
model.frame(fuel.fit) 
model.frame(sqrt(skips) ~ ., solder) 
# 
# This second model empahsizes the use of 'drop.unused.levels' in the  
#    process of fitting a model. 
# 
fuel.fit2 <- lm(Fuel ~ Weight + Type, fuel.frame, subset = Type!="Van") 
model.frame(fuel.fit2)