File: programming.html

package info (click to toggle)
r-cran-tidyr 1.3.1-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 2,720 kB
sloc: cpp: 268; sh: 9; makefile: 2
file content (499 lines) | stat: -rw-r--r-- 20,608 bytes
<!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>

<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 { 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">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" tabindex="-1"></a><span class="fu">library</span>(tidyr)</span>
<span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a></span>
<span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a>iris <span class="sc">%&gt;%</span></span>
<span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a>  <span class="fu">nest</span>(<span class="at">data =</span> <span class="sc">!</span>Species)</span>
<span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a><span class="co">#&gt; # A tibble: 3 × 2</span></span>
<span id="cb1-6"><a href="#cb1-6" tabindex="-1"></a><span class="co">#&gt;   Species    data             </span></span>
<span id="cb1-7"><a href="#cb1-7" tabindex="-1"></a><span class="co">#&gt;   &lt;fct&gt;      &lt;list&gt;           </span></span>
<span id="cb1-8"><a href="#cb1-8" tabindex="-1"></a><span class="co">#&gt; 1 setosa     &lt;tibble [50 × 4]&gt;</span></span>
<span id="cb1-9"><a href="#cb1-9" tabindex="-1"></a><span class="co">#&gt; 2 versicolor &lt;tibble [50 × 4]&gt;</span></span>
<span id="cb1-10"><a href="#cb1-10" tabindex="-1"></a><span class="co">#&gt; 3 virginica  &lt;tibble [50 × 4]&gt;</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>&quot;Species&quot;</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(&quot;x&quot;)</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$my_variable</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(&quot;in-packages&quot;)</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" tabindex="-1"></a><span class="fu">packageVersion</span>(<span class="st">&quot;tidyr&quot;</span>)</span>
<span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a><span class="co">#&gt; [1] &#39;1.3.1&#39;</span></span>
<span id="cb2-3"><a href="#cb2-3" tabindex="-1"></a></span>
<span id="cb2-4"><a href="#cb2-4" tabindex="-1"></a>mini_iris <span class="ot">&lt;-</span> <span class="fu">as_tibble</span>(iris)[<span class="fu">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" tabindex="-1"></a>mini_iris</span>
<span id="cb2-6"><a href="#cb2-6" tabindex="-1"></a><span class="co">#&gt; # A tibble: 6 × 5</span></span>
<span id="cb2-7"><a href="#cb2-7" tabindex="-1"></a><span class="co">#&gt;   Sepal.Length Sepal.Width Petal.Length Petal.Width Species   </span></span>
<span id="cb2-8"><a href="#cb2-8" tabindex="-1"></a><span class="co">#&gt;          &lt;dbl&gt;       &lt;dbl&gt;        &lt;dbl&gt;       &lt;dbl&gt; &lt;fct&gt;     </span></span>
<span id="cb2-9"><a href="#cb2-9" tabindex="-1"></a><span class="co">#&gt; 1          5.1         3.5          1.4         0.2 setosa    </span></span>
<span id="cb2-10"><a href="#cb2-10" tabindex="-1"></a><span class="co">#&gt; 2          4.9         3            1.4         0.2 setosa    </span></span>
<span id="cb2-11"><a href="#cb2-11" tabindex="-1"></a><span class="co">#&gt; 3          7           3.2          4.7         1.4 versicolor</span></span>
<span id="cb2-12"><a href="#cb2-12" tabindex="-1"></a><span class="co">#&gt; 4          6.4         3.2          4.5         1.5 versicolor</span></span>
<span id="cb2-13"><a href="#cb2-13" tabindex="-1"></a><span class="co">#&gt; 5          6.3         3.3          6           2.5 virginica </span></span>
<span id="cb2-14"><a href="#cb2-14" tabindex="-1"></a><span class="co">#&gt; 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(&quot;a&quot;))</code> selects all columns
whose name starts with “a”; <code>select(df, ends_with(&quot;z&quot;))</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" tabindex="-1"></a>nest_egg <span class="ot">&lt;-</span> <span class="cf">function</span>(df, cols) {</span>
<span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a>  <span class="fu">nest</span>(df, <span class="at">egg =</span> {{ cols }})</span>
<span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a>}</span>
<span id="cb3-4"><a href="#cb3-4" tabindex="-1"></a></span>
<span id="cb3-5"><a href="#cb3-5" tabindex="-1"></a><span class="fu">nest_egg</span>(mini_iris, <span class="sc">!</span>Species)</span>
<span id="cb3-6"><a href="#cb3-6" tabindex="-1"></a><span class="co">#&gt; # A tibble: 3 × 2</span></span>
<span id="cb3-7"><a href="#cb3-7" tabindex="-1"></a><span class="co">#&gt;   Species    egg             </span></span>
<span id="cb3-8"><a href="#cb3-8" tabindex="-1"></a><span class="co">#&gt;   &lt;fct&gt;      &lt;list&gt;          </span></span>
<span id="cb3-9"><a href="#cb3-9" tabindex="-1"></a><span class="co">#&gt; 1 setosa     &lt;tibble [2 × 4]&gt;</span></span>
<span id="cb3-10"><a href="#cb3-10" tabindex="-1"></a><span class="co">#&gt; 2 versicolor &lt;tibble [2 × 4]&gt;</span></span>
<span id="cb3-11"><a href="#cb3-11" tabindex="-1"></a><span class="co">#&gt; 3 virginica  &lt;tibble [2 × 4]&gt;</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" tabindex="-1"></a>nest_egg <span class="ot">&lt;-</span> <span class="cf">function</span>(df, cols) {</span>
<span id="cb4-2"><a href="#cb4-2" tabindex="-1"></a>  <span class="fu">nest</span>(df, <span class="at">egg =</span> <span class="fu">all_of</span>(cols))</span>
<span id="cb4-3"><a href="#cb4-3" tabindex="-1"></a>}</span>
<span id="cb4-4"><a href="#cb4-4" tabindex="-1"></a></span>
<span id="cb4-5"><a href="#cb4-5" tabindex="-1"></a>vars <span class="ot">&lt;-</span> <span class="fu">c</span>(<span class="st">&quot;Sepal.Length&quot;</span>, <span class="st">&quot;Sepal.Width&quot;</span>, <span class="st">&quot;Petal.Length&quot;</span>, <span class="st">&quot;Petal.Width&quot;</span>)</span>
<span id="cb4-6"><a href="#cb4-6" tabindex="-1"></a><span class="fu">nest_egg</span>(mini_iris, vars)</span>
<span id="cb4-7"><a href="#cb4-7" tabindex="-1"></a><span class="co">#&gt; # A tibble: 3 × 2</span></span>
<span id="cb4-8"><a href="#cb4-8" tabindex="-1"></a><span class="co">#&gt;   Species    egg             </span></span>
<span id="cb4-9"><a href="#cb4-9" tabindex="-1"></a><span class="co">#&gt;   &lt;fct&gt;      &lt;list&gt;          </span></span>
<span id="cb4-10"><a href="#cb4-10" tabindex="-1"></a><span class="co">#&gt; 1 setosa     &lt;tibble [2 × 4]&gt;</span></span>
<span id="cb4-11"><a href="#cb4-11" tabindex="-1"></a><span class="co">#&gt; 2 versicolor &lt;tibble [2 × 4]&gt;</span></span>
<span id="cb4-12"><a href="#cb4-12" tabindex="-1"></a><span class="co">#&gt; 3 virginica  &lt;tibble [2 × 4]&gt;</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" tabindex="-1"></a>sel_vars <span class="ot">&lt;-</span> <span class="cf">function</span>(df, cols) {</span>
<span id="cb5-2"><a href="#cb5-2" tabindex="-1"></a>  tidyselect<span class="sc">::</span><span class="fu">eval_select</span>(rlang<span class="sc">::</span><span class="fu">enquo</span>(cols), df)</span>
<span id="cb5-3"><a href="#cb5-3" tabindex="-1"></a>}</span>
<span id="cb5-4"><a href="#cb5-4" tabindex="-1"></a><span class="fu">sel_vars</span>(mini_iris, <span class="sc">!</span>Species)</span>
<span id="cb5-5"><a href="#cb5-5" tabindex="-1"></a><span class="co">#&gt; Sepal.Length  Sepal.Width Petal.Length  Petal.Width </span></span>
<span id="cb5-6"><a href="#cb5-6" tabindex="-1"></a><span class="co">#&gt;            1            2            3            4</span></span></code></pre></div>
<p>Learn more in <code>vignette(&quot;tidyselect&quot;)</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>