Description

This page the describes the <tidy-select> argument modifier which indicates the argument uses tidy selection (a special type of tidy evaluation). Tidy selection provides a concise DSL for selecting variables based on their names.

Overview of selection features

Tidyverse selections implement a dialect of R where operators make it easy to select variables:

• : for selecting a range of consecutive variables.

• ! for taking the complement of a set of variables.

• & and | for selecting the intersection or the union of two sets of variables.

• c() for combining selections.

In addition, you can use selection helpers. Some helpers select specific columns:

• everything(): Matches all variables.

• last_col(): Select last variable, possibly with an offset.

These helpers select variables by matching patterns in their names:

• starts_with(): Starts with a prefix.

• ends_with(): Ends with a suffix.

• contains(): Contains a literal string.

• matches(): Matches a regular expression.

• num_range(): Matches a numerical range like x01, x02, x03.

These helpers select variables from a character vector:

• all_of(): Matches variable names in a character vector. All names must be present, otherwise an out-of-bounds error is thrown.

• any_of(): Same as all_of(), except that no error is thrown for names that don't exist.

This helper selects variables with a function:

• where(): Applies a function to all variables and selects those for which the function returns TRUE.

Indirection

There are two main cases:

• If you have a character vector of column names, use all_of() or any_of(), depending on whether or not you want unknown variable names to cause an error, e.g unnest(df, all_of(vars)), unnest(df, !any_of(vars)).

• If you want the user to supply a tidyselect specification in a function argument, you need to tunnel the selection through the function argument. This is done by embracing the function argument {{ }}, e.g unnest(df, {{ vars }}).

Learn more in vignette("programming.Rmd").