TP6 : Les données, on en fait quoi ?
BUT 3 - Domaines d’application
Nous allons voir comment utiliser des données dans le package.
Disposer d’un jeu de données pour les exemples, démonstrations et tests du package.
Prérequis
Rappel
Nous avons inclus une application R-Shiny dans notre package. Il est facile de partager ce package, ainsi que l’application Shiny.
Un membre du binôme doit faire le TP sur sa session (différent du TP précédent). Au prochain TP vous changerez de membre.
Pensez à sauvegarder et à versionner votre travail aux étapes importantes.
Pensez bien à faire un pull avant de commencer à travailler.
L’issue du TP
- Créer une issue dans votre projet avec pour nom TP6.
- Y ajouter ceci :
# TP6 : Les données
## Tâches :
1. [ ] Inclure un jeu de données
2. [ ] Documenter le jeu de données
...
## Version
Le commit correspondant au rendu final du TP : <clé SHA>- Dans l’issue principal du projet Rendu de notre projet associer cette dernière issue dans Linked Items
- utiliser le numéro de l’issue ou son nom
Les données
Durant vos études et dans votre vie professionnel vous êtes amené à manipuler des jeux de données.
Le package et l’application R {Shiny} vous permettre d’utiliser (et réutiliser) des méthodes que vous avez implémentés.
Ces dernières peuvent manipuler des données spécifiques ou plus génériques et plus ou moins volumineuses. Dans ces cas plusieurs possibilités s’offrent à vous afin de disposer des jeux de données.
Vous pouvez :
- Récupérer ces données via un fichier
- Récupérer ces données via une BDD
- Récupérer ces données via une API
- etc.
Afin de rendre ces données accessibles à l’utilisateur (vous), vous devez implémenter une ou plusieurs méthodes qui récupérées et effectues un post-traitement sur ces dernières afin de les exploiter.
Ici dans notre TP, nous allons inclure un jeu de données dans le package afin de disposer d’un minima de données et nous présenterons le format de ce dernier. Ce jeu de données peut être utilisé comme ressources pour les démonstrations/exemples (package et application R Shiny), le développement et les tests, etc.
Les données disponibles dans un package ne doivent pas dépasser quelques Mo (<5Mo), ce sont des données à titre d’exemples et démonstrations. Il est possible de créer un package qui ne contient que des données et dans ce cas elles peuvent dépasser quelques Mo.
Inclure des données dans le package
Pour cette partie vous pouvez utiliser votre propre jeu de données ou celui des pokemons.
Le travaille à effectuer est expliqué à la fin.
Au format BRUT (raw)
Disposer d’un jeu de données brut donne plusieurs avantages, il n’y a pas de contrainte de format (le package restera valide) et l’utilisateur peut explorer ces données comme bon lui semble.
Pour mettre à disposition des données brutes, elles doivent êtres stocké dans un ou plusieurs fichiers sous le répertoire <mon_package>/inst/extdata/ du package.
Par la suite, dans votre package (une fois installé), vous pouvez accéder aux données en listant les fichiers.
list.files(system.file("extdata", package = "<monpackage>" ))Idéalement nous créerons une méthode (dans par exemple R/chargement_données.R) qui permet de charger les données. Par exemple :
#' load_pokemon
#' @description permet de charger le fichier opkemon.csv au format tableau et de créer un dataframe des pokemons de niveau 1 à 6.
#' @return un dataframe des pokemons
#' @export
load_pokemon <- function() {
## TODO vérifier que le fichier est présent et valide avant lecture et retour.
read.csv2(paste0(system.file("extdata", package = "<monpackage>",mustWork = TRUE), "pokemon.csv"), header=TRUE, sep=",")
}Dans une application R Shiny, il est possible de mettre des données dans le dossier www, qui seront accessibles uniquement à l’application.
Au format rda
Disposer d’un jeux de données rda donne plusieurs avantages aussi. Ces données sont déjà formatées pour une utilisation dans R et elles sont accessibles et documentés directement à l’utilisation du package.
Il est possible d’utiliser le format rds mais celui-ci ne fonctionne que sur un objet R contrairement au format rda.
Pour ajouter une donnée au format rda il suffit de mettre le fichier dans le répertoire ___package>/data/__ (répertoire à créer à la racine du package).
Comment acceder aux données
Ici c’est très simple, l’option LazyData: true dans le fichier DESCRIPTION demande à ce que les données contenues dans data/ soient chargées à l’utilisation du package. Dans l’exemple le jeu de donnée sera accessible avec la variable pokemon.
il est possible de mettre le LazyData à false, dans ce cas il faudra charger explicitement le jeu de donnée. Cela peut être fait des trois manières suivantes:
data(pokemon) data(pokemon, package=<monpackage>) # avec lazyData à true pokemon <monpackage>::pokemon
Documenter les données
Un package normé et valide doit obligatoirement documenter ses jeux de données. Il faut donc créer un/des fichiers .Rd dans le répertoire man/ qui décrivent ces données. Nous avons vu au TP3 qu’il est possible d’automatiser la documentation, pour ce faire nous allons créer un fichier R/pokemon.R qui contient la documentation.
pokemon.R
#' Liste des Pokemons
#'
#' Ce jeu de donnée décrit les pokemons de niveau 1 à 6.
#'
#' @format ## `pokemon`
#' a data frame with 801 lines and 13 columns :
#' \describe{
#' \item{#}{numéro identifiant}
#' \item{Name}{le nom du Pokemon}
#' \item{Type 1}{le Type 1}
#' \item{Type 2}{le type 2}
#' \item{Total}{point total}
#' \item{HP}{point de vie}
#' \item{Attack}{point d'attaque}
#' \item{Defense}{point de défense}
#' \item{Sp.Atk}{point attaque spécial}
#' \item{Sp.Def}{point défense spécial}
#' \item{Speed}{vitesse}
#' \item{Generation}{la génération}
#' \item{Legendary}{a true si c'est un legendaire}}
#' @source <https://gist.githubusercontent.com/armgilles/194bcff35001e7eb53a2a8b441e8b2c6/raw/92200bc0a673d5ce2110aaad4544ed6c4010f687/pokemon.csv>
"pokemon"Autres solutions
Il existe d’autres solutions pour des cas de figures différents. c.f.: https://r-pkgs.org/data.html
Travail à effectuer
- Mettre un jeu de donnée au format rda dans votre package.
- Documenter le jeu de données et accéder à la documentation dans la console R.
- Accéder au jeu de donnés depuis la console R
- monpackage
|- data
|- pokemon.rda
|- inst
|- shinyapps
|- monapp
|- ui.R
|- server.R
|- www
|- ...
|- extdata
|- pokemon.csv
|- R
|- runMonApp.R
|- ...
|- DESCRIPTION
|- NAMESPACE
|- .Rbuildignore
|- .gitlab-ci.yml
|- .gitignore
|-...Maintenant vous disposez d’un package R et d’une application R Shiny qui embarquent leurs propres données.
Avant d’aller plus loin
- Vérifier que vous avez suivie les consignes.
- Vérifier la liste des vérifications vu dans les TP précédents.
- Vérifier que votre package est toujours valide et bien documenté.
- Vérifier que le contenu des jobs GitLab ne comporte pas d’erreur.
- Vérifier la clarté des commentaires et du code.
- Vérifier que le jeu de donnée est bien chargé à l’utilisation de votre package
Questions:
- Dans l’issue de ce TP (“TP6”).
- Ajouter le message et la version du commit correspondant à ce TP
(menu de gauche -> Code -> Commits) le commit correspond à la clé SHA.
- Ajouter le Tags TP6 au commit
- Répondez aux questions suivantes dans la description de l’issue :
- Quel est la contrainte d’embarquer des données dans un package R ?
- Pourquoi le dossier data/ ne contient que des fichiers au format rds ou rda ?
- En plus de permettre de tester le package, a quoi peut servir le jeu de donnée du package ?
- Quels sont les formats de fichiers acceptés dans le dossier inst/extdata/ ?
- Quel est la contrainte d’embarquer des données dans un package R ?
Comment générer le fichier rda
Un fichier rda est simplement un fichier binaire compréhensible par R. Il permet de stocker un ou des objects R.
Prenons l’exemple des pokemons, pour inclure le dataframe des pokemons il faut :
Exemple (pour créer le fichier pokemone.rda) :