Functions for Querying, Validating and Extracting from Formulas

Source: R/formula.utilities.R

A suite of utilities for handling model formulas of the style used in Statnet packages.

append_rhs.formula(
  object = NULL,
  newterms,
  keep.onesided = FALSE,
  env = if (is.null(object)) NULL else environment(object)
)

append.rhs.formula(object, newterms, keep.onesided = FALSE)

filter_rhs.formula(object, f, ...)

nonsimp_update.formula(object, new, ..., from.new = FALSE)

nonsimp.update.formula(object, new, ..., from.new = FALSE)

term.list.formula(rhs, sign = +1)

list_summands.call(object)

list_rhs.formula(object)

eval_lhs.formula(object)

Arguments

object

formula object to be updated or evaluated

newterms

a term_list object, or any list of terms (names or calls) to append to the formula, or a formula whose RHS terms will be used; its "sign" attribute vector can give the sign of each term (+1 or -1), and its "env" attribute vector will be used to set its environment, with the first available being used and subsequent ones producing a warning.

keep.onesided

if the initial formula is one-sided, keep it whether to keep it one-sided or whether to make the initial formula the new LHS

env

an environment for the new formula, if object is NULL

f

a function whose first argument is the term and whose additional arguments are forwarded from ... that returns either TRUE or FALSE, for whether that term should be kept.

...

Additional arguments. Currently unused.

new

new formula to be used in updating

from.new

logical or character vector of variable names. controls how environment of formula gets updated.

rhs, sign

Arguments to the deprecated term.list.formula.

Value

append_rhs.formula each return an updated formula object; if object is NULL (the default), a one-sided formula containing only the terms in newterms will be returned.

nonsimp_update.formula each return an updated formula object

list_summands.call returns an object of type term_list; its "env" attribute is set to a list of NULLs, however.

list_rhs.formula returns an object of type term_list.

eval_lhs.formula an object of whatever type the LHS evaluates to.

Functions

  • append_rhs.formula(): append_rhs.formula appends a list of terms to the RHS of a formula. If the formula is one-sided, the RHS becomes the LHS, if keep.onesided==FALSE (the default).

  • append.rhs.formula(): append.rhs.formula has been renamed to append_rhs.formula.

  • filter_rhs.formula(): filter_rhs.formula filters through the terms in the RHS of a formula, returning a formula without the terms for which function f(term, ...) is FALSE. Terms inside another term (e.g., parentheses or an operator other than + or -) will be unaffected.

  • nonsimp_update.formula(): nonsimp_update.formula is a reimplementation of update.formula that does not simplify. Note that the resulting formula's environment is set as follows. If from.new==FALSE, it is set to that of object. Otherwise, a new sub-environment of object, containing, in addition, variables in new listed in from.new (if a character vector) or all of new (if TRUE).

  • nonsimp.update.formula(): nonsimp.update.formula has been renamed to nonsimp_update.formula.

  • term.list.formula(): term.list.formula is an older version of list_rhs.formula that required the RHS call, rather than the formula itself.

  • list_summands.call(): list_summands.call, given an unevaluated call or expression containing the sum of one or more terms, returns an object of class term_list with the terms being summed, handling + and - operators and parentheses, and keeping track of whether a term has a plus or a minus sign.

  • list_rhs.formula(): list_rhs.formula returns an object of type term_list, containing terms in a given formula, handling + and - operators and parentheses, and keeping track of whether a term has a plus or a minus sign.

  • eval_lhs.formula(): eval_lhs.formula extracts the LHS of a formula, evaluates it in the formula's environment, and returns the result.

Examples


## append_rhs.formula

(f1 <- append_rhs.formula(y~x,list(as.name("z1"),as.name("z2"))))
#> y ~ x + z1 + z2
#> <environment: 0x558a9d424910>
(f2 <- append_rhs.formula(~y,list(as.name("z"))))
#> y ~ z
#> <environment: 0x558a9d424910>
(f3 <- append_rhs.formula(~y+x,structure(list(as.name("z")),sign=-1)))
#> y + x ~ -z
#> <environment: 0x558a9d424910>
(f4 <- append_rhs.formula(~y,list(as.name("z")),TRUE))
#> ~y + z
#> <environment: 0x558a9d424910>
(f5 <- append_rhs.formula(y~x,~z1-z2))
#> y ~ x + z1 - z2
#> <environment: 0x558a9d424910>
(f6 <- append_rhs.formula(NULL,list(as.name("z"))))
#> ~z
#> NULL
(f7 <- append_rhs.formula(NULL,structure(list(as.name("z")),sign=-1)))
#> ~-z
#> NULL

fe <- ~z2+z3
environment(fe) <- new.env()
(f8 <- append_rhs.formula(NULL, fe)) # OK
#> ~z2 + z3
#> <environment: 0x558a9df6f810>
(f9 <- append_rhs.formula(y~x, fe)) # Warning
#> Warning: ‘newterms[[1]]’ has an environment that differs from the specified environment or another term's environment.
#> Warning: ‘newterms[[2]]’ has an environment that differs from the specified environment or another term's environment.
#> y ~ x + z2 + z3
#> <environment: 0x558a9d424910>
(f10 <- append_rhs.formula(y~x, fe, env=NULL)) # No warning, environment from fe.
#> y ~ x + z2 + z3
#> <environment: 0x558a9df6f810>
(f11 <- append_rhs.formula(fe, ~z1)) # Warning, environment from fe
#> Warning: ‘newterms[[1]]’ has an environment that differs from the specified environment or another term's environment.
#> z2 + z3 ~ z1
#> <environment: 0x558a9df6f810>

#> Error: identical(environment(f9), globalenv()) is not TRUE

## filter_rhs.formula
(f1 <- filter_rhs.formula(~a-b+c, `!=`, "a"))
#> ~-b + c
#> <environment: 0x558a9d424910>
(f2 <- filter_rhs.formula(~-a+b-c, `!=`, "a"))
#> ~b - c
#> <environment: 0x558a9d424910>
(f3 <- filter_rhs.formula(~a-b+c, `!=`, "b"))
#> ~a + c
#> <environment: 0x558a9d424910>
(f4 <- filter_rhs.formula(~-a+b-c, `!=`, "b"))
#> ~-a - c
#> <environment: 0x558a9d424910>
(f5 <- filter_rhs.formula(~a-b+c, `!=`, "c"))
#> ~a - b
#> <environment: 0x558a9d424910>
(f6 <- filter_rhs.formula(~-a+b-c, `!=`, "c"))
#> ~-a + b
#> <environment: 0x558a9d424910>
(f7 <- filter_rhs.formula(~c-a+b-c(a),
                          function(x) (if(is.call(x)) x[[1]] else x)!="c"))
#> ~-a + b
#> <environment: 0x558a9d424910>



stopifnot(identical(list_rhs.formula(a~b),
          structure(alist(b), sign=1, env=list(globalenv()), class="term_list")))
#> Error: identical(list_rhs.formula(a ~ b), structure(alist(b), sign = 1,  .... is not TRUE
stopifnot(identical(list_rhs.formula(~b),
          structure(alist(b), sign=1, env=list(globalenv()), class="term_list")))
#> Error: identical(list_rhs.formula(~b), structure(alist(b), sign = 1,  .... is not TRUE
stopifnot(identical(list_rhs.formula(~b+NULL),
          structure(alist(b, NULL),
                    sign=c(1,1), env=rep(list(globalenv()), 2), class="term_list")))
#> Error: identical(list_rhs.formula(~b + NULL), structure(alist(b, NULL),  .... is not TRUE
stopifnot(identical(list_rhs.formula(~-b+NULL),
          structure(alist(b, NULL),
                    sign=c(-1,1), env=rep(list(globalenv()), 2), class="term_list")))
#> Error: identical(list_rhs.formula(~-b + NULL), structure(alist(b, NULL),  .... is not TRUE
stopifnot(identical(list_rhs.formula(~+b-NULL),
          structure(alist(b, NULL),
                    sign=c(1,-1), env=rep(list(globalenv()), 2), class="term_list")))
#> Error: identical(list_rhs.formula(~+b - NULL), structure(alist(b, NULL),  .... is not TRUE
stopifnot(identical(list_rhs.formula(~+b-(NULL+c)),
          structure(alist(b, NULL, c),
                    sign=c(1,-1,-1), env=rep(list(globalenv()), 3), class="term_list")))
#> Error: identical(list_rhs.formula(~+b - (NULL + c)), structure(alist(b,  .... is not TRUE

## eval_lhs.formula

(result <- eval_lhs.formula((2+2)~1))
#> [1] 4

stopifnot(identical(result,4))