Rcpp on R Views

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 6

Mon, 28 Sep 2020 00:00:00 +0000

In this final post of the six part series on R package integration with modern reusable C++ Code using Rcpp, we will look at providing documentation for an R package. To review, we previously covered the following topics:

Installation and configuration of an Rcpp package project in RStudio
Design considerations for integrating R with reusable C++ code
Rcpp interface code examples that are exported to R
Creating an Rcpp Package Project in RStudio, and building and distributing an R package
An introductory example of integrating independent and standard C++ code in an R package, with sample code provided on GitHub

Let’s now look at how to provide html documentation that conforms to the familiar form one finds in R packages.

Documentation

In the discussion that follows, we will look at a quick and relatively easy way to provide documentation for each of the C++ functions that is exported as an R function in an Rcpp-based package. It should be noted that there are alternatives that are often preferred for packages that are submitted to CRAN for publication; for example, using the ROxygen2 package for generating the documentation from inline statements in the interface code. This, however, involves sophistication and complexity beyond the scope of this “getting started” series.

The approach we will examine here involves filling a file template for each exported function, as well as a file that provides information common to the entire package. These file templates carry an Rd extension, as we shall see. The corresponding html files are then generated when you build your package. The good news is that RStudio makes this a relatively painless process.

If you create an Rcpp package project as discussed in the previous posts in this series, you will find the following two files provided by default under the man subdirectory:

Default documentation files

These files are provided by default. You ultimately won’t need the hello world help file, but the RcppProject-package.Rd will contain common information for the entire package; this latter file will be introduced shortly.

Documentation for Exported Functions

Let’s first cover how to create a help file for an exported Rcpp interface function. To show this, let’s go back to the sample code provided on GitHub for Part 5. Suppose you wanted to provide documentation for the rAdd(.) function that is exported from the CppInterface.cpp file. How would you do this?

With RStudio, the solution is quite easy. First, you would select New File/Documentation... from the File menu at the top:

You will then see an input panel as follows. Under Topic name, type in the function name rAdd, and be sure the selection under Rd template is set to function (the default):

New R documentation file selection

After clicking OK, you will see the rAdd.Rd file appear in the man subdirectory in the RStudio files pane:

New documentation file in man folder

Next, double click on this file to open it in RStudio. Note that RStudio is smart enough to glean the proper number of arguments from the function and place this information in the file:

Top of the created rAdd.Rd file

Work down the file section by section and replace the comments in green (beginning with a % character) with the relevant information as described to fill in the necessary information; also, the commented line: %- Also NEED an '\alias' for EACH other topic documented here. can just be removed. The contents for each section should be placed inside the curly brackets { } following each of the following items, as will be demonstrated in the example that follows these descriptions.

name and alias: Just leave these as they are, with the function name.

title: Provide brief description of what the function does .

description: Provide a more detailed description of what the function does.

usage: The easiest thing to do here is to leave it as is.

arguments: You will notice the description of each argument x and y is nested. Just enter the type of each variable, and a short description of each if desired.

details: This can be removed if no further details are required; otherwise, place additional details about the functionality here.

value: Indicate the return type here.

references: Place references you wish to cite here; otherwise, this can be removed if not needed.

author: Provide the names of authors/contributors for this package function.

note and seealso: Enter any additional information about the function; may be removed if not needed.

examples: Place working example(s) of your function here. This should be completely self-contained, including any input data (if needed).

After the examples section, remove the trailing comments at the bottom of the file.

A complete sample file could then be as follows. You could also use this as a blueprint for your own function documentation if you wish.

\name{rAdd}
\alias{rAdd}
\title{Add two numbers}
\description{Adds two real numbers}
\usage{
rAdd(x, y)
}
\arguments{
  \item{x}{A real number}
  \item{y}{A real number}
}
\details{This is a trivial example}
\value{numeric}
\references{Courant and Hilbert, Methods of Mathematical Physics, Volumes 1 & 2}
\author{Fred Sanford}
\note{Nothing to say}
\seealso{https://rviews.rstudio.com/}
\examples{
x <- 586.3
y <- 922.6
rAdd(x, y)
}

To generate the html help file, rebuild your project. When complete, and with the package reloaded into your current R session, look up rAdd in the usual help section in RStudio. The result should look like this:

The generated help file for the rAdd(.) function

As a matter of best practice, you will want to follow the same instructions per the above for all of the remaining exported interface functions in your package. The remaining .Rd files have been uploaded to the man directory in the GitHub repository for this post. These help files accompany the source files that were provided for Part 5.

Documentation of Common Package Information

A default file is also provided with an RStudio Rcpp project that is to contain an overall help file for the entire package; it is of the form PackageName-package.Rd. However, modifying this file for your particular package can sometimes be a source of build errors and package check errors, so I recommend just keeping it simple, at least until you become more accustomed to writing your own R packages. In particular, you will probably save yourself some trouble by removing the code examples section from this file and relegating them to the individual function help files, at least to get started.

As an example, the RcppBlogCode-package.Rd file is also included in the GitHub folder for this post, as noted above. As you can see, this is short and sweet, but if applied to a realistic situation, it should be reasonably informative. The generated result is shown here:

Generated help file containing common package information

The `Check Package` Utility

After building and testing your package as discussed earlier on, there is one more task that one should run before deploying an R package, and this is the Check Package procedure, which can be found under the Build menu in RStudio:

Starting the Check Package process

As described in the R documentation (devtools), Check Package “automatically builds and checks a source package, using all know best practices”. While this is more of a critical step for submitting a package to CRAN, even for internal deployment it’s a good idea to run it to be sure that your documentation is complete, and the examples in your documentation run properly. If you are missing an .Rd file for a function exported to your package, or if an example in your documentation does not run, the check procedure will flag an error.

The heavy details related to checking a package for CRAN submission are located on the CRAN website, and of course many other sources are available on the internet. These are beyond the scope of this series, but if at some point you are contemplating a CRAN submission, it will be necessary to work through the details.

Summary

This concludes our series on integrating independent, standard, and reusable C++ code in an R package using RStudio and the Rcpp package. Hopefully, this will help you avoid some of the frustrations one can encounter from the proverbial fire hose of ubiquitous information that often obscures the essentials at the outset. Happy packaging!

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 5

Mon, 24 Aug 2020 00:00:00 +0000

Daniel Hanson is a full-time lecturer in the Computational Finance & Risk Management program within the Department of Applied Mathematics at the University of Washington.

In the previous post, we went through the build processes for a simple package containing a single C++ .cpp file, using the rcpp_hello_world.cpp example that is included by default when one creates a new R package using Rcpp in RStudio.

What we’ll do now is examine a more realistic case which involves multiple reusable C++ files as well as the C++ interface files that export functions to R. For this example, you should download the C++ files from this GitHub repository. In addition, you should download a set of test functions in R, here (RStudioBlogTests.R). Please note that this file is not part of the package code; we will discuss this shortly.

Building an `Rcpp` Package with Reusable C++

The code you have downloaded from the first link is the same as that referenced in Part 3 of this series. You will now create an Rcpp package project in RStudio and import this code.

Create an RStudio Project

This procedure is the same as what we covered in the previous post. For convenience later, I suggest you name your project RcppBlogCode. Make sure to modify the NAMESPACE file as we discussed before. Also, while not mandatory, you may find it simpler to delete the rcpp_hello_world.cpp file; we will not use it in this example.

Import the C++ Code into the Project

Next, copy or move the code you downloaded from the /src subdirectory on GitHub into the /src subdirectory of your RStudio project. When this is done, you should see the files present in this location in the files pane in RStudio:

Note that this source code contains:

Declaration (header files) for the reusable C++ code
- NonmemberCppFcns.h: Declarations of nonmember functions
- ConcreteShapes.h: Declarations of the Square and Circle classes
Files containing implementations of functions and classes in the reusable C++ code
- NonmemberCppFcns.cpp: Nonmember function implementations
- ConcreteShapes.cpp: Square and Circle class implementations
C++ files that call reusable code and export functions to R (.cpp files only); each exported function is indicated by the // [[Rcpp::export]] tag
- CppInterface.cpp: Calls nonmember functions in the code base
- CppInterface2.cpp: Creates and uses instances of classes in the code base

Build and Run Functions in the R Package

Next, let’s build this package, just as we did for our simpler example in the previous post. Select Clean and Rebuild from the Build menu at the top of the RStudio IDE. When complete, R will restart, and the RcppBlogCode package will be loaded into your R session. You can now call functions from this package in the console; e.g. ,

Calculate the product of the LCM and GCD of 10 and 20: rProdLcmGcd(10, 20)
Calculate the area of a square with length 4: squareArea(4)

Try package functions in console

Congratulations again! You have now successfully imported resuable C++ code, independent of R and Rcpp, and used it via an interface as an R function in your generated package. However, this of course is not a realistic scenario. What we really want is to use this package in a regular and independent R session.

Use the Package Independently of the `Rcpp` Project

So far, you have built an R package containing C++ code, and you have called a couple of functions from the console, but that of course is not what a real R user does. What you’ll want to do is open a new (and empty) RStudio instance. As the RcppBlogCode package is installed on your machine, all you need to do is load it as you would any other R package:

library(RcppBlogCode)

Next, open up the RStudioBlogTests.R test file that you downloaded at the outset. Again, make sure this file is located outside of the Rcpp package directory structure. You can now use the package functions that call the C++ nonmember functions internally in the package:

rAdd(531, 9226)    

(x <- c(5:1))
rSortVec(x)

rProdLcmGcd(10, 20)

You can also run the R functions that create instances of the Square and Circle classes in the C++ code:

squareArea(4)
circleArea(1)

The actual mathematics here are obviously nothing exciting, but you should now see that you have a blueprint that takes in independent and reusable C++ source code, wraps its functionality in C++ interface functions that get exported by Rcpp, and allows you to use these exported functions just as you would any other R package functions.

Perhaps more interesting is to see how you can take the results of these package functions and use them in other R functions and packages. For this next example, you will need to install and load the plotly package. We will define vectors of square sides and circle radii, and compute the corresponding areas using our package functions. This is again nothing earth-shattering, but we can then use them in plotly to generate some reasonably professional quality graphs:

library(plotly)

squareSides <- c(1:10)
circleRadii <- c(1:10)

squareAreas <- sapply(squareSides, squareArea)
circleAreas <- sapply(circleRadii, circleArea)

### Use plotly to visualize some results:
dfSq <- matrix(data=c(squareSides, squareAreas), nrow=length(squareSides), ncol=2)
dfSq <- as.data.frame(dfSq)
colnames(dfSq) = c("Side", "Area")
rownames(dfSq) = NULL
plot_ly(dfSq, x = ~Side, y = ~ Area, type = "bar") %>% 
  layout(title="Areas of Squares")


dfCirc <- matrix(data=c(circleRadii, circleAreas), nrow=length(squareSides), ncol=2)
dfCirc <- as.data.frame(dfCirc)
colnames(dfCirc) = c("Radius", "Area")
rownames(dfCirc) = NULL
plot_ly(dfCirc, x = ~Radius, y = ~ Area, type = 'scatter', 
        mode = 'lines', color = 'red') %>%
  layout(title="Areas of Circles")

Using results from package in Plotly graphs

Remark 1: If you wish to go back and modify the package code, you will need to close your R session that is using the package; otherwise, the code will not build.

Remark 2: As discussed last time, you can also export the package to a binary and deploy it on another machine. In general, this allows you to design and build your own Rcpp R package, and deploy it for your colleagues to use, if you wish.

Summary

You have now seen how to import standard and reusable C++ code into an R package using Rcpp, use the package in R, and deploy it as a binary. The one remaining topic to cover is documentation, which we will take up next time.

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 4

Tue, 18 Aug 2020 00:00:00 +0000

Daniel Hanson is a full-time lecturer in the Computational Finance & Risk Management program within the Department of Applied Mathematics at the University of Washington.

In the previous post in this series, we looked at how to write interface files using Rcpp to call functions and instantiate classes in standard and reusable C++, with a code interface and reusable code examples shown in the discussion. My original plan for this week was to show how to import that code into an RStudio Rcpp project and build it into an R package, but as there are a number of steps in the setup and build process, we’ll first look at a very simple example to demonstrate these, and then we’ll turn our attention to importing the reusable C++ code next time.

The following discussion will be a step by step guide in the project configuration and build process with a single example .cpp file that is included by default when creating an Rcpp project in the RStudio IDE.

Creating an Rcpp Package Project in the RStudio IDE

Open the RStudio IDE, and select New Project... from the File menu at the top, and select New Directory as shown here:

Next, you will see the following selections, from which you should choose R Package using Rcpp. Be sure to make this selection, and not R package alone as shown above:

Next, enter the desired directory path and new subdirectory name, and create the project; the subdirectory will be the name of your R package, e.g. RcppProject:

When finished, your RStudio session should look something like this:

There is one more step to complete in order to ensure your interface functions will be exposed as R functions to your package users. In the Files pane at lower right, you should see a file called NAMESPACE:

Double click on this file to open it in RStudio; you will see the following:

Now, delete line 2, and then append a new line 3, as shown below. This will allow your tagged C++ interface files to be exportable to R. Leave line 4 blank, just as it is in the original. Then, save the file:

Remark: There are more advanced ways to configure the NAMESPACE file when building an R package, which would require in-depth explanation, distracting us from the main task of getting up and running with Rcpp. As such, we’ll just use this simple fix for our discussion.

Building an R Package

Returning to the Files pane in the RStudio IDE (see Figure 5 above), note the following sudirectories:

man: For documentation files (we will return to this in a later installment).
R: For R code to be included in a package; for now, we will only be concerned with C++ code.
src: This is where C++ code is located in the package:
- Both header (.h) and implementation (.cpp) files
- Both interface and reusable C++ code files

By clicking on the src subdirectory, you will see that there are two C++ files that are present by default in a blank RStudio Rcpp project:

rcpp_hello_world.cpp: Simple interface function included as an example, by default.
RcppExports.cpp: This is a C++ file that is generated each time the Rcpp project is built in the RStudio environment. You need not be concerned about its contents, but it is crucial that you never modify this file on your own.

The `rcpp_hello_world.cpp` file

Let’s look at this simple example first. It should look somewhat similar to the C++ interface files presented last time. The main difference is it does not call any functions in an external file; it simply returns an R List object to the function user in R. Note the // [[Rcpp::export]] tag; this will export the rcpp_hello_world() function to R:

#include <Rcpp.h>
using namespace Rcpp;
// [[Rcpp::export]]
List rcpp_hello_world() {
    CharacterVector x = CharacterVector::create( "foo", "bar" )  ;
    NumericVector y   = NumericVector::create( 0.0, 1.0 ) ;
    List z            = List::create( x, y ) ;
    return z ;
}

Your First R Package with C++ Code

Now, let’s build the package with this single C++ function. To do this, from the Build menu at the top of the RStudio IDE, and select Clean and Rebuild. In the upper right hand pane in the IDE, you will then see the C++ being compiled, and the package being built.

When the build is complete, your R session will restart, and your package will be loaded into your current R session, as shown in the console at the bottom of the R Studio IDE:

Now, type in rcpp_hello_world() at the console prompt, and check your results. You should see the following:

Congratulations! You have just built your first R package with integrated C++, and you called the exported function from an R session. You can also check that the package contents have been placed in the usual .../R-4.0.x/library directory, in a subdirectory with the package name, just like any other R package you load from CRAN.

Distribute the Package as a Binary

You can also export the package in binary form to a .zip file on Windows, or a tar.gz file on the Mac or on Linux. To do this, again from the Build menu, select Build Binary Package.

You will again see the compile and build process in the upper right hand corner of the RStudio IDE. When complete, you can find your distributable file, e.g. RcppProject.zip, in the directory one level up from your project directory. To deploy it, either copy it to another machine with the same OS and R setup, or delete the package subdirectory, e.g. .../R-4.0.x/library/RcppProject. Then, open an new RStudio session, and install the package just as you would any other package locally:
\newpage

Next, load the package in your session, e.g. library(RcppProject), and then call the exported function again to verify it works.

Summary

We have now covered the process of building an R package containing C++ code in RStudio IDE, by integrating the code into an Rcpp project. The C++ code in this case consisted of a single .cpp file, with a single interface function tagged for export to R, to keep the discussion focused more on the process itself. Next time, we will revisit the C++ code file examples in the previous post, and show how to integrate them into an R package. The process is essentially the same as above, but with multiple source code files and multiple interface files, it will involve some additional management and other details.

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 3

Fri, 31 Jul 2020 00:00:00 +0000

Daniel Hanson is a full-time lecturer in the Computational Finance & Risk Management program within the Department of Applied Mathematics at the University of Washington.

In the previous post in this series, we looked at some design considerations when integrating standard and reusable C++ code into an R package. Specific emphasis was on Rcpp’s role in facilitating a means of communication between R and the C++ code, particularly highlighting a few of the C++ functions in the Rcpp namespace that conveniently and efficiently pass data between an R numeric vector and a C++ std::vector<double> object.

Today, we will look at a specific example of implementing the interface. We will see how to configure code that allows the use of standard reusable C++ in an R package, without having to modify it with any R or Rcpp-specific syntax. It is admittedly a simple and toy example, but the goal is to provide a starting point that can be easily extended for more real world examples.

The Code

To get started, let’s have a look at the code we will use for our demonstration. It is broken into three categories, consistent with the design considerations from the previous post:

Standard and reusable C++: No dependence on R or Rcpp
Interface level C++: Uses functions in the Rcpp namespace
R functions exported by the interface level: Same names as in the interface level

Standard and Reusable C++ Code

In this example, we will use a small set of C++ non-member functions, and two classes. There is a declaration (header) file for the non-member functions, say NonmemberCppFcns.h, and another with class declarations for two shape classes, Square and Circle, called ConcreteShapes.h. Each of these is accompanied by a corresponding implementation file, with file extension .cpp, as one might expect in a more realistic C++ code base.

Nonmember C++ Functions

These functions are shown and described here, as declared in the following C++ header file:

#include <vector>
// Adds two real numbers
double add(double x, double y);
// Sorts a vector of real numbers and returns it
std::vector<double> sortVec(std::vector<double> v);
// Computes the product of the LCM and GCD of two integers, 
// using C++17 functions std::lcm(.) and std::gcd(.)
int prodLcmGcd(int m, int n);

The last function uses recently added features in the C++ Standard Library, to show that we can use C++17.

C++ Classes

The two classes in our reusable code base are declared in the ConcreteShapes.h file, as shown and described here. Much like textbook C++ examples, we’ll write classes for two geometric shapes, each with a member function to compute the area of its corresponding object.

#include <cmath>
class Circle
{
public:
  Circle(double radius);
  
  // Computes the area of a circle with given radius
  double area() const;
  
private:
  double radius_;
};
class Square
{
public:
  Square(double side);
  
  // Computes the area of a square with given side length
  double area() const;
private:
  double side_;
};

Interface Level C++

Now, the next step is to employ Rcpp, namely for the following essential tasks:

Export the interface functions to R
Facilitate data exchange between R and C++ container objects

An interface file containing functions designated for export to R does not require a header file with declarations; one can think of it as being analogous to a .cpp file that contains the main() function in a C++ executable project. In addition, the interface can be contained in one file, or split into multiple files. For demonstration, I have written two such files: CppInterface.cpp, which provides the interface to the non-member functions above, and CppInterface2.cpp, which does the same for the two C++ classes.

Interface to Non-Member C++ Functions:

Let’s first have a look the CppInterface.cpp interface file, which connects R with the nonmember functions in our C++ code base:

#include "NonmemberCppFcns.h"
#include <vector>
#include <Rcpp.h>     
// Nonmember Function Interfaces:
// [[Rcpp::export]]
int rAdd(double x, double y)
{
  // Call the add(.) function in the reusable C++ code base:
  return add(x, y);
}
// [[Rcpp::export]]
Rcpp::NumericVector rSortVec(Rcpp::NumericVector v)
{
  // Transfer data from NumericVector to std::vector<double>
  auto stlVec = Rcpp::as<std::vector<double>>(v); 
  
  // Call the reusable sortVec(.) function, with the expected
  // std::vector<double> argument:
  stlVec = sortVec(stlVec);
  
  // Reassign the results from the vector<double> return object
  // to the same NumericVector v, using Rcpp::wrap(.):
  v = Rcpp::wrap(stlVec);
  
  // Return as an Rcpp::NumericVector:
  return v;
}
// C++17 example:
// [[Rcpp::export]]
int rProdLcmGcd(int m, int n)
{
  return prodLcmGcd(m, n);
}

Included Declarations:

The NonmemberCppFcns.h declaration file is included at the top with #include, just as it would in a standalone C++ application, so that the interface will recognize these functions that reside in the reusable code base. The STL vector declaration is required, as we shall soon see. And, the key in making the interface work resides in the Rcpp.h file, which provides access to very useful C++ functions in the Rcpp namespace.

Function implementations:

Each of these functions is designated for export to R when the package is built, by placing the // [[Rcpp::export]] tag just above the each function signature, as shown above. In this particular example, each interface function simply calls a function in the reusable code base. For example, the rAdd(.) function simply calls the add(.) function in the reusable C++ code. In the absence of a user-defined namespace, the interface function name must be different from the function it calls to prevent name clash errors during the build, so I have simply chosen to prefix an r to the name of each interface function.

Note that the rSort(.) function takes in an Rcpp::NumericVector object, v. This type will accept data passed in from R as a numeric vector and present it as a C++ object. Then, so that we can call a function in our code base, such as sort(.), which expects a std::vector<double> type as its input, Rcpp also provides the Rcpp::as<.>(.) function that facilitates the transfer of data from an Rcpp::NumericVector object to the STL container:

auto stlVec = Rcpp::as<std::vector<double>>(v);

Rcpp also gives us a function that will transfer data from a std::vector<double> type being returned from our reusable C++ code back into an Rcpp::NumericVector, so that the results can be passed back to R as a familiar numeric vector type:

v = Rcpp::wrap(stlVec);

As the std::vector<double> object is the workhorse C++ STL containers in quantitative work, these two Rcpp functions are a godsend.

Remark 1: There is no rule that says an interface function can only call a single function in the reusable code; one can use whichever functions or classes that are needed to get the job done, just like with any other C++ function. I’ve merely kept it simple here for demonstration purposes.

Remark 2: The tag // [[Rcpp::plugins(cpp17)]] is sometimes placed at the top of a C++ source file in online examples related to Rcpp and C++17. I have not found this necessary in my own code, however, as long as the Makeconf file has been updated for C++17, as described in the first post in this series.

Interface to C++ Classes:

We now turn our attention to the second interface file, CppInterface2.cpp, which connects R with the C++ classes in our reusable code. It is shown here:

#include "ConcreteShapes.h"
// Class Member Function Interfaces:
// Interface to Square member
// function area(.):
// [[Rcpp::export]]
double squareArea(double side)
{
  Square sq(side);
  return sq.area();
}
// Interface to Circle member
// function area(.):
// [[Rcpp::export]]
double circleArea(double radius)
{
  Circle circ(radius);
  return circ.area();
}

This is again nothing terribly sophisticated, but the good news is it shows the process of creating instances of classes from the code base is not difficult at all. We first #include only the header file containing these class declarations; Rcpp.h is not required here, as we are not using any functions in the the Rcpp namespace.

To compute the area of a square, the side length is input in R as a simple numeric type and passed to the interface function as a C++ double. The Square object, sq, is constructed with the side argument, and its area() member function performs said calculation and returns the result. The process is trivally similar for the circleArea(.) function.

R Functions Exported by the Interface Level

To wrap up this discussion, let’s look at the functions an R user will have available after we build the package in RStudio (coming next in this series). Each of these functions will be exported from their respective C++ interface functions as regular R functions, namely:

rAdd(.)
rSortVec(.)
rProdLcmGcd(.)
squareArea(.)
circleArea(.)

The package user will not need to know or care that the core calculations are being performed in C++. Visually, we can represent the associations as shown in the following diagram:

The solid red line represents a “Chinese Wall” that separates our code base from the interface and allows us to maintain it as standard and reusable C++.

Summary

This concludes our example of configuring code that allows the use of standard reusable C++ in an R package, without having to modify it with any R or Rcpp-specific syntax. In the next post, we will examine how to actually build this code into an R package by leveraging the convenience of Rcpp and RStudio, and deploy it for any number of R users. The source code will also be made available so that you can try it out for yourself.

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 2

Tue, 14 Jul 2020 00:00:00 +0000

Daniel Hanson is a full-time lecturer in the Computational Finance & Risk Management program within the Department of Applied Mathematics at the University of Washington. His appointment followed over 25 years of experience in private sector quantitative development in finance and data science.

In the first post in this series, we looked at configuring a Windows 10 environment for using the Rcpp package. However, what follows below, and going forward, is applicable to an up-to-date R, RStudio, and Rcpp configuration on any operating system.

Today, we will examine design considerations in integrating standard and portable C++ code in an R package, using Rcpp in the interface level alone. This will ensure no R-related dependencies are introduced into the C++ code base. In general, of course, best programming practices say we should strive to keep interface and implementation separate.

Design Considerations

For this discussion, we will assume the package developer has access to a repository of standard C++ code that is intended for use with other mathematical or scientific applications and interfaces. The goal is integrate this code into an R package, and then export functions to R that will use this existing C++ code. The end users need not be concerned that they are using C++ code; they will only see the exported functions that can be used and called like any other R function.

The package developer, at this stage, has two components that cannot communicate with each other, at least yet:

Establishing Communication

This is where Rcpp comes in. We will create an interface layer that utilizes functions and objects in the Rcpp C++ namespace that facilitate communication between R and C++. This interface will ensure that no dependence on R or Rcpp is introduced into our reusable code base.

The Rcpp namespace contains a treasure trove of functions and objects that abstract away the terse underlying C interface provided by R, making our job far less painful. However, at this initial stage, to keep the discussion focused on a basic interface example, we will limit our use of Rcpp functions to facilitate the transfer of numeric vector data in R to the workhorse STL container std::vector<double>, which is of course ubiquitous in quantitative C++ code.

Tags to Indicate Interface Functions

C++ interface functions are indicated by a tag that needs to be placed just above the function name and signature. It is written as

// [[Rcpp::export]]

This tag instructs the package build process to export a function of the exact same name to R. As an interface function, it will take arguments from an R session, route them in a call to a function or class in the C++ code base, and then take the results that are returned and pass them back to the calling function in R.

Conversion between R Vectors and C++ Vectors

The Rcpp::NumericVector class, as its name suggests, stores data taken from an R numeric vector, but what makes Rcpp even more powerful here is its inclusion of the C++ template function Rcpp::as<T>(.). This function safely and efficiently copies the contents of an Rcpp::NumericVector to a std::vector<double> object, as demonstrated in Figure 3, below.

Remark: Rcpp also has the function Rcpp::wrap(.), which copies values in an STL vector back into an Rcpp::NumericVector object, so that the results can then be to R; this function will be covered in our next article in this series.

A C++ Interface Function

Figure 3 shows a mythical Rcpp interface function at the top, called fcn(.), and a function in our reusable standard C++ code base called doSomething(.). Note first the tag that appears just above the interface function signature. It must be exactly one line above, and there must be a single space only between the second forward slash and the first left square bracket.

This interface function will be exported to R, where it can be called by the same function name, fcn(.), taking in an R numeric vector input. The Rcpp::NumericVector object takes this data in as the input to C++. The contents are then transferred to a C++ std::vector<double>, using the Rcpp template function Rcpp::as<vector<double>>(.).

The data can then be passed to the doSomething(.) function in the standard C++ code base, as it is expecting a std::vector<double> input. This function returns the C++ double variable ret to the variable y in the interface function. This requires no special conversion and can be passed back to R as a C++ double type.

Putting the High-Level Design Together

With the C++ interface in place, this means an R user can call an R function that has been exported from C++. When the results are returned, they can be used in other R functions, but where we get an extraordinarily complementary benefit is with R’s powerful data visualization capabilities. Unlike languages such as Python, Java, or VB.NET, C++ does not have a standard GUI, but we can use cutting-edge R packages such as ggplot2, plotly, shiny, and xts – among many others – to generate a massive variety of plots and visualizations that are simply not available in other general purpose languages.

Next Steps

This concludes our discussion of high-level design considerations. Coming next, we will look at examples of writing actual interface functions to simple, but real, standard C++ functions and classes.

R Package Integration with Modern Reusable C++ Code Using Rcpp

Wed, 08 Jul 2020 00:00:00 +0000

One of the most time-consuming, tedious, and thankless tasks a quantitative developer frequently confronts is writing interfaces to C++ code from applications such as Excel, Python, and R. Fortunately, this process has been made far less painful when interfacing to a front-end in R, thanks to the Rcpp package.

Rcpp was first developed by Dirk Eddelbeuttel and Romain Francois about ten years ago. It has since evolved significantly under Dirk’s direction in terms of rapid development, and build and documentation tools, which are now conveniently integrated into in RStudio. Rcpp represents a major breakthrough in allowing a programmer to farm out computationally-intensive tasks to C++, return the results to R, and then use them as arguments to other R functions, including R’s powerful data visualization tools. Although there is quite a bit of documentation on using Rcpp, there does not seem to be much written either in print, or online, regarding C++ best practices.

This post is the first in a series of posts in which I will address the best practice of developing Rcpp implementations that keep both reusable and standard C++ code separate from the R interface. Additionally, I will also cover a subtheme that does not seem to get a lot of press, namely using Rcpp in a Windows environment. Linux of course is where the action is, and for good reason, but the reality remains that when a quant developer takes a new job, on the new hire’s desk will almost surely be a Windows notebook or desktop computer, and s/he will be expected to produce applications that can run on Windows machines used by managers and colleagues. So, we will first look at how to set up an Rcpp development environment on Windows 10, including some of the peculiarities and limitations that are involved, but which will not significantly prevent a developer from being highly productive in writing R packages with integrated reusable and standard C++ code.

Setting up on Windows 10

As with an Rcpp development environment on Linux or the Mac, in order to take advantage of the latest features in C++, as well as the convenient package build tools in RStudio, a Windows user will need the following:

An R installation
A C++ compiler
RStudio

For Windows users, however, the R interface is not compatible with Microsoft’s Visual Studio C++ compiler, due to R itself being built with the GNU gcc compiler. Fortunately, there is a very easy way to make one’s Windows environment compatible. This is where Rtools comes in.

Rtools

Rtools contains a collection of utilities and libraries for building R packages on Windows. More specifically, for integrating C++ code with Rcpp, beginning with version 4.0, Rtools now contains support for the gcc 8.3.0 compiler on Windows. The Rtools installation provides reliable configuration of the gcc compiler that is quick and painless; however, it does come with a small compromise.

The gcc 8.3.0 compiler was released in February 2019, and it has since been superseded by its most recent stable release (9.3). As such, it is fully up to date with C++14 specifications, but it only supports a partial list of language and Standard Library features in C++17. Two specific items very useful for quant development are available:

Special math functions (Bessel functions, Legendre polynomials, etc)
New types std::variant, std::optional, and std::any

However, the gcc compiler lacks the big daddy of them all, parallel STL algorithms. A comprehensive list of C++17 features supported in gcc 8.3.0 can be found here.

Still, as Rtools saves Windows users from considerable time and effort in configuring one’s machine for not just the gcc compiler, but also integrating (mostly) modern C++ code in R packages, it is advised that newcomers stick to Rtools and gcc 8.3.0.

It is very important to note that:

You will need version 4.0.0 of R or above to install Rtools 4.0
Unless there is a compelling reason otherwise, you should install the 64-bit version of Rtools: rtools40-x86_64.exe

Configuration in RStudio

After installing R and Rtools, as well as RStudio (v 1.3.959 or later recommended), you can now complete the configuration of your development environment for integrated R/C++ package development.

Enable C++17

In order to use the C++17 features available in Rtools, as well as C++14, you need to change the settings in the Makeconf file, located under your R installation (not Rtools), as follows:

In Windows File Explorer, go to your R installation and click down to the .../R-4.0.0/etc/x64 subdirectory
Locate the Makeconf file, and copy it to a backup file (always a prudent idea), e.g. Makeconf.bak
Using a standard text editor (eg Notepad++), open the Makeconf file
Locate the line CXX = $(BINPREF)g++ -std=gnu++11 $(M_ARCH)
Change the 11 to 17; viz, CXX = $(BINPREF)g++ -std=gnu++17 $(M_ARCH)
Save the updated file.

Install the Rcpp Package

Installing Rcpp is no different from any other typical R package. Either use the R command:

install.packages("Rcpp")

Or, use the Tools/Install Packages... selection in RStudio.

Next Steps

After completing the above, you will now have a development environment ready to start designing and developing an R package containing standard and reusable C++ code. In the next post, we will first spend a little time examining design considerations, before we begin actual code implementation.

Rcpp on R Views

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 6

Documentation

Documentation for Exported Functions

Documentation of Common Package Information

The Check Package Utility

Summary

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 5

Building an Rcpp Package with Reusable C++

Create an RStudio Project

Import the C++ Code into the Project

Build and Run Functions in the R Package

Use the Package Independently of the Rcpp Project

Summary

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 4

Creating an Rcpp Package Project in the RStudio IDE

Building an R Package

The rcpp_hello_world.cpp file

Your First R Package with C++ Code

Distribute the Package as a Binary

Summary

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 3

The Code

Standard and Reusable C++ Code

Nonmember C++ Functions

C++ Classes

Interface Level C++

Interface to Non-Member C++ Functions:

Included Declarations:

Function implementations:

Interface to C++ Classes:

R Functions Exported by the Interface Level

Summary

R Package Integration with Modern Reusable C++ Code Using Rcpp - Part 2

Design Considerations

Establishing Communication

Tags to Indicate Interface Functions

Conversion between R Vectors and C++ Vectors

A C++ Interface Function

Putting the High-Level Design Together

Next Steps

R Package Integration with Modern Reusable C++ Code Using Rcpp

Setting up on Windows 10

Rtools

Configuration in RStudio

Enable C++17

Install the Rcpp Package

Next Steps

The `Check Package` Utility

Building an `Rcpp` Package with Reusable C++

Use the Package Independently of the `Rcpp` Project

The `rcpp_hello_world.cpp` file