File: dplyr_tidy_select.Rd

package info (click to toggle)
r-cran-dplyr 1.1.4-4
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 4,292 kB
  • sloc: cpp: 1,403; sh: 17; makefile: 7
file content (73 lines) | stat: -rw-r--r-- 3,041 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/doc-params.R
\name{dplyr_tidy_select}
\alias{dplyr_tidy_select}
\title{Argument type: tidy-select}
\description{
This page describes the \verb{<tidy-select>} argument modifier which indicates
the argument supports \strong{tidy selections}. Tidy selection provides a concise
dialect of R for selecting variables based on their names or properties.

Tidy selection is a variant of tidy evaluation. This means that inside
functions, tidy-select arguments require special attention, as described in
the \emph{Indirection} section below. If you've never heard of tidy evaluation
before, start with \code{vignette("programming")}.
}
\section{Overview of selection features}{
Tidyverse selections implement a dialect of R where operators make
it easy to select variables:
\itemize{
\item \code{:} for selecting a range of consecutive variables.
\item \code{!} for taking the complement of a set of variables.
\item \code{&} and \code{|} for selecting the intersection or the union of two
sets of variables.
\item \code{c()} for combining selections.
}

In addition, you can use \strong{selection helpers}. Some helpers select specific
columns:
\itemize{
\item \code{\link[tidyselect:everything]{everything()}}: Matches all variables.
\item \code{\link[tidyselect:everything]{last_col()}}: Select last variable, possibly with an offset.
\item \code{\link[=group_cols]{group_cols()}}: Select all grouping columns.
}

Other helpers select variables by matching patterns in their names:
\itemize{
\item \code{\link[tidyselect:starts_with]{starts_with()}}: Starts with a prefix.
\item \code{\link[tidyselect:starts_with]{ends_with()}}: Ends with a suffix.
\item \code{\link[tidyselect:starts_with]{contains()}}: Contains a literal string.
\item \code{\link[tidyselect:starts_with]{matches()}}: Matches a regular expression.
\item \code{\link[tidyselect:starts_with]{num_range()}}: Matches a numerical range like x01, x02, x03.
}

Or from variables stored in a character vector:
\itemize{
\item \code{\link[tidyselect:all_of]{all_of()}}: Matches variable names in a character vector. All
names must be present, otherwise an out-of-bounds error is
thrown.
\item \code{\link[tidyselect:all_of]{any_of()}}: Same as \code{all_of()}, except that no error is thrown
for names that don't exist.
}

Or using a predicate function:
\itemize{
\item \code{\link[tidyselect:where]{where()}}: Applies a function to all variables and selects those
for which the function returns \code{TRUE}.
}
}

\section{Indirection}{
There are two main cases:
\itemize{
\item If you have a character vector of column names, use \code{all_of()}
or \code{any_of()}, depending on whether or not you want unknown variable
names to cause an error, e.g. \code{select(df, all_of(vars))},
\code{select(df, !any_of(vars))}.
\item If you want the user to be able to supply a tidyselect specification in
a function argument, embrace the function argument, e.g.
\code{select(df, {{ vars }})}.
}
}

\keyword{internal}