dplyr, rlang: Unable to predict if minor varients of passing names to nested dplyr functions will work

Question

Data for reproducibility

.i <- tibble(a=2*1:4+1, b=2*1:4)

This function is supposed to take its data and other arguments as unquoted names, find those names in the data, and use them to add a column and filter out the top row. It does not work. Mutate says it can not find a.

t1 <- function(.j=.i, X=a, Y=b){
  e_X <- enquo(X)
  e_Y <- enquo(Y)
  mutate(.data=.j, pass=UQ(e_X)+1) %>% 
    filter(UQ(e_Y) > 3) -> out
  out
}
t1(a,b)

This function, which I found by typo -- note the .i instead of .j in the mutate statement -- does what the previous function was supposed to do. And I don't know why. I think it is skipping over the function arguments and finding .i in the global environment. Or maybe it is using a ouiji board.

t2 <- function(.j=.i, X=a, Y=b){
  e_X <- enquo(X)
  e_Y <- enquo(Y)
  mutate(.data=.i, pass=UQ(e_X)+1) %>% 
  filter(UQ(e_Y) > 3) -> out
  out
}
t1(a,b)

Since mutate could not find .j when passed to it in the usual R way, maybe it needs to be passed in an rlang-style quosure, like the formals X and Y. This function also does not work, with UQ in mutate saying that it can not find a. Like the first function above, it works if the .j in mutate is replaced with a .i. (Seems like there should be an "enquos" to parallel quos).

t3 <- function(.j=.i, X=a, Y=b){
  e_j <- enquo(.j)
  e_X <- enquo(X)
  e_Y <- enquo(Y)
  mutate(.data=UQ(.j), pass=UQ(e_X)+1) %>% 
    filter(UQ(e_Y) > 3) -> out
  out
}
t1(a,b)

Finally, it appears that, once the .i substitution in mutate is made, t4() no longer needs a data argument at all. See below, where I replace it with bop_foo_foo. If, however, you replace bop_foo_foo throughout with the name of the data, .i, (t5()) then UQ again fails to find a.

bop_foo_foo <- 0
t4 <- function(bop_foo_foo, X=a, Y=b){
  e_j <- enquo(bop_foo_foo)
  e_X <- enquo(X)
  e_Y <- enquo(Y)
  mutate(.data=UQ(.i), pass=UQ(e_X)+1) %>% 
    filter(UQ(e_Y) > 3) -> out
  out
}
t1(a,b)

The functions above seem to me to be relatively minor variants on a single function. I have run dozens more, and although I have observed some patterns, and read the enquo and UQ help files I do not know how many times, a real understanding continues to elude me.

I would like to know why the functions above that that don't work don't, and why the ones that do work do. I don't necessarily need a function by function critique. If you can state general principles that embody the required, understanding, that would be delightful. And more than sufficient.

Answer 1

I think it is skipping over the function arguments and finding .i in the global environment.

Yes, scope of symbols in R is hierarchical. The variables local to a function are looked up first, and then the surrounding environment of the function is inspected, and so on.

mutate(.data = UQ(.j), ...)

I think you are missing the difference between regular arguments and (quasi)quoted arguments. Unquoting is only relevant for quasiquoted arguments. Since the .data argument of mutate() is not quasiquoted it does not make sense to try and unquote stuff. The quasiquoted arguments are the ones that are captured/quoted with enexpr() or enquo(). You can tell whether an argument is quasiquoted either by looking at the documentation or by recognising that the argument supports direct references to columns (regular arguments need to be explicit about where to find the columns).

In the next version of rlang, the exported UQ() function will throw an error to make it clear that it should not be called directly and that it can only be used in quasiquoted arguments.

I would suggest:

• Call the first argument of your function data or df rather than .i.
• Don't give it a default. The user should always supply the data.
• Don't capture it with enquo() or enexpr() or substitute(). Instead pass it directly to the data argument of other verbs.

Once this is out of the way it will be easier to work out the rest.