R avancé et introduction à Git
Raphaël Nedellec
Les packages
Un package
Un ‘package’ ou une ‘librairie’ rassemble du code, des données, de la documentation et des tests ensemble et est facile à partager.
- Pourquoi faire un package ?
- Qu’est-ce qu’un package et comment développer un package ?
- Tester et documenter son package.
Pourquoi faire un package ?
Motivation
Pour le développeur :
- Se faciliter la vie, s’organiser ;
- mutualiser et maintenir des fonctions en un seul endroit ;
- monter en compétence ;
- documenter et partager avec la communauté sous un format standardisé.
Motivation
Pour l’utilisateur :
- Utiliser des outils testés et validés par la communauté ;
- gagner en efficacité et optimalité ;
- accélérer les différents processus de data science.
CRAN
- Dépôt officiel historique
- Plusieurs miroirs disponibles
- “Validation” des packages
- Liste de librairie par thèmes
Github
Github
Github et Git
Voir cours n°2
Installer, charger
Installer un package :
install.packagesen R base, depuis le CRAN ou des sourcesremotes: librairie permettant l’installation depuis le CRAN et différents dépôt de code programmaticalement, tels que github, gitlab, bitbucket, ainsi que Bioconductor.pak: librairie pour l’installation interactive de packages
Développer un package
Développer un package
- usethis Outil de setup et d’aide aux développement d’une librairie.
- devtools Sorte de
tidyversedu développement de librairie.
Utilisation interactive
usethis est un outil d’aide au développement : vous l’utiliserez toujours (ou presque) interactivement, en appelant les instructions dans la console R, et non par le biais de scripts !
Structure d’un package
Arborescence : randomForest
Code R/
Contient le code R du package.
- Ce code est exécuté au
build time; - différent d’un script/ d’une analyse interactive dans RStudio où le code est exécuté au
run time.
Pas de sous-dossier
Utilisez des préfixes “smthing-*.R” pour organiser les fichiers par thème
Code R/
Contient le code R du package.
- Ce code est exécuté au
build time; - différent d’un script/ d’une analyse interactive dans RStudio où le code est exécuté au
run time.
Points de vigilance
- Ne modifiez pas le système de l’utilisateur ! Pas d’appels aux fonctions
source,librarydans le code d’un package - Utilisez avec vigilance
par,options,setwd…
Exemple R/
Contenu des fichiers
Rester cohérent et clair sur le contenu des fichiers - ni trop, ni pas assez. Dépend du contexte.
data/
- Partage de dataset utiles au package pour la documentation, les exemples, le fonctionnement interne du package ;
- data packages : nycflights13, babynames ;
- organisation différentes en fonction des données et de leur utilité.
usethis
Voir usethis::use_data()
data/
- Stocker des objets R pour qu’ils soient disponibles pour les utilisateurs :
data/au format.rda/.RData - Stocker des objets à des fins de développement :
R/sysdata.rda - Stocker des objets au format brut (xls, xlsx, json, ..) :
inst/extdata/
Préserver la reproducibilité des datasets
Voir usethis::use_data_raw()
man/
man/
vignettes/
vignettes/
man/ et vignettes/
- Il est possible d’écrire les documents .Rd à la main. Mais il recommandé d’utiliser
roxygen2pour les générer automatiquement ! roxygen2est bien intégré au workflowdevtools- Les vignettes sont des guides d’utilisation détaillés pour le package ou certaines de ses fonctionnalités.
- À écrire en Rmarkdown ou en quarto
Autres dossiers
inst/: pour les fichiers additionnels à inclure dans la librairie ;src/: pour stocker des fichiers sources et “header” C/C++/… et utiliser du code compilé dans un package R ;demo/,exec/,po/,tools/, …
Plus d’informations
Voir le chapitre dédié dans R packages
Metadata : DESCRIPTION
Package: mynewpackage
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R:
person("First", "Last", , "first.last@example.com", role = c("aut", "cre"),
comment = c(ORCID = "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.1
Suggests:
testthat (>= 3.0.0)
Config/testthat/edition: 3Metadata : DESCRIPTION
Title: Décrire en une phrase la librairieDescription: Décrire de manière plus détaillée l’intérêt et les fonctionnalités de la librairieAuthors@R: Les auteurs. Voir?person().Version: Version du package. Important de le maintenir à jour, voir chapitre dédié dans R avancé.License: Quelle licence et quels droits d’utilisation ?Suggests,Imports, and others : Gestion des dépendances avec des librairies tierces.
Quand utiliser des dépendances ?
Plusieurs critères et questions à se poser :
- Type de dépendance
- Nombre de dépendances indirectes induites
- Coût d’installation des dépendances (dépendances systèmes, code compilé, taille des packages)
- Maintenance et suivi des librairies
- Criticité des fonctionnalités
Dépendances : DESCRIPTION
Imports: Les packages listés ici doivent être présents et installés pour que votre librairie fonctionne.Suggests: Votre package peut utiliser ces dépendances, mais ne sont pas nécessaires à son fonctionnement. Par exemple, ces packages peuvent être utilisés dans les vignettes ou les tests.
DESCRIPTION
Les dépendances déclarées dans le fichier DESCRIPTION aident R à valider la présence des packages nécessaires et à les installer lors de l’installation de votre package.
Dépendances : NAMESPACE
Quelle fonction here() est disponible dans l’environnement global ?
Dépendances : NAMESPACE
Dépendances : NAMESPACE
Que se passe-t-il lorsque l’on déclare une nouvelle fonction var ?
Cela est possible grâce au namespace du package stats où la fonction var du package stats est déjà référencée.
Dépendances : NAMESPACE
Exemple tiré du package remotes
# Generated by roxygen2: do not edit by hand
S3method(format,bioc_git2r_remote)
S3method(format,bioc_xgit_remote)
...
export(add_metadata)
export(available_packages)
...
importFrom(stats,update)
importFrom(tools,file_ext)roxygen2
Une bonne pratique aujourd’hui est d’utiliser roxygen2 pour générer automatiquement le fichier NAMESPACE
Dépendances : NAMESPACE
importFrom: importe un objet (fonction) d’une dépendanceimport: importe tous les objets exportésS3method: pour exporter une méthode S3export: pour exporter une fonction (rendre une fonction publique)
Autres instructions
Plus rares : useDynLib(), exportPattern(), exportClasses(), exportMethods(), importClassesFrom(), importMethodsFrom()
Développer un package
Un exemple de workflow avec Devtools
Setup
Création d’un squelette de package :
RStudio initialise un nouveau projet.
Setup : nouveau projet
Nouveau projet
En utilisant l’interface graphique, il est possible de créer des projets avec des templates, dont des packages. Ceci utilise in fine usethis.
Écrire et documenter ses fonctions
- les fonctions sont dans des fichiers .R au sein du répertoire R/
- il faut documenter ses fonctions en utilisant les balises
roxygen2
usethis
usethis::use_r pour créer un fichier .R dans le répertoire R/, ou naviguer dans celui-ci dans RStudio.
roxygen2
Resultats ?
roxygen2
Résultats :
roxygen2
#' @param data A data.frame
#' @param col A string, the column name for which we compute the stats
#' @param by A string, the column name by which we group
#' @param stats A string, the name of the function. Must be one of "mean",
#' "min", "max".
compute_stats_by_levels <- function(
data, col, by, stats
) {
if (stats %in% c("mean", "max", "min")) {
res <- tapply(data[[col]], data[[by]], stats)
} else {
stop("wrong stats")
}
return(res)
}#' @param data A data.frame
#' @param col A string, the column name for which we compute the stats
#' @param by A string, the column name by which we group
#' @param stats A string, the name of the function. Must be one of "mean",
#' "min", "max".
compute_stats_by_levels <- function(
data, col, by, stats
) {
if (stats %in% c("mean", "max", "min")) {
res <- tapply(data[[col]], data[[by]], stats)
} else {
stop("wrong stats")
}
return(res)
}roxygen2
#' @param data A data.frame
#' @param col A string, the column name for which we compute the stats
#' @param by A string, the column name by which we group
#' @param stats A string, the name of the function. Must be one of "mean",
#' "min", "max".
#'
#' @export
compute_stats_by_levels <- function(
data, col, by, stats
) {
if (stats %in% c("mean", "max", "min")) {
res <- tapply(data[[col]], data[[by]], stats)
} else {
stop("wrong stats")
}
return(res)
}#' @param data A data.frame
#' @param col A string, the column name for which we compute the stats
#' @param by A string, the column name by which we group
#' @param stats A string, the name of the function. Must be one of "mean",
#' "min", "max".
#'
#' @export
compute_stats_by_levels <- function(
data, col, by, stats
) {
if (stats %in% c("mean", "max", "min")) {
res <- tapply(data[[col]], data[[by]], stats)
} else {
stop("wrong stats")
}
return(res)
}roxygen2
#' A Function to Compute Group Statistics
#'
#' @description This function is designed for example only and is not really usefull..
#'
#' @param data A data.frame
#' @param col A string, the column name for which we compute the stats
#' @param by A string, the column name by which we group
#' @param stats A string, the name of the function. Must be one of "mean", "min", "max".
#' @return A named vector statistics, of size `length(unique(data[[col]]))`
#'
#' @export
#' @examples
#' compute_stats_by_levels(mtcars, "mpg", "cyl", "mean")
compute_stats_by_levels <- function(
data, col, by, stats
) {
if (stats %in% c("mean", "max", "min")) {
res <- tapply(data[[col]], data[[by]], stats)
} else {
stop("wrong stats")
}
return(res)
}#' A Function to Compute Group Statistics
#'
#' @description This function is designed for example only and is not really usefull..
#'
#' @param data A data.frame
#' @param col A string, the column name for which we compute the stats
#' @param by A string, the column name by which we group
#' @param stats A string, the name of the function. Must be one of "mean", "min", "max".
#' @return A named vector statistics, of size `length(unique(data[[col]]))`
#'
#' @export
#' @examples
#' compute_stats_by_levels(mtcars, "mpg", "cyl", "mean")
compute_stats_by_levels <- function(
data, col, by, stats
) {
if (stats %in% c("mean", "max", "min")) {
res <- tapply(data[[col]], data[[by]], stats)
} else {
stop("wrong stats")
}
return(res)
}roxygen2 : balises
@title,@description,@detail: pour présenter et détailler sa fonction. Peuvent être implicites.@param: pour documenter les paramètres de la fonction@return: quel est l’output de la fonction@examples: suite d’examples@export: pour exposer la fonction dans le NAMESPACE@importFrom: quand la fonction importe une fonction depuis une librairie tierce@noRd: pour documenter la fonction mais ne pas exposer la documentation publiquement
roxygen2
- Possibilité d’utiliser des balises Mardown dans la documentation.
- Possibilité de réutiliser/mutualiser de la documentation entre fonctions, en utilisant les balises
@describe,@rdname,@inheritParams,@inheritSection,@inherit - Pour documenter des fonctions, mais aussi des datasets.
Liste des balises
https://roxygen2.r-lib.org/articles/rd.html pour le processus de base https://roxygen2.r-lib.org/reference/tags-rd.html pour la liste exhaustive
roxygen2 : en résumé
- documentez vos fonctions avec les balises roxygen2
- roxygen2 générera la documentation et le NAMESPACE de votre package
- multiples balises disponibles, et il est possible de moduler la documentation ;
- s’intègre au workflow de développement
devtools
Testing
Tester vos fonctions
En développement logiciel (donc quand vous développez une librairie / des fonctions en R) :
- il faut tester vos fonctions pour s’assurer qu’elles se comportent comme attendu ;
- de manière reproductible et non de manière informelle et ad’hoc ;
- un bug : un nouveau test à ajouter ;
- évaluer la couverture des tests et la robustesse du code.
testthat
Framework dominant pour l’écriture de tests en R.
# from dplyr test suite
# https://github.com/tidyverse/dplyr/blob/2af5c86112c697a8abf114eb5dc323e5116777bc/tests/testthat/test-bind-cols.R#L33
test_that("bind_cols() handles all-NULL values (#2303)", {
expect_identical(bind_cols(list(a = NULL, b = NULL)), tibble())
expect_identical(bind_cols(NULL), tibble())
})testthat, exemple
Dans R/
Dans tests/testthat/test-myfunction.R
Quelques assertions
expect_equal()expect_identical()expect_type()expect_s3_class()expect_length()expect_true()expect_false()expect_error()expect_warning()expect_message()expect_condition()
Liste exhaustive ici
En résumé : processus de développement
Processus de développement d’une fonction
- Écrire sa fonction
- Documenter
- Écrire les tests associés (voir
usethis::use_testthat()et?usethis::use_test()) - Charger son package en émulant son installation avec
?devtools::load_all() - Itérer
Développement d’une librairie
- Développez vos fonctions et ajoutez vos datasets.
- Documenter.
devtools::document()permet de générer et mettre à jour automatiquement les différents documents (.Rd, NAMESPACE). - Testez régulièrement vos fonctions en utilisant
devtools::test()qui exécutera la suite de test de la librairie en développement. - Utilisez
devtools::check()si vous voulez tester la compatibilité avec le CRAN.
Développement d’une librairie
- Utilisez les bonnes pratiques et outils de développement logiciel : git, versioning, CI/CD, code coverage…
- Améliorer et maintenir la documentation, pourquoi pas avec
pkgdownet des vignettes détaillées.
Ressources additionnelles
Ressources additionnelles
Questions ?
R avancé et introduction à Git Raphaël Nedellec
Comment testez-vous une fonction ?