skimr

<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta http-equiv="X-UA-Compatible" content="IE=EDGE" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Technical description of tidyselect</title> <script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to // be compatible with the behavior of Pandoc < 2.8). document.addEventListener('DOMContentLoaded', function(e) { var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); var i, h, a; for (i = 0; i < hs.length; i++) { h = hs[i]; if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 a = h.attributes; while (a.length > 0) h.removeAttribute(a[0].name); } }); </script> <style type="text/css"> code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} </style> <style type="text/css"> code { white-space: pre; } .sourceCode { overflow: visible; } </style> <style type="text/css" data-origin="pandoc"> pre > code.sourceCode { white-space: pre; position: relative; } pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } pre > code.sourceCode > span:empty { height: 1.2em; } .sourceCode { overflow: visible; } code.sourceCode > span { color: inherit; text-decoration: inherit; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { pre > code.sourceCode { white-space: pre-wrap; } pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } } pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } } code span.al { color: #ff0000; font-weight: bold; } code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } code span.at { color: #7d9029; } code span.bn { color: #40a070; } code span.bu { color: #008000; } code span.cf { color: #007020; font-weight: bold; } code span.ch { color: #4070a0; } code span.cn { color: #880000; } code span.co { color: #60a0b0; font-style: italic; } code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } code span.do { color: #ba2121; font-style: italic; } code span.dt { color: #902000; } code span.dv { color: #40a070; } code span.er { color: #ff0000; font-weight: bold; } code span.ex { } code span.fl { color: #40a070; } code span.fu { color: #06287e; } code span.im { color: #008000; font-weight: bold; } code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } code span.kw { color: #007020; font-weight: bold; } code span.op { color: #666666; } code span.ot { color: #007020; } code span.pp { color: #bc7a00; } code span.sc { color: #4070a0; } code span.ss { color: #bb6688; } code span.st { color: #4070a0; } code span.va { color: #19177c; } code span.vs { color: #4070a0; } code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } </style> <script> // apply pandoc div.sourceCode style to pre.sourceCode instead (function() { var sheets = document.styleSheets; for (var i = 0; i < sheets.length; i++) { if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue; try { var rules = sheets[i].cssRules; } catch (e) { continue; } var j = 0; while (j < rules.length) { var rule = rules[j]; // check if there is a div.sourceCode rule if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") { j++; continue; } var style = rule.style.cssText; // check if color or background-color is set if (rule.style.color === '' && rule.style.backgroundColor === '') { j++; continue; } // replace div.sourceCode by a pre.sourceCode rule sheets[i].deleteRule(j); sheets[i].insertRule('pre.sourceCode{' + style + '}', j); } } })(); </script> <style type="text/css">body { background-color: #fff; margin: 1em auto; max-width: 700px; overflow: visible; padding-left: 2em; padding-right: 2em; font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.35; } #TOC { clear: both; margin: 0 0 10px 10px; padding: 4px; width: 400px; border: 1px solid #CCCCCC; border-radius: 5px; background-color: #f6f6f6; font-size: 13px; line-height: 1.3; } #TOC .toctitle { font-weight: bold; font-size: 15px; margin-left: 5px; } #TOC ul { padding-left: 40px; margin-left: -1.5em; margin-top: 5px; margin-bottom: 5px; } #TOC ul ul { margin-left: -2em; } #TOC li { line-height: 16px; } table { margin: 1em auto; border-width: 1px; border-color: #DDDDDD; border-style: outset; border-collapse: collapse; } table th { border-width: 2px; padding: 5px; border-style: inset; } table td { border-width: 1px; border-style: inset; line-height: 18px; padding: 5px 5px; } table, table th, table td { border-left-style: none; border-right-style: none; } table thead, table tr.even { background-color: #f7f7f7; } p { margin: 0.5em 0; } blockquote { background-color: #f6f6f6; padding: 0.25em 0.75em; } hr { border-style: solid; border: none; border-top: 1px solid #777; margin: 28px 0; } dl { margin-left: 0; } dl dd { margin-bottom: 13px; margin-left: 13px; } dl dt { font-weight: bold; } ul { margin-top: 0; } ul li { list-style: circle outside; } ul ul { margin-bottom: 0; } pre, code { background-color: #f7f7f7; border-radius: 3px; color: #333; white-space: pre-wrap; } pre { border-radius: 3px; margin: 5px 0px 10px 0px; padding: 10px; } pre:not([class]) { background-color: #f7f7f7; } code { font-family: Consolas, Monaco, 'Courier New', monospace; font-size: 85%; } p > code, li > code { padding: 2px 0px; } div.figure { text-align: center; } img { background-color: #FFFFFF; padding: 2px; border: 1px solid #DDDDDD; border-radius: 3px; border: 1px solid #CCCCCC; margin: 0 5px; } h1 { margin-top: 0; font-size: 35px; line-height: 40px; } h2 { border-bottom: 4px solid #f7f7f7; padding-top: 10px; padding-bottom: 2px; font-size: 145%; } h3 { border-bottom: 2px solid #f7f7f7; padding-top: 10px; font-size: 120%; } h4 { border-bottom: 1px solid #f7f7f7; margin-left: 8px; font-size: 105%; } h5, h6 { border-bottom: 1px solid #ccc; font-size: 105%; } a { color: #0033dd; text-decoration: none; } a:hover { color: #6666ff; } a:visited { color: #800080; } a:visited:hover { color: #BB00BB; } a[href^="http:"] { text-decoration: underline; } a[href^="https:"] { text-decoration: underline; } code > span.kw { color: #555; font-weight: bold; } code > span.dt { color: #902000; } code > span.dv { color: #40a070; } code > span.bn { color: #d14; } code > span.fl { color: #d14; } code > span.ch { color: #d14; } code > span.st { color: #d14; } code > span.co { color: #888888; font-style: italic; } code > span.ot { color: #007020; } code > span.al { color: #ff0000; font-weight: bold; } code > span.fu { color: #900; font-weight: bold; } code > span.er { color: #a61717; background-color: #e3d2d2; } </style> </head> <body> <h1 class="title toc-ignore">Technical description of tidyselect</h1> This is a technical description of the tidyselect syntax. <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>library(tidyselect) <a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>library(magrittr) <a href="#cb1-3" aria-hidden="true" tabindex="-1"></a> <a href="#cb1-4" aria-hidden="true" tabindex="-1"></a># For better printing <a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>mtcars <- tibble::as_tibble(mtcars) <a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>iris <- tibble::as_tibble(iris)</code></pre></div> To illustrate the semantics of tidyselect, we’ll use variants of <code>dplyr::select()</code> and <code>dplyr::rename()</code> that return the named vector of locations for the selected or renamed elements: <div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>select_loc <- function(data, ...) { <a href="#cb2-2" aria-hidden="true" tabindex="-1"></a> eval_select(rlang::expr(c(...)), data) <a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>} <a href="#cb2-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb2-5" aria-hidden="true" tabindex="-1"></a>rename_loc <- function(data, ...) { <a href="#cb2-6" aria-hidden="true" tabindex="-1"></a> eval_rename(rlang::expr(c(...)), data) <a href="#cb2-7" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> <div id="sets-of-variables" class="section level2"> <h2>Sets of variables</h2> The tidyselect syntax is all about sets of variables, internally represented by integer vectors of locations. For example, <code>c(1L, 2L)</code> represents the set of the first and second variables, as does <code>c(1L, 2L, 1L)</code>. If a vector of locations contains duplicates, they are normally treated as the same element, since they represent sets. An exception to this occurs with named elements whose names differ. If the names don’t match, they are treated as different elements in order to allow renaming a variable to multiple names (see section on Renaming variables). Today, the syntax of tidyselect is generally designed around Boolean algebra, i.e. we recommend writing <code>starts_with("a") & !ends_with("z")</code>. Earlier versions of tidyselect had more of a flavour of set operations, so that you’d write <code>starts_with("a") - ends_with("b")</code>. While the set operations are still supported, and is how tidyselect represents variables internally, we no longer recommend them because Boolean algebra is easy for people to understand. <div id="bare-names" class="section level3"> <h3>Bare names</h3> Within data-expressions (see Evaluation section), bare names represent their own locations, i.e. a set of size 1. The following expressions are equivalent: <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(mpg:hp, !cyl, vs) <a href="#cb3-2" aria-hidden="true" tabindex="-1"></a>#> mpg cyl disp hp drat wt qsec vs am gear carb <a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>#> 1 2 3 4 5 6 7 8 9 10 11 <a href="#cb3-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb3-5" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(1:4, !2, 8) <a href="#cb3-6" aria-hidden="true" tabindex="-1"></a>#> mpg cyl disp hp drat wt qsec vs am gear carb <a href="#cb3-7" aria-hidden="true" tabindex="-1"></a>#> 1 2 3 4 5 6 7 8 9 10 11</code></pre></div> </div> <div id="the-operator" class="section level3"> <h3>The <code>:</code> operator</h3> <code>:</code> can be used to select consecutive variables between two locations. It returns the corresponding sequence of locations. <div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(2:4) <a href="#cb4-2" aria-hidden="true" tabindex="-1"></a>#> cyl disp hp <a href="#cb4-3" aria-hidden="true" tabindex="-1"></a>#> 2 3 4</code></pre></div> Because bare names represent their own locations, it is easy to select a range of variables: <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(cyl:hp) <a href="#cb5-2" aria-hidden="true" tabindex="-1"></a>#> cyl disp hp <a href="#cb5-3" aria-hidden="true" tabindex="-1"></a>#> 2 3 4</code></pre></div> </div> <div id="boolean-operators" class="section level3"> <h3>Boolean operators</h3> The <code>|</code> operator takes the union of two sets: <div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(starts_with("Sepal") | ends_with("Width")) <a href="#cb6-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Sepal.Width Petal.Width <a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>#> 1 2 4</code></pre></div> The <code>&</code> operator takes the intersection of two sets: <div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(starts_with("Sepal") & ends_with("Width")) <a href="#cb7-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Width <a href="#cb7-3" aria-hidden="true" tabindex="-1"></a>#> 2</code></pre></div> The <code>!</code> operator takes the complement of a set: <div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(!ends_with("Width")) <a href="#cb8-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Petal.Length Species <a href="#cb8-3" aria-hidden="true" tabindex="-1"></a>#> 1 3 5</code></pre></div> Taking the intersection with a complement produces a set difference: <div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(starts_with("Sepal") & !ends_with("Width")) <a href="#cb9-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length <a href="#cb9-3" aria-hidden="true" tabindex="-1"></a>#> 1</code></pre></div> </div> <div id="dots-and-c" class="section level3"> <h3>Dots and <code>c()</code></h3> tidyselect functions can take dots, like <code>dplyr::select()</code>, or a named argument, like <code>tidyr::pivot_longer()</code>. In the latter case, the dots syntax is accessible via <code>c()</code>. In fact <code>...</code> syntax is implemented through <code>c(...)</code> and is thus completely equivalent. <div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(mpg, disp:hp) <a href="#cb10-2" aria-hidden="true" tabindex="-1"></a>#> mpg disp hp <a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>#> 1 3 4 <a href="#cb10-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb10-5" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(c(mpg, disp:hp)) <a href="#cb10-6" aria-hidden="true" tabindex="-1"></a>#> mpg disp hp <a href="#cb10-7" aria-hidden="true" tabindex="-1"></a>#> 1 3 4</code></pre></div> <code>c(x, y, z)</code> is a equivalent to <code>x | y | z</code>: <div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(starts_with("Sepal"), ends_with("Width"), Species) <a href="#cb11-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Sepal.Width Petal.Width Species <a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>#> 1 2 4 5 <a href="#cb11-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(starts_with("Sepal") | ends_with("Width") | Species) <a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Sepal.Width Petal.Width Species <a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>#> 1 2 4 5</code></pre></div> </div> <div id="renaming-variables" class="section level3"> <h3>Renaming variables</h3> <div id="name-combination-and-propagation" class="section level4"> <h4>Name combination and propagation</h4> When named inputs are provided in <code>...</code> or <code>c()</code>, the selection is renamed. If the inputs are already named, the outer and inner names are combined with a <code>...</code> separator: <div class="sourceCode" id="cb12"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(foo = c(bar = mpg, baz = cyl)) <a href="#cb12-2" aria-hidden="true" tabindex="-1"></a>#> foo...bar foo...baz <a href="#cb12-3" aria-hidden="true" tabindex="-1"></a>#> 1 2</code></pre></div> Otherwise the outer names is propagated to the selected elements according to the following rules: <ul> <li>With data frames, a numeric suffix is appended because columns must be uniquely named. <div class="sourceCode" id="cb13"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(foo = c(mpg, cyl)) <a href="#cb13-2" aria-hidden="true" tabindex="-1"></a>#> foo1 foo2 <a href="#cb13-3" aria-hidden="true" tabindex="-1"></a>#> 1 2</code></pre></div></li> <li>With normal vectors, the name is simply assigned to all selected inputs. <div class="sourceCode" id="cb14"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a>as.list(mtcars) %>% select_loc(foo = c(mpg, cyl)) <a href="#cb14-2" aria-hidden="true" tabindex="-1"></a>#> foo foo <a href="#cb14-3" aria-hidden="true" tabindex="-1"></a>#> 1 2</code></pre></div></li> </ul> Combination and propagation can be composed by using nested <code>c()</code>: <div class="sourceCode" id="cb15"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(foo = c(bar = c(mpg, cyl))) <a href="#cb15-2" aria-hidden="true" tabindex="-1"></a>#> foo...bar1 foo...bar2 <a href="#cb15-3" aria-hidden="true" tabindex="-1"></a>#> 1 2</code></pre></div> </div> <div id="set-combination-with-named-variables" class="section level4"> <h4>Set combination with named variables</h4> Named elements have special rules to determine their identities in a set. Unnamed elements match any names: <ul> <li><code>a | c(foo = a)</code> is equivalent to <code>c(foo = a)</code>.</li> <li><code>a & c(foo = a)</code> is equivalent to <code>c(foo = a)</code>.</li> </ul> Named elements with different names are distinct: <ul> <li><code>c(foo = a) & c(bar = a)</code> is equivalent to <code>c()</code>.</li> <li><code>c(foo = a) | c(bar = a)</code> is equivalent to <code>c(foo = a, bar = a)</code>.</li> </ul> Because unnamed elements match any named ones, it is possible to select multiple elements and rename one of them: <div class="sourceCode" id="cb16"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(!Species, foo = Sepal.Width) <a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length foo Petal.Length Petal.Width <a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>#> 1 2 3 4</code></pre></div> </div> </div> <div id="predicate-functions" class="section level3"> <h3>Predicate functions</h3> Predicate function objects can be supplied as input in an env-expression, typically with the selection helper <code>where()</code>. They are applied to all elements of the data, and should return <code>TRUE</code> or <code>FALSE</code> to indicate inclusion. Predicates in env-expressions are effectively expanded to the set of variables that they represent: <div class="sourceCode" id="cb17"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(where(is.numeric)) <a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Sepal.Width Petal.Length Petal.Width <a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>#> 1 2 3 4 <a href="#cb17-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(where(is.factor)) <a href="#cb17-6" aria-hidden="true" tabindex="-1"></a>#> Species <a href="#cb17-7" aria-hidden="true" tabindex="-1"></a>#> 5 <a href="#cb17-8" aria-hidden="true" tabindex="-1"></a> <a href="#cb17-9" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(where(is.numeric) | where(is.factor)) <a href="#cb17-10" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species <a href="#cb17-11" aria-hidden="true" tabindex="-1"></a>#> 1 2 3 4 5 <a href="#cb17-12" aria-hidden="true" tabindex="-1"></a> <a href="#cb17-13" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(where(is.numeric) & where(is.factor)) <a href="#cb17-14" aria-hidden="true" tabindex="-1"></a>#> named integer(0)</code></pre></div> </div> </div> <div id="selection-helpers" class="section level2"> <h2>Selection helpers</h2> We call selection helpers any function that inspects the currently active variables with <code>peek_vars()</code> and returns a selection. <ul> <li><code>peek_vars()</code> returns a character vector of names.</li> <li>The returned selection can be any output conforming to the types described in the Data types section.</li> </ul> Examples of selection helpers are <code>all_of()</code>, <code>contains()</code>, or <code>last_col()</code>. These selection helpers are evaluated as env-expressions (see Evaluation section). </div> <div id="supported-data-types" class="section level2"> <h2>Supported data types</h2> The following data types can be returned from selection helpers or forced via <code>!!</code> or <code>force()</code> (the latter works in tidyselect because it is treated as an env-expression, see Evaluation section): <ul> <li>Vectors of locations: <div class="sourceCode" id="cb18"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(force(c(1, 3))) <a href="#cb18-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Petal.Length <a href="#cb18-3" aria-hidden="true" tabindex="-1"></a>#> 1 3</code></pre></div></li> <li>Vectors of names. These are matched and transformed to locations. <div class="sourceCode" id="cb19"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(force(c("Sepal.Length", "Petal.Length"))) <a href="#cb19-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Petal.Length <a href="#cb19-3" aria-hidden="true" tabindex="-1"></a>#> 1 3</code></pre></div></li> <li>Predicate functions. These are applied to all elements to determine inclusion. <div class="sourceCode" id="cb20"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a>iris %>% select_loc(force(is.numeric)) <a href="#cb20-2" aria-hidden="true" tabindex="-1"></a>#> Sepal.Length Sepal.Width Petal.Length Petal.Width <a href="#cb20-3" aria-hidden="true" tabindex="-1"></a>#> 1 2 3 4</code></pre></div></li> </ul> </div> <div id="evaluation" class="section level2"> <h2>Evaluation</h2> <div id="data-expressions-and-env-expressions" class="section level3"> <h3>Data-expressions and env-expressions</h3> tidyselect is not a typical tidy evaluation UI. The main difference is that there is no data masking. In a typical tidy eval function, expressions are evaluated with data-vars first in scope, followed by env-vars: <div class="sourceCode" id="cb21"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a>mask <- function(data, expr) { <a href="#cb21-2" aria-hidden="true" tabindex="-1"></a> rlang::eval_tidy(rlang::enquo(expr), data) <a href="#cb21-3" aria-hidden="true" tabindex="-1"></a>} <a href="#cb21-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb21-5" aria-hidden="true" tabindex="-1"></a>foo <- 10 <a href="#cb21-6" aria-hidden="true" tabindex="-1"></a>cyl <- 200 <a href="#cb21-7" aria-hidden="true" tabindex="-1"></a> <a href="#cb21-8" aria-hidden="true" tabindex="-1"></a># `cyl` represents the data frame column here: <a href="#cb21-9" aria-hidden="true" tabindex="-1"></a>mtcars %>% mask(cyl * foo) <a href="#cb21-10" aria-hidden="true" tabindex="-1"></a>#> [1] 60 60 40 60 80 60 80 40 40 60 60 80 80 80 80 80 80 40 40 40 40 80 80 80 80 <a href="#cb21-11" aria-hidden="true" tabindex="-1"></a>#> [26] 40 40 40 80 60 80 40</code></pre></div> It is possible to bypass the data frame variables by forcing symbols to be looked up in the environment with <code>!!</code> or <code>.env</code>: <div class="sourceCode" id="cb22"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% mask(!!cyl * foo) <a href="#cb22-2" aria-hidden="true" tabindex="-1"></a>#> [1] 2000 <a href="#cb22-3" aria-hidden="true" tabindex="-1"></a>mtcars %>% mask(.env$cyl * foo) <a href="#cb22-4" aria-hidden="true" tabindex="-1"></a>#> [1] 2000</code></pre></div> With tidyselect, there is no such hierarchical data masking. Instead, expressions are evaluated either in the context of the data frame or in the user environment, without overlap. The scope of lookup depends on the kind of expression: <ol style="list-style-type: decimal"> <li>data-expressions are evaluated in the data frame only. This includes bare symbols, the boolean operators, <code>-</code>, <code>:</code>, and <code>c()</code>. You can’t refer to environment-variables in a data-expression: <div class="sourceCode" id="cb23"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a>cyl_pos <- 2 <a href="#cb23-2" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(mpg | cyl_pos) <a href="#cb23-3" aria-hidden="true" tabindex="-1"></a>#> Error in `select_loc()`: <a href="#cb23-4" aria-hidden="true" tabindex="-1"></a>#> ! Can't subset columns that don't exist. <a href="#cb23-5" aria-hidden="true" tabindex="-1"></a>#> ✖ Column `cyl_pos` doesn't exist.</code></pre></div></li> <li>env-expressions are evaluated in the environment. This includes all calls other than those mentioned above, as well as symbols that are part of those calls. You can’t refer to data-variables in a data-expression: <div class="sourceCode" id="cb24"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(all_of(mpg)) <a href="#cb24-2" aria-hidden="true" tabindex="-1"></a>#> Error in `select_loc()`: <a href="#cb24-3" aria-hidden="true" tabindex="-1"></a>#> ! Problem while evaluating `all_of(mpg)`. <a href="#cb24-4" aria-hidden="true" tabindex="-1"></a>#> Caused by error in `as_indices_impl()`: <a href="#cb24-5" aria-hidden="true" tabindex="-1"></a>#> ! object 'mpg' not found</code></pre></div></li> </ol> Because the scoping is unambiguous, you can safely refer to env-vars in an env-expression, without having to worry about potential naming clashes with data-vars: <div class="sourceCode" id="cb25"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a>x <- data.frame(x = 1:3, y = 4:6, z = 7:9) <a href="#cb25-2" aria-hidden="true" tabindex="-1"></a> <a href="#cb25-3" aria-hidden="true" tabindex="-1"></a># `ncol(x)` is an env-expression, so `x` represents the data frame in <a href="#cb25-4" aria-hidden="true" tabindex="-1"></a># the environment rather than the column in the data frame <a href="#cb25-5" aria-hidden="true" tabindex="-1"></a>x %>% select_loc(2:ncol(x)) <a href="#cb25-6" aria-hidden="true" tabindex="-1"></a>#> y z <a href="#cb25-7" aria-hidden="true" tabindex="-1"></a>#> 2 3</code></pre></div> If you have variable names in a character vector, it is safe to refer to the env-var containing the names with <code>all_of()</code> because it is an env-expression: <div class="sourceCode" id="cb26"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a>y <- c("y", "z") <a href="#cb26-2" aria-hidden="true" tabindex="-1"></a>x %>% select_loc(all_of(y)) <a href="#cb26-3" aria-hidden="true" tabindex="-1"></a>#> y z <a href="#cb26-4" aria-hidden="true" tabindex="-1"></a>#> 2 3</code></pre></div> Note that currently, env-vars are still allowed in some data-expressions, for compatibility. However this is in the process of being deprecated and you should see a note recommending to use <code>all_of()</code> instead. This note will become a deprecation warning in the future, and then an error. <div class="sourceCode" id="cb27"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(cyl_pos) <a href="#cb27-2" aria-hidden="true" tabindex="-1"></a>#> Warning: Using an external vector in selections was deprecated in tidyselect 1.1.0. <a href="#cb27-3" aria-hidden="true" tabindex="-1"></a>#> ℹ Please use `all_of()` or `any_of()` instead. <a href="#cb27-4" aria-hidden="true" tabindex="-1"></a>#> # Was: <a href="#cb27-5" aria-hidden="true" tabindex="-1"></a>#> data %>% select(cyl_pos) <a href="#cb27-6" aria-hidden="true" tabindex="-1"></a>#> <a href="#cb27-7" aria-hidden="true" tabindex="-1"></a>#> # Now: <a href="#cb27-8" aria-hidden="true" tabindex="-1"></a>#> data %>% select(all_of(cyl_pos)) <a href="#cb27-9" aria-hidden="true" tabindex="-1"></a>#> <a href="#cb27-10" aria-hidden="true" tabindex="-1"></a>#> See <https://tidyselect.r-lib.org/reference/faq-external-vector.html>. <a href="#cb27-11" aria-hidden="true" tabindex="-1"></a>#> cyl <a href="#cb27-12" aria-hidden="true" tabindex="-1"></a>#> 2</code></pre></div> </div> <div id="arithmetic-operators" class="section level3"> <h3>Arithmetic operators</h3> Within data-expressions (see Evaluation section), <code>+</code>, <code>*</code> and <code>/</code> are overridden to cause an error. This is to prevent confusion stemming from normal data masking usage where variables can be transformed on the fly: <div class="sourceCode" id="cb28"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb28-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(cyl^2) <a href="#cb28-2" aria-hidden="true" tabindex="-1"></a>#> Error in `select_loc()`: <a href="#cb28-3" aria-hidden="true" tabindex="-1"></a>#> ! Can't use arithmetic operator `^` in selection context. <a href="#cb28-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb28-5" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(mpg * wt) <a href="#cb28-6" aria-hidden="true" tabindex="-1"></a>#> Error in `select_loc()`: <a href="#cb28-7" aria-hidden="true" tabindex="-1"></a>#> ! Can't use arithmetic operator `*` in selection context.</code></pre></div> </div> </div> <div id="selecting-versus-renaming" class="section level2"> <h2>Selecting versus renaming</h2> The select and rename variants take the same types of inputs and have the same type of return value. They have a few important differences. <div id="all-renaming-inputs-must-be-named" class="section level3"> <h3>All renaming inputs must be named</h3> Unlike <code>eval_select()</code> which can select without renaming, <code>eval_rename()</code> expects a fully named selection. If one or several names are missing, an error is thrown. <div class="sourceCode" id="cb29"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb29-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(mpg) <a href="#cb29-2" aria-hidden="true" tabindex="-1"></a>#> mpg <a href="#cb29-3" aria-hidden="true" tabindex="-1"></a>#> 1 <a href="#cb29-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb29-5" aria-hidden="true" tabindex="-1"></a>mtcars %>% rename_loc(mpg) <a href="#cb29-6" aria-hidden="true" tabindex="-1"></a>#> Error in `rename_loc()`: <a href="#cb29-7" aria-hidden="true" tabindex="-1"></a>#> ! All renaming inputs must be named.</code></pre></div> </div> <div id="renaming-to-an-existing-variable-name" class="section level3"> <h3>Renaming to an existing variable name</h3> If the input data is a data frame, tidyselect generally throws an error when duplicate column names are selected, in order to respect the invariant of unique column names. <div class="sourceCode" id="cb30"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a># Lists can have duplicates <a href="#cb30-2" aria-hidden="true" tabindex="-1"></a>as.list(mtcars) %>% select_loc(foo = mpg, foo = cyl) <a href="#cb30-3" aria-hidden="true" tabindex="-1"></a>#> foo foo <a href="#cb30-4" aria-hidden="true" tabindex="-1"></a>#> 1 2 <a href="#cb30-5" aria-hidden="true" tabindex="-1"></a> <a href="#cb30-6" aria-hidden="true" tabindex="-1"></a># Data frames cannot <a href="#cb30-7" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(foo = mpg, foo = cyl) <a href="#cb30-8" aria-hidden="true" tabindex="-1"></a>#> Error in `select_loc()`: <a href="#cb30-9" aria-hidden="true" tabindex="-1"></a>#> ! Names must be unique. <a href="#cb30-10" aria-hidden="true" tabindex="-1"></a>#> ✖ These names are duplicated: <a href="#cb30-11" aria-hidden="true" tabindex="-1"></a>#> * "foo" at locations 1 and 2.</code></pre></div> A selection can rename a variable to an existing name if the latter is not part of the selection: <div class="sourceCode" id="cb31"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb31-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(cyl, cyl = mpg) <a href="#cb31-2" aria-hidden="true" tabindex="-1"></a>#> Error in `select_loc()`: <a href="#cb31-3" aria-hidden="true" tabindex="-1"></a>#> ! Names must be unique. <a href="#cb31-4" aria-hidden="true" tabindex="-1"></a>#> ✖ These names are duplicated: <a href="#cb31-5" aria-hidden="true" tabindex="-1"></a>#> * "cyl" at locations 1 and 2. <a href="#cb31-6" aria-hidden="true" tabindex="-1"></a> <a href="#cb31-7" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(disp, cyl = mpg) <a href="#cb31-8" aria-hidden="true" tabindex="-1"></a>#> disp cyl <a href="#cb31-9" aria-hidden="true" tabindex="-1"></a>#> 3 1</code></pre></div> This is not possible when renaming. <div class="sourceCode" id="cb32"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb32-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% rename_loc(cyl, cyl = mpg) <a href="#cb32-2" aria-hidden="true" tabindex="-1"></a>#> Error in `rename_loc()`: <a href="#cb32-3" aria-hidden="true" tabindex="-1"></a>#> ! All renaming inputs must be named. <a href="#cb32-4" aria-hidden="true" tabindex="-1"></a> <a href="#cb32-5" aria-hidden="true" tabindex="-1"></a>mtcars %>% rename_loc(disp, cyl = mpg) <a href="#cb32-6" aria-hidden="true" tabindex="-1"></a>#> Error in `rename_loc()`: <a href="#cb32-7" aria-hidden="true" tabindex="-1"></a>#> ! All renaming inputs must be named.</code></pre></div> However, the name conflict can be solved by renaming the existing variable to another name: <div class="sourceCode" id="cb33"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb33-1" aria-hidden="true" tabindex="-1"></a>mtcars %>% select_loc(foo = cyl, cyl = mpg) <a href="#cb33-2" aria-hidden="true" tabindex="-1"></a><span