/usr/lib/R/site-library/dplyr/doc/compatibility.html

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<meta charset="utf-8" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="pandoc" />

<meta name="viewport" content="width=device-width, initial-scale=1">



<title>dplyr compatibility</title>



<style type="text/css">code{white-space: pre;}</style>
<style type="text/css">
div.sourceCode { overflow-x: auto; }
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
  margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
code > span.dt { color: #902000; } /* DataType */
code > span.dv { color: #40a070; } /* DecVal */
code > span.bn { color: #40a070; } /* BaseN */
code > span.fl { color: #40a070; } /* Float */
code > span.ch { color: #4070a0; } /* Char */
code > span.st { color: #4070a0; } /* String */
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
code > span.ot { color: #007020; } /* Other */
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
code > span.fu { color: #06287e; } /* Function */
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
code > span.cn { color: #880000; } /* Constant */
code > span.sc { color: #4070a0; } /* SpecialChar */
code > span.vs { color: #4070a0; } /* VerbatimString */
code > span.ss { color: #bb6688; } /* SpecialString */
code > span.im { } /* Import */
code > span.va { color: #19177c; } /* Variable */
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code > span.op { color: #666666; } /* Operator */
code > span.bu { } /* BuiltIn */
code > span.ex { } /* Extension */
code > span.pp { color: #bc7a00; } /* Preprocessor */
code > span.at { color: #7d9029; } /* Attribute */
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
</style>



<link href="data:text/css;charset=utf-8,body%20%7B%0Abackground%2Dcolor%3A%20%23fff%3B%0Amargin%3A%201em%20auto%3B%0Amax%2Dwidth%3A%20700px%3B%0Aoverflow%3A%20visible%3B%0Apadding%2Dleft%3A%202em%3B%0Apadding%2Dright%3A%202em%3B%0Afont%2Dfamily%3A%20%22Open%20Sans%22%2C%20%22Helvetica%20Neue%22%2C%20Helvetica%2C%20Arial%2C%20sans%2Dserif%3B%0Afont%2Dsize%3A%2014px%3B%0Aline%2Dheight%3A%201%2E35%3B%0A%7D%0A%23header%20%7B%0Atext%2Dalign%3A%20center%3B%0A%7D%0A%23TOC%20%7B%0Aclear%3A%20both%3B%0Amargin%3A%200%200%2010px%2010px%3B%0Apadding%3A%204px%3B%0Awidth%3A%20400px%3B%0Aborder%3A%201px%20solid%20%23CCCCCC%3B%0Aborder%2Dradius%3A%205px%3B%0Abackground%2Dcolor%3A%20%23f6f6f6%3B%0Afont%2Dsize%3A%2013px%3B%0Aline%2Dheight%3A%201%2E3%3B%0A%7D%0A%23TOC%20%2Etoctitle%20%7B%0Afont%2Dweight%3A%20bold%3B%0Afont%2Dsize%3A%2015px%3B%0Amargin%2Dleft%3A%205px%3B%0A%7D%0A%23TOC%20ul%20%7B%0Apadding%2Dleft%3A%2040px%3B%0Amargin%2Dleft%3A%20%2D1%2E5em%3B%0Amargin%2Dtop%3A%205px%3B%0Amargin%2Dbottom%3A%205px%3B%0A%7D%0A%23TOC%20ul%20ul%20%7B%0Amargin%2Dleft%3A%20%2D2em%3B%0A%7D%0A%23TOC%20li%20%7B%0Aline%2Dheight%3A%2016px%3B%0A%7D%0Atable%20%7B%0Amargin%3A%201em%20auto%3B%0Aborder%2Dwidth%3A%201px%3B%0Aborder%2Dcolor%3A%20%23DDDDDD%3B%0Aborder%2Dstyle%3A%20outset%3B%0Aborder%2Dcollapse%3A%20collapse%3B%0A%7D%0Atable%20th%20%7B%0Aborder%2Dwidth%3A%202px%3B%0Apadding%3A%205px%3B%0Aborder%2Dstyle%3A%20inset%3B%0A%7D%0Atable%20td%20%7B%0Aborder%2Dwidth%3A%201px%3B%0Aborder%2Dstyle%3A%20inset%3B%0Aline%2Dheight%3A%2018px%3B%0Apadding%3A%205px%205px%3B%0A%7D%0Atable%2C%20table%20th%2C%20table%20td%20%7B%0Aborder%2Dleft%2Dstyle%3A%20none%3B%0Aborder%2Dright%2Dstyle%3A%20none%3B%0A%7D%0Atable%20thead%2C%20table%20tr%2Eeven%20%7B%0Abackground%2Dcolor%3A%20%23f7f7f7%3B%0A%7D%0Ap%20%7B%0Amargin%3A%200%2E5em%200%3B%0A%7D%0Ablockquote%20%7B%0Abackground%2Dcolor%3A%20%23f6f6f6%3B%0Apadding%3A%200%2E25em%200%2E75em%3B%0A%7D%0Ahr%20%7B%0Aborder%2Dstyle%3A%20solid%3B%0Aborder%3A%20none%3B%0Aborder%2Dtop%3A%201px%20solid%20%23777%3B%0Amargin%3A%2028px%200%3B%0A%7D%0Adl%20%7B%0Amargin%2Dleft%3A%200%3B%0A%7D%0Adl%20dd%20%7B%0Amargin%2Dbottom%3A%2013px%3B%0Amargin%2Dleft%3A%2013px%3B%0A%7D%0Adl%20dt%20%7B%0Afont%2Dweight%3A%20bold%3B%0A%7D%0Aul%20%7B%0Amargin%2Dtop%3A%200%3B%0A%7D%0Aul%20li%20%7B%0Alist%2Dstyle%3A%20circle%20outside%3B%0A%7D%0Aul%20ul%20%7B%0Amargin%2Dbottom%3A%200%3B%0A%7D%0Apre%2C%20code%20%7B%0Abackground%2Dcolor%3A%20%23f7f7f7%3B%0Aborder%2Dradius%3A%203px%3B%0Acolor%3A%20%23333%3B%0Awhite%2Dspace%3A%20pre%2Dwrap%3B%20%0A%7D%0Apre%20%7B%0Aborder%2Dradius%3A%203px%3B%0Amargin%3A%205px%200px%2010px%200px%3B%0Apadding%3A%2010px%3B%0A%7D%0Apre%3Anot%28%5Bclass%5D%29%20%7B%0Abackground%2Dcolor%3A%20%23f7f7f7%3B%0A%7D%0Acode%20%7B%0Afont%2Dfamily%3A%20Consolas%2C%20Monaco%2C%20%27Courier%20New%27%2C%20monospace%3B%0Afont%2Dsize%3A%2085%25%3B%0A%7D%0Ap%20%3E%20code%2C%20li%20%3E%20code%20%7B%0Apadding%3A%202px%200px%3B%0A%7D%0Adiv%2Efigure%20%7B%0Atext%2Dalign%3A%20center%3B%0A%7D%0Aimg%20%7B%0Abackground%2Dcolor%3A%20%23FFFFFF%3B%0Apadding%3A%202px%3B%0Aborder%3A%201px%20solid%20%23DDDDDD%3B%0Aborder%2Dradius%3A%203px%3B%0Aborder%3A%201px%20solid%20%23CCCCCC%3B%0Amargin%3A%200%205px%3B%0A%7D%0Ah1%20%7B%0Amargin%2Dtop%3A%200%3B%0Afont%2Dsize%3A%2035px%3B%0Aline%2Dheight%3A%2040px%3B%0A%7D%0Ah2%20%7B%0Aborder%2Dbottom%3A%204px%20solid%20%23f7f7f7%3B%0Apadding%2Dtop%3A%2010px%3B%0Apadding%2Dbottom%3A%202px%3B%0Afont%2Dsize%3A%20145%25%3B%0A%7D%0Ah3%20%7B%0Aborder%2Dbottom%3A%202px%20solid%20%23f7f7f7%3B%0Apadding%2Dtop%3A%2010px%3B%0Afont%2Dsize%3A%20120%25%3B%0A%7D%0Ah4%20%7B%0Aborder%2Dbottom%3A%201px%20solid%20%23f7f7f7%3B%0Amargin%2Dleft%3A%208px%3B%0Afont%2Dsize%3A%20105%25%3B%0A%7D%0Ah5%2C%20h6%20%7B%0Aborder%2Dbottom%3A%201px%20solid%20%23ccc%3B%0Afont%2Dsize%3A%20105%25%3B%0A%7D%0Aa%20%7B%0Acolor%3A%20%230033dd%3B%0Atext%2Ddecoration%3A%20none%3B%0A%7D%0Aa%3Ahover%20%7B%0Acolor%3A%20%236666ff%3B%20%7D%0Aa%3Avisited%20%7B%0Acolor%3A%20%23800080%3B%20%7D%0Aa%3Avisited%3Ahover%20%7B%0Acolor%3A%20%23BB00BB%3B%20%7D%0Aa%5Bhref%5E%3D%22http%3A%22%5D%20%7B%0Atext%2Ddecoration%3A%20underline%3B%20%7D%0Aa%5Bhref%5E%3D%22https%3A%22%5D%20%7B%0Atext%2Ddecoration%3A%20underline%3B%20%7D%0A%0Acode%20%3E%20span%2Ekw%20%7B%20color%3A%20%23555%3B%20font%2Dweight%3A%20bold%3B%20%7D%20%0Acode%20%3E%20span%2Edt%20%7B%20color%3A%20%23902000%3B%20%7D%20%0Acode%20%3E%20span%2Edv%20%7B%20color%3A%20%2340a070%3B%20%7D%20%0Acode%20%3E%20span%2Ebn%20%7B%20color%3A%20%23d14%3B%20%7D%20%0Acode%20%3E%20span%2Efl%20%7B%20color%3A%20%23d14%3B%20%7D%20%0Acode%20%3E%20span%2Ech%20%7B%20color%3A%20%23d14%3B%20%7D%20%0Acode%20%3E%20span%2Est%20%7B%20color%3A%20%23d14%3B%20%7D%20%0Acode%20%3E%20span%2Eco%20%7B%20color%3A%20%23888888%3B%20font%2Dstyle%3A%20italic%3B%20%7D%20%0Acode%20%3E%20span%2Eot%20%7B%20color%3A%20%23007020%3B%20%7D%20%0Acode%20%3E%20span%2Eal%20%7B%20color%3A%20%23ff0000%3B%20font%2Dweight%3A%20bold%3B%20%7D%20%0Acode%20%3E%20span%2Efu%20%7B%20color%3A%20%23900%3B%20font%2Dweight%3A%20bold%3B%20%7D%20%20code%20%3E%20span%2Eer%20%7B%20color%3A%20%23a61717%3B%20background%2Dcolor%3A%20%23e3d2d2%3B%20%7D%20%0A" rel="stylesheet" type="text/css" />

</head>

<body>




<h1 class="title toc-ignore">dplyr compatibility</h1>



<p>This vignette is aimed at package authors who need to update their code because of a backward incompatible change to dplyr. We do try and minimise 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.</p>
<p>This vignette starts with some general advice on writing package code that works with multiple version of dplyr, then continues to discuss specific changes in dplyr versions.</p>
<div id="working-with-multiple-dplyr-versions" class="section level2">
<h2>Working with multiple dplyr versions</h2>
<p>Ideally, you 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:</p>
<ol style="list-style-type: decimal">
<li><p>It’s more convenient for your users, since they’re not forced to update dplyr if they don’t want to)</p></li>
<li><p>It’s easier on CRAN since it doesn’t require a massive coordinated release of multiple packages.</p></li>
</ol>
<p>To make code work with multiple versions of a package, your first tool is the simple if statement:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="cf">if</span> (utils<span class="op">::</span><span class="kw">packageVersion</span>(<span class="st">&quot;dplyr&quot;</span>) <span class="op">&gt;</span><span class="st"> &quot;0.5.0&quot;</span>) {
  <span class="co"># code for new version</span>
} <span class="cf">else</span> {
  <span class="co"># code for old version</span>
}</code></pre></div>
<p>Always condition on <code>&gt; current-version</code>, not <code>&gt;= 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 “0.5.0”, the development version will be “0.5.0.9000”.</p>
<p>Occasionally, you’ll run into a situation where the <code>NAMESPACE</code> has changed and you need to conditionally import different functions. This typically occurs when functions are moved from one package to another. We try out best to provide automatic fallbacks, but this is not always possible. Often you can work around the problem by avoiding <code>importFrom</code> and using <code>::</code> instead. Do this where possible:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="cf">if</span> (utils<span class="op">::</span><span class="kw">packageVersion</span>(<span class="st">&quot;dplyr&quot;</span>) <span class="op">&gt;</span><span class="st"> &quot;0.5.0&quot;</span>) {
  dbplyr<span class="op">::</span><span class="kw">build_sql</span>(...)
} <span class="cf">else</span> {
  dplyr<span class="op">::</span><span class="kw">build_sql</span>(...)
}</code></pre></div>
<p>This will generate an <code>R CMD check</code> NOTE (because the one of the functions will always be missing), but this is ok. Simply explain that you get the note because you have written a wrapper to make sure your code is backward compatible.</p>
<p>Sometimes it’s not possible to avoid <code>importFrom()</code>. For example you might be importing a generic so that you can define a method for it. In this case, you can take advantage of a little-known feature in the <code>NAMESPACE</code> file: you can include <code>if</code> statements.</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="co">#' @rawNamespace</span>
<span class="co">#' if (utils::packageVersion(&quot;dplyr&quot;) &gt; &quot;0.5.0&quot;) {</span>
<span class="co">#'   importFrom(&quot;dbplyr&quot;, &quot;build_sql&quot;)</span>
<span class="co">#' } else {</span>
<span class="co">#'   importFrom(&quot;dplyr&quot;, &quot;build_sql&quot;)</span>
<span class="co">#' }</span></code></pre></div>
</div>
<div id="dplyr-0.6.0" class="section level2">
<h2>dplyr 0.6.0</h2>
<div id="database-code-moves-to-dbplyr" class="section level3">
<h3>Database code moves to dbplyr</h3>
<p>Almost all database related code has been moved out of dplyr and into a new package, <a href="http://github.com/hadley/dbplyr/">dbplyr</a>. This makes dplyr simpler, and will make it easier to release fixes for bugs that only affect databases. If you’ve implemented a database backend for dplyr, please read the <a href="https://github.com/hadley/dbplyr/blob/master/NEWS.md#backends">backend news</a> on the backend.</p>
<p>Depending on what generics you use, and what generics you provide methods for you, you may need to write some conditional code. To help make this easier we’ve written <code>wrap_dbplyr_obj()</code> which will write the helper code for you:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">wrap_dbplyr_obj</span>(<span class="st">&quot;build_sql&quot;</span>)

<span class="kw">wrap_dbplyr_obj</span>(<span class="st">&quot;base_agg&quot;</span>)</code></pre></div>
<p>Simply copy the results of this function in your package.</p>
<p>These will generate <code>R CMD check</code> NOTES, so make sure to tell CRAN that this is to ensure backward compatibility.</p>
</div>
<div id="deprecation-of-underscored-verbs_" class="section level3">
<h3>Deprecation of underscored <code>verbs_()</code></h3>
<p>Because the tidyeval framework allows us to combine SE and NSE semantics within the same functions, the underscored verbs have been softly deprecated.</p>
<div id="for-users-of-se_-verbs" class="section level4">
<h4>For users of SE_ verbs</h4>
<p>The legacy underscored versions take objects for which a <code>lazyeval::as.lazy()</code> method is defined. This includes symbols and calls, strings, and formulas. All of these objects have been replaced with quosures and you can call tidyeval verbs with unquoted quosures:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">quo &lt;-<span class="st"> </span><span class="kw">quo</span>(cyl)
<span class="kw">select</span>(mtcars, <span class="op">!!</span><span class="st"> </span>quo)</code></pre></div>
<p>Symbolic expressions are also supported, but note that bare symbols and calls do not carry scope information. If you’re referring to objects in the data frame, it’s safe to omit specifying an enclosure:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">sym &lt;-<span class="st"> </span><span class="kw">quote</span>(cyl)
<span class="kw">select</span>(mtcars, <span class="op">!!</span><span class="st"> </span>sym)

call &lt;-<span class="st"> </span><span class="kw">quote</span>(<span class="kw">mean</span>(cyl))
<span class="kw">summarise</span>(mtcars, <span class="op">!!</span><span class="st"> </span>call)</code></pre></div>
<p>Transforming objects into quosures is generally straightforward. To enclose with the current environment, you can unquote directly in <code>quo()</code> or you can use <code>as_quosure()</code>:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">quo</span>(<span class="op">!!</span><span class="st"> </span>sym)
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~cyl</span>
<span class="kw">quo</span>(<span class="op">!!</span><span class="st"> </span>call)
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~mean(cyl)</span>

rlang<span class="op">::</span><span class="kw">as_quosure</span>(sym)
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~cyl</span>
rlang<span class="op">::</span><span class="kw">as_quosure</span>(call)
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~mean(cyl)</span></code></pre></div>
<p>Note that while formulas and quosures are very similar objects (and in the most general sense, formulas are quosures), they can’t be used interchangeably in tidyeval functions. Early implementations did treat bare formulas as quosures, but this created compatibility issues with modelling functions of the stats package. Fortunately, it’s easy to transform formulas to quosures that will self-evaluate in tidyeval functions:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">f &lt;-<span class="st"> </span><span class="er">~</span>cyl
f
<span class="co">#&gt; ~cyl</span>
rlang<span class="op">::</span><span class="kw">as_quosure</span>(f)
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~cyl</span></code></pre></div>
<p>Finally, and perhaps most importantly, <strong>strings are not and should not be parsed</strong>. As developers, it is tempting to try and solve problems using strings because we have been trained to work with strings rather than quoted expressions. However it’s almost always the wrong way to approach the problem. The exception is for creating symbols. In that case it is perfectly legitimate to use strings:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">rlang<span class="op">::</span><span class="kw">sym</span>(<span class="st">&quot;cyl&quot;</span>)
<span class="co">#&gt; cyl</span>
rlang<span class="op">::</span><span class="kw">syms</span>(letters[<span class="dv">1</span><span class="op">:</span><span class="dv">3</span>])
<span class="co">#&gt; [[1]]</span>
<span class="co">#&gt; a</span>
<span class="co">#&gt; </span>
<span class="co">#&gt; [[2]]</span>
<span class="co">#&gt; b</span>
<span class="co">#&gt; </span>
<span class="co">#&gt; [[3]]</span>
<span class="co">#&gt; c</span></code></pre></div>
<p>But you should never use strings to create calls. Instead you can use quasiquotation:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">syms &lt;-<span class="st"> </span>rlang<span class="op">::</span><span class="kw">syms</span>(<span class="kw">c</span>(<span class="st">&quot;foo&quot;</span>, <span class="st">&quot;bar&quot;</span>, <span class="st">&quot;baz&quot;</span>))
<span class="kw">quo</span>(<span class="kw">my_call</span>(<span class="op">!!!</span><span class="st"> </span>syms))
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~my_call(foo, bar, baz)</span>

fun &lt;-<span class="st"> </span>rlang<span class="op">::</span><span class="kw">sym</span>(<span class="st">&quot;my_call&quot;</span>)
<span class="kw">quo</span>(<span class="kw">UQ</span>(fun)(<span class="op">!!!</span><span class="st"> </span>syms))
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~my_call(foo, bar, baz)</span></code></pre></div>
<p>Or create the call with <code>lang()</code>:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">call &lt;-<span class="st"> </span>rlang<span class="op">::</span><span class="kw">lang</span>(<span class="st">&quot;my_call&quot;</span>, <span class="op">!!!</span><span class="st"> </span>syms)
call
<span class="co">#&gt; my_call(foo, bar, baz)</span>

rlang<span class="op">::</span><span class="kw">as_quosure</span>(call)
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~my_call(foo, bar, baz)</span>

<span class="co"># Or equivalently:</span>
<span class="kw">quo</span>(<span class="op">!!</span><span class="st"> </span>rlang<span class="op">::</span><span class="kw">lang</span>(<span class="st">&quot;my_call&quot;</span>, <span class="op">!!!</span><span class="st"> </span>syms))
<span class="co">#&gt; &lt;quosure: global&gt;</span>
<span class="co">#&gt; ~my_call(foo, bar, baz)</span></code></pre></div>
<p>Note that idioms based on <code>interp()</code> should now generally be avoided and replaced with quasiquotation. Where you used to interpolate:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">lazyeval<span class="op">::</span><span class="kw">interp</span>(<span class="op">~</span><span class="st"> </span><span class="kw">mean</span>(var), <span class="dt">var =</span> rlang<span class="op">::</span><span class="kw">sym</span>(<span class="st">&quot;mpg&quot;</span>))</code></pre></div>
<p>You would now unquote:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">var &lt;-<span class="st"> &quot;mpg&quot;</span>
<span class="kw">quo</span>(<span class="kw">mean</span>(<span class="op">!!</span><span class="st"> </span>rlang<span class="op">::</span><span class="kw">sym</span>(var)))</code></pre></div>
<p>See also <code>vignette(&quot;programming&quot;)</code> for more about quasiquotation and quosures.</p>
</div>
<div id="for-package-authors" class="section level4">
<h4>For package authors</h4>
<p>For package authors, rlang provides a <a href="https://github.com/hadley/rlang/blob/master/R/compat-lazyeval.R">compatibility file</a> that you can copy to your package. <code>compat_lazy()</code> and <code>compat_lazy_dots()</code> turn lazy-able objects into proper quosures. This helps providing an underscored version to your users for backward compatibility. For instance, here is how we defined the underscored version of <code>filter()</code> in dplyr 0.6:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">filter_.tbl_df &lt;-<span class="st"> </span><span class="cf">function</span>(.data, ..., <span class="dt">.dots =</span> <span class="kw">list</span>()) {
  dots &lt;-<span class="st"> </span><span class="kw">compat_lazy_dots</span>(.dots, <span class="kw">caller_env</span>(), ...)
  <span class="kw">filter</span>(.data, <span class="op">!!!</span><span class="st"> </span>dots)
}</code></pre></div>
<p>With tidyeval, S3 dispatch to the correct method might be an issue. In the past, the genericity of dplyr verbs was accomplished by dispatching in the underscored versions. Now that those are deprecated, we’ve turned the non-underscored verbs into S3 generics.</p>
<p>We maintain backward compatibility by redispatching to old underscored verbs in the default methods of the new S3 generics. For example, here is how we redispatch <code>filter()</code>:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">filter.default &lt;-<span class="st"> </span><span class="cf">function</span>(.data, ...) {
  <span class="kw">filter_</span>(.data, <span class="dt">.dots =</span> <span class="kw">compat_as_lazy_dots</span>(...))
}</code></pre></div>
<p>This gets the job done in most cases. However, the default method will not be called for objects inheriting from one of the classes for which we provide non-underscored methods: <code>data.frame</code>, <code>tbl_df</code>, <code>tbl_cube</code> and <code>grouped_df</code>. An example of this is the <code>sf</code> package whose objects have classes <code>c(&quot;sf&quot;, &quot;data.frame&quot;)</code>. Authors of such packages should provide a method for the non-underscored generic in order to be compatible with dplyr:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">filter.sf &lt;-<span class="st"> </span><span class="cf">function</span>(.data, ...) {
  <span class="kw">st_as_sf</span>(<span class="kw">NextMethod</span>())
}</code></pre></div>
<p>If you need help with this, please let us know!</p>
</div>
</div>
<div id="deprecation-of-mutate_each-and-summarise_each" class="section level3">
<h3>Deprecation of <code>mutate_each()</code> and <code>summarise_each()</code></h3>
<p>These functions have been replaced by a more complete family of functions. This family has suffixes <code>_if</code>, <code>_at</code> and <code>_all</code> and includes more verbs than just <code>mutate</code> <code>summarise</code>.</p>
<p>If you need to update your code to the new family, there are two relevant functions depending on which variables you apply <code>funs()</code> to. If you called <code>mutate_each()</code> without supplying a selection of variables, <code>funs</code> is applied to all variables. In this case, you should update your code to use <code>mutate_all()</code> instead:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">mutate_each</span>(starwars, <span class="kw">funs</span>(as.character))
<span class="kw">mutate_all</span>(starwars, <span class="kw">funs</span>(as.character))</code></pre></div>
<p>Note that the new verbs support bare functions as well, so you don’t necessarily need to wrap with <code>funs()</code>:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">mutate_all</span>(starwars, as.character)</code></pre></div>
<p>On the other hand, if you supplied a variable selection, you should use <code>mutate_at()</code>. The variable selection should be wrapped with <code>vars()</code>.</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">mutate_each</span>(starwars, <span class="kw">funs</span>(as.character), height, mass)
<span class="kw">mutate_at</span>(starwars, <span class="kw">vars</span>(height, mass), as.character)</code></pre></div>
<p><code>vars()</code> supports all the selection helpers that you usually use with <code>select()</code>:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">summarise_at</span>(mtcars, <span class="kw">vars</span>(<span class="kw">starts_with</span>(<span class="st">&quot;d&quot;</span>)), mean)</code></pre></div>
<p>Note that intead of a <code>vars()</code> selection, you can also supply character vectors of column names:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">mutate_at</span>(starwars, <span class="kw">c</span>(<span class="st">&quot;height&quot;</span>, <span class="st">&quot;mass&quot;</span>), as.character)</code></pre></div>
</div>
</div>



<!-- 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>
r-cran-dplyr 0.7.4-3 / usr / lib / R / site-library / dplyr / doc / compatibility.html
