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>Using dplyr in packages</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">Using dplyr in packages</h1> <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb1-1" tabindex="-1"></a>library(dplyr)</code></pre></div> This vignette is aimed at package authors who use dplyr in their packages. We will discuss best practices learned over the years to avoid <code>R CMD check</code> notes and warnings, and how to handle when dplyr deprecates functions. <div id="join-helpers" class="section level2"> <h2>Join helpers</h2> As of dplyr 1.1.0, we’ve introduced <code>join_by()</code> along 4 helpers for performing various types of joins: <ul> <li><code>closest()</code></li> <li><code>between()</code></li> <li><code>within()</code></li> <li><code>overlaps()</code></li> </ul> <code>join_by()</code> implements a domain specific language (DSL) for joins, and internally interprets calls to these functions. You’ll notice that <code>dplyr::closest()</code> isn’t an exported function from dplyr (<code>dplyr::between()</code> and <code>base::within()</code> do happen to be preexisting functions). If you use <code>closest()</code> in your package, then this will cause an <code>R CMD check</code> note letting you know that you’ve used a symbol that doesn’t belong to any package. To silence this, place <code>utils::globalVariables("closest")</code> in a source file in your package (but outside of any function). dbplyr does a similar thing for SQL functions, so you can see an example of that <a href="https://github.com/tidyverse/dbplyr/blob/7edf5d607fd6b0b897721ea96d1c9ca9401f0f9b/R/backend-redshift.R#L144">here</a>. You may also have to add utils to your package Imports, even though it is a base package. You can do that easily with <code>usethis::use_package("utils")</code>. </div> <div id="data-masking-and-tidy-selection-notes" class="section level2"> <h2>Data masking and tidy selection NOTEs</h2> If you’re writing a package and you have a function that uses data masking or tidy selection: <div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb2-1" tabindex="-1"></a>my_summary_function <- function(data) { <a href="#cb2-2" tabindex="-1"></a> data %>% <a href="#cb2-3" tabindex="-1"></a> select(grp, x, y) %>% <a href="#cb2-4" tabindex="-1"></a> filter(x > 0) %>% <a href="#cb2-5" tabindex="-1"></a> group_by(grp) %>% <a href="#cb2-6" tabindex="-1"></a> summarise(y = mean(y), n = n()) <a href="#cb2-7" tabindex="-1"></a>}</code></pre></div> You’ll get an <code>NOTE</code> because <code>R CMD check</code> doesn’t know that dplyr functions use tidy evaluation: <pre><code>N checking R code for possible problems my_summary_function: no visible binding for global variable ‘grp’, ‘x’, ‘y’ Undefined global functions or variables: grp x y</code></pre> To eliminate this note: <ul> <li>For data masking, import <code>.data</code> from <a href="https://rlang.r-lib.org/">rlang</a> and then use <code>.data$var</code> instead of <code>var</code>.</li> <li>For tidy selection, use <code>"var"</code> instead of <code>var</code>.</li> </ul> That yields: <div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb4-1" tabindex="-1"></a>#' @importFrom rlang .data <a href="#cb4-2" tabindex="-1"></a>my_summary_function <- function(data) { <a href="#cb4-3" tabindex="-1"></a> data %>% <a href="#cb4-4" tabindex="-1"></a> select("grp", "x", "y") %>% <a href="#cb4-5" tabindex="-1"></a> filter(.data$x > 0) %>% <a href="#cb4-6" tabindex="-1"></a> group_by(.data$grp) %>% <a href="#cb4-7" tabindex="-1"></a> summarise(y = mean(.data$y), n = n()) <a href="#cb4-8" tabindex="-1"></a>}</code></pre></div> For more about programming with dplyr, see <code>vignette("programming", package = "dplyr")</code>. </div> <div id="deprecation" class="section level2"> <h2>Deprecation</h2> This section is focused on updating package code to deal with backwards incompatible changes in dplyr. We do try and minimize backward incompatible changes as much as possible, but sometimes they are necessary in order to radically simplify existing code, or unlock a lot of potential value in the future. We will start with some general advice about supporting multiple versions of dplyr at once, and then we will discuss some specific changes in dplyr. <div id="multiple-dplyr-versions" class="section level3"> <h3>Multiple dplyr versions</h3> Ideally, when we introduce a breaking change you’ll want to make sure that your package works with both the released version and the development version of dplyr. This is typically a little bit more work, but has two big advantages: <ul> <li>It’s more convenient for your users, since your package will work for them regardless of what version of dplyr they have installed.</li> <li>It’s easier on CRAN since it doesn’t require a massive coordinated release of multiple packages.</li> </ul> If we break your package, we will typically send you a pull request that implements a patch before releasing the next version of dplyr. Most of the time, this patch will be backwards compatible with older versions of dplyr as well. Ideally, you’ll accept this patch and submit a new version of your package to CRAN before the new version of dplyr is released. To make code work with multiple versions of a package, your first tool is the simple if statement: <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb5-1" tabindex="-1"></a>if (utils::packageVersion("dplyr") > "0.5.0") { <a href="#cb5-2" tabindex="-1"></a> # code for new version <a href="#cb5-3" tabindex="-1"></a>} else { <a href="#cb5-4" tabindex="-1"></a> # code for old version <a href="#cb5-5" tabindex="-1"></a>}</code></pre></div> Always condition on <code>> current-version</code>, not <code>>= next-version</code> because this will ensure that this branch is also used for the development version of the package. For example, if the current release is version <code>"0.5.0"</code>, the development version will be <code>"0.5.0.9000"</code>. This typically works well if the branch for the “new version” introduces a new argument or has a slightly different return value. This doesn’t work if we’ve introduced a new function that you need to switch to, like: <div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb6-1" tabindex="-1"></a>if (utils::packageVersion("dplyr") > "1.0.10") { <a href="#cb6-2" tabindex="-1"></a> dplyr::reframe(df, x = unique(x)) <a href="#cb6-3" tabindex="-1"></a>} else { <a href="#cb6-4" tabindex="-1"></a> dplyr::summarise(df, x = unique(x)) <a href="#cb6-5" tabindex="-1"></a>}</code></pre></div> In this case, when checks are run with dplyr 1.0.10 you’ll get a warning about using a function from dplyr that doesn’t exist (<code>reframe()</code>) even though that branch will never run. You can get around this by using <code>utils::getFromNamespace()</code> to indirectly call the new dplyr function: <div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb7-1" tabindex="-1"></a>if (utils::packageVersion("dplyr") > "1.0.10") { <a href="#cb7-2" tabindex="-1"></a> utils::getFromNamespace("reframe", "dplyr")(df, x = unique(x)) <a href="#cb7-3" tabindex="-1"></a>} else { <a href="#cb7-4" tabindex="-1"></a> dplyr::summarise(df, x = unique(x)) <a href="#cb7-5" tabindex="-1"></a>}</code></pre></div> As soon as the next version of dplyr is actually on CRAN (1.1.0 in this case), you should feel free to remove this code and unconditionally use <code>reframe()</code> as long as you also require <code>dplyr (>= 1.1.0)</code> in your <code>DESCRIPTION</code> file. This is typically not very painful for users, because they’d already be updating your package when they run into this requirement, so updating one more package along the way is generally easy. It also helps them get the latest bug fixes and features from dplyr. Sometimes, it isn’t possible to avoid a call to <code>@importFrom</code>. For example you might be importing a generic so that you can define a method for it, but that generic has moved between packages. In this case, you can take advantage of a little-known feature in the <code>NAMESPACE</code> file: you can include raw <code>if</code> statements. <div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb8-1" tabindex="-1"></a>#' @rawNamespace <a href="#cb8-2" tabindex="-1"></a>#' if (utils::packageVersion("dplyr") > "0.5.0") { <a href="#cb8-3" tabindex="-1"></a>#' importFrom("dbplyr", "build_sql") <a href="#cb8-4" tabindex="-1"></a>#' } else { <a href="#cb8-5" tabindex="-1"></a>#' importFrom("dplyr", "build_sql") <a href="#cb8-6" tabindex="-1"></a>#' }</code></pre></div> </div> <div id="deprecation-of-mutate_-and-summarise_" class="section level3"> <h3>Deprecation of <code>mutate_*()</code> and <code>summarise_*()</code></h3> The following <code>mutate()</code> and <code>summarise()</code> variants were deprecated in dplyr 0.7.0: <ul> <li><code>mutate_each()</code>, <code>summarise_each()</code></li> </ul> and the following variants were superseded in dplyr 1.0.0: <ul> <li><code>mutate_all()</code>, <code>summarise_all()</code></li> <li><code>mutate_if()</code>, <code>summarise_if()</code></li> <li><code>mutate_at()</code>, <code>summarise_at()</code></li> </ul> These have all been replaced by using <code>mutate()</code> or <code>summarise()</code> in combination with <code>across()</code>, which was introduced in dplyr 1.0.0. If you used <code>mutate_all()</code> or <code>mutate_each()</code> without supplying a selection, you should update to use <code>across(everything())</code>: <div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb9-1" tabindex="-1"></a>starwars %>% mutate_each(funs(as.character)) <a href="#cb9-2" tabindex="-1"></a>starwars %>% mutate_all(funs(as.character)) <a href="#cb9-3" tabindex="-1"></a>starwars %>% mutate(across(everything(), as.character))</code></pre></div> If you provided a selection through <code>mutate_at()</code> or <code>mutate_each()</code>, then you can switch to <code>across()</code> with a selection: <div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb10-1" tabindex="-1"></a>starwars %>% mutate_each(funs(as.character), height, mass) <a href="#cb10-2" tabindex="-1"></a>starwars %>% mutate_at(vars(height, mass), as.character) <a href="#cb10-3" tabindex="-1"></a>starwars %>% mutate(across(c(height, mass), as.character))</code></pre></div> If you used predicates with <code>mutate_if()</code>, you can switch to using <code>across()</code> in combination with <code>where()</code>: <div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb11-1" tabindex="-1"></a>starwars %>% mutate_if(is.factor, as.character) <a href="#cb11-2" tabindex="-1"></a>starwars %>% mutate(across(where(is.factor), as.character))</code></pre></div> </div> </div> <div id="data-frame-subclasses" class="section level2"> <h2>Data frame subclasses</h2> If you are a package author that is extending dplyr to work with a new data frame subclass, then we encourage you to read the documentation in <code>?dplyr_extending</code>. This contains advice on how to implement the minimal number of extension generics possible to get maximal compatibility across dplyr’s verbs. </div>   <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>