presentation_Rcpp.Rmd

---
classoption: table, dvipsname
colorlinks: no
fontsize: 10pt
link-citations: yes
linkcolor: Black
output:
  beamer_presentation:
    includes:
      after_body: doc_suffix.tex
      before_body: doc_prefix.tex
      in_header: header.tex
    slide_level: 3
urlcolor: Maroon
---

```{r options, include=FALSE}
library(knitr)
library(kableExtra)
opts_chunk$set(echo=TRUE, cache=F,
               #results="hide", 
               warning=FALSE,
               message=FALSE, highlight=TRUE,
               fig.show="hide", size="small",
               fig.align="center",
               tidy=FALSE)
options(knitr.kable.NA="-")
```

\frametitle{Outline}
      \tableofcontents[sections=1]
      \tableofcontents[sections=2]
      \vspace{0.5cm}
      \tableofcontents[sections=3]
      \vspace{0.5cm}
      \tableofcontents[sections=4]

<!-- ================================================================= -->
<!-- PART 1: Rcpp* packages -->
<!-- ================================================================= -->

# Short presentation of Rcpp* packages

## Rcpp : extending R with C++

### Rcpp R package

- **Rcpp** is an R package to extend R with C++ code

- Main advantage: C++ is fast, it accelerates R as shown in the examples

- Written by **Dirk EDDELBUETTEL** and **Romain FRANCOIS**

- <http://www.rcpp.org/>

### Useful Rcpp features 

**`// [[Rcpp::export]]` preceding the C++ function definition**

- Indicate that it should be made available as an R function

- Check if the function have return and entry types compatible with Rcpp i.e. convertible into R object according to the following correspondence tables of data types : 
\pause
\begin{center}
\includegraphics[width=0.4\textwidth]{figs/datatypes.png} \hspace{0.2cm}
\includegraphics[width=0.3\textwidth]{figs/datatypes2.png}
\end{center}
\vspace{0.5cm}

### Useful Rcpp features 

**Thanks to `Rcpp::sourceCpp()`**

- Compile the C++ code

- Export the function to the R session

- Direct conversion of objects (including S3, S4) between R and C++ 

- For more details see `vignette("Rcpp-package")`
\vspace{0.2cm}

\pause 
**Thanks to `Rcpp::depends`**

- Specify additional build dependencies on other packages for `Rcpp::sourceCpp()`

- `Rcpp::sourceCpp()` therefore configures the build environment to correctly compile and link against the package specified

- examples : `[[Rcpp::depends(RcppArmadillo)]]`,  `[[Rcpp::depends(RcppGSL)]]` ... 

### Simple Rcpp example

**C++ code** (in file `Code/addition.cpp`)
```{Rcpp Rcpp-addition, eval=FALSE}
#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
int addition(const int& a, const int& b) {
  return a + b;
}
```

**R code**
```{r addition-r}
Rcpp::sourceCpp("Code/addition.cpp")
addition(2, 2)
```

### Reference in C++

* A variable can be declared as reference by putting `&` in the declaration. 

* The variable declared as reference becomes an alternative name for an existing variable, avoiding copy of large structures.

* Useful to save copying of big objects when passed as arguments to functions, if we pass it without reference, a new copy of it is created which causes wastage of CPU time and memory. 

* If a function receives a reference to a variable as argument, it can modify the value of the variable in memory, the `const` added in the argument declaration will stop it from being altered.

## RcppGSL for fast random draws

### GSL and RcppGSL

\bcols
\bcol{0.1\textwidth}
\includegraphics[height=1.5cm]{figs/logo_GNU.png}
\ecol
\bcol{0.9\textwidth}

**GNU Scientific Library**

- Numerical library for C and C++ programmers

- Reliable random number generator algorithms

- Thoroughly tested and fast random number distributions

- Linear algebra (matrices and vectors)

- <https://www.gnu.org/software/gsl/>

\vspace{0.5cm}

**RcppGSL**

- Interface between R and GSL

- Using Rcpp to interface R and C

- <http://dirk.eddelbuettel.com/code/rcpp.gsl.html>

\ecol
\ecols

### GSL random number distributions

\bcols
\bcol{0.1\textwidth}
\includegraphics[height=1.5cm]{figs/logo_GNU.png}
\ecol
\bcol{0.9\textwidth}

- GSL v2.6 includes **38 random number distributions** (see [GNU GSL](https://www.gnu.org/software/gsl/doc/html/randist.html))
\vspace{0.1cm}
- For comparison, R API includes "only" 24 random number distributions (see [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Distribution-functions))
\vspace{0.1cm}
\pause
- It's easy to implement additional random number distributions from the GSL base distributions (e.g. truncated normal or inverse gamma distribution)
\vspace{0.1cm}
- Random draws are faster with GSL than with R (eg. `gsl_ran_gamma()` vs. `R::rgamma()`)
\vspace{0.1cm}
\pause
- Examples of functions to generate random sample : `gsl_ran_multivariate_gaussian()`, `gsl_ran_wishart()`, `gsl_ran_dirichlet()`
\vspace{0.1cm}
- Probability density function (`_pdf`), upper or lower cumulative distribution functions (`_Q` or `_P`) and quantile functions (`_Qinv` or `_Pinv`) are also available for each distribution. 

\ecol
\ecols

## RcppArmadillo for high-performance linear algebra

### Armadillo and RcppArmadillo

\bcols
\bcol{0.1\textwidth}
\includegraphics[height=1.4cm]{figs/logo_Armadillo.png}  
\ecol
\bcol{0.9\textwidth}

**Armadillo**
\vspace{0.1cm}

- C++ library for linear algebra and scientific computing

- Provides high-level syntax and functionality: speed and ease of use

- Classes for vectors, matrices and cubes convertible in R vector, matrice and array. 

- Matrix operations (` +, -, *, %`), identify the elements of a matrix that meet a condition (`arma::find(A>0)`), matrix decomposition (`arma::chol()`), linear model solver (`arma::solve(A,B)`), etc.

- <http://arma.sourceforge.net/>

\vspace{0.3cm}

\pause 

**RcppArmadillo**

\vspace{0.1cm}

- Interface between R and Armadillo 

- Using Rcpp to interface R and C++

- <http://dirk.eddelbuettel.com/code/rcpp.armadillo.html>

\ecol
\ecols

### Licenses

- Licenses: GNU General Public License, Apache License 2.0 for Armadillo

- Free software licenses: we can use, modify and redistribute these softwares

# Build of R package using Rcpp

## Useful functions

### How to build an R package around C++ functions 

- `Rcpp.package.skeleton()` to generate a new Rcpp package (modifying `DESCRIPTION` and `NAMESPACE`)
  
- `Rcpp::compileAttributes()` scans the C++ files and generates the `RcppExports.cpp` file to make the functions preceded by `[[Rcpp::export]]` available in R.

- Implement R function that checks the conformity of user-defined parameters, calls functions in C++ and returns the results in an easy-to-use format.

## Example of package using Rcpp

### jSDM R package
\vspace{0.2cm}
\begin{center}
\includegraphics[width=0.9\textwidth, height = 0.65\textheight]{figs/jSDM-website.png}
\end{center}
\vspace{0.2cm}

- <https://ecology.ghislainv.fr/jSDM>
  
- Made with Rcpp, RcppGSL and RcppArmadillo packages