Implementing tidyselect interfaces

Selections as dots or as named arguments

There are two major ways of designing a function that takes selections.

• Passing dots as in dplyr::select().

  mtcars %>% dplyr::select(mpg, cyl)

• Interpolating named arguments as in tidyr::pivot_longer(). In this case, multiple inputs can be provided inside c() or by using boolean operators:

  mtcars %>% pivot_longer(c(mpg, cyl))
  mtcars %>% pivot_longer(mpg | cyl)

Our general recommendation is to take dots when the main purpose of the function is to create a new data structure based on a selection. When the selection is accessory to the main purpose of the function, take it as a named argument. In doubt, we recommend using named arguments because it is easier to change a named argument to dots than the other way around. For more advice about this, see the Making data with ... section of the tidyverse design book.

Do you need tidyselect?

The tools described in this vignette are rather low level. Depending on your use case, it may be easier to wrap dplyr::select(). You’ll get a data frame containing the columns selected by your user, which you can then handle in various ways.

The following examples illustrate how you could write a function that takes a selection of data and returns the corresponding data frame with capitalised names:

# Passing dots
toupper_dots <- function(data, ...) {
  sel <- dplyr::select(data, ...)
  rlang::set_names(sel, toupper)
}
# Interpolating a named argument with {{ }}
toupper_arg <- function(data, arg) {
  sel <- dplyr::select(data, {{ arg }})
  rlang::set_names(sel, toupper)
}

mtcars %>% toupper_dots(mpg:disp, vs)
#> # A tibble: 32 x 4
#>     MPG   CYL  DISP    VS
#>   <dbl> <dbl> <dbl> <dbl>
#> 1  21       6   160     0
#> 2  21       6   160     0
#> 3  22.8     4   108     1
#> 4  21.4     6   258     1
#> # … with 28 more rows

mtcars %>% toupper_arg(c(mpg:disp, vs))
#> # A tibble: 32 x 4
#>     MPG   CYL  DISP    VS
#>   <dbl> <dbl> <dbl> <dbl>
#> 1  21       6   160     0
#> 2  21       6   160     0
#> 3  22.8     4   108     1
#> 4  21.4     6   258     1
#> # … with 28 more rows

The main advantage of the lower level tidyselect tools is that they offer a bit more information and flexibility. Instead of returning the selected data, they return the locations of selected elements inside the input data. If you don’t need the selected locations and can afford the dependency, you may consider wrapping dplyr instead.

Defusing and resuming evaluation of R code

When a function argument is defused, R halts the evaluation of the code and returns a defused expression instead. This expression contains the code that describes how to compute the intended value.

Defuse your own R code with expr():

own <- rlang::expr(1 + 2)
own
#> 1 + 2

Defuse the user’s R code with enquo():

fn <- function(arg) {
  expr <- rlang::enquo(arg)
  expr
}
user <- fn(1 + 2)
user
#> <quosure>
#> expr: ^1 + 2
#> env:  global

To resume the evaluation of the defused R code, use eval_tidy():

rlang::eval_tidy(own)
#> [1] 3

rlang::eval_tidy(user)
#> [1] 3

You can resume the evaluation in data context by passing a data frame as data argument:

with_data <- function(data, x) {
  expr <- rlang::enquo(x)
  rlang::eval_tidy(expr, data = data)
}

Resuming evaluation in a data context is known as data masking. The data-vars inside the data frame are combined with the env-vars of the environment, making it possible for users to refer to their data variables:

NULL %>% with_data(mean(cyl) * 10)
#> [1] 2000

mtcars %>% with_data(mean(cyl) * 10)
#> [1] 61.875

Resuming defused R code with tidyselect rules

Taking tidyselect selections in your functions follows the same principles. First defuse an expression, then resume its evaluation. Instead of eval_tidy(), we need the special interpreters eval_select() and eval_rename(). Like eval_tidy(), they take a defused expression and some data. They return a vector of locations for the selected elements:

eval_select(rlang::expr(mpg), mtcars)
#> mpg 
#>   1

eval_select(rlang::expr(c(mpg:disp, vs)), mtcars)
#>  mpg  cyl disp   vs 
#>    1    2    3    8

If the user has renamed some of the selected elements, the names of the vector of locations reflect the new names.

eval_select(rlang::expr(c(foo = mpg, bar = disp)), mtcars)
#> foo bar 
#>   1   3

eval_rename(rlang::expr(c(foo = mpg, bar = disp)), mtcars)
#> foo bar 
#>   1   3

eval_select() is most likely the variant that you’ll need to implement your tidyselect functions.

select <- function(.data, ...) {
  expr <- rlang::expr(c(...))
  pos <- eval_select(expr, data = .data)
  rlang::set_names(.data[pos], names(pos))
}

mtcars %>%
  select(mpg, cyl)
#> # A tibble: 32 × 2
#>     mpg   cyl
#>   <dbl> <dbl>
#> 1  21       6
#> 2  21       6
#> 3  22.8     4
#> 4  21.4     6
#> # ℹ 28 more rows

select <- function(.data, cols) {
  expr <- rlang::enquo(cols)
  pos <- eval_select(expr, data = .data)
  rlang::set_names(.data[pos], names(pos))
}

mtcars %>%
  select(c(mpg, cyl))
#> # A tibble: 32 × 2
#>     mpg   cyl
#>   <dbl> <dbl>
#> 1  21       6
#> 2  21       6
#> 3  22.8     4
#> 4  21.4     6
#> # ℹ 28 more rows

eval_select(rlang::expr(c(foo = mpg)), mtcars)
#> foo 
#>   1

eval_rename(rlang::expr(c(foo = mpg)), mtcars)
#> foo 
#>   1

eval_rename(rlang::expr(mpg), mtcars)
#> Error:
#> ! All renaming inputs must be named.

eval_rename(rlang::expr(c(mpg)), mtcars)
#> Error:
#> ! All renaming inputs must be named.

eval_rename(rlang::expr(c(foo = mpg)), mtcars)
#> foo 
#>   1

wrapper <- function(data, ...) {
  eval_rename(rlang::expr(c(...)), data)
}

mtcars %>% wrapper(foo = mpg, bar = hp:wt)
#>  foo bar1 bar2 bar3 
#>    1    4    5    6

rename <- function(.data, ...) {
  pos <- eval_rename(rlang::expr(c(...)), .data)
  names(.data)[pos] <- names(pos)
  .data
}

mtcars %>%
  rename(foo = mpg, bar = hp:wt)
#> # A tibble: 32 × 11
#>     foo   cyl  disp  bar1  bar2  bar3  qsec    vs    am  gear  carb
#>   <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
#> 1  21       6   160   110  3.9   2.62  16.5     0     1     4     4
#> 2  21       6   160   110  3.9   2.88  17.0     0     1     4     4
#> 3  22.8     4   108    93  3.85  2.32  18.6     1     1     4     1
#> 4  21.4     6   258   110  3.08  3.22  19.4     1     0     3     1
#> # ℹ 28 more rows

Handling duplicate variables

However our current implementation of if_width() has a design flaw. It doesn’t work properly when the input has duplicate names:

dups <- vctrs::new_data_frame(list(foo = 1, quux = 2, foo = 3))

dups %>% select(if_width(3))
#>   foo
#> 1   1

Supporting duplicates is recommended because data frames in the wild don’t always have unique names. Also, tidyselect can be used with vectors that don’t require unique names, and it might be extended to allow recoding character vectors in the future. In these cases, handling duplicates is part of the normal usage for selection helpers.

To support duplicates it is recommended to return vectors of locations from selection helpers rather than vector of names. Fixing if_width() is easy:

if_width <- function(n, vars = peek_vars(fn = "if_width")) {
  which(nchar(vars) == n)
}

If the input is a data frame, the user is now informed that their selection should not contain duplicates:

dups %>% select(if_width(3))
#> Error in `select()`:
#> ! Names must be unique.
#> ✖ These names are duplicated:
#>   * "foo" at locations 1 and 2.

And all the duplicates are selected if the input is not a data frame, as expected:

as.list(dups) %>% select(if_width(3))
#> $foo
#> [1] 1
#> 
#> $foo
#> [1] 3