qenv

Initialization

The qenv() function serves as the gateway to create an initial qenv object:

library(teal.code)

# create a new qenv object
empty_qenv <- qenv()
print(empty_qenv)

## <environment: 0x7fa67d3ae9b0> [L]
## Parent: <environment: package:teal.code>

qenv basic usage

The eval_code() function executes code within a qenv environment, yielding a new qenv object as the output.

library(magrittr)

# evaluate code in qenv
my_qenv <- eval_code(empty_qenv, "x <- 2")
print(my_qenv)

## <environment: 0x7fa67d4e8d98> [L]
## Parent: <environment: package:magrittr>
## Bindings:
## • x: <dbl> [L]

get_env(my_qenv)

## <environment: 0x7fa67d4e8d98>

q1 <- eval_code(my_qenv, "y <- x * 2") %>% eval_code("z <- y * 2")

# my_qenv still contains only x
print(my_qenv)

## <environment: 0x7fa67d4e8d98> [L]
## Parent: <environment: package:magrittr>
## Bindings:
## • x: <dbl> [L]

ls(get_env(my_qenv))

## [1] "x"

# q1 contains x, y and z
print(q1)

## <environment: 0x7fa685c59a20> [L]
## Parent: <environment: package:magrittr>
## Bindings:
## • x: <dbl> [L]
## • y: <dbl> [L]
## • z: <dbl> [L]

ls(get_env(q1))

## [1] "x" "y" "z"

The same result can be achieved with the within method for the qenv class.

q2 <- within(my_qenv, y <- x * 2) %>% within(z <- y * 2)
print(q2)

## <environment: 0x7fa6865de940> [L]
## Parent: <environment: package:magrittr>
## Bindings:
## • x: <dbl> [L]
## • y: <dbl> [L]
## • z: <dbl> [L]

To extract objects from a qenv, use [[; this is particularly useful for displaying them in a shiny app. You can retrieve the code used to generate the qenv using the get_code() function.

print(q2[["y"]])

## [1] 4

cat(get_code(q2))

## x <- 2
## y <- x * 2
## z <- y * 2

Substitutions

In some cases, one may want to substitute some elements of the code before evaluation. Consider a case when a subset of iris is defined by an input value.

q <- qenv()
q <- eval_code(q, quote(i <- subset(iris, Species == "setosa")))
q <- eval_code(q, substitute(
  ii <- subset(iris, Species == species),
  env = list(species = "versicolor")
))
input_value <- "virginica"
q <- eval_code(q, substitute(
  iii <- subset(iris, Species == species),
  env = list(species = input_value)
))

summary(q[["i"]]$Species)

##     setosa versicolor  virginica 
##         50          0          0

summary(q[["ii"]]$Species)

##     setosa versicolor  virginica 
##          0         50          0

summary(q[["iii"]]$Species)

##     setosa versicolor  virginica 
##          0          0         50

A more convenient way to pass code with substitution is to use the within method.

qq <- qenv()
qq <- within(qq, i <- subset(iris, Species == "setosa"))
qq <- within(qq, ii <- subset(iris, Species == species), species = "versicolor")
input_value <- "virginica"
qq <- within(qq, iii <- subset(iris, Species == species), species = input_value)

summary(qq[["i"]]$Species)

##     setosa versicolor  virginica 
##         50          0          0

summary(qq[["ii"]]$Species)

##     setosa versicolor  virginica 
##          0         50          0

summary(qq[["iii"]]$Species)

##     setosa versicolor  virginica 
##          0          0         50

See ?qenv for more details.

Combining qenv objects

Given a pair of qenv objects, you may be able to “join” them, creating a new qenv object encompassing the union of both environments, along with the requisite code for reproduction:

common_q <- eval_code(qenv(), quote(x <- 1))

x_q <- eval_code(common_q, quote(y <- 5))
y_q <- eval_code(common_q, quote(z <- 5))

join_q <- join(x_q, y_q)

print(join_q)

## <environment: 0x7fa682b521f0>
## Parent: <environment: package:magrittr>
## Bindings:
## • x: <dbl>
## • y: <dbl>
## • z: <dbl>

ls(get_env(join_q))

## [1] "x" "y" "z"

The feasibility of joining qenv objects hinges on the contents of the environments and the code’s order. Refer to the function documentation for further details.

Warnings and messages in qenv objects

In cases where warnings or messages arise while evaluating code within a qenv environment, these are captured and stored within the qenv object. Access these messages and warnings using the @ operator.

q_message <- eval_code(qenv(), quote(message("this is a message")))
q_message@messages

## [1] "> this is a message\n"

q_warning <- eval_code(qenv(), quote(warning("and this is a warning")))
q_warning@warnings

## [1] "> and this is a warning\n"

If a particular line of code doesn’t trigger any warnings or messages, the corresponding message/warning value will be an empty string.

q_message@warnings

## [1] ""

q_warning@messages

## [1] ""

Additionally, a helper function, get_warnings(), is available to generate a formatted string comprising the warnings and the code responsible for generating them. It returns NULL when no warnings are present.