The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.
library(tidyselect)
library(magrittr)tidyselect implements a specialised sublanguage of R for selecting variables from data frames and other data structures. A technical description of the DSL is available in the syntax vignette.
In this vignette, we describe how to include tidyselect in your own packages. If you just want to know how to use tidyselect syntax in dplyr or tidyr, please read ?language instead.
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.
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 rowsThe 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.
tidyselect is implemented with non-standard evaluation (NSE). This unique feature of the R language refers to the ability of functions to defuse (i.e. delay the execution) some or all of their arguments, and resume evaluation later on1. Crucially, evaluation can be resumed in a different context or according to different rules, which is often how domain-specific languages are created in R.
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 + 2Defuse 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: globalTo resume the evaluation of the defused R code, use eval_tidy():
rlang::eval_tidy(own)
#> [1] 3
rlang::eval_tidy(user)
#> [1] 3You 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.875Taking 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 8If 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 3eval_select() is most likely the variant that you’ll need to implement your tidyselect functions.
If your selecting function takes dots:
Pass the dots to c() inside a defused expression.
Resume evaluation of the defused c() expression with eval_select().
Use the vector of locations returned by eval_select() to subset and rename the input data.
Here is how to reimplement dplyr::select() in 3 lines representing each of the steps above:
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 rowsIf your selecting function takes named arguments, the defusing step is a bit different. We need to use enquo() to defuse the function argument itself.
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 rowsThe eval_rename() variant is rarely needed and only mentioned here for completeness. First note that both eval_select() and eval_rename() allow renaming variables:
eval_select(rlang::expr(c(foo = mpg)), mtcars)
#> foo
#> 1
eval_rename(rlang::expr(c(foo = mpg)), mtcars)
#> foo
#> 1eval_rename() is very similar to eval_select() but it has more constraints because it is meant for renaming variables in place. In particular it throws an error if the selected inputs are unnamed. In practice, eval_rename() only accepts a c() expression as expr argument, and all inputs inside the outermost c() must be named:
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
#> 1Because of this constraint, it doesn’t make much sense to take a named argument, most of the time you’ll want to pass dots to a defused c() expression. This way the user can easily pass names with the selections:
wrapper <- function(data, ...) {
eval_rename(rlang::expr(c(...)), data)
}
mtcars %>% wrapper(foo = mpg, bar = hp:wt)
#> foo bar1 bar2 bar3
#> 1 4 5 6As an example of how to use the vector of locations returned by eval_rename(), here is how to implement dplyr::rename():
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 rowsTools like starts_with() or contains() are called selection helpers. These tools inspect the variable names currently available for selection with peek_vars(). The variable names are registered automatically by eval_select() for the duration of the evaluation:
x <- rlang::expr(print(peek_vars()))
invisible(eval_select(x, data = mtcars))
#> [1] "mpg" "cyl" "disp" "hp" "drat" "wt" "qsec" "vs" "am" "gear"
#> [11] "carb"Such properties temporarily available by calling a function like peek_vars() are called descriptors. Descriptors are useful because they are very easy to compose. For instance, a user could combine starts_with() and ends_with() without having to worry about passing the variables or the environment in which they can be found:
my_selector <- function(prefix, suffix) {
intersect(
starts_with(prefix),
ends_with(suffix)
)
}
iris %>% select(my_selector("Sepal", "Length"))
#> # A tibble: 150 × 1
#> Sepal.Length
#> <dbl>
#> 1 5.1
#> 2 4.9
#> 3 4.7
#> 4 4.6
#> # ℹ 146 more rowsTo create a new selection helper:
Inspect the variables with peek_vars(). By convention this should be done in an argument that the user can override.
Return one of the supported data types: vector of names or locations (the latter is recommended, see section on handling duplicate variables), or a predicate function.
if_width <- function(n, vars = peek_vars(fn = "if_width")) {
vars[nchar(vars) == n]
}
mtcars %>% select(if_width(2))
#> # A tibble: 32 × 4
#> hp wt vs am
#> <dbl> <dbl> <dbl> <dbl>
#> 1 110 2.62 0 1
#> 2 110 2.88 0 1
#> 3 93 2.32 1 1
#> 4 110 3.22 1 0
#> # ℹ 28 more rowsThe fn argument makes the error message more informative when the helper is used in the wrong context:
mtcars[if_width(2)]
#> Error:
#> ! `if_width()` must be used within a *selecting* function.
#> ℹ See <https://tidyselect.r-lib.org/reference/faq-selection-context.html> for
#> details.Because the variables are inspected in a default argument, it is easy to override. This is mostly useful in unit tests:
if_width(2, vars = names(mtcars))
#> [1] "hp" "wt" "vs" "am"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 1Supporting 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] 3The defusing step is also known as quoting.↩︎
These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.