Voir la source de R: construire un package

[[Catégorie:Tutoriel]]

Cette page reprend quelques idées de base pour faciliter la '''construction d'un package sous R'''.

== Pour qui construire un package? ==

- 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 '''installation''' plutôt que par des copier-collers de code.

== Pourquoi construire un package? ==

- 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 '''partager''' et '''valoriser''' ses codes
== Création de l'arborescence des fichiers ==

Dans le menu principal de RStudio, faire:

''File => New Project => New Directory => R package''

Le dossier est automatiquement construit et contient:

- ⚙️ '''.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)

- 📁 '''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'''

=== Cas spécial: dépendance à l'opérateur pipe %>% ===

<syntaxhighlight lang="r">
usethis::use_pipe()
</syntaxhighlight>

== 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.).