This page describes the <tidy-select>
argument modifier which
indicates that the argument uses tidy selection, a sub-type of
tidy evaluation. If you've never heard of tidy evaluation before,
start with the practical introduction in
https://r4ds.hadley.nz/functions.html#data-frame-functions then
then read more about the underlying theory in
https://rlang.r-lib.org/reference/topic-data-mask.html.
Overview of selection features
tidyselect implements a DSL for selecting variables. It provides helpers for selecting variables:
var1:var10
: variables lying betweenvar1
on the left andvar10
on the right.
starts_with("a")
: names that start with"a"
.ends_with("z")
: names that end with"z"
.contains("b")
: names that contain"b"
.matches("x.y")
: names that match regular expressionx.y
.num_range(x, 1:4)
: names following the pattern,x1
,x2
, ...,x4
.all_of(vars)
/any_of(vars)
: matches names stored in the character vectorvars
.all_of(vars)
will error if the variables aren't present;any_of(var)
will match just the variables that exist.everything()
: all variables.last_col()
: furthest column on the right.where(is.numeric)
: all variables whereis.numeric()
returnsTRUE
.
As well as operators for combining those selections:
!selection
: only variables that don't matchselection
.selection1 & selection2
: only variables included in bothselection1
andselection2
.selection1 | selection2
: all variables that match eitherselection1
orselection2
.
Key techniques
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.gunnest(df, {{ vars }})
.If you have a character vector of column names, use
all_of()
orany_of()
, depending on whether or not you want unknown variable names to cause an error, e.gunnest(df, all_of(vars))
,unnest(df, !any_of(vars))
.To suppress
R CMD check
NOTE
s about unknown variables use"var"
instead ofvar
: