04-manipuler.Rmd

```{R echo = FALSE, warnings = FALSE}
source("include.cpp.r")
includeCppPath <- "../introRcppManipulation/src/"
```

# Manipuler les objets de R en C++

All the examples are in the R package...
Install it with

```{R eval = FALSE, prompt = TRUE}
devtools::install_github("introRcpp/introRcppManipulation")
```

Load it with
```{R}
library(introRcppManipulation)
```

## Premiers objets Rcpp : les vecteurs

La librairie `Rcpp` définit des types `NumericVector`, `IntegerVector`
et `LogicalVector` qui permettent de manipuler en C++ les vecteurs de R.

### Créer des vecteurs, les manipuler

L'initialisation avec la syntaxe utilisée dans `vec0` remplit le vecteur de 0.
Notez l'accès aux éléments d'un vecteur par l'opérateur `[]`; **contrairement
à la convention utilisée par R, les vecteurs sont numérotés de 0 à n-1.** 

```{R echo = FALSE, results = "asis"}
include.cpp("vec.cpp")
```


### Exemple : compter les zéros


```{R echo = FALSE, results = "asis"}
include.cpp("countZeroes.cpp")
```

Comment les performances de cette fonction se comparent-elles avec le code R `sum(a == 0)` ?

```{r prompt = TRUE, comment = NA, fig.width = 5, fig.height = 2, fig.align = 'center', message = FALSE, cache = TRUE}
set.seed(1); a <- sample(0:99, 1e6, TRUE)
countZeroes(a);
sum(a == 0)

mbm <- microbenchmark::microbenchmark( R = sum(a == 0), Cpp = countZeroes(a)) 
mbm
ggplot2::autoplot(mbm)
```

La différence de vitesse d'exécution s'explique en partie par le fait que le
code R commence par créer un vecteur de type `logical` (le résultat de `a == 0`),
puis le parcourt pour faire la somme. Ceci implique beaucoup de lectures écritures
en mémoire, ce qui ralentit l'exécution.


## Vecteurs

### Creating vectors 

On a vu l'initialisation avec la syntaxe `NumericVector R(n)` qui crée
un vecteur de longueur $n$, rempli de $0$. On peut utiliser `NumericVector R(n, 1.0)`
pour un vecteur rempli de $1$ ; **attention à bien taper `1.0` pour avoir un 
`double` et non un `int`; dans le cas contraire, on a un message d'erreur 
difficilement compréhensible à la compilation**.

On peut utiliser `NumericVector R = no_init(n);` pour un vecteur non
initialisé (ce qui fait gagner du temps d'exécution).


```{R echo = FALSE, results = "asis"}
include.cpp("zeros.cpp")
include.cpp("whatever.cpp")
include.cpp("uninitialized.cpp")
include.cpp("favourites.cpp")
```

```{r prompt = TRUE, comment = NA}
zeros(5)
whatever(5, 2L)
uninitialized(5) # sometime 0s, not always
favourites()
```

Comparons les performances des trois premières fonctions (comme
à chaque fois, les résultats peuvent varier d'une architecture 
à l'autre).

```{r prompt = TRUE, comment = NA, fig.width = 5, fig.height = 2, fig.align = 'center', message = FALSE, cache = TRUE}
mbm <- microbenchmark::microbenchmark(zeros(1e6), whatever(1e6, 0), uninitialized(1e6))
mbm
ggplot2::autoplot(mbm)
```

### Accessing elements

Using `x.size()` or `x.length()`.
Beware O-based indices.

BLA BLA

### Missing data

Cette fonction utilise `IntegerVector::is_na` qui est la bonne manière de 
tester si un membre d'un vecteur entier est `NA`.


```{R echo = FALSE, results = "asis"}
include.cpp("countNAs.cpp")
```

Une nouveauté : le fichier `countNAS.h` ...

```{R echo = FALSE, results = "asis"}
include.cpp("countNAs.h")
include.cpp("getNonNAs.cpp")
```


Comparons ces deux fonctions avec leurs analogues R, `sum(is.na(x))` et `x[!is.na(x)]`.

```{r prompt = TRUE, comment = NA, fig.width = 5, fig.height = 2, fig.align = 'center', message = FALSE, cache = TRUE}
x <- sample( c(NA, rnorm(10)), 1e6, TRUE)
mbm <- microbenchmark::microbenchmark( sum(is.na(x)), countNAs(x), x[!is.na(x)], getNonNAs(x) )
mbm
ggplot2::autoplot(mbm)
```
 

## Vecteurs nommés

Ça n'est pas passionnant en soi (on ne manipule pas si souvent des
vecteurs nommés), mais ce qu'on voit là sera utile pour les listes
et les data frames.

### Créer des vecteurs nommés 
Voici d'abord comment créer un vecteur nommé.

```{R echo = FALSE, results = "asis"}
include.cpp("createVec1.cpp")
```

Application :
```{r prompt = TRUE, comment = NA}
a <- createVec1()
a
```

Une syntaxe plus dense est possible :

```{R echo = FALSE, results = "asis"}
include.cpp("createVec2.cpp")
```

Cela produit le même résultat.

```{r prompt = TRUE, comment = NA}
createVec2()
```

### Accéder aux éléments par leurs noms

On utilise toujours la syntaxe `x[]` :

```{R echo = FALSE, results = "asis"}
include.cpp("getOne.cpp")
```

Notez la fonction `Rcpp::stop` qui correspond à la fonction R du même nom.

```{r prompt = TRUE, comment = NA, error = TRUE}
getOne(a)
getOne(b)
```


### Obtenir les noms d'un vecteur 

Et voici comment obtenir les noms d'un vecteur.

```{R echo = FALSE, results = "asis"}
include.cpp("names1.cpp")
```

Utilisons cette fonction:
```{r prompt = TRUE, comment = NA, error = TRUE}
names1(a)
```

Cette fonction semble se comporter correctement, elle a cependant un gros
défaut. Nous y reviendrons dans la section suivante.

## Objets génériques : SEXP

Les objets R les plus génériques sont les `SEXP`, « S expression ». Les principaux types de `SEXP`
sont illustrés par la fonction suivante.

```{R echo = FALSE, results = "asis"}
include.cpp("RType.cpp")
```

Utiliser les types définis par Rcpp est généralement plus
facile et plus sûr. Cependant à l'intérieur des fonctions Rcpp ils peuvent 
être utiles, par exemple dans le cas où une fonction peut renvoyer des objets
de types différents, par exemple soit un `NILSXP`, soit un objet d'un autre type.

### Exemple : vecteurs nommés (ou pas)

Testons à nouveau la fonction `names1`, en lui passant un vecteur non nommé.

```{r prompt = TRUE, comment = NA, error = TRUE}
b <- seq(0,1,length=6)
names1(b)
```

Bien sûr, le vecteur `b` n'a pas de noms ; la fonction `x.names()` a renvoyé 
l'objet `NULL`, de type `NILSXP`, qui ne peut être utilisé pour 
initialiser le vecteur `R` de type `STRSXP`.
Une solution est d'attraper le
résultat de `x.names()` dans un `SEXP`, et de tester son type
avec `TYPEOF`.

```{R echo = FALSE, results = "asis"}
include.cpp("names2.cpp")
```

```{r prompt = TRUE, comment = NA, error = TRUE}
names2(a)
names2(b)
```


### Exemple : énumerer les noms et le contenu

On va utiliser l'opérateur `CHAR` qui, appliqué à un élément
d'un `CharacterVector`, renvoie une valeur de type `const char *` 
c'est-à-dire un pointeur vers une chaîne de caractère (constante,
ie non modifiable) « à la C » (voir chapitre dédié).

```{R echo = FALSE, results = "asis"}
include.cpp("enumerate.cpp")
```

```{r prompt = TRUE, comment = NA}
enumerate(a)
```

## Facteurs

```{R echo = FALSE, results = "asis"}
include.cpp("getLevels.cpp")
```

```{r prompt = TRUE, comment = NA}
x <- factor( sample(c("M","F"), 10, TRUE) )
getLevels(x)
x <- sample(1:2, 10, TRUE)
# getLevels(x)
attr(x, "levels") <- c(0.1, 0.4)
# getLevels(x)
```

```{R echo = FALSE, results = "asis"}
include.cpp("someFactor.cpp")
```

```{r prompt = TRUE, comment = NA}
someFactor()
```

## Listes et Data frames

Nous avons déjà vu les fonctions utiles dans le cas des vecteurs nommés, en particulier 
`containsElementNamed`. 

La fonction suivante prend une liste `L` qui a un élément `L$alpha` de type `NumericVector`
et renvoie celui-ci à l'utilisateur. En cas de problème un message d'erreur informatif
est émis.

```{R echo = FALSE, results = "asis"}
include.cpp("getAlpha.cpp")
```

Pour renvoyer des valeurs hétéroclites dans une liste c'est très facile:

```{R echo = FALSE, results = "asis"}
include.cpp("createList.cpp")
```
```{r prompt = TRUE, comment = NA}
createList()
```

Les data frames, ont l'a vu, sont des listes avec quelques attributs supplémentaires.
En Rcpp cela fonctionne de la même façon, avec la classe `DataFrame`.
Ils ont une certaine tendance à se transformer en liste quand on leur ajoute des
éléments.

Here is a useful trick.


```{R echo = FALSE, results = "asis"}
include.cpp("createDF.cpp")
```
```{r prompt = TRUE, comment = NA}
createDF()
```