model.frame               package: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, ...)
     model.frame.default(formula, data = NULL,
                         subset = NULL, na.action = na.fail,
                         drop.unused.levels = FALSE, xlev = NULL, ...)

     Methods for
             lm      glm     aovlist

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.

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 `...'.

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

