EVOLUTION-MANAGER
Edit File: programming.html
<!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>Programming with tidyr</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> <script>// Hide empty <a> tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) --> // v0.0.1 // Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020. document.addEventListener('DOMContentLoaded', function() { const codeList = document.getElementsByClassName("sourceCode"); for (var i = 0; i < codeList.length; i++) { var linkList = codeList[i].getElementsByTagName('a'); for (var j = 0; j < linkList.length; j++) { if (linkList[j].innerHTML === "") { linkList[j].setAttribute('aria-hidden', 'true'); } } } }); </script> <style type="text/css">code{white-space: pre;}</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; } 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; } /* Alert */ code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ code span.at { color: #7d9029; } /* Attribute */ code span.bn { color: #40a070; } /* BaseN */ code span.bu { } /* BuiltIn */ code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ code span.ch { color: #4070a0; } /* Char */ code span.cn { color: #880000; } /* Constant */ code span.co { color: #60a0b0; font-style: italic; } /* Comment */ code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ code span.do { color: #ba2121; font-style: italic; } /* Documentation */ code span.dt { color: #902000; } /* DataType */ code span.dv { color: #40a070; } /* DecVal */ code span.er { color: #ff0000; font-weight: bold; } /* Error */ code span.ex { } /* Extension */ code span.fl { color: #40a070; } /* Float */ code span.fu { color: #06287e; } /* Function */ code span.im { } /* Import */ code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ code span.kw { color: #007020; font-weight: bold; } /* Keyword */ code span.op { color: #666666; } /* Operator */ code span.ot { color: #007020; } /* Other */ code span.pp { color: #bc7a00; } /* Preprocessor */ code span.sc { color: #4070a0; } /* SpecialChar */ code span.ss { color: #bb6688; } /* SpecialString */ code span.st { color: #4070a0; } /* String */ code span.va { color: #19177c; } /* Variable */ code span.vs { color: #4070a0; } /* VerbatimString */ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ </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; } for (var j = 0; j < rules.length; j++) { var rule = rules[j]; // check if there is a div.sourceCode rule if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") continue; var style = rule.style.cssText; // check if color or background-color is set if (rule.style.color === '' && rule.style.backgroundColor === '') 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">Programming with tidyr</h1> <div id="introduction" class="section level2"> <h2>Introduction</h2> <p>Most tidyr verbs use <strong>tidy evaluation</strong> to make interactive data exploration fast and fluid. Tidy evaluation is a special type of non-standard evaluation used throughout the tidyverse. Here’s some typical tidyr code:</p> <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1"></a><span class="kw">library</span>(tidyr)</span> <span id="cb1-2"><a href="#cb1-2"></a></span> <span id="cb1-3"><a href="#cb1-3"></a>iris <span class="op">%>%</span></span> <span id="cb1-4"><a href="#cb1-4"></a><span class="st"> </span><span class="kw">nest</span>(<span class="dt">data =</span> <span class="op">!</span>Species)</span> <span id="cb1-5"><a href="#cb1-5"></a><span class="co">#> # A tibble: 3 x 2</span></span> <span id="cb1-6"><a href="#cb1-6"></a><span class="co">#> Species data </span></span> <span id="cb1-7"><a href="#cb1-7"></a><span class="co">#> <fct> <list> </span></span> <span id="cb1-8"><a href="#cb1-8"></a><span class="co">#> 1 setosa <tibble [50 × 4]></span></span> <span id="cb1-9"><a href="#cb1-9"></a><span class="co">#> 2 versicolor <tibble [50 × 4]></span></span> <span id="cb1-10"><a href="#cb1-10"></a><span class="co">#> 3 virginica <tibble [50 × 4]></span></span></code></pre></div> <p>Tidy evaluation is why we can use <code>!Species</code> to say “all the columns except <code>Species</code>”, without having to quote the column name (<code>"Species"</code>) or refer to the enclosing data frame (<code>iris$Species</code>).</p> <p>Two basic forms of tidy evaluation are used in tidyr:</p> <ul> <li><p><strong>Tidy selection</strong>: <code>drop_na()</code>, <code>fill()</code>, <code>pivot_longer()</code>/<code>pivot_wider()</code>, <code>nest()</code>/<code>unnest()</code>, <code>separate()</code>/<code>extract()</code>, and <code>unite()</code> let you select variables based on position, name, or type (e.g. <code>1:3</code>, <code>starts_with("x")</code>, or <code>is.numeric</code>). Literally, you can use all the same techniques as with <code>dplyr::select()</code>.</p></li> <li><p><strong>Data masking</strong>: <code>expand()</code>, <code>crossing()</code> and <code>nesting()</code> let you refer to use data variables as if they were variables in the environment (i.e. you write <code>my_variable</code> not <code>df$myvariable</code>).</p></li> </ul> <p>We focus on tidy selection here, since it’s the most common. You can learn more about data masking in the equivalent vignette in dplyr: <a href="https://dplyr.tidyverse.org/dev/articles/programming.html" class="uri">https://dplyr.tidyverse.org/dev/articles/programming.html</a>. For other considerations when writing tidyr code in packages, please see <code>vignette("in-packages")</code>.</p> <p>We’ve pointed out that tidyr’s tidy evaluation interface is optimized for interactive exploration. The flip side is that this adds some challenges to indirect use, i.e. when you’re working inside a <code>for</code> loop or a function. This vignette shows you how to overcome those challenges. We’ll first go over the basics of tidy selection and data masking, talk about how to use them indirectly, and then show you a number of recipes to solve common problems.</p> <p>Before we go on, we reveal the version of tidyr we’re using and make a small dataset to use in examples.</p> <div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1"></a><span class="kw">packageVersion</span>(<span class="st">"tidyr"</span>)</span> <span id="cb2-2"><a href="#cb2-2"></a><span class="co">#> [1] '1.1.2'</span></span> <span id="cb2-3"><a href="#cb2-3"></a></span> <span id="cb2-4"><a href="#cb2-4"></a>mini_iris <-<span class="st"> </span><span class="kw">as_tibble</span>(iris)[<span class="kw">c</span>(<span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">51</span>, <span class="dv">52</span>, <span class="dv">101</span>, <span class="dv">102</span>), ]</span> <span id="cb2-5"><a href="#cb2-5"></a>mini_iris</span> <span id="cb2-6"><a href="#cb2-6"></a><span class="co">#> # A tibble: 6 x 5</span></span> <span id="cb2-7"><a href="#cb2-7"></a><span class="co">#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species </span></span> <span id="cb2-8"><a href="#cb2-8"></a><span class="co">#> <dbl> <dbl> <dbl> <dbl> <fct> </span></span> <span id="cb2-9"><a href="#cb2-9"></a><span class="co">#> 1 5.1 3.5 1.4 0.2 setosa </span></span> <span id="cb2-10"><a href="#cb2-10"></a><span class="co">#> 2 4.9 3 1.4 0.2 setosa </span></span> <span id="cb2-11"><a href="#cb2-11"></a><span class="co">#> 3 7 3.2 4.7 1.4 versicolor</span></span> <span id="cb2-12"><a href="#cb2-12"></a><span class="co">#> 4 6.4 3.2 4.5 1.5 versicolor</span></span> <span id="cb2-13"><a href="#cb2-13"></a><span class="co">#> 5 6.3 3.3 6 2.5 virginica </span></span> <span id="cb2-14"><a href="#cb2-14"></a><span class="co">#> 6 5.8 2.7 5.1 1.9 virginica</span></span></code></pre></div> </div> <div id="tidy-selection" class="section level2"> <h2>Tidy selection</h2> <p>Underneath all functions that use tidy selection is the <a href="https://tidyselect.r-lib.org/">tidyselect</a> package. It provides a miniature domain specific language that makes it easy to select columns by name, position, or type. For example:</p> <ul> <li><p><code>select(df, 1)</code> selects the first column; <code>select(df, last_col())</code> selects the last column.</p></li> <li><p><code>select(df, c(a, b, c))</code> selects columns <code>a</code>, <code>b</code>, and <code>c</code>.</p></li> <li><p><code>select(df, starts_with("a"))</code> selects all columns whose name starts with “a”; <code>select(df, ends_with("z"))</code> selects all columns whose name ends with “z”.</p></li> <li><p><code>select(df, where(is.numeric))</code> selects all numeric columns.</p></li> </ul> <p>You can see more details in <code>?tidyr_tidy_select</code>.</p> <div id="indirection" class="section level3"> <h3>Indirection</h3> <p>Tidy selection makes a common task easier at the cost of making a less common task harder. When you want to use tidy select indirectly with the column specification stored in an intermediate variable, you’ll need to learn some new tools. There are three main cases where this comes up:</p> <ul> <li><p>When you have the tidy-select specification in a function argument, you must <strong>embrace</strong> the argument by surrounding it in doubled braces.</p> <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1"></a>nest_egg <-<span class="st"> </span><span class="cf">function</span>(df, cols) {</span> <span id="cb3-2"><a href="#cb3-2"></a> <span class="kw">nest</span>(df, <span class="dt">egg =</span> {{ cols }})</span> <span id="cb3-3"><a href="#cb3-3"></a>}</span> <span id="cb3-4"><a href="#cb3-4"></a></span> <span id="cb3-5"><a href="#cb3-5"></a><span class="kw">nest_egg</span>(mini_iris, <span class="op">!</span>Species)</span> <span id="cb3-6"><a href="#cb3-6"></a><span class="co">#> # A tibble: 3 x 2</span></span> <span id="cb3-7"><a href="#cb3-7"></a><span class="co">#> Species egg </span></span> <span id="cb3-8"><a href="#cb3-8"></a><span class="co">#> <fct> <list> </span></span> <span id="cb3-9"><a href="#cb3-9"></a><span class="co">#> 1 setosa <tibble [2 × 4]></span></span> <span id="cb3-10"><a href="#cb3-10"></a><span class="co">#> 2 versicolor <tibble [2 × 4]></span></span> <span id="cb3-11"><a href="#cb3-11"></a><span class="co">#> 3 virginica <tibble [2 × 4]></span></span></code></pre></div></li> <li><p>When you have a character vector of variable names, you must use <code>all_of()</code> or <code>any_of()</code> depending on whether you want the function to error if a variable is not found. These functions allow you to write for loops or a function that takes variable names as a character vector.</p> <div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1"></a>nest_egg <-<span class="st"> </span><span class="cf">function</span>(df, cols) {</span> <span id="cb4-2"><a href="#cb4-2"></a> <span class="kw">nest</span>(df, <span class="dt">egg =</span> <span class="kw">all_of</span>(cols))</span> <span id="cb4-3"><a href="#cb4-3"></a>}</span> <span id="cb4-4"><a href="#cb4-4"></a></span> <span id="cb4-5"><a href="#cb4-5"></a>vars <-<span class="st"> </span><span class="kw">c</span>(<span class="st">"Sepal.Length"</span>, <span class="st">"Sepal.Width"</span>, <span class="st">"Petal.Length"</span>, <span class="st">"Petal.Width"</span>)</span> <span id="cb4-6"><a href="#cb4-6"></a><span class="kw">nest_egg</span>(mini_iris, vars)</span> <span id="cb4-7"><a href="#cb4-7"></a><span class="co">#> # A tibble: 3 x 2</span></span> <span id="cb4-8"><a href="#cb4-8"></a><span class="co">#> Species egg </span></span> <span id="cb4-9"><a href="#cb4-9"></a><span class="co">#> <fct> <list> </span></span> <span id="cb4-10"><a href="#cb4-10"></a><span class="co">#> 1 setosa <tibble [2 × 4]></span></span> <span id="cb4-11"><a href="#cb4-11"></a><span class="co">#> 2 versicolor <tibble [2 × 4]></span></span> <span id="cb4-12"><a href="#cb4-12"></a><span class="co">#> 3 virginica <tibble [2 × 4]></span></span></code></pre></div></li> <li><p>In more complicated cases, you might want to use tidyselect directly:</p> <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1"></a>sel_vars <-<span class="st"> </span><span class="cf">function</span>(df, cols) {</span> <span id="cb5-2"><a href="#cb5-2"></a> tidyselect<span class="op">::</span><span class="kw">eval_select</span>(rlang<span class="op">::</span><span class="kw">enquo</span>(cols), df)</span> <span id="cb5-3"><a href="#cb5-3"></a>}</span> <span id="cb5-4"><a href="#cb5-4"></a><span class="kw">sel_vars</span>(mini_iris, <span class="op">!</span>Species)</span> <span id="cb5-5"><a href="#cb5-5"></a><span class="co">#> Sepal.Length Sepal.Width Petal.Length Petal.Width </span></span> <span id="cb5-6"><a href="#cb5-6"></a><span class="co">#> 1 2 3 4</span></span></code></pre></div> <p>Learn more in <code>vignette("tidyselect")</code>.</p></li> </ul> <p>Note that many tidyr functions use <code>...</code> so you can easily select many variables, e.g. <code>fill(df, x, y, z)</code>. I now believe that the disadvantages of this approach outweigh the benefits, and that this interface would have been better as <code>fill(df, c(x, y, z))</code>. For new functions that select columns, please just use a single argument and not <code>...</code>.</p> </div> </div> <!-- code folding --> <!-- dynamically load mathjax for compatibility with self-contained --> <script> (function () { var script = document.createElement("script"); script.type = "text/javascript"; script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"; document.getElementsByTagName("head")[0].appendChild(script); })(); </script> </body> </html>