Chapitre 1 Construire un package

Nous présentons ici comment construire un package efficacement à l’aide d’outils graphiques présents dans RStudio et du package devtools.

Le support de référence sur ce sujet est le livre R packages¹ d’Hadley Wickham & Jennifer Bryan, disponible en ligne.

1.1 Initialiser un package

Une manière simple, et intégrée à RStudio, pour initialiser un package est d’executer les étapes suivantes :

👉 À vous de jouer (déjà)!

créer un nouveau projet (menu déroulant en haut à gauche dans RStudio)

choisir “New Directory”

choisir “R package using devtools” (s’il n’est pas disponible c’est que le package devtools n’est pas installer et dans ce cas on peut alors choisir “R package” – la différence étant qu’avec “R package”, il faudra supprimer des fichiers créés automatiquement mais inutiles)

donner un nom au package, par exemple mypkgr.

On récupère alors la structure minimale pour un package , à savoir :

un fichier DESCRIPTION dont les parties Title, Version, Authors@R et Description sont à éditer (d’autres parties pourront être éditer voire même ajouter de manière automatique, comme nous le verrons plus loin)
un fichier NAMESPACE qui sera édité automatiquement ultérieurement
un dossier R/ dans lequel on va ajouter des fichiers de scripts .R

devtools ajoute également trois fichiers facultatifs :

.gitignore, relatif à git, outils de contrôle de version que nous verrons en détails dans la partie suivante sur git & GitHub
mypkgr.Rproj qui est un fichier spécifique de RStudio, et permet de définirles caractéristiques et préférences du projet que nous venons de créer
.Rbuildignore qui permet d’ignorer certains fichiers au moment où on construira le package un peu plus loin (par exemple, le fichier mypkgr.Rproj ne doit pas être inclus dans le package)

1.2 Ajouter une fonction : exemple fil rouge

Nous vous proposons de coder la fonction suivante, que nous reprendrons tout au long de la formation :

Nous souhaitons calculer la valeur de la densité d’une loi normale multivariée sur \(\mathbb{R}^p\) en \(n\) points. Notre fonction doit pouvoir s’appliquer pour n’importe quelle loi normale multivariée (vecteur de moyennes \(\boldsymbol \mu\) dans \(\mathbb{R}^p\) et matrice de variance-covariance \(\boldsymbol\Sigma\) d’ordre de \(p\) quelconques), et on souhaite pouvoir calculer toutes les valeurs de la densité évaluées sur les \(n\) points \(\mathbf{x}\) en un seul appel de la fonction.

Pour rappel, la fonction de densité d’une loi normale multivariée s’écrit : \[\displaystyle (2\pi )^{-p/2}\det({\boldsymbol {\Sigma }})^{-1/2}\,\exp \left(-{\frac {1}{2}}(\mathbf {x} -{\boldsymbol {\mu }})^{\mathsf {T}}{\boldsymbol {\Sigma }}^{-1}(\mathbf {x} -{\boldsymbol {\mu }})\right)\]

Vous devez donc créer une fonction mvnpdf() dans un fichier nommé mvnpdf.R dans le dossier R/ du package, qui :

prend en arguments :
- x une matrice, à \(n\) colonnes (les observations) et \(p\) lignes
- mean un vecteur de moyennes
- varcovM une matrice de variance-covariance
- Log un paramètre logique valant TRUE par défaut
renvoie une liste contenant la matrice x ainsi qu’un vecteur des images des points de x par la fonction de densité de la variable aléatoire de loi normale multivariée considérée.

👉 À vous de jouer !

Voici une proposition de fonction que vous pouvez télécharger ici. ⚠️ ATTENTION ! Si vous cliquez trop vite sur le lien ci-dessous, cela invalidera votre participation à la formation !

Pour des conseils lors de la rédaction de code, voir le chapitre R code dans R packages (2023) de Wickham & Bryan².

1.3 Documenter une fonction

Il est important de bien documenter votre code. Tout projet a au moins 2 développeurs :

vous
vous dans 6 mois

Par égard à votre “futur vous”, soyez sympas et prenez le temps de documenter votre code 😉 !

Nous vous conseillons vivement d’utiliser le package roxygen2 pour documenter vos packages. L’avantage principal étant d’avoir l’aide d’une fonction dans le même fichier que le code définissant cette fonction.

👉 À vous de jouer !

Commencer par insérer le squelette de l’aide grâce à “Insert Roxygen Skeleton” situé dans le menu “Code” ou le sous-menu Baguette magique dans la fenêtre de script.

Compléter la documentation en renseignant :

le titre de la fonction (première ligne)

la description de ce que fait la fonction (deuxième paragraphe)

si vous renseignez un troisième paragraphe, cette partie ira dans la section “Details” de la page d’aide

la signification des paramètres

la sortie, après la balise @return

Générer la documentation à l’aide de “Document” dans le menu “More” de l’onglet “Build” (ou Ctrl+Shift+D ou devtools::document()). L’effet de cette commande est multiple :

un dossier man a été créé et à l’intérieur, un fichier mvnpdf.Rd a été créé et contient les informations de l’aide de la fonction

le fichier NAMESPACE a été modifié

En cas de bug ou par curiosité ET une fois que vous avez terminé vous pouvez consulter cette proposition.

Pour plus de détails sur la documentation de package et les balises roxygen2, voir la page Object documentation du site d’Hadley.

Finissons par évoquer une fonction du package usethis qui initialise une page d’aide pour le package dans son ensemble :

usethis::use_package_doc()

La page d’aide générée sera alors accessible, une fois le package installé, via :

?mypkgr

1.4 Tester le package de manière intéractive

Pour tester le package, vous devez le charger dans R à l’aide de : dans l’onglet “Build”, le menu “More” puis “Load All” (ou Ctrl+Shift+L ou devtools::load_all()).

Vous pouvez alors utiliser votre package directement dans R : consulter l’aide de la fonction avec ?mvnpdf et par exemple exécuter les commandes renseignées dans la section exemple de cette page d’aide.

?mvndpf

Ainsi, lors du développement, vous pouvez :

Ajouter/Modifier le code
Re-charger le package Ctrl+Shift+L
L’essayer dans la console
Et ainsi de suite…

1.5 Tester le package de manière automatique

Pour initialiser la fonctionnalité de tests automatiques dans le package, executer la commande suivante :

usethis::use_testthat()

Cette commande induit la création d’un dossier tests qui comprend un fichier testthat.R – à ne pas modifier – et un dossier testthat/ dans lequel on va insérer nos tests. Cet outils s’appuie sur la théorie des tests unitaires.

Voici par exemple le contenu d’un fichier contenant 2 tests qui devrait s’appeller test-mvnpdf.R à mettre dans le dossier testthat/ (plutôt que de le créer vous-même, vous pouvez simplement utiliser la fonction usethis::use_test() qui créera le fichier pour vous en le plaçant directement au bon endroit) :

test_that("correct result for univariate gaussian", {
  expect_equal(mvnpdf(x=matrix(1.96), Log=FALSE)$y, dnorm(1.96))
  expect_equal(mvnpdf(x=matrix(c(1.96, -0.5), ncol = 2), Log=FALSE)$y,
               dnorm(c(1.96, -0.5)))
})

test_that("correct results for bivariate gaussian", {
  expect_equal(mvnpdf(x=matrix(rep(1.96,2), nrow=2, ncol=1), Log=FALSE)$y,
               mvtnorm::dmvnorm(rep(1.96, 2)))
})

Pour exécuter ces tests, on peut utiliser “Test package” (Ctrl+Shift+T) du menu “More” dans l’onglet “Build”, ou alors executer devtools::test() dans la console.

L’avantage de ces tests automatiques est qu’ils vont s’exécuter à chaque fois qu’on effectuera un check du package.

Une bonne pratique est d’ajouter un test unitaire à chaque fois qu’un bug est identifié et résolu, afin de pouvoir immédiatement identifier et prévenir qu’une erreur identique ne se reproduise dans le futur.

1.6 Faire un check du package

Faire un check signifie vérifier que tout est correct dans le package et fonctionne comme attendu, afin que l package puisse s’installer sans problème sur différents systèmes d’exploitation. Il est impératif de “passer” le R CMD CHECK pour pouvoir déposer un package sur le CRAN.

Pour exécuter celui-ci, utiliser “Check” (Ctrl+Shift+E) dans l’onglet “Build”, ou alors executez devtools::check() dans la console.

Lors du R CMD CHECK, les tests que nous avons mis au point précédemment sont exécutées. C’est justement l’avantage d’avoir fait ces tests, nous n’avons plus besoin de s’en préoccuper, mais juste de réagir en cas d’erreurs renvoyées.

1.7 Installer le package

Pour le moment, le package n’existe que dans l’environnement associé au projet Rstudio qu’on a créé. Pour pouvoir l’utiliser dans R de manière générale, il faut l’installer (comme un package du CRAN par exemple).

Pour faire ça, utiliser “Install and Restart” Ctrl+Shift+B dans l’onglet “Build” (devtools::install() ou ).

Et enfin, vous pouvez configurer le comportement de RStudio pour qu’au moment de l’installation, il documente en même temps le package : aller dans l’onglet “Build”, le menu “More” puis “Configure Build Tools…”. Cliquer ensuite sur “Configure” juste à côté de “Generate documentation with Roxygen” puis cocher la case “Install and Restart”.

Annexe 1.1 : ajouter une méthode S3

Dans la plupart des packages on est amenés à implémenter des méthodes S3, très souvent pour qu’à partir d’un objet résultat res, on puisse exécuter print(res), summary(res), plot(res)…

Voici un exemple de méthode plot() qu’on peut ajouter dans notre package :

#' Plot of the mvnpdf function
#'
#' @param x an object of class \code{mvnpdf} resulting from a call of
#' \code{mnvpdf()} function.
#' @param ... graphical parameters passed to \code{plot()} function.
#'
#' @return Nothing is returned, only a plot is given.
#' @export
#'
#' @examples
#' pdfvalues <- mvnpdf(x=matrix(seq(-3, 3, by = 0.1), nrow = 1), Log=FALSE)
#' plot(pdfvalues)
plot.mvnpdf <- function(x, ...) {
  plot(x$x, x$y, type = "l", ...)
}

⚠️ ATTENTION ! Pour que cette méthode fasse bien ce qu’on veut quand on l’applique au résultat de notre fonction mvnpdf(), il faut déclarer que ce résultat est de classe mvnpdf.

Tester cette fonction, en exécutant l’exemple.
N’oubliez pas de réinstaller le package (“Install and Restart” ou Ctrl+Shift+B).

Consulter le contenu du dossier man et les modifications qui ont été apportées au fichier NAMESPACE.

Voici une proposition de solution : le fichier contient le code complet de la fonction mvnpdf() et de la méthode plot() associée.

Annexe 1.2 : soumettre son package au CRAN

Executer les 2 commandes suivantes : devtools::check() puis devtools::submit_cran().

Pour plus de détails, voir la procédure recommandée dans Wickham & Bryan (2023)³

Présentation de la formation

2 Contrôle de version avec git et GitHub: historique de changement, développement collaboratif et intégration continue