Formula (version 1.2-5)

Formula: 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 Formula
formula(x, lhs = NULL, rhs = NULL,
  collapse = FALSE, update = FALSE, drop = TRUE, ...)
as.Formula(x, ...)
is.Formula(object)

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.

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.

References

Zeileis A, Croissant Y (2010). Extended Model Formulas in R: Multiple Parts and Multiple Responses. Journal of Statistical Software, 34(1), 1--13. tools:::Rd_expr_doi("10.18637/jss.v034.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)