R: Extended Formulas: Multiple Responses and Multiple Regressor...

Formula {Formula} | R Documentation

## Extended Formulas: Multiple Responses and Multiple Regressor Parts

### Description

The new class `Formula` extends the base class `formula` by allowing for multiple responses and multiple parts of regressors.

### Usage

    Formula(object)

    ## S3 method for class 'Formula'
    formula(x, lhs = NULL, rhs = NULL,
      collapse = FALSE, update = FALSE, drop = TRUE, ...)

    as.Formula(x, ...)
    is.Formula(object)

### Arguments

`object, x` | an object. For `Formula` it needs to be a `formula` object.
`lhs, rhs` | indexes specifying which elements of the left- and right-hand side, respectively, should be employed. `NULL` corresponds to all parts, `0` to none.
`collapse` | logical. Should multiple parts (if any) be collapsed to a single part (essentially by replacing the `|` operator by `+`)? `collapse` can be a vector of length 2, corresponding for different handling of left- and right-hand side respectively.
`update` | logical. Only used if `all(collapse)`. Should the resulting formula be updated to remove possibly redundant terms occuring in multiple terms?
`drop` | logical. Should the `Formula` class be dropped? If `TRUE` (the default) a `formula` is returned, if `FALSE` the corresponding `Formula` is returned.
`...` | further arguments.

### Details

`Formula` objects extend the basic `formula` objects. These extensions include multi-part formulas such as `y ~ x1 + x2 | u1 + u2 + u3 | v1 + v2`, multiple response formulas `y1 + y2 ~ x1 + x2 + x3`, multi-part responses such as `y1 | y2 + y3 ~ x`, and combinations of these.

The `Formula` creates a `Formula` object from a `formula` which can have the `|` operator on the left- and/or right-hand side (LHS and/or RHS). Essentially, it stores the original `formula` along with attribute lists containing the decomposed parts for the LHS and RHS, respectively.

The main motivation for providing the `Formula` class is to be able to conveniently compute model frames and model matrices or extract selected responses based on an extended formula language. This functionality is provided by methods to the generics `model.frame`, and `model.matrix`. For details and examples, see their manual page: `model.frame.Formula`.

In addition to these workhorses, a few further methods and functions are provided. By default, the `formula()` method switches back to the original `formula`. Additionally, it allows selection of subsets of the LHS and/or RHS (via `lhs`, and `rhs`) and collapsing multiple parts on the LHS and/or RHS into a single part (via `collapse`).

`is.Formula` checks whether the argument inherits from the `Formula` class.

`as.Formula` is a generic for coercing to `Formula`, the default method first coerces to `formula` and then calls `Formula`. The default and `formula` method also take an optional `env` argument, specifying the environment of the resulting `Formula`. In the latter case, this defaults to the environment of the `formula` supplied.

Methods to further standard generics `print`, `update`, and `length` are provided for `Formula` objects. The latter reports the number of parts on the LHS and RHS, respectively.

### Value

`Formula` returns an object of class `Formula` which inherits from `formula`. It is the original `formula` plus two attributes `"lhs"` and `"rhs"` that contain the parts of the decomposed left- and right-hand side, respectively.

### References

Zeileis A, Croissant Y (2010). Extended Model Formulas in R: Multiple Parts and Multiple Responses. Journal of Statistical Software, 34(1), 1–13. http://www.jstatsoft.org/v34/i01/.

### See Also

`model.frame.Formula`

### Examples

    ## create a simple Formula with one response and two regressor parts
    f1 <- y ~ x1 + x2 | z1 + z2 + z3
    F1 <- Formula(f1)
    class(F1)
    length(F1)

    ## switch back to original formula
    formula(F1)

    ## create formula with various transformations
    formula(F1, rhs = 1)
    formula(F1, collapse = TRUE)
    formula(F1, lhs = 0, rhs = 2)

    ## put it together from its parts
    as.Formula(y ~ x1 + x2, ~ z1 + z2 + z3)

    ## update the formula
    update(F1, . ~ . + I(x1^2) | . - z2 - z3)
    update(F1, . | y2 + y3 ~ .)

    # create a multi-response multi-part formula
    f2 <- y1 | y2 + y3 ~ x1 + I(x2^2) | 0 + log(x1) | x3 / x4
    F2 <- Formula(f2)
    length(F2)

    ## obtain various subsets using standard indexing
    ## no lhs, first/seconde rhs
    formula(F2, lhs = 0, rhs = 1:2)
    formula(F2, lhs = 0, rhs = -3)
    formula(F2, lhs = 0, rhs = c(TRUE, TRUE, FALSE))
    ## first lhs, third rhs
    formula(F2, lhs = c(TRUE, FALSE), rhs = 3)

[Package Formula version 1.2-3 Index]