Cours 5 — Packaging 📦

Patrick Fournier

MAT8186 — Techniques avancées en programmation statistiques R

Automne 2023

Qu'est-ce qu'un package?

Définition

Terminologie

Package
Répertoire de fichiers ajoutant des fonctionnalités à R
Source
Ensemble des fichiers utilisés pour le développement d'un package
Bundle
Tarball (archive) contenant le package
Installed
Ce que l'on obtient en exécutant R CMD INSTALL sur un package
Binary
zip ou tarball contenant les fichiers d'un package installé

Outils

  • Parfaitement possible de créer un package à la main
  • devtools simplifie la tâche
  • Référence rapide (cheat sheet)
  • Plusieurs fonctionalités de devtools sont intégrées à RStudio

Structure d'un package

.gitignore
fichiers ignorés par git
.Rbuildignore
fichiers ignorés lors de la création du bundle
<nom>.Rproj
fichier de configuration de RStudio
DESCRIPTION
Métadonnées du package
NAMESPACE
Symboles importés/exportés
man
documentation
R
Code R

DESCRIPTION: champs obligatoires

Package
nom du package
Version
version du package
License
licence sous laquelle est distribué le package
Title
description courte
Description
description longue
Author
auteurs du package (nom, e-mail, rôle)
Maintainer
Responsable (unique) du package

DESCRIPTION: champs falcultatifs 1

Copyright
détenteur du copyright
Date
date de sortie du package
Depends
dépendances attachées
Suggest
packages utiles qui ne sont pas des dépendances
Imports
dépendances non attachées
Collate
ordre de chargement des fichiers R/
URL
liste d'URL liés au package

DESCRIPTION: champs facultatifs 2

BugReports
URL pour la soumission des bugs
LazyData
les données doivent être chargées paresseusement
ByteCompile
le package doit être byte compilé
BuildVignette
les vignettes doivent être construites
NeedsCompilation
le package nécessite une phase de compilation

DESCRIPTION: recommandations

  • Possible d'utiliser des champs arbitraires
  • Depends ne devrait être utilisé que pour spécifier une version minimale de R
  • Imports, Suggests, Enhances et Linkingto ne devraient jamais être modifiés à la main \( \Rightarrow \) usethis::use_package
  • Authors@R doit contenir un vecteur d'objets de classe person

Documentation & namespace

Roxygen2

  • Documentation: répertoire man/
  • Pas nécessaire/souhaitable de la modifier par nous-même
  • Roxygen2 génère la documentation automatiquement
  • Utilise les commentaires commençant par #'
  • Mise à jour: devtools::document
Exemple de documentation 

                    #' Titre
                    #'
                    #' Le second paragraphe est toujours la description.
                    #' Le premier paragraphe est le titre et ne devrait
                    #' pas être plus long qu'une phrase. Ce paragraphe
                    #' donne une description générale de l'objet à
                    #' documenter.
                    #'
                    #' L'ensemble des paragraphes suivants contient
                    #' les détails de l'objet à documenter.
                    mafonction <- function()

Documentation du package

  • Il est d'usage de documenter le package lui-même
  • Documenter la chaîne de caractère _PACKAGE

Tags usuels

@param
décrit un des arguments d'une fonction
@examples
code R valide
@return
valeur de retour d'une fonction
@format
apperçu de la structure d'un jeu de données
@references
publication liée à l'objet documenté
@seealso
autre ressources liées à l'objet

Shadowing


                r$> address <- function() "PK-5323"
                r$> x <- 42
                r$> address
                [1] "PK-5323"

                r$> pryr::address(x)
                [1] "0x560e0faa1e48"
            

                r$> library(pryr)
                Attaching package: ‘pryr’
                The following object is masked _by_
                ‘.GlobalEnv’:
                    address

                r$> address(x)
                Error in address(x): unused argument (x)

Namespace

  • La plupart des packages rendent disponibles certains symboles
  • Chaque package possède son propre namespace
  • library(pkg) attache pkg
  • \( \Rightarrow \) Symboles exportés par pkg disponible dans l'environement global
  • \( \Rightarrow \) Risque de conflit
  • Possible de charger un package sans l'attacher
  • Nécessaire de référer explicitement aux symboles: ::

Fichier NAMESPACE

  • Namespace: controlé par le fichier NAMESPACE
  • Ne devrais jamais être modifié à la main
  • Peut être géré à partir de commentaires Roxygen2
  • Chaque modification doit être suivie d'un devtools::document() pour prendre effet

Importation

  • 99% du temps: Import et ::
  • Import: pkg s'assure que pkg est installé
  • pkg::obj charge automatiquement pkg sans l'attacher
  • Possible impact sur la performance causé par ::
  • Solution: attacher obj

                #' @importFrom pkg obj

Exportation

  • \( \Rightarrow \) ajouter une entrée dans NAMESPACE
  • On utilise Roxygen
  • tag: @export
  • Avantage: Détermine automatiquement si "fonction normale", méthode S3, etc