1 Notes techniques et choix éditoriaux

Nous décrivons ici les choix pédagogiques, le style et les décisions éditoriales spécifiques prises lors de l’écriture de ce guide.

1.1 Approche et style

Le public visé par ce manuel est large. Nous espérons qu’il sera utile aux épidémiologistes novices en R, mais aussi aux utilisateurs expérimentés à la recherche de bonnes pratiques et d’astuces. L’ouvrage doit donc être à la fois accessible et succinct. Notre cherchons à fournir juste assez d’explications textuelles pour qu’une personne débutante en R puisse appliquer le code et comprendre ce qu’il fait.

En conséquences de quoi, ce guide est :

un ouvrage de référence de code, accompagné d’exemples relativement brefs, et non un manuel complet sur R ou la science des données
un guide R à utiliser dans le cadre de l’épidémiologie appliquée, et non un manuel sur les méthodes ou la science de l’épidémiologie appliquée
un document évolutif : les paquets R optimaux pour une tâche donnée changent souvent et nous sommes ouverts à toute discussion sur les paquets à privilégier dans ce manuel.

Paquets R

Tellement de possibilités…

Un aspect difficile de l’apprentissage de R est de savoir quel paquet R utiliser pour une tâche donnée. Il n’est pas rare que l’on se décarcasse à écrire vingt (cent ?) lignes de code, pour se rendre compte plus tard qu’il existe un paquet R qui donne le même résultat recheré en une seule ligne de commande !

Dans ce guide, nous essayons de vous proposer au moins deux façons de réaliser chaque tâche : une méthode éprouvée (probablement dans R de base ou utilisant le tidyverse) et un paquet R spécialement conçu à cet effet. Nous voulons que vous ayez les deux options, au cas où vous ne pourriez pas télécharger un paquet donné ou si celui-ci ne vous convient pas.

Pour choisir les paquets à utiliser, nous avons donné la priorité aux paquets R et aux approches qui ont été testés et approuvés par la communauté, qui minimisent le nombre de paquets utilisés dans une session de travail typique, qui sont stables (ne changent pas très souvent) et qui accomplissent la tâche simplement et proprement.

Ce manuel donne généralement la priorité aux paquets et fonctions R du méta-paquet tidyverse. Tidyverse est une collection de paquets R conçus pour la science des données, et qui partagent une grammaire et des structures de données sous-jacentes. Tous les paquets du Tidyverse peuvent être installés ou chargés séparément, ou en masse via le paquet tidyverse. Pour en savoir plus, consultez le site Web du tidyverse.

Nous proposons également souvent des options de code utilisant R de base (les paquets et fonctions fournis avec R à l’installation). En effet, nous sommes conscients que certains lecteurs de ce livre ne disposent pas d’un accès Internet fiable pour télécharger des paquets supplémentaires.

Expliciter quelle fonction appartient à quel paquet

Il est souvent frustrant lorsque l’on suit un tutoriel R de ne pas savoir de quel paquet provient une fonction (et donc de ne pas pouvoir l’utiliser immédiatement dans notre code) !

Dans ce guide, les noms des paquets seront écrits en gras (par exemple dplyr) et les fonctions sont écrites comme ceci : mutate(). Nous nous efforçons d’être explicites quant au paquet dont provient une fonction, soit en faisant référence au paquet dans le texte voisin, soit en spécifiant le paquet explicitement dans le code, comme ceci : dplyr::mutate(). Cela alourdit un petit peu le code, mais rend plus facile la réutilisation du code chez vous.

Consultez la page sur les Bases de R pour en savoir plus sur les paquets et les fonctions.

Choix d’yn style de code

Dans le manuel, nous allons fréquemment à la ligne, ce qui rend notre code “long”. Nous faisons cela pour plusieurs raisons :

cela permet d’écrire des commentaires explicatifs avec # adjacents à la commande qu’ils décrivent,
généralement, un code plus long (vertical) est plus facile à lire,
il est plus facile à lire sur un écran étroit (pas de défilement latéral nécessaire),
il est plus facile de savoir quels arguments appartiennent à quelle fonction grâce aux indentations.

Par conséquent, un bout de code code qui pourrait être écrit comme ceci :

linelist %>% group_by(hospital) %>%  # groupe les lignes par hopital
  slice_max(date, n = 1, with_ties = F) # s'il y a égalité de date, prendre la première

…est écrit comme cela :

linelist %>% 
  group_by(hospital) %>% # groupe les lignes par hopital
  slice_max(
    date,                # Garde les lignes avec la date maximun à l'intérieur de chaque groupe
    n = 1,               # Ne garder que la date maximum
    with_ties = F)       # S'il y a égalité de date, prendre la première

Le code R n’est généralement pas affecté par les nouvelles lignes ou les indentations. Lorsque vous écrivez dans Rstudio (ou un éditeur décent), l’indentation se fera automatiquement lorsque vous allez à la ligne après une virgule.

Nous utilisons beaucoup d’espaces (par exemple n = 1 au lieu de n=1) parce que c’est plus facile à lire pour beaucoup de personnes. Pensez aux gens qui lisent votre code !

Nomenclature

Dans ce manuel, nous faisons généralement référence aux “colonnes” et aux “lignes” plutôt qu’aux “variables” et “observations”. Comme l’explique cette introduction aux “données ordonnées”, la plupart des jeux de données statistiques épidémiologiques se composent structurellement de lignes, de colonnes et de valeurs.

Les variables contiennent les valeurs qui mesurent le même attribut sous-jacent (comme le groupe d’âge, le résultat ou la date d’apparition des symptomes). Les observations contiennent toutes les valeurs mesurées sur la même unité (par exemple, une personne, un site ou un échantillon de laboratoire). Ces aspects peuvent donc être plus difficiles à définir de manière tangible.

Dans les ensembles de données “ordonnés” (tidy data en anglais), chaque colonne est une variable, chaque ligne est une observation et chaque cellule est une valeur unique. Cependant, certains jeux de données que vous rencontrerez ne correspondront pas à ce modèle - un ensemble de données au format “large” peut avoir une variable répartie sur plusieurs colonnes (voir un exemple à la page Transformation long-large). De même, les observations peuvent être réparties sur plusieurs lignes.

La majeure partie de ce manuel porte sur le nettoyage et la transformation des données, et il est donc plus pertinent de se référer aux structures de données concrètes que sont les lignes et les colonnes qu’aux observations et aux variables plus abstraites. Les exceptions se produisent principalement dans les pages sur l’analyse des données, où vous verrez davantage de références aux “variables” et aux “observations”.

Notes

Voici les types de notations utilisées dans le guide :

NOTE: Ceci est une note
TIP: Ceci est un conseil ou une astuce.
CAUTION: Ceci vous invite à bien prêter attention.
DANGER: Ceci est un avertissement.

1.2 Choix techniques

Ci-dessous, nous décrivons les principales décisions concernant le choix des paquets et des fonctions. Si vous n’êtes pas d’accord ou si vous souhaitez proposer un nouvel outil à examiner, veuillez rejoindre/démarrer une conversation sur notre page Github.

Tableau des paquets, fonction et autres choix techniques

Sujet	Considéré	Choisi	Explication brève
Approche générale	tidyverse, data.table, base	tidyverse, avec un chapitre sur data.table, et mentions d’alternatives en R de base pour les lecteurs avec une connexion Internet faible	lisibilité accrue, universel, paquets très répandus
Importation des paquets	`library()`,`install.packages()`, `require()`, pacman	pacman	Simplification et code plus court pour les cas avec de nombreux paquets à installer puis importer
Import et export de données	rio, de nombreux paquets spécialisés	rio	Gère un grand nombre de format de jeux de données
Résumer des données agrégées	dplyr `group_by()`, stats `aggregate()`	dplyr `group_by()`	Reste cohérent avec nos choix d’utiliser le tidyverse
Transformation long-large	tidyr (fonctions `pivot_XXX`), reshape2 (melt/cast), tidyr (spread/gather)	tidyr (fonctions `pivot_XXX`)	reshape2 est en fin de vie (recommandations officielles d’utiliser tidyr), tidyr utilise les fonctions `pivot_XXX` dès la versions v1.0.0
Nettoyer les noms des colonnes	matchmaker, janitor	janitor	Janitor est utilisé pour plusieus tâches dans le guide (optimisation des paquets)
Semaines epi	lubridate, aweek, tsibble, zoo	lubridate en général, avec utilisation ponctuelle d’autres paquets pour des cas spécifiques	La grande flexibilité de lubridate, la cohérence avec le tidyverse, une meilleure maintenance future (?)
Labels ggplot	`labs()`, `ggtitle()`/`ylab()`/`xlab()`	`labs()`	Simplicité, tous les labels dans la même commande
Conversion en facteur	`factor()`, forcats	forcats	différentes fonctions pour transformer les facteurs dans la même commande
Courbes épidémiques	incidence, ggplot2, EpiCurve	incidence2 pour le plus rapide, ggplot2 pour les détails	fiabilité
Concaténation	`paste()`, `paste0()`, `str_glue()`, `glue()`	`str_glue()`	syntaxe plus simple que `paste()`; dans stringr

1.3 Révisions majeures

Date	Changements majeurs
10 Mai 2021	Publication de la version 1.0.0
20 Nov 2022	Publication de la version 1.0.1

NEWS Avec la version 1.0.1, les changements suivants ont été mis en œuvre :

Mise à jour vers la version 4.2 de R
Nettoyage des données : remplacement de {linelist} par {matchmaker}, suppression d’une ligne inutile dans l’exemple case_when().
Dates : remplacement de {linelist} guess_date() par {parsedate} parse_date().
Pivot : légère mise à jour de pivot_wider()id_cols=`.
Analyse d’enquête : remplacement de plot_age_pyramid() par age_pyramid(), légère modification du code du tracé alluvial.
Graphiques de chaleur : ajout de ungroup() au chunk agg_weeks.
Graphiques interactifs : ajout de ungroup() au chunk qui fait agg_weeks pour que expand() fonctionne comme prévu.
Séries temporelles : ajout de data.frame() autour des objets dans toutes les commandes trending::fit() et predict().
Analyse des combinaisons : Remplacer case_when() par ifelse() et ajouter le code optionnel across() pour préparer les données.

1.4 Information de session (R, RStudio, paquets)

Vous trouverez ci-dessous les informations sur les versions de R, RStudio et les paquets R utilisés lors de la compilation du guide.

sessioninfo::session_info()

─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.3.2 (2023-10-31 ucrt)
 os       Windows 11 x64 (build 22621)
 system   x86_64, mingw32
 ui       RTerm
 language (EN)
 collate  English_United States.utf8
 ctype    English_United States.utf8
 tz       Europe/Stockholm
 date     2024-06-19
 pandoc   3.1.11 @ C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown)

─ Packages ───────────────────────────────────────────────────────────────────
 package     * version date (UTC) lib source
 cli           3.6.2   2023-12-11 [2] CRAN (R 4.3.2)
 digest        0.6.35  2024-03-11 [1] CRAN (R 4.3.3)
 evaluate      0.23    2023-11-01 [2] CRAN (R 4.3.2)
 fastmap       1.1.1   2023-02-24 [2] CRAN (R 4.3.2)
 htmltools     0.5.8   2024-03-25 [1] CRAN (R 4.3.3)
 htmlwidgets   1.6.4   2023-12-06 [2] CRAN (R 4.3.2)
 jsonlite      1.8.8   2023-12-04 [2] CRAN (R 4.3.2)
 knitr         1.45    2023-10-30 [2] CRAN (R 4.3.2)
 rlang         1.1.3   2024-01-10 [2] CRAN (R 4.3.2)
 rmarkdown     2.26    2024-03-05 [1] CRAN (R 4.3.3)
 rstudioapi    0.15.0  2023-07-07 [2] CRAN (R 4.3.2)
 sessioninfo   1.2.2   2021-12-06 [2] CRAN (R 4.3.2)
 xfun          0.43    2024-03-25 [1] CRAN (R 4.3.3)

 [1] C:/Users/ngulu864/AppData/Local/R/win-library/4.3
 [2] C:/Program Files/R/R-4.3.2/library

──────────────────────────────────────────────────────────────────────────────