Fiche_targets.qmd

# Construire une chaîne de traitement reproductible avec `targets` {#targets}

```{r}
#| include: false
knitr::opts_knit$set(root.dir = '..')
```

```{r entree_fiche_targets, message=FALSE, warning=FALSE, echo=FALSE, cache=FALSE, eval=TRUE}
library(targets)
```

## Tâches concernées et recommandations

L'utilisateur souhaite automatiser une chaîne de traitement complexe afin de la rendre reproductible et rapide à exécuter en cas de modification.

::: {.callout-important}
## Tâche concernée et recommandation

Le *package* `targets` permet de construire simplement une chaîne de traitement reproductible.

Les deux éléments suivants sont à prendre en considération :

- ce *package* ne sera approprié que si la chaîne de traitement
est exclusivement écrite en `R` ;
- il est fortement recommandé de savoir créer des fonctions, afin de modulariser
le code.

:::

## Pourquoi utiliser `targets` ?

Le *package* `targets` peut être particulièrement intéressant : 

* dans le cadre du développement d'un prototype ayant vocation à devenir une chaîne de production
pérenne écrite avec `R` ;
* dans le cas d'un projet d'étude qui vise à une forte reproductibilité.

Plus précisément, utiliser `targets` pour un projet permet de :

1. Viser la __reproductibilité__
de l'ensemble des étapes de traitement,
tout en réduisant au strict nécessaire la répétition de ces étapes, parfois longues ;
2. Adopter des __bonnes pratiques__ de développement en `R` par l'usage
(modulariser le code, décomposer ses traitements par étapes,
assurer la lisibilité des étapes successives du traitement...)
3. Représenter __sous forme de *pipeline*__ les étapes de sa chaîne
de traitement et leurs dépendances à partir d'une technique de
graphiques directionnels asynchrones (appelés *DAG* pour l'acronyme anglais
dans la sphère informatique)
4. Faciliter la prise en main par une autre personne
grâce à une __organisation standardisée des codes__
et à une description complète de l'enchaînement des étapes intégrée
dans le code lui-même.

::: {.callout-note}

Le [guide des bonnes pratiques `utilitR`](https://www.pratiques.utilitr.org/)
devrait prochainement s'enrichir d'éléments concernant la gestion de
_pipelines_ de données en `R` et en `Python`. 

Les premiers éléments du débat sont disponibles sur 
[l'issue #388](https://github.com/InseeFrLab/utilitR/issues/388)
dans le dépôt `Github` d'`utilitR`.

:::


## Quelles sont les tâches automatisées par `targets` ?

`targets` permet de définir et d'exécuter une chaîne de traitement avec :

* Sauvegarde automatique de résultats intermédiaires, ce qu'on appelle les
_"targets"_ (cibles)
* Traçabilité de ces résultats intermédiaires par `targets`:
lors de la répétition d'une exécution de la chaîne de traitement,
ils ne sont mobilisés que si ils sont reproductibles.
* Si une fonction ou un _input_ nécessaire au calcul d'une _"target"_
est modifié, `targets` repère automatiquement les étapes à reconduire,
et seulement celles-ci. 

Ainsi, le lancement du traitement et la vérification de la reproductibilité
sont effectués ensemble au cours du développement du
projet par l'appel de `tar_make()`.

__Vérifier la reproductibilité revient ainsi à ne pas 'tout relancer' de 0__ !
Ceci représenterait un coût trop élevé.
`targets` automatise le travail d'aller-retour dans les étapes d'une étude ou
de prototypage
(j'ai modifié l'étape 1, il faut donc que je relance l'étape 2 qui en dépend...),
en construisant un graphe des dépendances des différentes étapes du traitement.

Pour la suite de la fiche,
prenons l'exemple d'une étude qui se structurerait suivant les étapes suivantes :

0. Charger les données
1. Traiter les données
2. Produire des résultats
3. Représenter des résultats


## Un projet minimal pour comprendre l'essentiel

### Structure du projet

Un projet `targets` est un projet `R` en règle générale structuré de la sorte :

* un fichier `_targets.R` décrivant les éléments de configuration (par exemple
_packages_ utilisés) et l'enchaînement des traitements
* un dossier `R` comprenant les scripts définissant les fonctions utilisées par le projet
* un dossier `data` pour les données externes (non générées au cours du projet)

L'architecture des dossiers du projet ressemble par conséquent à ceci :

```
├── _targets.R
├── R/
├───── mesfonctions_pour_faire_ceci.R
├───── mesfonctions_pour_faire_cela.R
├──── ...
├── data/
├───── donnees_entrees.csv
└───── ...
```

::: {.callout-tip}

Organiser ses fichiers de cette façon est très commun,
mais pas indispensable pour l'utilisation de `targets`.
La seule obligation est que le fichier `_targets.R`
soit positionné dans le répertoire de travail.

Une manière commode pour un utilisateur souhaitant utiliser `targets`  est donc de créer un [projet RStudio](rproject.html) à la racine duquel il place ce fichier.
En prévision des futures fonctions qu'il va écrire, il crée un dossier `R/`. Le fichier `_targets.R` détaille l'enchaînement des traitements.
Il doit toujours contenir une instruction chargeant le *package* `targets`.

:::

### Premier exemple

```{r, include = FALSE}
# move in root dir
file.copy("resources/targets/_targets.R", "_targets.R", overwrite = TRUE)
file.copy("resources/targets/mesfonctions_pour_faire_ceci.R", "mesfonctions_pour_faire_ceci.R", overwrite = TRUE)
```

Partons d'un exemple simple : 

- on lit les données de population depuis un fichier CSV ;
- on a créé une fonction pour ne garder que les communes de plus
de 200 000 habitants ;
- sur ces communes, on désire connaître la proportion dont le revenu
médian est supérieur à 25 000 euros.

La chaîne de traitement est donc ici linéaire. Chaque étape dépend
de la précédente et uniquement de celle-ci. Le fichier d'instruction
`_targets` prendra alors la forme suivante:

```{r eval=FALSE, code=readLines('_targets.R'), cache=FALSE}
```

Les fonctions écrites par l'analyste et utilisées dans la chaîne de traitement
(en l'occurrence `garde_grandes_villes`) sont contenues dans les fichiers que l'on _"source"_ au départ,
ici depuis un script `"mesfonctions_pour_faire_ceci.R`. 

Les _packages_ utilisés dans les traitements sont définis via la fonction
`tar_option_set` du *package* `targets`. Ici, on a besoin des 
_packages_ `dplyr` et `readr` dans notre chaîne de traitement.

La chaîne de traitement est représentée par une liste de `tar_target`,
soit les objets `R` qui sont les cibles intermédiaires de l'analyse.
Ils sont le résultat de l'application à une cible précédente d'une fonction pour obtenir la cible suivante :

1. Ici la première cible est particulière (`format = file`) : on spécifie où sont les données d'entrée afin de surveiller si elles changent.
2. La seconde prend en entrée la première cible `data_file` et la transforme en appliquant la fonction `readr::read_csv` en un nouvel objet R, `raw_filosofi_epci`. Il s'agit ainsi des données brutes après l'import
dans `R`, avant toute modification
3. La troisième applique cette fois une fonction écrite par l'utilisateur à `raw_filosofi_epci` pour obtenir `grandes_villes`, et ainsi de suite...

Ainsi, le fichier `_targets.R` contient la description de
l'ensemble des étapes du traitement.
La complexité des traitements est résumée de façon concise
par un ensemble minimal de fonctions résumant les grandes étapes.
Afin de faire tourner l'analyse,
l'utilisateur fait appel au sein du projet à la fonction `tar_make()`.
Il s'agit de la fonction qu'un utilisateur du package `targets`
utilisera le plus fréquemment.
L'utilisateur est informé de l'évolution des calculs.

```{r}
tar_make()
```

Lorsque la chaîne de traitement est de taille relativement
modeste (comme ici), on peut la visualiser avec la fonction
`tar_visnetwork`:

```{r, echo = FALSE}
#| eval: false
tar_visnetwork(targets_only = TRUE, reporter = "silent")
```

```{r, eval = FALSE}
tar_visnetwork()
```

On obtient bien un diagramme linéaire comme
on en avait l'intuition. 

::: {.callout-note}

Il est tout à fait possible de stocker l'ensemble des 
cibles intermédiaires dans un emplacement différent
du projet. Il s'agit même d'une bonne pratique de
séparer le lieu de stockage du code de celui des données. 

Il sera nécessaire d'éditer les options
de la chaîne dans le fichier `_targets.R`. Par exemple 
avec cette ligne de commande, au début du fichier
`_targets.R` (mais après l'appel à `library(targets)`:

```{r, eval  = FALSE}
tar_config_set(store = "mon_dossier_donnees/projet-toto")
```
:::


### Modification d'une étape intermédiaire

L'utilisateur décide ensuite de modifier la définition 
des grandes villes considérées. Supposons qu'il
ajoute un argument à la fonction `garde_grandes_villes`
pour ne garder que celles dont la population est supérieure
à `seuil`. Dans le fichier `_targets.R`, il est
nécessaire de changer
la définition de l'étape de définition de 
`grandes_villes`. Cela amènera à une 
chaîne ayant la structure suivante

```{r, include = FALSE}
# move in root dir
file.copy("resources/targets/_targets_mod2.R", "_targets.R", overwrite = TRUE)
file.copy("resources/targets/mesfonctions_pour_faire_ceci.R", "mesfonctions_pour_faire_ceci.R", overwrite = TRUE)
```

```{r eval=FALSE, code=readLines('_targets.R'), cache=FALSE}
```

Ici, le _pipeline_ est de taille relativement modeste et il
est facile d'identifier la source de modification. Néanmoins,
la représentation sous forme de diagramme peut aider à mieux
s'en rendre compte

```{r, echo = FALSE}
#| eval: false
tar_visnetwork(targets_only = TRUE, reporter = "silent")
```

```{r, eval = FALSE}
tar_visnetwork()
```


La modification de la fonction `garde_grandes_villes`
entraîne la nécessaire mise à jour de `grandes_villes`
et toutes les cibles qui en dépendent, mais pas du début de la chaîne de traitement !

`targets` va ainsi intelligemment utiliser ceci pour minimiser
le temps nécessaire pour mettre à jour l'ensemble de la chaîne
de traitement

```{r}
tar_make()
```

Les cibles définies sont calculées successivement, stockées et mises à jour automatiquement dans un dossier `_targets/objects/`.

### Accéder à des éléments du pipeline dans une session `R`

On peut facilement accéder à un objet cible, quel que soit son
emplacement dans la chaîne de traitement, puisque chaque
cible est stockée sous la forme d'un fichier temporaire. 

La fonction `tar_load` permet de charger dans l'environnement
`R` l'objet en question. Par exemple, si on désire tester
des choses sur `grandes_villes`, on pourra utiliser la commande
suivante

```{r}
tar_load(grandes_villes)
head(grandes_villes)
```

Cela permettra à l'utilisateur de `targets` de prototyper une 
nouvelle étape de traitement dans sa session `R` puis,
une fois satisfait, la mettre en production en mettant les
fonctions dans le fichier `XXXXX.R` et en créant l'étape
`tar_target` adéquate. 


::: {.callout-tip}

Par défaut, les cibles sont stockées
au format `rds`. Ce format présente
deux inconvénients :

- il est spécifique à `R` et ne permet
pas de lire les étapes intermédiaires
dans un autre langage (par exemple `Python`) ;
- la sérialisation des objets `R` nécessaire
pour écrire sous format `rds` ou lire un tel fichier
est assez lente. 

Il est conseillé d'utiliser
un autre format de stockage
des cibles.

En premier lieu, le format par défaut qui peut être utilisé est le
format [qs](https://cran.r-project.org/web/packages/qs/index.html).
À l'instar du format `rds`, celui-ci est spécifique à `R` mais
présente l'avantage d'être beaucoup plus rapide en termes de temps en lecture/écriture.
Pour cela, il convient d'ajouter la ligne suivante
au début des options du fichier `_targets.R` :

```{r, eval = FALSE}
tar_option_set(format = "fst_dt")
```

Pour les dataframes, il est possible d'utiliser
des formats plus universels ou plus 
appropriés. Les formats à privilégier sont
les suivants:

- `parquet`: format qui tend à devenir un standard dans le monde
de la science des données. Ce format présente plusieurs avantages,
parmi lesquels le fait qu'il est
très compressé, très rapide et qu'il conserve
les métadonnées du fichier ce qui permet, à la différence
des formats type CSV, de conserver l'intégrité des typages des colonnes 
(voir la fiche [Importer des fichiers parquets](#importparquet) pour plus
de détails) ;
- `fst_tbl` (utilisateurs du tidyverse) ou `fst_dt` (utilisateurs de data.table) :
formats spécifiques à `R` présentant des avantages proches de ceux d'un fichier
`parquet`. Ils préservent la nature d'un data.frame, ce qui permet de
repartir d'un tibble ou d'un datatable sans avoir à faire de conversion
à chaque étape du *pipeline*.

Le choix du format de stockage d'un objet se fait directement
lors de la déclaration de la cible dans `_targets.R`:

```{r, eval = FALSE}
tar_target(
    grandes_villes, garde_grandes_villes(raw_filosofi_epci),
    format = "parquet"
)
```

Dans le dossier `_targets/object`, le fichier sera ainsi stocké au 
format exigé. 

Il n'est pas recommandé d'utiliser les formats `parquet`, `fst_dt` ou
`fst_tbl` par défaut car ils ne permettent de stocker que des 
dataframes. Or, un _pipeline_ peut stocker des objets de nature
beaucoup plus diverses (listes, objets ggplot, etc.)

:::


::: {.callout-note}

L'utilisation du _garbage collector_ peut
parfois s'avérer utile pour nettoyer la 
mémoire de la session `R` dans laquelle
tourne le _pipeline_. Ceci est
particulièrement utile lorsque les
objets manipulés sont volumineux (voir
la fiche [Superviser sa session R](https://book.utilitr.org/01_r_insee/fiche_utiliser_ressources)).

Dans `targets`, cette opération est possible en ajoutant
l'argument `garbage_collection = TRUE` à la définition de
la cible :

```{r, eval = FALSE}
tar_target(
    grandes_villes, garde_grandes_villes(raw_filosofi_epci),
    garbage_collection = TRUE
)
```

:::


## Intégrer un rapport en Rmarkdown

L'un des principaux gains à utiliser `targets` est 
dans la fiabilisation du processus de production
de fichiers markdown à l'issue d'une chaîne de
traitement. 

Deux philosophies existent pour produire un 
fichier reproductible dans une chaîne de traitement :

- Intégrer directement le fichier à la chaîne
comme une étape finale du processus
de production. Cela revient à produire le `RMarkdown`
via un `tar_target` particulier ;
- Exécuter la chaîne de traitement, ou les parties nouvelles
de la chaîne de traitement, directement depuis le fichier `RMarkdown`.
Dans ce cas, le fichier `.Rmd` n'est plus exécuté depuis le `_targets.R`
mais au contraire sert à l'exécuter.

### Concevoir un rapport en sortie de chaîne de traitement

Le *package* `tarchetypes` est un complément utile.
Ce *package* permet d'intégrer simplement des rapports `Rmarkdown`
dans la pipeline avec `tarchetypes::tar_render()`.
L'essentiel des calculs doit être en amont du rapport markdown,
qui doit être rapide à exécuter. 

Par exemple, on peut écrire un Rmarkdown `report.Rmd` considéré comme une des
cibles de l'analyse (par exemple, c'est le compte-rendu de l'analyse), et qui
dépend d'autres cibles.
On souhaite également qu'il soit reproductible,
et mis à jour automatiquement en fonction des modifications
sur les cibles dont il dépend. 

Il suffit d'intégrer ces cibles via `tar_read(data)` ou `tar_load(data)` appelé
dans un chunk du `.Rmd`, et de spécifier un `_targets.R` sur le modèle suivant :

```{r, eval=FALSE}
# Fichier _targets.R
# report.Rmd est présent dans le projet.
library(targets)
library(tarchetypes)

list(
  tar_target(data, data.frame(a = seq(2,9), b = seq(2,9))),
  tar_render(report, path = 'report.Rmd')
)

```

### Utiliser des objets issus d'une chaîne de traitement dans un `R Markdown`

Cette méthode est particulièrement appropriée lorsqu'on 
désire prototyper un rapport en utilisant un ou plusieurs
objets de la chaîne de traitement.

Plus d'éléments sont disponibles [dans la documentation officielle](https://books.ropensci.org/targets/literate-programming.html#target-markdown)

## Les branches

Souvent, les cibles d'une analyse (étapes intermédiaires) sont nombreuses et ont un certain degré de redondance. 

Comment créer des cibles automatiquement (sans écrire explicitement dans
`_targets.R` chacune d'entre elles) ? `targets` propose de décliner les cibles
en _"branches"_.

On distingue :

* les branches définies dynamiquement : avant l'exécution, le nombre de branches est inconnu ;
* les branches définies statiquement : le nombre de branche est défini précisément avant l'exécution.

Le premier cas correspond à la répétition d'un grand nombre de tâches homogènes,
le second plutôt à un petit nombre de tâches hétérogènes.

::: {.callout-note}

Les branches statiques, qui nécessitent l'usage du package `tarchetypes`,
ne sont pas abordées ici.

:::

### Les branches dynamiques

Certaines cibles peuvent être le résultat de l'application d'une même fonction à des variantes d'arguments
(par exemple, un graphique de restitution pour plusieurs populations d'intérêt).

Pour cela, `targets` propose les _branches dynamiques_. 

### Un exemple

Voici un exemple minimal de pipeline qui va itérer sur _N_ couples d'arguments
une même _"simulation"_, en évitant de créer _N_ cibles distinctes pour les _N_ 
résultats, et plutôt créer une seule cible résultats qui donnera lieu à autant
de branches que de _"simulations"_ : 

```{r, eval=FALSE}
#_targets.R
library(targets)

simulation <- function(x, y) x * y

list(
  tar_target(x, c(10, 20, 30)),
  tar_target(y, c(1, 2, 3)),
  tar_target(
    resultat,
    data.frame(argument_1 = x, argument_2 = y, res = simulation(x, y)),
    pattern = map(x, y))
)
```


Ce qui distingue ici la cible `resultat`  de ce qui a été vu précédemment, c'est
l'utilisation de l'argument `pattern`, qui a vocation à itérer sur les vecteurs
cibles `x`  et `y` grâce à `map`.

Dans la console `R`, l'utilisateur qui fait appel à `tar_make()`
voit apparaître la déclinaison de `resultat` en trois branches,
exécutées en parallèle.

```{r, eval=FALSE}
tar_make()
```
```
● run target x
● run target y
● run branch resultat_1851c9ee
● run branch resultat_445bc859
● run branch resultat_1a0263ff
● end pipeline
```
On obtient le résultat suivant:
```{r, eval=FALSE}
tar_read(resultat)
```
```
argument_1 argument_2 res
1         10          1  10
2         20          2  40
3         30          3  90
```


### Itérer, croiser les arguments pour créer des branches

Les patterns peuvent être de plusieurs types : `map` (itérer sur les arguments ligne à ligne), `cross` (produit cartésien des arguments), `head` (pour récupérer les premiers arguments), `select` (pour récupérer certains arguments) ...

Par exemple, remplacer `map` par `cross` dans la pipeline précédente donne lieu après un `tar_make()` à 

```
✓ skip target x
✓ skip target y
✓ skip branch resultat_1851c9ee
● run branch resultat_cca1045b
● run branch resultat_3b73d14e
● run branch resultat_fe2f6b6a
✓ skip branch resultat_66951ce8
● run branch resultat_ff612dde
● run branch resultat_d0a65303
● run branch resultat_0a18e8b1
✓ skip branch resultat_7fd56d9a
● end pipeline
```

Plutôt que d'appliquer la fonction simulation itérativement
aux couples d'`x` et `y` (3 branches),
la fonction est appliquée au produit cartésien de `x` et `y` (3 x 3 branches).
On remarque d'ailleurs que `targets` a compris que cela ne changeait pas
certains résultats précédents (3 branches strictement identiques, qui ne sont
pas recalculées).

```{r, eval=FALSE}
tar_read(resultat)
```
```
argument_1 argument_2 res
1         10          1  10
2         10          2  20
3         10          3  30
4         20          1  20
5         20          2  40
6         20          3  60
7         30          1  30
8         30          2  60
9         30          3  90
```

Les *pattern* peuvent être combinés, avec par exemple `pattern = cross(x, map(y, z))`.

```{r, eval=FALSE}
#_targets.R
library(targets)

simulation <- function(x, y, z) x * y + z

list(
  tar_target(x, c(10, 20, 30)),
  tar_target(y, c(1, 2, 3)),
  tar_target(z, c(2, 4, 6)),
  tar_target(
    resultat,
    data.frame(argument_1 = x, argument_2 = y, argument_3 = z, res = simulation(x, y, z)),
    pattern = cross(x, map(y, z)))
)
```

qui donne le résultat :

```
argument_1 argument_2 argument_3 res
1         10          1          2  12
2         10          2          4  24
3         10          3          6  36
4         20          1          2  22
5         20          2          4  44
6         20          3          6  66
7         30          1          2  32
8         30          2          4  64
9         30          3          6  96
```

Si l'on souhaite itérer sur des listes, plutôt que sur des vecteurs,
on peut spécifier à la création de la cible qui sert d'argument aux branches,
par exemple une liste de `data.frames`, que l'on veut itérer sur les éléments
`"list"`.

```{r, eval=FALSE}
#_targets.R
library(targets)

#' Multiplie la colonne "a" de df par un facteur
#' @param: df: data.frame
#' @param: factor: int
multiply <- function(df, factor){
  df$a <- df$a * factor
  df
}

list(
  tar_target(x, list(data.frame(name = c('Marie','Marwan'), a = c(1, 2)),
                     data.frame(name = c('Bill','Boule'), a = c(2, 4))), iteration = 'list'),
  tar_target(y, c(2, 3)),
  tar_target(
    resultat,
    multiply(x, y),
    pattern = map(x, y))
)
```

Etc...

## Pour en savoir plus

* [Manuel d'utilisation de `targets`](https://books.ropensci.org/targets/)
* [Organiser un projet avec `targets`](https://juba.github.io/tidyverse/21-targets.html), une chapitre de _Introduction à R et au tidyverse_ de Julien Barnier
* [_High Performance Computing avec `targets`_](https://books.ropensci.org/targets/hpc.html)
* Landau, W. M., (2021). The targets R package: a dynamic Make-like function-oriented pipeline toolkit for reproducibility and high-performance computing. _Journal of Open Source Software_, 6(57), 2959, https://doi.org/10.21105/joss.02959 
* [Vidéo de présentation de `targets` par Will Landau au meetup R Lille de juin 2021](https://www.youtube.com/watch?v=FODSavXGjYg&t=598s)
* https://cran.r-project.org/web/packages/targets/targets.pdf 
* https://docs.ropensci.org/tarchetypes/ 
* Un exemple https://github.com/InseeFrLab/lockdown-maps-R/ 
* Les "target factories": https://wlandau.github.io/targetopia/contributing.html 
* Un tutoriel de Noam Ross présentant l'usage de `targets` avec un système de stockage de type AWS (similaire au principe du `SSPCloud`): https://github.com/noamross/targets-minio-versioning