data(iris)Inclure des données
TP
Frédéric Santos 
Voyons à présent dans cette section comment inclure des jeux de données dans notre package.
1 Pourquoi inclure des données ?
Tout utilisateur régulier de R a probablement déjà exécuté la commande suivante :
Cette instruction charge et rend disponible le dataframe iris correspondant au célèbre jeu de données de iris de Fisher (1936). Les raisons pouvaient être multiples, mais il s’agit généralement de tester une fonction R (méthode statistique, data wrangling, …) sur un jeu de données très simple avant de l’appliquer sur nos propres données, et/ou d’écrire un exemple reproductible pour un post de forum ou de blog.
Inclure des données dans notre package nous permettra notamment de :
- disposer de données pour mieux documenter le package (à travers une vignette, ou des exemples utiles dans chaque page d’aide des fonctions du package) ;
- disposer de données “fixes” facilitant l’implémentation de tests unitaires (voir section suivante) ;
- fournir à l’utilisateur des données pertinentes et déjà correctement mises en forme pour tester les différentes fonctions du package.
2 Où placer les données ?
Comme dans le cas des fonctions, un jeu de données peut toutefois être exporté ou non, c’est-à-dire accessible à l’utilisateur final (via la fonction data()), ou “caché” à l’utilisateur final et simplement disponible pour les besoins internes propres au(x) développeur(s).
Les données à inclure doivent être placées à des endroits différents de l’arborescence du package en fonction de l’usage qui en sera fait.
| Usage des données | Emplacement | Format attendu |
|---|---|---|
| Exportées pour l’utilisateur final | Dossier data/ |
Spécifique .rda |
| Usage interne seulement | Fichier R/sysdata.rda |
Spécifique .rda |
| Exemples de fichiers bruts | Dossier inst/extdata |
Au choix : .csv, .dat, .txt, .xlsx, … |
Nous nous concentrerons ci-dessous sur le cas d’usage le plus fréquent, qui est celui de l’inclusion de données exportées.
3 Inclure des données exportées
3.1 Les formats de données spécifiques à R
Il existe deux formats de données spécifiques à R :
- les fichiers RData dont l’extension est
.rda, et qui peuvent stocker un ou plusieurs objets R ; - les fichiers RDataSingle, dont l’extension est
.rdset qui peuvent contenir un seul objet R.
Toutefois, l’usage du format RDS est plus rare dans le contexte de la création de package, et la recommandation officielle est plutôt de créer un fichier RDA par jeu de données à stocker, et d’inclure ces fichiers dans le répertoire data/ du package.
3.2 Inclure et exporter des données
Les fichiers RDA peuvent être créés par la fonction de base save(), mais là encore, une fonction du package {usethis} peut faciliter l’opération.
Commençons par générer un dataframe de données d’exemples, croisant les observations (en l’occurrence des longueurs d’os) effectuées par deux personnes sur la même série d’individus :
set.seed(2024)
## Créer une première série d'observations de 30 individus :
x <- runif(n = 30, min = 25, max = 40)
## Simuler une seconde série d'observations en "bruitant" la première :
y <- x + rnorm(30, mean = 0.5, sd = 1.5)
## Créer et résumer un dataframe :
bonelengths <- data.frame(
Obs1 = x,
Obs2 = y
)
summary(bonelengths) Obs1 Obs2
Min. :25.01 Min. :24.02
1st Qu.:29.40 1st Qu.:28.98
Median :33.48 Median :32.89
Mean :32.70 Mean :32.91
3rd Qu.:37.17 3rd Qu.:37.32
Max. :39.30 Max. :39.62 Ces données peuvent alors être ajoutées au package en exécutant l’instruction :
usethis::use_data(bonelengths)3.3 Documenter un jeu de données
Avec les paramètres par défaut de use_data(), le jeu de données est exporté, et placé dans data/. Puisque ce jeu de données est désormais accessible à l’utilisateur et fait partie des fonctionnalités du package, il doit être documenté.
Une manière de procéder est de créer un nouveau script R dans le dossier R/, par exemple en exécutant :
usethis::use_r("data")Il suffit ensuite d’insérer dans ce fichier un squelette de documentation Roxygen, comme nous l’avons fait précédemment pour les fonctions, et le package {roxygen2} se chargera alors de produire automatiquement le fichier .Rd correspondant dans le dossier man/.
Assez curieusement1, Rstudio ne propose pas d’insérer automatiquement un squelette de documentation Roxygen pour les jeux de données, et réserve cette fonctionnalité aux fonctions. On doit donc pour cela passer par le package {sinew} pour obtenir un template adéquat :
sinew::makeOxygen("bonelengths")#' @title DATASET_TITLE
#' @description DATASET_DESCRIPTION
#' @format A data frame with 30 rows and 2 variables:
#' \describe{
#' \item{\code{Obs1}}{double COLUMN_DESCRIPTION}
#' \item{\code{Obs2}}{double COLUMN_DESCRIPTION}
#'}
#' @details DETAILS
"bonelengths"Exercice. Pour finaliser la documentation de notre jeu de données bonelengths :
- Copier-coller ce template, et l’insérer dans le fichier
R/data.R. - En éditer/compléter le contenu avec les arguments adéquats.
- Sauvegarder, puis exécuter à nouveau les fonctions
document()etcheck()afin de vérifier que la documentation est correctement écrite. - Effectuer un nouveau commit pour l’état actuel du package.
4 Autres cas
La mise à disposition de fichiers bruts dans le dossier inst/extdata est assez rare et correspond à des cas d’usage très spécifiques (par exemple, permettre à l’utilisateur de tester des fonctions de parsing ou d’analyse textuelle).
Enfin, la mise à disposition de données à usage interne au format .rda ne diffère qu’en deux petits détails du cas général de données exportées : ces données sont à regrouper dans un seul fichier .rda placé dans le répertoire R/, et ces données n’ont pas à être documentées.
Références
Fisher, R. A. 1936. « The Use of Multiple Measurements in Taxonomic Problems ». Annals of Eugenics 7 (2): 179‑88. https://doi.org/10.1111/j.1469-1809.1936.tb02137.x.
Notes de bas de page
Au mieux de mes connaissances, et à date du 26 avril 2024 en tout cas !↩︎