6  Utiliser des packages R

Tâche concernée et recommandation
  • Avant d’installer un package, il est indispensable de déterminer précisément quel est le package dont vous avez besoin. Pour cela, vous pouvez consulter les autres fiches de la documentation utilitR, et la fiche [Comment choisir un package ?].
  • Il est recommandé d’utiliser la fonction install.packages pour installer et mettre à jour les packages, sans modifier les arguments repos, lib, type et dependencies. L’usage de la fonction update.packages est destiné à des usages avancés.
  • Il est recommandé d’utiliser la fonction library pour charger les packages sans modifier l’argument lib.loc.

6.1 Introduction aux packages R

6.1.1 Qu’est-ce qu’un package R ?

Un package est un ensemble de fonctions développées par des utilisateurs de R, qui améliorent ou étendent les fonctionnalités de base de R.

Par exemple, le package ggplot2 propose des fonctions pour réaliser toutes sortes de graphiques avec R. Les packages sont au coeur de la logique collaborative de R, car ils permettent de bénéficier des contributions d’autres utilisateurs de R. Début 2021, il existe plus de 14 000 packages disponibles pour R, qui couvrent une multitude de tâches. Il est donc primordial de savoir où chercher des packages et comment les utiliser.

D’un point de vue technique, un package est constitué d’objets R (la plupart du temps des fonctions, parfois des données) et d’une documentation empaquetés en un seul fichier, dans le but d’être partagé facilement. En outre, les packages R ont trois caractéristiques importantes :

  • Un package R peut exiger une version minimale de R pour fonctionner. Par exemple, le package ggplot2 (qui sert à faire des graphiques) ne peut fonctionner qu’avec R 3.2 au minimum. Vous pouvez donc être contraints de modifier la version de R que vous utilisez pour pouvoir installer un package. En pratique cela arrive rarement.
  • Les packages R sont spécifiques à la version de R avec laquelle ils ont été installés. Ainsi, un package installé avec la version 3.6 de R peut ne pas fonctionner avec les versions 3.5 ou 4.0. La principale conséquence pratique de cette caractéristique est que vous devrez réinstaller les packages si vous modifiez la version de R que vous utilisez. Cette réinstallation ne présente généralement aucune difficulté technique, mais elle peut prendre du temps.
  • Les packages R font fréquemment appel à d’autres packages appelés dépendances : la fonction fonction1() du package package1 fait appel à la fonction fonction2() du package package2, et ainsi de suite. Un package R ne pourra être utilisé que si ses dépendances sont également installées. Fort heureusement, la plupart du temps vous n’avez pas à vous préoccuper des dépendances de packages car R installe par défaut toutes les dépendances nécessaires.

6.1.2 Où peut-on trouver des packages R ?

Les packages R sont disponibles sur des sites spécialisés appelés dépôts (repositories ou repo en anglais). Le principal dépôt est le dépôt officiel du projet R, le CRAN (Comprehensive R Archive Network).

Les packages peuvent également être mis à disposition par leurs auteurs sur les forges logicielles (telles que Github et Gitlab), mais il s’agit alors la plupart du temps de versions expérimentales dont l’usage est principalement destiné aux utilisateurs avancés de R.

Note

Le CRAN dispose de plusieurs copies, appelées miroirs, dont la plupart sont hébergés sur des serveurs d’universités ou d’établissements de recherche. Télécharger un package sur un miroir ou un autre est strictement équivalent. L’intérêt de choisir un miroir proche de sa localisation permet simplement de gagner en vitesse et de réduire les flux sur le réseau.

6.1.3 Comment utiliser un package R ?

Pour utiliser un package R, il est nécessaire de réaliser deux actions, qui sont détaillées dans la suite de cette fiche :

  • l’installation consiste à télécharger le package sur internet, puis à l’installer sur l’ordinateur, dans un dossier connu de R. La fonction principale pour installer un package est install.packages ;
  • le chargement consiste à indiquer à R que l’on souhaite utiliser le package dans la session courante. La fonction principale pour charger un package est library.

Il est important de comprendre que ces deux actions sont complètement distinctes. L’installation est une opération qu’on ne réalise qu’une seule fois : une fois qu’un package a été installé sur un ordinateur, il y est présent de façon permanente. A noter qu’il existe toutefois des raisons de réinstaller un package, par exemple pour le mettre à jour. Inversement, le chargement d’un package est une opération qu’il faut réaliser à chaque fois que vous ouvrez une session R.

6.2 Installer un package R

6.2.1 La méthode standard : la fonction install.packages

La façon la plus commune (et commode) d’installer un package est d’utiliser la fonction install.packages. Cette fonction réalise successivement deux actions :

  1. Elle télécharge la dernière version du package sur un dépôt distant de packages R (typiquement le dépôt officiel) ;
  2. Elle installe le package sur la machine de l’utilisateur, dans un dossier appelé librairie.

La fonction install.packages propose de multiples options, dont les principales sont décrites ci-dessous. Il est toutefois recommandé de ne pas modifier les réglages par défaut et d’utiliser cette fonction sous sa forme la plus simple :

install.packages("monBeauPackage")

Trois points sont à noter sur l’utilisation de la fonction install.packages :

  • Cette fonction requiert que vous disposiez d’un accès à internet (pour télécharger les packages) ;

  • Les noms des packages sont sensibles à la casse : il est donc important de bien respecter majuscules et minuscules. Par exemple, la commande install.packages("Ggplot2") ne fonctionnera pas, car le package s’appelle en réalité ggplot2 (en minuscules) ;

  • Cette fonction accepte en paramètre un vecteur de noms de packages, afin d’installer plusieurs packages en une seule fois :

    install.packages(c("package1", "package2", "package3"))

Une fois qu’un package a été installé sur un ordinateur, il y est présent de façon permanente. Il est donc conseillé de ne pas inclure les instructions d’installation des packages dans les programmes R, pour éviter des réinstallations superflues.

6.2.2 Utilisation de la fonction install.packages

6.2.2.1 Choix du dépôt

Par défaut, la fonction install.packages télécharge le package demandé sur le dépôt officiel du projet R, le CRAN. Il est possible de modifier le dépôt utilisé grâce à l’argument repos de install.packages, mais vous n’avez normalement pas besoin de le faire dans le cadre d’un usage standard de R.

L’installation de packages dans AUS fonctionne de façon légèrement différente. En effet, une session R ne peut pas se connecter au site du CRAN depuis AUS car les serveurs AUS n’ont pas accès à internet pour des raisons de sécurité. Pour contourner cette difficulté, l’Insee dispose de son propre dépôt de packages R, accessible uniquement depuis le réseau interne. Ce dépôt est un miroir du CRAN, et est mis à jour quotidiennement. La configuration de R dans AUS est définie de sorte que R utilise par défaut le dépôt interne. Par conséquent, vous n’avez donc aucun réglage à faire par vous-même pour utiliser ce dépôt.

6.2.2.2 Installation des dépendances

Par défaut, la fonction install.packages installe également toutes les dépendances nécessaires. Il est possible de modifier ce réglage grâce à l’argument dependencies, mais vous n’avez normalement pas besoin de le faire dans le cadre d’un usage standard de R.

6.2.2.3 Emplacement des packages installés

Une fois qu’un package a été téléchargé, la fonction install.packages l’installe, c’est-à-dire qu’elle le copie dans un dossier local appelé librairie (ou parfois bibliothèque). Par défaut, les librairies dans lesquelles les packages sont installés sont situées dans le sous-dossier library de l’emplacement où est installé R.

Sur AUS, les packages sont installés dans le dossier U:/R/win-library/x.y, où x.y désigne le numéro de version de R (3.6 ou 4.0 par exemple).

Il est possible de modifier la librairie dans laquelle un package est installé grâce à l’argument lib, mais vous n’avez normalement pas besoin de le faire dans le cadre d’un usage standard de R.

6.2.2.4 Type de packages

Sous Windows, les packages sont installés par défaut à partir de fichiers spécialement compilés pour ce système d’exploitation. Ces fichiers sont désignés sous le nom de fichiers binaires (binary en anglais).

L’argument type de install.packages permet de choisir une méthode alternative à la valeur par défaut, "win.binary". Utiliser type = "source" permet par exemple de récupérer une version plus récente d’un package (par exemple sur une forge logicielle), mais peut nécessiter l’installation d’outils de développement supplémentaires sous Windows. Ce type d’installation est plutôt destiné à des utilisateurs avancés ; il est donc conseillé de conserver la valeur par défaut de l’argument type.

6.2.3 Installation avancée

Il existe d’autres méthodes pour installer des packages R, qui sont décrites ci-dessous. De façon générale, ces méthodes sont destinées aux utilisateurs avancés de R.

6.2.3.1 Installer depuis une forge logicielle (GitHub, GitLab…)

Certains packages sont mis à disposition sur une forge logicielle, par exemple GitHub ou GitLab, et pas sur le CRAN. C’est notamment le cas des packages dont le développement est encore expérimental, ou dont l’usage est très spécifique.

Le package remotes a pour finalité principale d’installer des packages depuis des forges logicielles. Pour installer un package depuis une forge, il faut utiliser la fonction dédiée : install_github pour GitHub, install_gitlab pour GitLab, install_svn pour SVN, etc… Voici un exemple :

# installe depuis `https://github.com/InseeFrLab/doremifasolData`
remotes::install_github(repo = "InseeFrLab/doremifasolData")

Seul le premier argument (repo) est obligatoire. Il est formé du nom du compte sur la forge logicielle, suivi du nom du dépôt. Le package installé contiendra les modifications les plus récentes. Installer depuis une forge permet ainsi de récupérer la version de développement d’un package (seules les versions stables sont en général disponibles sur le CRAN). Pour installer un package tel qu’il était à un moment donné, il est également possible de faire suivre le nom du dépôt par une référence à un commit, à un tag (une version) ou à une branche. Voici un exemple avec un tag : remotes::install_gitlab("py_b/funprog@v-0.3.0"). Voici un exemple avec un commit : remotes::install_github("InseeFrLab/doremifasolData@a9df2d3d0e372").

Note

Lorsque vous installez un package depuis une forge logicielle, R crée automatiquement une archive temporaire (un fichier .tar.gz), puis installe le package à partir de celle-ci. Si vous travaillez dans un environnement Windows, il est nécessaire que Rtools soit installé sur votre poste pour que R puisse construire l’archive.

Rtools est un logiciel (pas un package) qui contient un certain nombre d’outils pour construire des packages R sous Windows. Rtools n’est en revanche pas nécessaire sur les systèmes Mac ou Linux. Vous pouvez vérifier si Rtools est installé en exécutant la fonction pkgbuild::has_rtools(). Celle-ci renvoie TRUE si Rtools est installé, FALSE sinon. Si Rtools n’est pas installé, vous pouvez l’installer facilement en le téléchargeant sur internet.

6.2.4 Installer depuis un fichier

Il est aussi possible d’installer un package depuis une archive compressée (fichiers “.zip” pour les binaires Windows ou “.tar.gz” pour les packages source). Pour indiquer que la source est un fichier local, il est obligatoire de spécifier repos = NULL.

install.packages("chemin/en/local/package1_x.y.z.zip", repos = NULL)

Si le fichier est de type “source” (extension .tar.gz), Rtools peut s’avérer nécessaire, notamment si certaines fonctions sont écrites en C ou en C++.

Installer un package depuis un fichier peut être utilisé dans les cas suivants :

  • le package n’est pas sur un dépôt distant (CRAN ou une forge logicielle) ;
  • on souhaite installer une version plus ancienne que celle actuellement sur le dépôt distant ;
  • aucune connexion internet n’est possible (par exemple, transmission du fichier compressé via une clé usb).

Il est à noter que cette méthode atteint rapidement ses limites dès lors que des dépendances non installées sont requises. En effet, il faudra installer manuellement ces dépendances (et éventuellement les dépendances des dépendances…).

6.2.5 Mettre à jour les packages

Il peut arriver qu’un de vos programmes génère une erreur parce que vous utilisez un package dans une version trop ancienne. Pour mettre à jour un package, il suffit de le réinstaller avec install.packages. Cette méthode de mise à jour est la plus simple, et résout la très grande majorité des problèmes de version de packages.

Il existe également la fonction update.packages. Cette fonction ne sert pas à mettre un package particulier, mais à mettre à jour tous les packages d’une librairie. Vous pouvez utiliser cette fonction si vous le souhaitez, mais son usage est plus complexe que celui d’install.packages. Vous pouvez en apprendre davantage sur cette fonction en consultant l’aide associée (?update.packages).

6.2.6 Gestion des packages avec RStudio

RStudio dispose d’un onglet “Packages” (par défaut dans le cadran en bas à droite) où l’on peut gérer les packages sans saisir des instructions dans la console. Les fonctionnalités principales sont les suivantes :

  • affichage des packages installés sur le système (correspond au résultat de la fonction installed_packages). Cocher un package dans cette liste permet de le charger en mémoire (library).
  • le bouton Install permet de chercher un package sur le CRAN (ou un autre dépôt) ou de sélectionner un package sous forme de fichier. L’auto-complétion sur le nom du package est proposée lors de la recherche, ce qui la rend plus aisée et prévient les problèmes de casse (majuscules / minuscules).
  • le bouton Update permet de lister les packages pour lesquels il existe une version plus récente et d’éventuellement les mettre à jour.

Chacune de ces manipulations effectuées par l’intermédiaire de l’interface graphique génère (et exécute) la commande correspondante dans la console.

Lors de l’ouverture d’un script, RStudio tente aussi de détecter automatiquement si les packages utilisés dans celui-ci sont installés. Dans le cas contraire, il affiche un bandeau en haut du script proposant d’installer les packages manquants : ▲ _package_ --- required but is not installed. Install Don't show again

Spécificité Insee

Il ne faut pas essayer d’installer des packages en cliquant sur le bouton Install du bandeau si vous travaillez dans AUS. En effet, si vous cliquez sur ce bouton, RStudio essaie de télécharger le package depuis le CRAN (qui n’est pas accessible depuis AUS). Il faut utiliser la fonction install.packages à la place.

6.3 Utiliser un package R

Une fois qu’un package est installé sur votre machine, il est pratique de procéder au chargement du package avec la fonction library() pour pouvoir l’utiliser. Charger un package consiste à indiquer à R qu’on souhaite l’utiliser dans la session courante. Ceci rend possible l’utilisation des fonctions implémentées par le package. Par exemple, pour charger le package ggplot2, il est nécessaire d’exécuter la commande suivante :

Par défaut, la fonction library cherche le package dans la librairie d’installation des packages (voir le paragraphe @ref(libraries)). R renvoie une erreur s’il ne trouve pas le package considéré dans la librairie. Il est possible de modifier la librairie dans laquelle la fonction library cherche les packages grâce à l’argument lib.loc, mais vous n’avez normalement pas besoin de le faire dans le cadre d’un usage standard de R.

Tip

Il est indispensable de rassembler les instructions de chargement de package au début des programmes R, car cela permet à un utilisateur qui ne connaît pas les programmes de repérer facilement les packages utilisés.

Note

Même si un package n’a pas été chargé à l’aide de la fonction library(), il est possible d’appeler ses fonctions avec l’opérateur ::. Par exemple, même sans avoir chargé le package ggplot2, il est possible d’initialiser un plot avec la commande suivante :

ggplot2::ggplot(data = df)

L’opérateur :: est particulièrement utile en cas de conflits entre packages, comme détaillé dans la fiche sur les bonnes pratiques pour améliorer la reproductibilité.

6.4 Pour en savoir plus

  • Le livre R Packages par Hadley Wickham et Jenny Brian (en anglais). Il porte principalement sur le développement de packages, mais l’introduction du livre détaille les concepts abordés dans cette fiche.
  • La fiche sur la gestion des dépendances.