1 Logiciels

L’outil central est évidemment R, mais son fonctionnement est aujourd’hui difficilement envisageable sans son environnement de développement RStudio. Pour le contrôle de source, git et GitHub sont de fait les standards. L’ensemble doit être complété par une distribution LaTeX pour la production de documents au format PDF. Un outil de gestion bibliographique est indispensable : Zotero et son extension Better BibTeX sont parfaitement adaptés au cadre de travail présenté ici. Enfin, d’autres logiciels d’usage plus ponctuel peuvent être nécessaires, comme Go.

Leur installation et leur organisation cohérente sont présentées dans ce chapitre.

1.1 R

1.1.1 Installation

R est inclus dans les distributions de Linux : le paquet est nommé r-base. Il ne contient pas des outils de développement souvent nécessaires, donc il est préférable d’installer aussi le paquet r-base-dev. La version de R est souvent un peu ancienne. Pour disposer de la dernière version, il faut utiliser un miroir de CRAN comme source des paquets : voir la documentation complète pour Ubuntu¹.

Sous Windows ou Mac, installer R après l’avoir téléchargé depuis CRAN².

1.1.2 Rtools

Sur Mac, l’installation de R est suffisante à partir de la version 4.0.0.

Sous Windows, l’installation doit être complétée par les “Rtools”, qui contiennent les outils de développement dont ceux nécessaires à la compilation des packages contenant du code C++.

Le chemin des Rtools (avant la version 4.2) doit être déclaré à R, en exécutant dans la console de RStudio la commande suivante (adaptée à la version 4.0 des Rtools) :

# Rtools : déclaration du chemin, 
# nécessite de redémarrer RStudio
writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"',
           con = "~/.Renviron")

Depuis la version 4.2, cette action est inutile.

Les Rtools doivent être complétés par quelques utilitaires manquants, à installer quand le besoin apparaît (en général, un avertissement de R indiquant que le logiciel n’est pas installé).

La vérification des packages renvoie un avertissement si qpdf³ n’est pas installé. Télécharger le fichier zip et coller tout le contenu du dossier bin dans le dossier usr/bin de Rtools (C:\Rtools42\usr\bin pour la version 4.2).

Un autre avertissement est renvoyé en absence de Ghostscript⁴ à télécharger et installer. Copier ensuite le contenu du dossier bin dans le dossier usr/bin de Rtools.

1.1.3 Mise à jour

Il est conseillé d’utiliser la dernière version mineure de R : par exemple, 4.0.x jusqu’à la sortie de la version 4.1. Il est obligatoire d’utiliser la toute dernière version pour préparer un package soumis à CRAN.

Des changements importants ont lieu entre les versions majeures (la version 4 ne permet pas d’utiliser un package compilé pour la version 3) mais aussi parfois entre versions mineures (un fichier de données binaires .rda enregistré sous la version 3.3 ne peut pas être lu par la version 3.6). Il est donc utile de mettre R à jour régulièrement.

L’installation d’une nouvelle version ne désinstalle par automatiquement les versions anciennes, ce qui permet d’en utiliser plusieurs en cas de besoin (par exemple, si un package ancien et indispensable n’est plus disponible). En usage courant, il est préférable de désinstaller manuellement les anciennes versions après l’installation d’une nouvelle.

1.1.4 Librairies

Les packages de R se trouvent dans deux dossiers :

• la bibliothèque système (System Library) contient les packages fournis avec R : base, utils, graphics par exemple. Elle se trouve dans un sous-répertoire du programme d’installation (C:\Program Files\R\R-4.1.0\library pour R version 4.1.0 sous Windows 10).
• La bibliothèque utilisateur (User Library) contient ceux installés par l’utilisateur. Jusqu’à la version 4.1, elle se trouve dans le dossier personnel de l’utilisateur, dans un sous-dossier R\win-library\4.1\). Depuis la version 4.2, ce dossier se trouve dans les paramètres locaux de l’utilisateur dont l’emplacement du dossier se trouve dans la variable d’environnement %LOCALAPPDATA%.

Jusqu’à la version 4.1, si le dossier personnel de l’utilisateur est sauvegardé (par exemple, s’il est répliqué dans le cloud par OneDrive sous Windows), il n’est pas optimal d’y placer les packages : le trafic généré par leur sauvegarde serait lourd et inutile. Pour que les packages soient installés automatiquement dans la bibliothèque système, il suffit que l’utilisateur y ait le droit d’écrire. Sous Windows, donner le droit “Modifier” au groupe des utilisateurs de l’ordinateur sur le dossier de la bibliothèque, en plus du droit de lecture par défaut 1.1). A partir de la version 4.2, il n’y a plus de raison de modifier le fonctionnement par défaut : les paramètres locaux ne sont pas sauvegardés.

Figure 1.1: Activation du droit de modifier la bibliothèque système sous Windows.

Si la bibliothèque utilisateur est retenue, il faut penser à vider le dossier correspondant à l’ancienne version de R en cas changement de version mineure.

L’emplacement des librairies est donné par la fonction .libPaths() :

.libPaths()

## [1] "/Users/runner/work/_temp/Library"                                     
## [2] "/Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library"

1.2 RStudio

RStudio est une interface graphique pour R et bien plus : il est conçu pour simplifier la gestion des projets, faciliter la rédaction et la production de documents et intégrer le contrôle de source par exemple.

1.2.1 Installation

Installer la dernière version de RStudio Desktop à partir du site de RStudio⁵.

Une commande est disponible dans le menu “Help” de RStudio pour vérifier l’existence d’une version plus récente, à installer.

1.2.2 Encodage des fichiers

Les fichiers manipulés dans R sont très majoritairement des fichiers texte. Les caractères spéciaux, notamment les accents, peuvent être codés de diverses façons mais la déclaration du codage n’est pas intégrée aux fichiers. Le codage par défaut dépend du système d’exploitation, ce qui pose régulièrement des problèmes de lisibilité des fichiers partagés. Le codage UTF8 est devenu le standard parce qu’il est universellement reconnu et supporte tous les alphabets sans ambiguïtés.

Dès la première utilisation de RStudio, créer un nouveau fichier R (menu “File > New File > R Script”), l’enregistrer au format UTF8 (“File > Save with Encoding…”), choisir UTF8 dans la liste des formats et cocher la case “Set as default encoding for source files”. Supprimer le fichier après l’avoir enregistré.

Les nouveaux fichiers seront codés au format UTF8. Les fichiers codés sous un autre format ne s’afficheront pas correctement : ils pourront être réouverts avec leur codage d’origine (“File > Reopen with Encoding…”), en essayant éventuellement plusieurs codages jusqu’à obtenir un affichage correct, et sauvegardés au format UTF8 ensuite.

1.2.3 Dossier de travail

Le dossier de travail par défaut est le dossier personnel de l’utilisateur, appelé ~ par RStudio :

Sys.getenv("R_USER")

• Mes Documents sous Windows ;
• Home sous Mac ou Linux.

Il faut systématiquement travailler dans des sous-dossiers de ~, par exemple : ~/Formation.

Pour le bon fonctionnement des RTools, le nom complet du répertoire de travail ne doit pas contenir d’espace (utiliser les tirets bas _) ni de caractère spécial. Le dossier de travail en cours est obtenu par la commande getwd().

getwd()

## [1] "/Users/runner/work/travailleR/travailleR"

L’utilisation du contrôle de source (voir chapitre 3) crée de nombreux fichiers de travail. Les projets sous contrôle de source ne devraient pas se trouver dans un dossier déjà sauvegardé par un autre moyen, comme un lecteur OneDrive sous Windows, sous peine d’une utilisation excessive des ressources : chaque validation de modifications engendre la sauvegarde des fichiers modifiés, mais aussi des fichiers de contrôle qui peuvent être de grande taille.

1.2.4 Solution retenue

L’organisation de l’environnement travail est une affaire personnelle, qui dépend des préférences de chacun. L’organisation proposée ici n’est qu’une possibilité, à adapter à ses propres choix, mais en respectant les contraintes mentionnées.

Sous Windows, une organisation optimale est la suivante :

• Dans son dossier personnel (Mes Documents, ~ pour R), un dossier R est utilisé pour les projets simples, sans contrôle de source. La sauvegarde de ce dossier est gérée par ailleurs.
• Un dossier hors du dossier personnel est utilisé pour les projets sous contrôle de source. L’utilisateur doit y avoir le droit d’écrire. Dans l’organisation de Windows, le dossier correspondant à ces critères est %LOCALAPPDATA%, typiquement C:\Users\NomUtilisateur\AppData\Local. Le dossier sera donc %LOCALAPPDATA%\ProjetsR à créer : exécuter md %LOCALAPPDATA%\ProjetsR dans une invite de commande. Epingler ce dossier à l’accès rapide de l’explorateur de fichiers (figure 1.2) : coller %LOCALAPPDATA%\ProjetsR dans la barre d’adresse de l’explorateur de fichiers, valider, puis faire un clic droit sur “Accès Rapide” et épingler le dossier.

Figure 1.2: Dossier pour les projets sous contrôle de source, sous Windows.

1.2.5 Police de caractères

La police Fira Code⁶ fournit des ligatures : les caractères “<-” utilisés pour l’assignation dans R sont par exemple affichés comme une flèche. Pour l’utiliser dans l’éditeur de RStudio, il suffit de l’installer en suivant les instructions appropriées à son système d’exploitation et de la déclarer dans les options globales (menu “Tools > Global Options…”) : sélectionner Appearance et l’option Editor Font : Fira Code.

1.3 Packages

1.3.1 Installation depuis CRAN

L’installation classique des packages fait appel à CRAN. Un bouton “Install” se trouve dans la fenêtre Packages de RStudio.

Les packages sont déposés sur CRAN par leurs auteur sous forme de code source, compressé dans une fichier .tar.gz. Ils sont disponibles pour le téléchargement dès leur validation. Ils doivent ensuite être mis au format binaire pour Windows (dans un fichier .zip), ce qui prend un peu de temps.

A la demande de l’installation d’un package sous Windows, CRAN propose la version source plutôt que la version binaire si elle est plus récente 1.3).

Figure 1.3: Activation du droit de modifier la bibliothèque système sous Windows.

La liste des packages concernés est affichée dans la console, par exemple :

  There are binary versions available but the source 
  versions are later:
              binary   source needs_compilation
boot          1.3-24   1.3-25             FALSE
class         7.3-16   7.3-17              TRUE

Certains packages nécessitent une compilation (colonne needs_compilation), en général parce qu’ils contiennent du code C++. Ils ne pourront être installés que par les Rtools.

L’installation des packages en version source est beaucoup plus longue qu’en version binaire. Sauf si une version précise d’un package est nécessaire, il est donc préférable de refuser l’installation des versions source.

Les packages peuvent être mis à jour un peu plus tard, après leur compilation par CRAN.

Le bouton “Update” dans la fenêtre Packages de RStudio permet de mettre à jour tous les packages installés.

1.3.2 Installation depuis GitHub

Certains packages ne sont pas disponibles sur CRAN mais seulement sur GitHub parce qu’ils sont encore en développement ou parce qu’ils ne sont pas destinés à un large usage par la communauté des utilisateurs de R. Il peut aussi être utile d’installer une version de développement d’un package publié sur CRAN pour un usage ponctuel comme le test de nouvelles fonctionnalités.

L’installation est gérée par le package remotes. L’argument build_vignettes est nécessaire pour créer les vignettes du package.

remotes::install_github("EricMarcon/memoiR", build_vignettes = TRUE)

Le nom du package est entré sous la forme “GitHubID/NomduPackage”. L’installation est faite à partir du code source et nécessite donc les Rtools si une compilation est nécessaire. install_github() vérifie que la version sur GitHub est plus récente que l’éventuelle version installée sur le poste de travail et ne fait rien si elles sont identiques.

1.3.3 Installation depuis Bioconductor

Bioconductor est une plateforme complémentaire de CRAN qui héberge des packages spécialisés dans la génomique. L’installation des packages de Bioconductor nécessite le package BiocManager pour sa fonction install(). Le premier argument de la fonction est un vecteur de caractères contenant les noms des packages à installer, par exemple :

BiocManager::install(c("GenomicFeatures", "AnnotationDbi"))

La fonction install() appelée sans arguments met à jour les packages.

1.3.4 Solution retenue

A chaque mise à jour mineure de R, tous les packages doivent être réinstallés. La façon la plus efficace de le faire est de créer un script Packages.R à placer dans ~\R. Il contient une fonction qui vérifie si chaque package est déjà installé pour ne pas le refaire inutilement.

# Installation des packages de R ####

# Installer les packages si nécessaire ####
InstallPackages <- function(Packages) {
  sapply(Packages, function(Package) 
    if (!Package %in% installed.packages()[, 1]) 
      {install.packages(Package)})
}


# Outils de développement ####
InstallPackages(c(
  # Outils de développement. Importe remotes, etc.
  "devtools",
  # Exécution de Check par RStudio
  "rcmdcheck",
  # Formatage du code R (utilisé par knitr)
  "formatR",
  # Documentation des packages dans /docs sur GitHub
  "pkgdown",
  # Bibliographie avec roxygen
  "Rdpack",
  # Mesure des performances
  "rbenchmark",
  # Documentation automatique des packages
  "roxygen2",
  # Tests des packages
  "testthat"
  ))

# Markdown ####
InstallPackages(c(
  # Tricot
  "knitr",
  # Documents markdown complexes
  "bookdown",
  # Sites web
  "blogdown",
  # Modèles de documents
  "memoiR"
  ))


# Tidyverse ####
InstallPackages("tidyverse")

La dernière partie du script est à compléter avec les packages utilisés régulièrement.

Ce script est à exécuter à chaque mise à jour de R, après avoir éventuellement activé le droit d’écriture dans la librairie système (voir section 1.1.4).

1.4 git et GitHub

1.4.1 git

git est le logiciel de contrôle de source utilisé ici. Son utilisation est détaillée dans le chapitre 3.

Pour Windows et Mac, l’installation a lieu à partir du site web de git⁷.

git est intégré dans les distributions Linux. Pour Ubuntu, le package apt est git-all.

git est installé sans interface graphique, fournie par RStudio.

Dans RStudio, modifier les options globales (menu “Tools > Global Options…”). Sélectionner Terminal et l’option New Terminals open with : GitBash.

Vérifier la bonne installation de git en tapant la commande git -h dans le terminal de RStudio : l’aide doit s’afficher.

Après l’installation de git, il est possible que le terminal de RStudio ne fonctionne plus correctement et renvoie un message d’erreur contenant les éléments suivants :

*** fatal error - cygheap base mismatch detected
This problem is probably due to using incompatible 
versions of the cygwin DLL.

Le message d’erreur est imprécis : la librairie qui ne doit exister qu’en un seul exemplaire n’est pas cygwin1.dll mais msys-2.0.dll. Rechercher ce fichier dans les dossier d’installation de git et de Rtools. Ils se trouvent normalement dans usr/bin. Remplacer celui de git par celui de Rtools : la version des deux fichiers doit être identique.

Entrer ses informations d’identification en exécutant les commandes suivantes dans le terminal :

git config user.name
git config user.email

Le nom d’utilisateur est libre, de préférence “Prénom Nom”.

1.4.2 GitHub

GitHub est la plateforme accessible par un site web qui permet de partager le contenu des dépôts git. Pour l’utiliser, il suffit d’ouvrir un compte avec la même adresse de messagerie que celle enregistrée dans git.

Le nom du compte GitHub est noté ici GitHubID. Chaque compte GitHub permet d’héberger des dépôts (un dépôt contient les fichiers d’un projet) à l’adresse https://github.com/GitHubID/NomDuDepot⁸. Chaque dépôt peut disposer d’un site web à l’adresse https://GitHubID.github.io/NomDuDepot/⁹. Enfin, un site web global est prévu pour chaque utilisateur à l’adresse https://GitHubID.github.io/¹⁰.

1.4.3 Authentification SSH

La communication entre git (installé sur l’ordinateur local) et GitHub (plateforme en ligne) nécessite de s’authentifier.

Deux méthodes sont disponibles : HTTPS (aussi appelée SSL) et SSH. SSH est la plus robuste mais nécessite la création d’une clé privée.

Dans le terminal de RStudio, exécuter :

ssh-keygen -t ed25519 -C "user.email"

L’adresse de messagerie (qui remplace “user.email”) doit être celle enregistrée dans la configuration de git et le compte GitHub. La clé est enregistrée dans le dossier .ssh du répertoire personnel de l’utilisateur. Il est possible d’ajouter un mot de passe (passphrase) à la clé, qui devra être tapé à la première utilisation de chaque session de travail. Si l’ordinateur est correctement sécurisé (pas d’accès physique par des tiers), la laisser vide permet de gagner en fluidité.

Attention : la clé privée est strictement confidentielle et ne doit être copiée nulle part où elle pourrait être lue par un tiers (attention aux sauvegardes automatiques notamment). Elle n’a pas besoin d’être bien sauvegardée : en cas de perte, elle sera remplacée facilement.

Les clés sont normalement stockées dans le dossier ~/.ssh, quel que soit le système d’exploitation, mais l’emplacement du dossier personnel ~ est ambiguë sous Windows : pour R, c’est le dossier Documents, mais pour d’autres logiciels, c’est le dossier racine de l’utilisateur, parent de Documents.

Dans le terminal de RStudio, vérifier le bon fonctionnement de la clé :

ssh -T git@github.com

Si un message d’erreur indique qu’aucune clé n’est trouvée, deux solutions sont possibles :

• Dupliquer le dossier .ssh (avec l’explorateur de fichiers) dans Documents ;
• Dupliquer le dossier .ssh dans le dossier du programme RStudio (généralement C:\Program Files\RStudio\), dans resources\terminal\bash\.

En cas de succès, un message indique que l’authenticité du serveur GitHub ne peut pas être vérifiée : un contrôle manuel est nécessaire pour la première connexion. Vérifier auprès de GitHub que l’empreinte du serveur est correcte¹¹ et taper yes. Le serveur est ajouté automatiquement à la liste des serveurs connus, dans le fichier known_hosts.

Dans le dossier .ssh, deux fichiers sont créés : l’un contient la clé privée, l’autre, avec l’extension .pub, la clé publique correspondante. Ouvrir le second avec un éditeur de texte et copier la clé publique dans le presse-papier. Sur GitHub, afficher les réglages de son compte (menu “Settings”), sélectionner “SSH and GPG Keys”, cliquer sur “New SSH Key” et coller la clé dans le champ “Key”. Donner un nom à la clé dans le champ “Title”. Le nom peut être celui de l’ordinateur sur lequel la clé a été créée. La clé ne doit pas être copiée sur plusieurs ordinateurs : en cas de besoin, créer une nouvelle clé sur chaque poste de travail utilisé.

Si la clé est compromise (perte ou prêt de l’ordinateur qui la contient), la supprimer sur GitHub et en créer une nouvelle.

1.4.4 Obtention d’un jeton d’accès personnel

L’authentification HTTPS est l’alternative à l’authentification SSL : il faut choisir une méthode et s’y tenir par la suite. Pour utiliser l’authentification HTTPS, la création d’un jeton d’accès personnel est nécessaire.

Les jetons sont créés sur GitHub, dans les paramètres de son compte d’utilisateur, dans “Developer Settings > Personal Access Tokens”¹².

Générer un nouveau jeton, le décrire en tant que “git-RStudio” et lui donner l’autorisation “repo”, c’est-à-dire modifier tous les dépôts (il n’est pas possible de limiter l’accès à un dépôt particulier). Le jeton est une chaîne de caractère qui ne pourra pas être relue plus tard : elle doit être sauvegardée comme un mot de passe.

1.5 Compilateur LaTeX

Pour produire des documents au format PDF, une distribution LaTeX est nécessaire. La solution légère consiste à installer le package tinytex qui installe à son tour une distribution LaTeX optimisée pour R Markdown.

Une distribution complète permet l’utilisation de Latex au-delà de RStudio mais est inutile si l’usage de LaTeX se limite au tricot de documents R Markdown. MiKTeX est une très bonne solution pour Windows et Mac.

1.5.1 tinytex

Installer le package puis exécuter :

tinytex::install_tinytex()

L’ajout de packages LaTeX non inclus dans la distribution minimale de départ est automatique mais peut être lente.

La distribution peut être mise à jour par la commande :

tinytex::tlmgr_update()

1.5.2 MiKTeX

1.5.2.1 Installation

Télécharger le fichier d’installation¹³ et l’exécuter. Plusieurs choix sont à faire pendant l’installation :

• Installer le programme pour tous les utilisateurs (avec des droits d’administrateur) ;
• Le format par défaut du papier : choisir A4 ;
• Le mode d’installation des packages manquants : choisir “Always Install” pour qu’ils soient téléchargés automatiquement en cas de besoin.

Pour Linux, suivre les instructions sur le site de MiKTeX.

1.5.2.2 Mises à jour

MiKTeX est installé avec les packages LaTeX les plus utilisés. Si un document nécessite un package manquant, il est chargé automatiquement. Les mises à jour de packages doivent être faites périodiquement avec la console MiKTeX, accessible dans le menu Démarrer.

Quand elle est lancée sans élévation des privilèges, la console propose de passer en mode administrateur. Cliquer sur “Switch to Administrator mode”.

Dans les paramètres (Settings), vérifier que les packages s’installent toujours automatiquement et que le format du papier est bien A4.

Dans le menu des mises à jour (Updates), cliquer sur “Check for updates” puis “Update now”.

Si l’installation automatique est défaillante, il est possible d’installer manuellement un package dans le menu “Packages”.

1.6 Zotero

Zotero¹⁴ est le logiciel de gestion bibliographique le plus utilisé. Ses extensions permettent de compléter ses fonctionnalités selon les besoins de chacun. Better BibTeX permet d’exporter et de maintenir à jour une sélection des références bibliographiques (une collection de Zotero) sous la forme d’un fichier BibTeX dans un projet R, où il pourra être utilisé dans la rédaction de documents ou la documentation de packages.

Télécharger le fichier d’installation et l’exécuter. Créer un compte utilisateur sur le site web de Zotero. Lier l’installation locale au compte : dans le menu “Edition > Préférences”, sélectionner “Synchronisation > Paramètres” et s’authentifier dans la zone “Synchronisation des données”. Cocher ensuite la case “Synchroniser automatiquement” mais pas “Synchroniser le texte intégral des pièces jointes indexées” parce que la taille totale des textes intégraux synchronisés de cette manière entre le compte Zotero en ligne et le poste de travail est limitée à 300 Mo.

Télécharger l’extension Better BibTeX¹⁵ et l’installer avec le menu “Outils > Extensions” : cliquer sur le bouton des paramètres en haut à droite de la fenêtre, puis “Install Add-on From File…” et sélectionner le fichier qui vient d’être téléchargé.

Paramétrer Better BibTeX à partir du menu “Edition > Préférences > Better BibTeX”. Les options à modifier sont les suivantes :

• “Clés de citation > Format de clé” : [auth:capitalize][year] pour que les citations disposent d’un identifiant unique de la forme “Nom2021” ;
• “Clés de citation > Conserver les clés de citation uniques dans” : “Toutes les collections” pour que les identifiants des citations ne soient pas ambigus ;
• “Exportation > Gestion des Champs > Champs à exclure de l’exportation” : “abstract, file” pour ne pas générer des fichiers bibliographiques surchargés d’informations inutiles dans les projets R.

Il est conseillé d’utiliser l’extension ZotFile¹⁶ pour mieux contrôler l’emplacement du texte intégral (les fichiers PDF liés au références bibliographiques). L’installer puis la paramétrer dans “Outils > Préférences de ZotFile…> Paramètres généraux > Emplacement des fichiers > Dossier personnalisé” : choisir le dossier de stockage des textes intégraux. Si le dossier personnel de l’utilisateur est sauvegardé (par exemple, s’il est répliqué dans le cloud par OneDrive sous Windows), y placer ce dossier de stockage permet à la fois de sauvegarder les textes intégraux mais aussi d’y accéder à partir de plusieurs postes de travail ou directement en ligne. Cette solution est bien plus efficace que la synchronisation par défaut de Zotero, limitée en volume.

1.7 Go

Go¹⁷ n’est utilisé que par le générateur de sites web Hugo (voir section 4.7).

Télécharger le fichier d’installation et l’exécuter. A la fin de l’installation, exécuter la commande go version dans un terminal pour vérifier son bon fonctionnement.

Les mises à jour se font en installant la nouvelle version par dessus la précédente.