model.frame {base} | R Documentation

## Extracting the “Environment” of a Model Formula

### Description

`model.frame` (a generic function) and its methods return a `data.frame` with the variables needed to use `formula` and any `...` arguments.

### Usage

    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, ...)

### Arguments

`formula` | a model formula
`data` | `data.frame`, list, `environment` or object coercible to `data.frame` containing the variables in `formula`.
`subset` | a specification of the rows to be used: defaults to all rows. This can be any valid indexing vector (see `[.data.frame` for the rows of `data` or if that is not supplied, a data frame made up of the variables used in `formula`.
`na.action` | how `NA`s are treated. The default is first, any `na.action` attribute of `data`, second a `na.action` setting of `options`, and third `na.fail` if that is unset. The “factory-fresh” default is `na.omit`.
`drop.unused.levels` | should factors have unused levels dropped? Defaults to `FALSE`.
`xlev` | a named list of character vectors giving the full set of levels to be assumed for each factor.
`...` | further arguments such as `subset`, `offset` and `weights`. `NULL` arguments are treated as missing.

### Details

Variables in the formula, `subset` and in `...` are looked for first in `data` and then in the environment of `formula`: see the help for `formula()` for further details.

First all the variables needed are collected into a data frame. Then `subset` expression is evaluated, and it is is used as a row index to the data frame. Then the `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 `drop.unused.levels` and `xlev` arguments.

### Value

A `data.frame` containing the variables used in `formula` plus those specified `...`.

### References

Chambers, J. M. (1992) Data for models. Chapter 3 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole.

### See Also

`model.matrix` for the “design matrix”, `formula` for formulas and `expand.model.frame` for model.frame manipulation.

### Examples

    data(cars)
    data.class(model.frame(dist ~ speed, data = cars))

[Package Contents]