formula                 package:base                 R Documentation

Model Formulae

Description:

     The generic function `formula' and its specific methods provide a
     way of extracting formulae which have been included in other
     objects.

     `as.formula' is almost identical, additionally preserving
     attributes when `object' already inherits from `"formula"'. The
     default value of the `env' argument is used only when the formula
     would otherwise lack an environment.

Usage:

     y ~ model
     formula(x, ...)
     as.formula(object, env=parent.frame())
     I(x)

Arguments:

x, object: an object

     ...: further arguments passed to or from other methods.

     env: the environment to associate with the result.

Details:

     The models fit by, e.g., the `lm' and `glm' functions are
     specified in a compact symbolic form. The `~' operator is basic in
     the formation of such models. An expression of the form `y ~
     model' is interpreted as a specification that the response `y' is
     modelled by a linear predictor specified symbolically by `model'.
     Such a model consists of a series of terms separated by `+'
     operators. The terms themselves consist of variable and factor
     names separated by `:' operators. Such a term is interpreted as
     the interaction of all the variables and factors appearing in the
     term.

     In addition to `+' and `:', a number of other operators are useful
     in model formulae.  The `*' operator denotes factor crossing:
     `a*b' interpreted as `a+b+a:b'.  The `^' operator indicates
     crossing to the specified degree.  For example `(a+b+c)^2' is
     identical to `(a+b+c)*(a+b+c)' which in turn expands to a formula
     containing the main effects for `a', `b' and `c' together with
     their second-order interactions. The `%in%' operator indicates
     that the terms on its left are nested within those on the right. 
     For example `a+b%in%a' expands to the formula `a+a:b'.  The `-'
     operator removes the specified terms, so that `(a+b+c)^2 - a:b' is
     identical to `a + b + c + b:c + a:c'. It can also used to remove
     the intercept term: `y~x - 1' is a line through the origin. A
     model with no intercept can be also specified as `y~x + 0' or `0 +
     y~x'.

     While formulae usually involve just variable and factor names,
     they can also involve arithmetic expressions. The formula `log(y)
     ~ a + log(x)' is quite legal. When such arithmetic expressions
     involve operators which are also used symbolically in model
     formulae, there can be confusion between arithmetic and symbolic
     operator use.

     To avoid this confusion, the function `I()' can be used to bracket
     those portions of a model formula where the operators are used in
     their arithmetic sense.  For example, in the formula `y ~ a +
     I(b+c)', the term `b+c' is to be interpreted as the sum of `b' and
     `c'.

Value:

     All the functions above produce an object of class `formula' which
     contains a symbolic model formula.

Environments:

     A formula object has an associated environment, and this
     environment (rather than the parent environment) is used by
     `model.frame' to evaluate variables that are not found in the
     supplied `data' argument.

     Formulas created with the `~' operator use the environment in
     which they were created. Formulas created with `as.formula' will
     use the `env' argument for their environment. Pre-existing
     formulas extracted with `as.formula' will only have their
     environment changed if `env' is explicitly given.

See Also:

     For formula manipulation: `terms', and `all.vars'; for typical
     use: `lm', `glm', and `coplot'.

Examples:

     class(fo <- y ~ x1*x2) # "formula"
     fo
     typeof(fo)# R internal : "language"
     terms(fo)

     environment(fo)
     environment(as.formula("y~x"))
     environment(as.formula("y~x",env=new.env()))

     ## Create a formula for a model with a large number of variables:
     xnam <- paste("x", 1:25, sep="")
     (fmla <- as.formula(paste("y ~ ", paste(xnam, collapse= "+"))))

