Structure d’un package R

Cours

Auteur·rice

Affiliation

Frédéric Santos

CNRS, Univ. Bordeaux, MCC – UMR 5199 PACEA

Avant de commencer à créer notre propre package, commençons par observer et étudier la structure générale d’un package R. Tout ce qui suit est un condensé de la documentation officielle de R sur le sujet, que vous pourrez trouver sur la page Writing R extensions.

Prenons l’exemple du package {ClusterR}, disponible sur le CRAN mais également développé sur GitHub. Comme nous allons le voir, ce package est un exemple intéressant de l’application des bonnes pratiques de développement développées dans le chapitre précédent.

Si l’on inspecte (par exemple à partir de GitHub) le contenu de ce package, nous avons la structure générale suivante :

.
├── data
│   ├── dietary_survey_IBS.rda
│   ├── mushroom.rda
│   └── soybean.rda
├── DESCRIPTION
├── Dockerfile
├── inst
│   ├── CITATION
│   ├── include
│   └── papers_references
├── man
│   ├── AP_affinity_propagation.Rd
│   ├── AP_preferenceRange.Rd
│   ├── ...
│   └── tryCatch_optimal_clust_GMM.Rd
├── NAMESPACE
├── NEWS.md
├── R
│   ├── clustering_functions.R
│   ├── ClusterR.R
│   └── RcppExports.R
├── README.md
├── src
│   ├── export_inst_folder_headers.cpp
│   ├── ...
│   └── RcppExports.cpp
├── tests
│   ├── testthat
│   └── testthat.R
├── tic.R
└── vignettes
    ├── dog.jpg
    ├── ...
    ├── Rplot.png
    └── the_clusterR_package.Rmd

Détaillons le rôle de la plupart de ces éléments (les quelques éléments laissés de côté seront abordés lors de la dernière matinée de la formation).

• Le dossier R/ est le coeur du package : il contient le code source R des fonctions du package. Notons à ce stade qu’il n’est pas strictement nécessaire d’avoir un fichier .R séparé pour chaque fonction implémentée dans le package : chaque fichier .R peut contenir le code source de plusieurs fonctions. C’est d’ailleurs le cas du fichier clustering_functions.R de ce package.
• Son cousin le dossier src/ est destiné à recevoir du code source écrit en d’autres langages que R (ici, du C++).
• Le dossier man/ contient la documentation des fonctions implémentées dans le package. L’extension de ces fichiers est .Rd, et [la syntaxe de ces fichiers ressemble à une forme allégée de syntaxe LaTeX].
• Le dossier data/ inclut de petits jeux de données (au format spécifique .Rda) qui viennent directement avec le package, notamment pour faciliter l’écriture d’extraits de code reproductibles détaillant le fonctionnement du package.
• Le dossier tests/ contient une série de tests unitaires destinés à vérifier le bon fonctionnement du package et à empêcher l’apparition de régressions.
• Le dossier vignettes/ permet de générer une ou plusieurs vignettes pour détailler l’utilisation du package.
• Le dossier inst/, totalement facultatif, contient usuellement des fichiers annexes, non strictement nécessaires au fonctionnement du package, mais potentiellement utiles à l’utilisateur final (informations sur la façon de citer le package, fichiers de données dans des formats bruts, etc.).
• Le fichier DESCRIPTION contient des métadonnées basiques du package : auteur, titre, licence, dépendances à d’autres packages R…
• Le fichier NAMESPACE gère plus finement les dépendances à d’autres packages, et décide notamment aussi quelles fonctions devront être exportées (c’est-à-dire directement utilisables par l’utilisateur final) ou non (auquel cas elles restent des fonctions internes du package, “cachées” à l’utilisateur final).
• Le fichier .Rbuildignore liste l’ensemble des fichiers qui devront être ignorés par R au moment de compiler et construire le package.
• Enfin, les fichiers NEWS.md et README.md contiennent respectivement des informations sur les mises à jour du package, et sur l’objectif général du package.

Créer un package R passe donc par le fait de peupler l’ensemble de ces dossiers et fichiers avec du code R ou de la focumentation.

Notons que certains de ces éléments devront forcément être créés à la main par l’auteur du package (par exemple, le code source .R), alors que certains autres fichiers pourront être créés programmatiquement plutôt qu’écrits à la main. C’est notamment le cas des fichiers de documentation .Rd, comme nous le verrons plus tard.