Utilisateurs autorisés, Bureaucrates, Ingénieurs ISIG, Utilisateurs autorisés automatiquement, Masqueurs de modifications
375
modifications
« R: construire un package » : différence entre les versions
m
aucun résumé des modifications
mAucun résumé des modifications |
mAucun résumé des modifications |
||
| Ligne 1 : | Ligne 1 : | ||
Cette page reprend quelques idées de base pour faciliter la construction d'un package sous R. | Cette page reprend quelques idées de base pour faciliter la '''construction d'un package sous R'''. | ||
== Pour qui construire un package? == | == Pour qui construire un package? == | ||
| Ligne 5 : | Ligne 5 : | ||
- Pour '''soi''' (réunir un certain nombre de fonctions, et les documenter pour un usage futur) | - Pour '''soi''' (réunir un certain nombre de fonctions, et les documenter pour un usage futur) | ||
- Pour '''les autres''' (réunir un certain nombre de fonctions, les documenter et faciliter l'installation de ces fonctions par d'autres utilisateurs notamment via une | - Pour '''les autres''' (réunir un certain nombre de fonctions, les documenter et faciliter l'installation de ces fonctions par d'autres utilisateurs notamment via une '''installation''' plutôt que par des copier-collers de code. | ||
== Pourquoi construire un package? == | == Pourquoi construire un package? == | ||
- Pour '''réunir un certain nombre de fonctions''' s'intégrant dans une '''problématique commune''' | - Pour '''réunir un certain nombre de fonctions''' s'intégrant dans une '''problématique commune''' | ||
- Pour rendre son travail '''plus facilement reproductible''' que par un partage de script simple | - Pour rendre son travail '''plus facilement reproductible''' que par un partage de script simple | ||
- Pour '''partager''' et '''valoriser''' ses codes | - Pour '''partager''' et '''valoriser''' ses codes | ||
== Création de l'arborescence des fichiers == | == Création de l'arborescence des fichiers == | ||
| Ligne 22 : | Ligne 22 : | ||
Le dossier est automatiquement construit et contient: | Le dossier est automatiquement construit et contient: | ||
- '''.Rproj''': le fichier indiquant à R les caractéristiques du projet | - ⚙️ '''.Rproj''': le fichier indiquant à R les caractéristiques du projet. Le fait que le projet corresponde à un package fait apparaître '''un onglet "Build"''' en haut à droite de RStudio | ||
-📋 '''DESCRIPTION''' : le fichier de description du package (auteur, description de l'objectif du package, licence, etc.), à compléter / modifier | |||
-📋 '''NAMESPACE''': le fichier (read-only) qui '''liste les fonctions du package''', celles qui sont exportées (donc utilisables directement par les futurs utilisateurs du package) et les autres (celles qui servent au(x) développeur(s) uniquement) | - 📋 '''DESCRIPTION''' : le fichier de description du package (auteur, description de l'objectif du package, licence, etc.), à compléter / modifier | ||
-📁 '''R''': contient l'ensemble des scripts correspondant aux codes des fonctions | |||
-📁 '''man''': (pour "manual") contient l'ensemble des fichiers d'aide i.e. la documentation associée à chaque fonction | - 📋 '''NAMESPACE''': le fichier (read-only) qui '''liste les fonctions du package''', celles qui sont exportées (donc utilisables directement par les futurs utilisateurs du package) et les autres (celles qui servent au(x) développeur(s) uniquement) | ||
- 📁 '''R''': contient l'ensemble des scripts correspondant aux codes des fonctions | |||
- 📁 '''man''': (pour "manual") contient l'ensemble des fichiers d'aide i.e. la documentation associée à chaque fonction | |||
== Documentation des fonctions == | |||
La documentation des fonctions se fait via l'usage du package Roxygen. | |||
Dans les options de projet sur RStudio (Tools => Project, faire | |||
''Build tools => cocher "Generate documentation with Roxygen"'' | |||
ou bien<syntaxhighlight lang="r"> | |||
usethis::use_package_doc() | |||
</syntaxhighlight>On peut par la suite dans l'éditeur se placer sur le corps d'une fonction, puis faire | |||
🪄 => Insert Roxygen Skeleton (ou Ctrl + Alt + Shift + R) | |||
Un squelette Roxygen est alors créé. Voici à quoi il ressemble (en supposant que votre fonction compte deux arguments arg1 et arg2<syntaxhighlight lang="r"> | |||
#' Title | |||
#' | |||
#' @param arg1 | |||
#' @param arg1 | |||
#' @return | |||
#' @export | |||
#' @examples | |||
</syntaxhighlight>Et voici comment vous pouvez le compléter :<syntaxhighlight lang="r"> | |||
#' Estimates the value of the John Doe thingy | |||
#' | |||
#' @param arg1 number of this. Defaults to blah. | |||
#' @param arg2 type of blah. You can choose among values "blah" or "blablah". | |||
#' @return The estimates of blah | |||
#' @export | |||
#' @examples | |||
blah <- mean(blahblah) | |||
f(blah) | |||
</syntaxhighlight>On peut alors faire | |||
''Build => More => Document (ou Ctrl + Shift + D)'' | |||
Les fichiers d'aide (dans 📁 '''man''') seront alors générés automatiquement | |||
== Correction formelle du package == | |||
On peut procéder à une '''vérification du package''' (R CMD check) en procédant comme suit: | |||
''Build => Check'' | |||
Un certain nombre de vérifications sont exécutées, et vous obtiendrez en sortie un certain nombre d'erreurs, warnings ou notes qui vous orienteront sur des problèmes éventuels dans le code (et/ou la documentation) de vos fonctions. | |||
Par exemple, un warning: | |||
"Noms d'arguments dans le code mais pas dans la doc: arg3" | |||
Cette vérification constitue une première évaluation du "'''niveau de qualité formelle'''" du package. | |||
== "Build" du package == | |||
''Build => Install and Restart'' | |||
permet de "construire" et charger le package. Cela permet notamment au développeur de tester les fonctions qu'il vient de développer "comme si" il était un utilisateur venant d'installer et charger le package dans son état actuel de développement | |||
== Partage du package == | |||
Dans un premier temps, on peut partager son package en version "dev", par exemple en lui faisant correspondre un '''repo github.''' | |||
Pour cela: créez sur votre compte github un '''repo correspondant au nom du package''' (par exemple "blabla") | |||
Indiquez à RStudio que vous allez utiliser '''git''': | |||
''Tools => Project Options => Git/SVN => Version control system: Git'' | |||
Les opérations classiques de Git (commit, push notamment) deviennent réalisables depuis un menu Git en haut à droite de RStudio | |||
Indiquez en premier lieu l''''origine distante du repo''' | |||
par exemple https:://github.com/lvaudor/blabla | |||
puis vous pouvez commencer à réaliser commits et pushs. | |||
Votre package est installable par les utilisateurs via `devtools`: | |||
<syntaxhighlight lang="r"> | |||
devtools::install_github("lvaudor/blabla") | |||
</syntaxhighlight>Indiquez-le dans un fichier README qui s'affichera en "page d'accueil" de votre repo github. | |||
== Dépendances == | |||
Le package utilise des fonctions provenant d'autres packages. Pour lister un package parmi les dépendances, on peut faire:<syntaxhighlight lang="r"> | |||
usethis::use_package("nom_package") | |||
</syntaxhighlight>et le package sera ajouté à la liste des "Imports" dans le fichier 📋 '''DESCRIPTION''' | |||
== Tests == | |||
On peut mettre au point une batterie de "tests unitaires" pour s'assurer régulièrement du bon fonctionnement du package. Pour ce faire on peut utiliser le package '''testthat'''<syntaxhighlight lang="r"> | |||
usethis::use_testthat() | |||
</syntaxhighlight>va créer | |||
- 📁 tests/testthat et | |||
- 📋 tests/testthat.R | |||
Pour tester une fonction `f` en particulier:<syntaxhighlight lang="r"> | |||
usethis::use_test("f") | |||
</syntaxhighlight>va créer 📋 tests/testthat/test-f.R qui contient un exemple de test unitaire | |||
== Dépôt du package == | |||
Quand le package est "assez mûr" il est possible de le déposer auprès du CRAN (qui va procéder à une batterie de vérifications formelles) ou d'autres instances type ROpenSci ("review" de package plus large: utilité, convivialité, etc.). | |||