5 Dealing with multiple arguments
In the first chapter we have created
grouped_mean(), a function that takes one grouping variable and one summary variable and computes the grouped average. It would make sense to take multiple grouping variables instead of just one. Quoting and unquoting multiple variables is pretty much the same process as for single arguments:
Unquoting multiple arguments requires a variant of
!!, the big bang operator
Quoting multiple arguments can be done in two ways: internal quoting with the plural variant
enquos()and external quoting with
The dot-dot-dot argument is one of the nicest aspects of the R language. A function that takes
... accepts any number of arguments, named or unnamed. As a programmer you can do three things with
Evaluate the arguments contained in the dots and materialise them in a list by forwarding the dots to
The dots names conveniently become the names of the list:
Quote the arguments in the dots with
All arguments passed to
...are automatically quoted and returned as a list. The names of the arguments become the names of that list:
Forward the dots to another function:
When dots are forwarded the names of arguments in
...are matched to the arguments of the forwardee:
Let’s call the forwarding function with a bunch of named and unnamed arguments:
The unnamed argument
1was matched to
foopositionally. The named argument
barwas matched to
bar. The remaining arguments were passed in order.
For the purpose of writing tidy eval functions the last two techniques are important. There are two distinct situations:
You don’t need to modify the arguments in any way, just passing them through. Then simply forward
...to other quoting functions in the ordinary way.
You’d like to change the argument names (which become column names in
dplyr::mutate()calls) or modify the arguments themselves (for instance negate a
dplyr::select()ion). In that case you’ll need to use
enquos()to quote the arguments in the dots. You’ll then pass the quoted arguments to other quoting functions by forwarding them with the help of
5.2 Simple forwarding of
If you are not modifying the arguments in
... in any way and just want to pass them to another quoting function, just forward
... like usual! There is no need for quoting and unquoting because of the magic of forwarding. The arguments in
... are transported to their final destination where they will be quoted.
grouped_mean() is still going to need some remodelling because it is good practice to take all important named arguments before the dots. Let’s start by swapping
Then we replace
... and pass it to
It is good practice to make one final adjustment. Because arguments in
... can have arbitrary names, we don’t want to “use up” valid names. In tidyverse packages we use the convention of prefixing named arguments with a dot so that conflicts are less likely:
Let’s check this function now works with any number of grouping variables:
grouped_mean(mtcars, disp, cyl, am) #> `summarise()` regrouping output by 'cyl' (override with `.groups` argument) #> # A tibble: 6 x 3 #> # Groups: cyl  #> cyl am mean #> <dbl> <dbl> <dbl> #> 1 4 0 136. #> 2 4 1 93.6 #> 3 6 0 205. #> 4 6 1 155 #> 5 8 0 358. #> # … with 1 more row grouped_mean(mtcars, disp, cyl, am, vs) #> `summarise()` regrouping output by 'cyl', 'am' (override with `.groups` argument) #> # A tibble: 7 x 4 #> # Groups: cyl, am  #> cyl am vs mean #> <dbl> <dbl> <dbl> <dbl> #> 1 4 0 1 136. #> 2 4 1 0 120. #> 3 4 1 1 89.8 #> 4 6 0 1 205. #> 5 6 1 0 155 #> # … with 2 more rows
5.3 Quote multiple arguments
When we need to modify the arguments or their names, we can’t simply forward the dots. We’ll have to quote and unquote with the plural variants of
- We’ll quote the dots with
- We’ll unquote-splice the quoted dots with
While the singular
enquo() returns a single quoted argument, the plural variant
enquos() returns a list of quoted arguments. Let’s use it to quote the dots:
grouped_mean() now accepts and automatically quotes any number of grouping variables. However it doesn’t work quite yet:
FIXME: Depend on dev rlang to get a better error message.
grouped_mean2(mtcars, disp, cyl, am) #> Warning: `group_by_()` is deprecated as of dplyr 0.7.0. #> Please use `group_by()` instead. #> See vignette('programming') for more help #> This warning is displayed once every 8 hours. #> Call `lifecycle::last_warnings()` to see where this warning was generated. #> Error in UseMethod("group_by_"): no applicable method for 'group_by_' applied to an object of class "function"
Instead of forwarding the individual arguments to
group_by() we have passed the list of arguments itself! Unquoting is not the right operation here. Fortunately tidy eval provides a special operator that makes it easy to forward a list of arguments.
5.4 Unquote multiple arguments
The unquote-splice operator
!!! takes each element of a list and unquotes them as independent arguments to the surrounding function call. The arguments are spliced in the function call. This is just what we need for forwarding multiple quoted arguments.
qq_show() to observe the difference between
!!! in a
group_by() expression. We can only use
enquos() within a function so let’s create a list of quoted names for the purpose of experimenting:
qq_show() shows the difference between unquoting a list and unquote-splicing a list:
When we use the unquote operator
group_by() gets a list of expressions. When we unquote-splice with
!!!, the expressions are forwarded as individual arguments to
group_by(). Let’s use the latter to fix
The quote and unquote version of
grouped_mean() does a bit more work but is functionally identical to the forwarding version:
grouped_mean(mtcars, disp, cyl, am) #> `summarise()` regrouping output by 'cyl' (override with `.groups` argument) #> # A tibble: 6 x 3 #> # Groups: cyl  #> cyl am mean #> <dbl> <dbl> <dbl> #> 1 4 0 136. #> 2 4 1 93.6 #> 3 6 0 205. #> 4 6 1 155 #> 5 8 0 358. #> # … with 1 more row grouped_mean2(mtcars, disp, cyl, am) #> `summarise()` regrouping output by 'cyl' (override with `.groups` argument) #> # A tibble: 6 x 3 #> # Groups: cyl  #> cyl am mean #> <dbl> <dbl> <dbl> #> 1 4 0 136. #> 2 4 1 93.6 #> 3 6 0 205. #> 4 6 1 155 #> 5 8 0 358. #> # … with 1 more row
When does it become useful to do all this extra work? Whenever you need to modify the arguments or their names.
Up to now we have used the quote-and-unquote pattern to pass quoted arguments to other quoting functions “as is”. With this simple and powerful pattern you can extract complex combinations of quoting verbs into reusable functions.
However tidy eval provides much more flexibility. It is a general purpose meta-programming framework that makes it easy to modify quoted arguments before evaluation. In the next section you’ll learn about basic metaprogramming patterns that will allow you to modify expressions before passing them on to other functions.