Enrichir un package R avec des données : Guide complet

Un aperçu rapide

Dans cet article, nous présentons les différentes manières d’incorporer des données dans un package R. Nous couvrons les trois répertoires utilisés pour stocker les données et expliquons comment y accéder, que vous soyez un utilisateur ou un développeur de package. Enfin, nous discutons des meilleures pratiques pour documenter ces données.

Pourquoi inclure des données dans un package ?

Inclure des données dans un package peut être utile pour plusieurs raisons :

• Simplifier l’utilisation du package : Les données incluses dans le package sont directement accessibles par les utilisateurs.
• Faciliter la reproductibilité : Les données permettent aux utilisateurs de reproduire les exemples fournis dans la documentation.
• Améliorer les tests unitaires : Les données incluses peuvent être utilisées pour tester les fonctions du package.
• Partager des informations : Distribution de documentation, d’articles scientifiques, d’exemples de code, etc.

Le terme « données » doit être interprété de manière large. Il comprend des données tabulaires typiquement utilisées dans R (par exemple, des fichiers CSV ou XLSX, ou des objets data.frame), mais aussi des images, des fichiers de configuration, des articles, des exemples de code, etc.

Répertoires de données dans un package R

Il existe trois répertoires dans un package R utilisés pour stocker des données : data-raw/, data/ et inst/, chacun ayant un objectif spécifique et s’adressant à différents publics (développeurs contre utilisateurs).

Le couple data-raw/ et data/

L’objectif ici est de rendre les données disponibles aux utilisateurs du package, qui peuvent être utilisées par les fonctions du package ou incluses dans les exemples de documentation. Ces données seront représentées sous forme d’objets R (par exemple, data.frame, liste, etc.).

Le répertoire inst/

Ce répertoire vous permet de stocker des fichiers sans restrictions de format : fichiers tabulaires, scripts d’exemple de code, carnets au format Rmd/Qmd, documentation PDF, etc. Il n’y a pas de limites.

Utilisation de data-raw/ et data/

Cas d’utilisation : Vous souhaitez rendre les données disponibles aux utilisateurs du package pour qu’elles puissent être utilisées par les fonctions de celui-ci. L’objectif est de fournir un accès natif depuis les fonctions du package.

Exemple

1. Créez le répertoire data-raw/ en utilisant la commande usethis::use_data_raw("my_dataset_demo"). Cette commande crée un fichier my_dataset_demo.R dans le répertoire data-raw/.
2. Préparez le jeu de données dans le fichier my_dataset_demo.R :

# Créez un échantillon du jeu de données "starwars" du package dplyr
library(dplyr)
library(readr)
starwars_raw <- read_csv("data-raw/starwars.csv")
starwars_sample <- starwars_raw |> sample_n(size = 10)
usethis::use_data(starwars_sample, overwrite = TRUE)

3. Après avoir exécuté la commande usethis::use_data(starwars_sample, overwrite = TRUE), vous verrez un fichier nommé starwars_sample.rda dans le répertoire data/.
4. Il reste encore du travail : nous devons maintenant documenter le jeu de données. Pour cela, nous utiliserons le paquet {checkhelper}.

Utilisation de inst/

Cas d’utilisation : Vous souhaitez stocker des fichiers destinés uniquement à des tests unitaires ou pour partager une documentation supplémentaire (par exemple, un article scientifique).

Exemple

1. Créez le répertoire inst/ à la racine du package : dir.create(here::here("inst")).
2. Placez les fichiers souhaités dans le répertoire.
3. Installez le package : remotes::install_local().
4. Les fichiers sont maintenant accessibles à l’aide d’une fonction spéciale : system.file(), qui pointe vers la racine du répertoire inst/.