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>Get started with cpp11</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">Get started with cpp11</h1> This content is adapted (with permission) from the <a href="https://adv-r.hadley.nz/rcpp.html">Rcpp chapter</a> of Hadley Wickham’s book Advanced R. <div id="introduction" class="section level2"> <h2>Introduction</h2> Sometimes R code just isn’t fast enough. You’ve used profiling to figure out where your bottlenecks are, and you’ve done everything you can in R, but your code still isn’t fast enough. In this vignette you’ll learn how to improve performance by rewriting key functions in C++. This magic comes by way of the <a href="https://github.com/r-lib/cpp11">cpp11</a> package. cpp11 makes it very simple to connect C++ to R. While it is possible to write C or Fortran code for use in R, it will be painful by comparison. cpp11 provides a clean, approachable API that lets you write high-performance code, insulated from R’s more complex C API. Typical bottlenecks that C++ can address include: <ul> <li>Loops that can’t be easily vectorised because subsequent iterations depend on previous ones.</li> <li>Recursive functions, or problems which involve calling functions millions of times. The overhead of calling a function in C++ is much lower than in R.</li> <li>Problems that require advanced data structures and algorithms that R doesn’t provide. Through the standard template library (STL), C++ has efficient implementations of many important data structures, from ordered maps to double-ended queues.</li> </ul> The aim of this vignette is to discuss only those aspects of C++ and cpp11 that are absolutely necessary to help you eliminate bottlenecks in your code. We won’t spend much time on advanced features like object-oriented programming or templates because the focus is on writing small, self-contained functions, not big programs. A working knowledge of C++ is helpful, but not essential. Many good tutorials and references are freely available, including <a href="https://www.learncpp.com/" class="uri">https://www.learncpp.com/</a> and <a href="https://en.cppreference.com/w/cpp" class="uri">https://en.cppreference.com/w/cpp</a>. For more advanced topics, the Effective C++ series by Scott Meyers is a popular choice. <div id="outline" class="section level3"> <h3>Outline</h3> <ul> <li>Section <a href="#intro">intro</a> teaches you how to write C++ by converting simple R functions to their C++ equivalents. You’ll learn how C++ differs from R, and what the key scalar, vector, and matrix classes are called.</li> <li>Section <a href="#cpp-source">cpp_source</a> shows you how to use <code>cpp11::cpp_source()</code> to load a C++ file from disk in the same way you use <code>source()</code> to load a file of R code.</li> <li>Section <a href="#classes">classes</a> discusses how to modify attributes from cpp11, and mentions some of the other important classes.</li> <li>Section <a href="#na">na</a> teaches you how to work with R’s missing values in C++.</li> <li>Section <a href="#stl">stl</a> shows you how to use some of the most important data structures and algorithms from the standard template library, or STL, built-in to C++.</li> <li>Section <a href="#case-studies">case-studies</a> shows two real case studies where cpp11 was used to get considerable performance improvements.</li> <li>Section <a href="#package">package</a> teaches you how to add C++ code to an R package.</li> <li>Section <a href="#more">more</a> concludes the vignette with pointers to more resources to help you learn cpp11 and C++.</li> </ul> </div> <div id="prerequisites" class="section level3"> <h3>Prerequisites</h3> We’ll use <a href="https://github.com/r-lib/cpp11">cpp11</a> to call C++ from R: <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb1-1" tabindex="-1"></a>library(cpp11)</code></pre></div> You’ll also need a working C++ compiler. To get it: <ul> <li>On Windows, install <a href="https://cran.r-project.org/bin/windows/Rtools/">Rtools</a>.</li> <li>On Mac, install Xcode from the app store.</li> <li>On Linux, <code>sudo apt-get install r-base-dev</code> or similar.</li> </ul> </div> </div> <div id="intro" class="section level2"> <h2>Getting started with C++</h2> <code>cpp_function()</code> allows you to write C++ functions in R: <div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb2-1" tabindex="-1"></a>cpp_function('int add(int x, int y, int z) { <a href="#cb2-2" tabindex="-1"></a> int sum = x + y + z; <a href="#cb2-3" tabindex="-1"></a> return sum; <a href="#cb2-4" tabindex="-1"></a>}') <a href="#cb2-5" tabindex="-1"></a># add works like a regular R function <a href="#cb2-6" tabindex="-1"></a>add <a href="#cb2-7" tabindex="-1"></a>#> function (x, y, z) <a href="#cb2-8" tabindex="-1"></a>#> { <a href="#cb2-9" tabindex="-1"></a>#> .Call("_code_4b3136e975da_add", x, y, z, PACKAGE = "code_4b3136e975da") <a href="#cb2-10" tabindex="-1"></a>#> } <a href="#cb2-11" tabindex="-1"></a>add(1, 2, 3) <a href="#cb2-12" tabindex="-1"></a>#> [1] 6</code></pre></div> When you run the above code, cpp11 will compile the C++ code and construct an R function that connects to the compiled C++ function. There’s a lot going on underneath the hood but cpp11 takes care of all the details so you don’t need to worry about them. The following sections will teach you the basics by translating simple R functions to their C++ equivalents. We’ll start simple with a function that has no inputs and a scalar output, and then make it progressively more complicated: <ul> <li>Scalar input and scalar output</li> <li>Vector input and scalar output</li> <li>Vector input and vector output</li> <li>Matrix input and vector output</li> </ul> <div id="no-inputs-scalar-output" class="section level3"> <h3>No inputs, scalar output</h3> Let’s start with a very simple function. It has no arguments and always returns the integer 1: <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb3-1" tabindex="-1"></a>one <- function() 1L</code></pre></div> The equivalent C++ function is: <div class="sourceCode" id="cb4"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb4-1" tabindex="-1"></a>int one() { <a href="#cb4-2" tabindex="-1"></a> return 1; <a href="#cb4-3" tabindex="-1"></a>}</code></pre></div> We can compile and use this from R with <code>cpp_function()</code> <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb5-1" tabindex="-1"></a>cpp_function('int one() { <a href="#cb5-2" tabindex="-1"></a> return 1; <a href="#cb5-3" tabindex="-1"></a>}')</code></pre></div> This small function illustrates a number of important differences between R and C++: <ul> <li>The syntax to create a function looks like the syntax to call a function; you don’t use assignment to create functions as you do in R.</li> <li>You must declare the type of output the function returns. This function returns an <code>int</code> (a scalar integer). The classes for the most common types of R vectors are: <code>doubles</code>, <code>integers</code>, <code>strings</code>, and <code>logicals</code>.</li> <li>Scalars and vectors are different. The scalar equivalents of numeric, integer, character, and logical vectors are: <code>double</code>, <code>int</code>, <code>String</code>, and <code>bool</code>.</li> <li>You must use an explicit <code>return</code> statement to return a value from a function.</li> <li>Every statement is terminated by a <code>;</code>.</li> </ul> </div> <div id="scalar-input-scalar-output" class="section level3"> <h3>Scalar input, scalar output</h3> The next example function implements a scalar version of the <code>sign()</code> function which returns 1 if the input is positive, and -1 if it’s negative: <div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb6-1" tabindex="-1"></a>sign_r <- function(x) { <a href="#cb6-2" tabindex="-1"></a> if (x > 0) { <a href="#cb6-3" tabindex="-1"></a> 1 <a href="#cb6-4" tabindex="-1"></a> } else if (x == 0) { <a href="#cb6-5" tabindex="-1"></a> 0 <a href="#cb6-6" tabindex="-1"></a> } else { <a href="#cb6-7" tabindex="-1"></a> -1 <a href="#cb6-8" tabindex="-1"></a> } <a href="#cb6-9" tabindex="-1"></a>} <a href="#cb6-10" tabindex="-1"></a>cpp_function('int sign_cpp(int x) { <a href="#cb6-11" tabindex="-1"></a> if (x > 0) { <a href="#cb6-12" tabindex="-1"></a> return 1; <a href="#cb6-13" tabindex="-1"></a> } else if (x == 0) { <a href="#cb6-14" tabindex="-1"></a> return 0; <a href="#cb6-15" tabindex="-1"></a> } else { <a href="#cb6-16" tabindex="-1"></a> return -1; <a href="#cb6-17" tabindex="-1"></a> } <a href="#cb6-18" tabindex="-1"></a>}')</code></pre></div> In the C++ version: <ul> <li>We declare the type of each input in the same way we declare the type of the output. While this makes the code a little more verbose, it also makes clear the type of input the function needs.</li> <li>The <code>if</code> syntax is identical — while there are some big differences between R and C++, there are also lots of similarities! C++ also has a <code>while</code> statement that works the same way as R’s. As in R you can use <code>break</code> to exit the loop, but to skip one iteration you need to use <code>continue</code> instead of <code>next</code>.</li> </ul> </div> <div id="vector-input-scalar-output" class="section level3"> <h3>Vector input, scalar output</h3> One big difference between R and C++ is that the cost of loops is much lower in C++. For example, we could implement the <code>sum</code> function in R using a loop. If you’ve been programming in R a while, you’ll probably have a visceral reaction to this function! <div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb7-1" tabindex="-1"></a>sum_r <- function(x) { <a href="#cb7-2" tabindex="-1"></a> total <- 0 <a href="#cb7-3" tabindex="-1"></a> for (i in seq_along(x)) { <a href="#cb7-4" tabindex="-1"></a> total <- total + x[i] <a href="#cb7-5" tabindex="-1"></a> } <a href="#cb7-6" tabindex="-1"></a> total <a href="#cb7-7" tabindex="-1"></a>}</code></pre></div> In C++, loops have very little overhead, so it’s fine to use them. In Section <a href="#stl">stl</a>, you’ll see alternatives to <code>for</code> loops that more clearly express your intent; they’re not faster, but they can make your code easier to understand. <div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb8-1" tabindex="-1"></a>cpp_function('double sum_cpp(doubles x) { <a href="#cb8-2" tabindex="-1"></a> int n = x.size(); <a href="#cb8-3" tabindex="-1"></a> double total = 0; <a href="#cb8-4" tabindex="-1"></a> for(int i = 0; i < n; ++i) { <a href="#cb8-5" tabindex="-1"></a> total += x[i]; <a href="#cb8-6" tabindex="-1"></a> } <a href="#cb8-7" tabindex="-1"></a> return total; <a href="#cb8-8" tabindex="-1"></a>}')</code></pre></div> The C++ version is similar, but: <ul> <li>To find the length of the vector, we use the <code>.size()</code> method, which returns an integer. C++ methods are called with <code>.</code> (i.e., a full stop).</li> <li>The <code>for</code> statement has a different syntax: <code>for(init; check; increment)</code>. This loop is initialised by creating a new variable called <code>i</code> with value 0. Before each iteration we check that <code>i < n</code>, and terminate the loop if it’s not. After each iteration, we increment the value of <code>i</code> by one, using the special prefix operator <code>++</code> which increases the value of <code>i</code> by 1.</li> <li>In C++, vector indices start at 0, which means that the last element is at position <code>n - 1</code>. I’ll say this again because it’s so important: IN C++, VECTOR INDICES START AT 0! This is a very common source of bugs when converting R functions to C++.</li> <li>Use <code>=</code> for assignment, not <code><-</code>.</li> <li>C++ provides operators that modify in-place: <code>total += x[i]</code> is equivalent to <code>total = total + x[i]</code>. Similar in-place operators are <code>-=</code>, <code>*=</code>, and <code>/=</code>.</li> </ul> This is a good example of where C++ is much more efficient than R. As shown by the following microbenchmark, <code>sum_cpp()</code> is competitive with the built-in (and highly optimised) <code>sum()</code>, while <code>sum_r()</code> is several orders of magnitude slower. <div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb9-1" tabindex="-1"></a>x <- runif(1e3) <a href="#cb9-2" tabindex="-1"></a>bench::mark( <a href="#cb9-3" tabindex="-1"></a> sum(x), <a href="#cb9-4" tabindex="-1"></a> sum_cpp(x), <a href="#cb9-5" tabindex="-1"></a> sum_r(x) <a href="#cb9-6" tabindex="-1"></a>)[1:6] <a href="#cb9-7" tabindex="-1"></a>#> # A tibble: 3 × 6 <a href="#cb9-8" tabindex="-1"></a>#> expression min median `itr/sec` mem_alloc `gc/sec` <a href="#cb9-9" tabindex="-1"></a>#> <bch:expr> <bch:tm> <bch:tm> <dbl> <bch:byt> <dbl> <a href="#cb9-10" tabindex="-1"></a>#> 1 sum(x) 1.52µs 1.72µs 547073. 0B 0 <a href="#cb9-11" tabindex="-1"></a>#> 2 sum_cpp(x) 1.39µs 1.56µs 571050. 0B 0 <a href="#cb9-12" tabindex="-1"></a>#> 3 sum_r(x) 12.79µs 12.91µs 74068. 19.2KB 0</code></pre></div> </div> <div id="vector-input-vector-output" class="section level3"> <h3>Vector input, vector output</h3>  Next we’ll create a function that computes the Euclidean distance between a value and a vector of values: <div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb10-1" tabindex="-1"></a>pdist_r <- function(x, ys) { <a href="#cb10-2" tabindex="-1"></a> sqrt((x - ys) ^ 2) <a href="#cb10-3" tabindex="-1"></a>}</code></pre></div> In R, it’s not obvious that we want <code>x</code> to be a scalar from the function definition, and we’d need to make that clear in the documentation. That’s not a problem in the C++ version because we have to be explicit about types: <div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb11-1" tabindex="-1"></a>cpp_function('doubles pdist_cpp(double x, doubles ys) { <a href="#cb11-2" tabindex="-1"></a> int n = ys.size(); <a href="#cb11-3" tabindex="-1"></a> writable::doubles out(n); <a href="#cb11-4" tabindex="-1"></a> for(int i = 0; i < n; ++i) { <a href="#cb11-5" tabindex="-1"></a> out[i] = sqrt(pow(ys[i] - x, 2.0)); <a href="#cb11-6" tabindex="-1"></a> } <a href="#cb11-7" tabindex="-1"></a> return out; <a href="#cb11-8" tabindex="-1"></a>}')</code></pre></div> This function introduces a few new concepts: <ul> <li>Because we are creating a new vector we need to use <code>writable::doubles</code> rather than the read-only <code>doubles</code>.</li> <li>We create a new numeric vector of length <code>n</code> with a constructor: <code>cpp11::writable::doubles out(n)</code>. Another useful way of making a vector is to copy an existing one: <code>cpp11::doubles zs(ys)</code>.</li> <li>C++ uses <code>pow()</code>, not <code>^</code>, for exponentiation.</li> </ul> Note that because the R version is fully vectorised, it’s already going to be fast. <div class="sourceCode" id="cb12"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb12-1" tabindex="-1"></a>y <- runif(1e6) <a href="#cb12-2" tabindex="-1"></a>bench::mark( <a href="#cb12-3" tabindex="-1"></a> pdist_r(0.5, y), <a href="#cb12-4" tabindex="-1"></a> pdist_cpp(0.5, y) <a href="#cb12-5" tabindex="-1"></a>)[1:6] <a href="#cb12-6" tabindex="-1"></a>#> # A tibble: 2 × 6 <a href="#cb12-7" tabindex="-1"></a>#> expression min median `itr/sec` mem_alloc `gc/sec` <a href="#cb12-8" tabindex="-1"></a>#> <bch:expr> <bch:tm> <bch:tm> <dbl> <bch:byt> <dbl> <a href="#cb12-9" tabindex="-1"></a>#> 1 pdist_r(0.5, y) 1.99ms 2.07ms 479. 7.63MB 92.5 <a href="#cb12-10" tabindex="-1"></a>#> 2 pdist_cpp(0.5, y) 880.8µs 966.7µs 996. 7.63MB 168.</code></pre></div> On my computer, it takes around 5 ms with a 1 million element <code>y</code> vector. The C++ function is about 2.5 times faster, ~2 ms, but assuming it took you 10 minutes to write the C++ function, you’d need to run it ~200,000 times to make rewriting worthwhile. The reason why the C++ function is faster is subtle, and relates to memory management. The R version needs to create an intermediate vector the same length as y (<code>x - ys</code>), and allocating memory is an expensive operation. The C++ function avoids this overhead because it uses an intermediate scalar. </div> <div id="cpp-source" class="section level3"> <h3>Using cpp_source</h3> So far, we’ve used inline C++ with <code>cpp_function()</code>. This makes presentation simpler, but for real problems, it’s usually easier to use stand-alone C++ files and then source them into R using <code>cpp_source()</code>. This lets you take advantage of text editor support for C++ files (e.g., syntax highlighting) as well as making it easier to identify the line numbers in compilation errors. Your stand-alone C++ file should have extension <code>.cpp</code>, and needs to start with: <div class="sourceCode" id="cb13"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb13-1" tabindex="-1"></a>#include "cpp11.hpp" <a href="#cb13-2" tabindex="-1"></a>using namespace cpp11;</code></pre></div> And for each function that you want available within R, you need to prefix it with: <div class="sourceCode" id="cb14"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb14-1" tabindex="-1"></a>[[cpp11::register]]</code></pre></div> If you’re familiar with roxygen2, you might wonder how this relates to <code>@export</code>. <code>cpp11::register</code> registers a C++ function to be called from R. <code>@export</code> controls whether a function is exported from a package and made available to the user. To compile the C++ code, use <code>cpp_source("path/to/file.cpp")</code>. This will create the matching R functions and add them to your current session. Note that these functions can not be saved in a <code>.Rdata</code> file and reloaded in a later session; they must be recreated each time you restart R. This example also illustrates a different kind of a <code>for</code> loop, a for-each loop. <div class="sourceCode" id="cb15"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb15-1" tabindex="-1"></a>#include "cpp11/doubles.hpp" <a href="#cb15-2" tabindex="-1"></a>using namespace cpp11; <a href="#cb15-3" tabindex="-1"></a> <a href="#cb15-4" tabindex="-1"></a>[[cpp11::register]] <a href="#cb15-5" tabindex="-1"></a>double mean_cpp(doubles x) { <a href="#cb15-6" tabindex="-1"></a> int n = x.size(); <a href="#cb15-7" tabindex="-1"></a> double total = 0; <a href="#cb15-8" tabindex="-1"></a> for(double value : x) { <a href="#cb15-9" tabindex="-1"></a> total += value; <a href="#cb15-10" tabindex="-1"></a> } <a href="#cb15-11" tabindex="-1"></a> return total / n; <a href="#cb15-12" tabindex="-1"></a>}</code></pre></div> NB: if you run this code, you’ll notice that <code>mean_cpp()</code> is faster than the built-in <code>mean()</code>. This is because it trades numerical accuracy for speed. For the remainder of this vignette C++ code will be presented stand-alone rather than wrapped in a call to <code>cpp_function</code>. If you want to try compiling and/or modifying the examples you should paste them into a C++ source file that includes the elements described above. This is easy to do in RMarkdown by using <code>{cpp11}</code> instead of <code>{r}</code> at the beginning of your code blocks. </div> <div id="exercises" class="section level3"> <h3>Exercises</h3> <ol style="list-style-type: decimal"> <li>With the basics of C++ in hand, it’s now a great time to practice by reading and writing some simple C++ functions. For each of the following functions, read the code and figure out what the corresponding base R function is. You might not understand every part of the code yet, but you should be able to figure out the basics of what the function does.</li> </ol> <div class="sourceCode" id="cb16"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb16-1" tabindex="-1"></a>#include "cpp11.hpp" <a href="#cb16-2" tabindex="-1"></a> <a href="#cb16-3" tabindex="-1"></a>using namespace cpp11; <a href="#cb16-4" tabindex="-1"></a>namespace writable = cpp11::writable; <a href="#cb16-5" tabindex="-1"></a> <a href="#cb16-6" tabindex="-1"></a>[[cpp11::register]] <a href="#cb16-7" tabindex="-1"></a>double f1(doubles x) { <a href="#cb16-8" tabindex="-1"></a> int n = x.size(); <a href="#cb16-9" tabindex="-1"></a> double y = 0; <a href="#cb16-10" tabindex="-1"></a> <a href="#cb16-11" tabindex="-1"></a> for(int i = 0; i < n; ++i) { <a href="#cb16-12" tabindex="-1"></a> y += x[i] / n; <a href="#cb16-13" tabindex="-1"></a> } <a href="#cb16-14" tabindex="-1"></a> return y; <a href="#cb16-15" tabindex="-1"></a>} <a href="#cb16-16" tabindex="-1"></a> <a href="#cb16-17" tabindex="-1"></a>[[cpp11::register]] <a href="#cb16-18" tabindex="-1"></a>doubles f2(doubles x) { <a href="#cb16-19" tabindex="-1"></a> int n = x.size(); <a href="#cb16-20" tabindex="-1"></a> writable::doubles out(n); <a href="#cb16-21" tabindex="-1"></a> <a href="#cb16-22" tabindex="-1"></a> out[0] = x[0]; <a href="#cb16-23" tabindex="-1"></a> for(int i = 1; i < n; ++i) { <a href="#cb16-24" tabindex="-1"></a> out[i] = out[i - 1] + x[i]; <a href="#cb16-25" tabindex="-1"></a> } <a href="#cb16-26" tabindex="-1"></a> return out; <a href="#cb16-27" tabindex="-1"></a>} <a href="#cb16-28" tabindex="-1"></a> <a href="#cb16-29" tabindex="-1"></a>[[cpp11::register]] <a href="#cb16-30" tabindex="-1"></a>bool f3(logicals x) { <a href="#cb16-31" tabindex="-1"></a> int n = x.size(); <a href="#cb16-32" tabindex="-1"></a> <a href="#cb16-33" tabindex="-1"></a> for(int i = 0; i < n; ++i) { <a href="#cb16-34" tabindex="-1"></a> if (x[i]) { <a href="#cb16-35" tabindex="-1"></a> return true; <a href="#cb16-36" tabindex="-1"></a> } <a href="#cb16-37" tabindex="-1"></a> } <a href="#cb16-38" tabindex="-1"></a> return false; <a href="#cb16-39" tabindex="-1"></a>} <a href="#cb16-40" tabindex="-1"></a> <a href="#cb16-41" tabindex="-1"></a>[[cpp11::register]] <a href="#cb16-42" tabindex="-1"></a>int f4(cpp11::function pred, list x) { <a href="#cb16-43" tabindex="-1"></a> int n = x.size(); <a href="#cb16-44" tabindex="-1"></a> <a href="#cb16-45" tabindex="-1"></a> for(int i = 0; i < n; ++i) { <a href="#cb16-46" tabindex="-1"></a> logicals res(pred(x[i])); <a href="#cb16-47" tabindex="-1"></a> if (res[0]) { <a href="#cb16-48" tabindex="-1"></a> return i + 1; <a href="#cb16-49" tabindex="-1"></a> } <a href="#cb16-50" tabindex="-1"></a> } <a href="#cb16-51" tabindex="-1"></a> return 0; <a href="#cb16-52" tabindex="-1"></a>}</code></pre></div> <ol style="list-style-type: decimal"> <li>To practice your function writing skills, convert the following functions into C++. For now, assume the inputs have no missing values. <ol style="list-style-type: decimal"> <li><code>all()</code>.</li> <li><code>cumprod()</code>, <code>cummin()</code>, <code>cummax()</code>.</li> <li><code>diff()</code>. Start by assuming lag 1, and then generalise for lag <code>n</code>.</li> <li><code>range()</code>.</li> <li><code>var()</code>. Read about the approaches you can take on <a href="https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance">Wikipedia</a>. Whenever implementing a numerical algorithm, it’s always good to check what is already known about the problem.</li> </ol></li> </ol> </div> </div> <div id="classes" class="section level2"> <h2>Other classes</h2> You’ve already seen the basic vector classes (<code>integers</code>, <code>doubles</code>, <code>logicals</code>, <code>strings</code>) and their scalar (<code>int</code>, <code>double</code>, <code>bool</code>, <code>string</code>) equivalents. cpp11 also provides wrappers for other base data types. The most important are for lists and data frames, functions, and attributes, as described below. <div id="lists-and-data-frames" class="section level3"> <h3>Lists and data frames</h3> cpp11 also provides <code>list</code> and <code>data_frame</code> classes, but they are more useful for output than input. This is because lists and data frames can contain arbitrary classes but C++ needs to know their classes in advance. If the list has known structure (e.g., it’s an S3 object), you can extract the components and manually convert them to their C++ equivalents with <code>as_cpp()</code>. For example, the object created by <code>lm()</code>, the function that fits a linear model, is a list whose components are always of the same type. The following code illustrates how you might extract the mean percentage error (<code>mpe()</code>) of a linear model. This isn’t a good example of when to use C++, because it’s so easily implemented in R, but it shows how to work with an important S3 class. Note the use of <code>Rf_inherits()</code> and the <code>stop()</code> to check that the object really is a linear model.  <div class="sourceCode" id="cb17"><pre class="sourceCode cpp"><code class="sourceCode cpp"><a href="#cb17-1" tabindex="-1"></a>#include "cpp11.hpp" <a href="#cb17-2" tabindex="-1"></a>using namespace cpp11; <a href="#cb17-3" tabindex="-1"></a> <a href="#cb17-4" tabindex="-1"></a>[[cpp11::register]] <a href="#cb17-5" tabindex="-1"></a>double mpe(list mod) { <a href="#cb17-6" tabindex="-1"></a> if (!Rf_inherits(mod, "lm")) { <a href="#cb17-7" tabindex="-1"></a> stop("Input must be a linear model"); <a href="#cb17-8" tabindex="-1"></a> } <a href="#cb17-9" tabindex="-1"></a> doubles resid(mod["residuals"]); <a href="#cb17-10" tabindex="-1"></a> doubles fitted(mod["fitted.values"]); <a href="#cb17-11" tabindex="-1"></a> int n = resid.size(); <a href="#cb17-12" tabindex="-1"></a> double err = 0; <a href="#cb17-13" tabindex="-1"></a> for(int i = 0; i < n; ++i) { <a href="#cb17-14" tabindex="-1"></a> err += resid[i] / (fitted[i] + resid[i]); <a href="#cb17-15" tabindex="-1"></a> } <a href="#cb17-16" tabindex="-1"></a> return err / n; <a href="#cb17-17" tabindex="-1"></a>}</code></pre></div> <div class="sourceCode" id="cb18"><pre class="sourceCode r"><code class="sourceCode r"><a href="#cb18-1" tabindex="-1"></a>mod <- lm(mpg ~ wt, data = mtcars) <a href="#cb18-2" tabindex="-1"></a>mpe(mod) <a href="#cb18-3" tabindex="-1"></a>#> [1] -0.01541615</code></pre></div> </div> <div id="functions-cpp11" class