Comment écrire un package R

Lorsque vous voyez "R package", vous pouvez penser "Quelque chose à partager avec d'autres personnes". Mais un package R peut également être un bon moyen d'organiser votre propre travail rien que pour vous-même . Et surtout votre futur moi.

Les packages R vous donnent une structure cohérente, vous êtes donc plus susceptible de refactoriser le code en fonctions. Et, au moins aussi important: les packages vous offrent un moyen cohérent de documenter chacune de vos fonctions. Donc, l'année prochaine, il y a de meilleures chances que vous vous souveniez quelles parties de votre code font quoi.

Installation du système

Tout d'abord, vous souhaitez configurer votre système. Pour faciliter le développement de paquets, je suggère de vous assurer que ces bibliothèques sont installées sur votre système: devtools, usethis, roxygen2, testthat, knitr et rmarkdown.

Vous avez probablement également besoin d'un peu plus de configuration du système. Sous Windows, installez un logiciel appelé Rtools. C'est en fait une application logicielle, pas un package R. Sur un Mac, il est utile d'obtenir Xcode depuis l'App Store.

Si vous ne savez pas si votre système est prêt à écrire des packages, devtools a une fonction appelée has_devel()qui vérifie si votre environnement de développement de packages est OK. Je suggère de l'exécuter après avoir installé devtools.

Sharon Machlis /

Ensuite, vous pouvez créer un nouveau package dans RStudio en allant dans Fichier> Nouveau projet> Nouveau répertoire et en choisissant R Package.

On vous demande un nom de package et si vous voulez créer un référentiel Git (ce que je fais habituellement) et utiliser packrat (ce que je ne fais généralement pas).

Dans le panneau en bas à droite après la création du package, notez que quelques fichiers et deux répertoires ont été créés. 

Le sous-répertoire R est l'endroit où tous mes scripts R doivent vivre. Le dossier man est destiné à la documentation, en particulier aux fichiers d'aide aux fonctions . RStudio crée également un exemple de hello.Rfonction R.

Il y a également quelques fichiers importants dans le répertoire principal. Expliquer NAMESPACEpourrait être un article en soi, mais les débutants peuvent compter sur les outils de développement et utiliser ces packages pour s'en occuper.

DESCRIPTIONa des métadonnées requises importantes sur le package, vous devez donc les remplir. Ce sont principalement des choses simples comme le nom du package, l'auteur, la description et la licence. C'est aussi là que vont les dépendances des packages.

L'utilisation de ce package peut gérer le format de dépendance de package approprié pour vous. Par exemple, si vous avez besoin du package lubridate pour votre package, vous pouvez le charger avec library(usethis), puis l'exécuter use_package("lubridate")pour ajouter une dépendance. Vous pouvez voir comment cela ajoute automatiquement le texte nécessaire au DESCRIPTIONfichier dans la vidéo intégrée en haut de cet article (ou en exécutant un code similaire sur votre propre système).

Écrivez et documentez vos fonctions

Ensuite, écrivez n'importe quelle fonction comme d'habitude et enregistrez-la en tant que script R dans le répertoire R. Vous pouvez nommer le fichier comme vous le souhaitez et vous pouvez inclure une ou plusieurs fonctions dans le fichier.

Roxygen offre un moyen simple d'ajouter de la documentation à une fonction. Placez votre curseur n'importe où dans la définition de la fonction et choisissez l'option de menu RStudio Code> Insérer un squelette Roxygen.

Cela vous donne un échafaudage pour documenter la fonction d'une manière que R comprend, telle que 

#' Titre

# '

# '@param day

# '

#' @revenir

#' @exportation

# '

#' @exemples

Le champ Titre est assez explicite et vous pouvez également ajouter une ligne pour une courte description. Il y a une @paramligne pour chaque argument de fonction (dans cet exemple, la fonction a un argument appelé day) @return, et @examples. @paramest l'endroit où vous documentez le type de données qu'un argument doit être et pouvez donner une petite description. @returnindique quel type d'objet est retourné. @examplesn'est pas obligatoire, mais vous devez soit donner un exemple, soit supprimer cette valeur par défaut @examples.

Pour transformer cette structure en un fichier d'aide du package R, exécutez la devtools::document()fonction.

Maintenant, si vous regardez dans le répertoire man, vous devriez avoir un fichier d'aide Markdown pour votre nouvelle fonction (ainsi qu'un autre pour la hellofonction par défaut ).

Sharon Machlis,

Vous pouvez créer le package à l'aide de l'onglet RStudio Build. L'option Installer et redémarrer est idéale lorsque vous êtes en train de travailler sur votre code. Lorsque vous souhaitez le créer pour le partage, y compris pour obtenir un fichier source ou un fichier binaire, consultez la liste déroulante Plus dans l'onglet Générer.

Exécutez help(package = "yourpackagename")pour obtenir le fichier d'aide pour la nouvelle fonction.

Si vous souhaitez écrire une vignette de package, exécutez la fonction usethis package use_vignette()pour le configurer. Incluez le nom de la vignette souhaitée comme argument, par exemple usethis::use_vignette("Intro"). Vous devriez voir une vignette par défaut, dans laquelle vous pouvez remplir le titre de la vignette et le texte explicatif.

J'espère que cela suffit pour vous convaincre qu'il est assez facile d'écrire un package R de base! Vous pouvez faire beaucoup plus, comme ajouter des tests unitaires avec testthat.

Si vous souhaitez en savoir plus sur les tests, lisez mon précédent article intitulé "Testez votre code avec testthat". Et Hadley Wickham a un livre entier sur les packages d'écriture, disponible gratuitement en ligne sur r-pkgs.had.co.nz, bien qu'il soit un peu dépassé maintenant. Jenny Bryan de RStudio travaille avec Wickham sur une mise à jour. Vous pouvez voir un peu du travail en cours sur r-pkgs.org.