Guide packages R sous Unix - Informatique de MIA

Transcription

Version HTML
Introduction à la création de packages R sous Unix
A. Bouvier
Version 2_7 - juillet 2016
Ce document explique comment créer un package R: les étapes essentielles, ce qui est facultatif, comment traiter les
situations particulières et exploiter diverses possibilités. La procédure de soumission au CRAN est abordée en insistant
sur les points à vérifier pour minimiser les risques d'un refus. Enfin, des références vous permettront d'en savoir plus, ce
guide n'étant pas exhaustif.
Prérequis: le langage R et les normes de programmation.
Outils utilisés: Les tests ont été réalisés avec R 3.1.1 et devtools 1.5. La source des informations est le site "Writing R
Extensions" du CRAN.
La création d'un package avec RStudio n'est pas abordée ici.
Sommaire
Pourquoi faire un package R ? .......................................................................................................................................................................
p. 3
L'essentiel .......................................................................................................................................................................................................
p. 3
Qu'est-ce qu'un package R ? ...............................................................................................................................................................
p. 3
Préliminaire à la diffusion sur le CRAN ................................................................................................................................................
p. 3
Choisir une licence ...............................................................................................................................................................................
p. 3
La démarche de construction ...............................................................................................................................................................
p. 4
Fichier DESCRIPTION .........................................................................................................................................................................
p. 5
Fichier NAMESPACE ...........................................................................................................................................................................
p. 6
Répertoire man et fichiers Rd ...............................................................................................................................................................
p. 6
Répertoire R .........................................................................................................................................................................................
p. 6
Vérifier le package ................................................................................................................................................................................
p. 7
Construire le fichier tar-archive .............................................................................................................................................................
p. 7
Installer/utiliser le package ...................................................................................................................................................................
p. 8
Récapitulatif des étapes ....................................................................................................................................................................... p. 10
Autres répertoires et fichiers ................................................................................................................................................................. p. 10
Détails ............................................................................................................................................................................................................. p. 10
Les fichiers de documentation Rd (détail) ............................................................................................................................................ p. 10
Quelques balises Rd ............................................................................................................................................................................ p. 14
La vérification du package (détail) ........................................................................................................................................................ p. 16
Interprétation de messages de la commande 'check' ........................................................................................................................... p. 20
Situations particulières .................................................................................................................................................................................... p. 21
Caractères accentués ........................................................................................................................................................................... p. 21
Classes et méthodes ............................................................................................................................................................................ p. 21
Dépendances (besoin d'un autre package) .......................................................................................................................................... p. 26
Programmes C, Fortran, C++ ............................................................................................................................................................... p. 29
Données ............................................................................................................................................................................................... p. 30
Package récupéré sur le CRAN ........................................................................................................................................................... p. 31
Code issu d'un code préexistant ........................................................................................................................................................... p. 31
Facultatif ......................................................................................................................................................................................................... p. 31
Fichiers de tests ................................................................................................................................................................................... p. 31
Fichier CITATION (article de référence) ............................................................................................................................................... p. 33
Vignette ................................................................................................................................................................................................ p. 34
Autres fichiers de documentation ......................................................................................................................................................... p. 36
Démos .................................................................................................................................................................................................. p. 36
Fichier LICENSE .................................................................................................................................................................................. p. 36
Fichier NEWS ....................................................................................................................................................................................... p. 37
Comment faire pour ........................................................................................................................................................................................ p. 37
Faire un package de données .............................................................................................................................................................. p. 37
Mesurer les temps d'exécution ............................................................................................................................................................. p. 39
Effectuer des actions au chargement du package ............................................................................................................................... p. 40
Délivrer le PDF de la documentation .................................................................................................................................................... p. 40
Créer l'index du répertoire doc ............................................................................................................................................................. p. 41
Exclure/ajouter des fichiers du package ............................................................................................................................................... p. 41
Faire une version Windows .................................................................................................................................................................. p. 41
Gérer les versions successives ............................................................................................................................................................ p. 42
Soumettre au CRAN ....................................................................................................................................................................................... p. 43
Références et exemples ................................................................................................................................................................................. p. 44
Pourquoi faire un package R ?
Faire un package R peut paraître complexe de prime abord, car il y a des contraintes et des formats à respecter. Mais l'effort
nécessaire pour connaître et appliquer ces règles n'est pas si grand au regard des bénéfices: automatisation des tâches
d'organisation, test, documentation, maintenance, mise à disposition, diffusion sur le site du CRAN.
Qu'est-ce qu'un package R ?
●
Ce qu'il contient au minimum.
Un package contient des fonctions et/ou des données R, les fichiers qui décrivent la façon de les utiliser (les fichiers de
documentation en format Rd), un fichier de description générale qui mentionne notamment les auteurs et la licence (le
fichier DESCRIPTION) et un fichier qui liste les objets R à disposition de l'utilisateur et ceux importés d'autres packages
(le fichier NAMESPACE).
Ce qu'il peut contenir aussi.
Il peut contenir aussi des tests (conseillé), une vignette (document illustré d'exemples d'utilisation), de la documentation
supplémentaire, des démos, des programmes C, Fortran ou dans un autre langage de programmation, des données, un
fichier de licence, les références d'une publication (la publication à citer dans les articles utilisant le package), un fichier
NEWS (conseillé quand le package évolue), et tout autre document nécessaire à son utilisation ou facilitant son partage.
●
C'est un cadre d'organisation standardisé.
Quand on développe des fonctions R, faire un package est intéressant, même si on n'a pas l'intention de les diffuser, car
c'est un cadre d'organisation standardisé pour lequel beaucoup d'outils sont disponibles. On verra notamment comment
initier la hiérarchie d'un package avec la fonction package.skeleton(), comment créer la documentation avec les fonctions
de la famille prompt, procéder à sa vérification, distribution et installation à l'aide de fonctions du package devtools et de
commandes R.
●
Le schéma général de sa construction/utilisation.
Le source du package est composé d'une hiérarchie de fichiers organisés selon certaines conventions et respectant des
formats normalisés. Il est délivré sous la forme d'un fichier tar-archive compressé, que l'on crée par la commande R CMD
build (ou par la fonction build() du package devtools). Il s'installe par la commande R CMD install (ou par la fonction
install() du package devtools). L'utilisateur y accède dans une session R, par les fonctions library() ou require().
●
Sa diffusion.
S'il respecte la CRAN Repository Policy et passe avec succès la procédure de vérification, il peut être déposé sur le site
du CRAN, ce qui lui assure une large diffusion. Le CRAN le teste sur diverses plateformes et crée lui-même la version
compilée sur Windows.
Vous pouvez aussi le déposer sur GitHub, plateforme collaborative qui permet la gestion des versions avec git : voir
Putting your R package on GitHub dans le guide de Karl Broman.
Note. S'il s'agit d'un "bout de code" ou d'une fonction de démonstration, il est plus approprié de le déposer sur un site tel
que www.jstatsoft.org (voir l'onglet "Code Snippets" à droite sur cette page).
Préliminaire à la diffusion sur le CRAN
1. Choisir un nom de package unique et parlant.
Voir le nom des packages déjà déposés sur le site du CRAN.
Le nom du package peut être celui de sa fonction principale (c'est le cas par exemple du package nlme).
2. Choisir une licence.
●
Voir la liste des licences acceptées par le CRAN.
●
Voir le texte anglais des licences les plus fréquentes sur www.r-project.org/Licenses.
Copyright © 2016 INRA - CaSciSDI
page 3/44
La démarche de construction
Les objets du package doivent être stockés dans des fichiers organisés selon une certaine hiérarchie et respectant certaines
conventions. La fonction package.skeleton() crée l'arborescence initiale et les squelettes des fichiers indispensables. C'est à
nous de compléter ensuite ces fichiers. La démarche est la suivante :
1. Définir les objets à "packager".
Exemple. Les fichiers multplus.R et mafct.R contiennent les fonctions du package à construire (exemple de démonstration sans
aucun intérêt fonctionnel et réduit au strict minimum. La vérification des arguments a, en particulier, été omise).
Fichier multplus.R :
mult
x *
plus
x +
<- function (x, y) {
y }
<- function (x, y) {
y }
Fichier mafct.R :
mafct <- function (x) {
x <- x + 1
# utilisation de la fonction "pmvnorm" du package mvtnorm pmvnorm(lower=-Inf, upper=c(x,x))}
On remarquera que le package mvtnorm utilisé par la fonction mafct() n'a pas été chargé. Les fichiers DESCRIPTION et
NAMESPACE le feront pour nous (voir le paragraphe "Dépendances").
2. Invoquer la fonction package.skeleton().
Exemple. Création du squelette du package monpkg.
> package.skeleton(code_files = c("multplus.R", "mafct.R"), name="monpkg")
Creating directories ...
Creating DESCRIPTION ...
Creating NAMESPACE ...
Creating Read-and-delete-me ...
Copying code files ...
Making help files ...
Done.
Further steps are described in './monpkg/Read-and-delete-me'.
L'argument "code_files" introduit les noms des fichiers-sources. L'argument "name" introduit le nom choisi pour le package.
Cette commande crée la hiérarchie du package source dans un répertoire de même nom que celui du package (ici monpkg). Un
fichier Read-and-delete-me décrit brièvement les étapes à effectuer (c'est-à-dire les points énumérés ci_dessous). Comme son
nom l'indique, il doit être détruit après lecture.
3. Modifier les fichiers du répertoire source.
Sous éditeur de texte, modifier les fichiers DESCRIPTION (courte description du package, auteur, licence, ...), NAMESPACE (liste
des objets à importer ou exporter), les fichiers du répertoire man (documentation des objets R). Si le package est destiné à être
diffusé, il est conseillé de compléter les fichiers du répertoire R (source des fonctions) par un rappel du Copyright ou de l'auteur
(voir la note dans le paragraphe "Le répertoire R").
4. Rajouter si nécessaire d'autres fichiers ou répertoires.
5. Vérifier le package.
6. Créer le tar-archive.
7. Pour tester la distribution, l'installer et l'utiliser.
8. Éventuellement, le soumettre au CRAN, pour diffusion.
Voir le récapitulatif des étapes et le détail de celles-ci dans les paragraphes suivants.
page 4/44
Le fichier DESCRIPTION
Le fichier DESCRIPTION contient le titre du package, son numéro de version, le nom de ses auteurs, de quoi il a besoin, etc...
Exemple. Le fichier DESCRIPTION de monpkg:
Package: monpkg
Type: Package
Title: Illustrate Package Building
Version: 0.0-0
Date: 2015-12-06
Author: Chantal Dupont [aut, cre],
Pierre Durand [ctb] (up to 2013)
Maintainer: Chantal Dupont <[email protected]>
Description: Silly functions to illustrate the process of package building.
License: GPL (>=2)
Imports: mvtnorm
●
La version, obligatoire, est composée d'au minimum 2 nombres, le plus souvent 3, séparés par un point ou un tiret. Elle
indique l'importance de la modification effectuée depuis la précédente livraison : <majeure>.<mineure>.<patch> ou
<majeure>.<mineure>-.<révisionh>
●
Le rôle des auteurs entre crochets est facultatif. "aut" signifie "auteur", "cre" signifie "créateur" (dans le sens de
"maintainer", celui qui maintient le package), "ctb" signifie "contributeur". Voir la commande R "?person" pour toutes les
valeurs possibles.
Un commentaire peut être ajouté entre parenthèses (comme ici "up to 2013").
●
Le champ "Description" peut contenir plusieurs lignes d'au plus 80 caractères, mais un seul paragraphe. Les lignes suite
doivent commencer par un espace ou un tabulate. La dernière phrase doit se terminer par un point.
●
Dans les champs "Title" et "Description", les quotes sont autorisées: les doubles quotes seront réservées aux titres
d'article et les simples quotes aux termes non anglais et aux noms de logiciels ou des autres packages.
●
Le champ "License" est obligatoire et doit être valide.
●
Le champ "Imports" introduit le nom des autres packages nécessaires à l'exécution, s'il y en a. Attention: plusieurs types
de dépendances sont possibles. Voir le paragraphe "Dépendances".
●
S'il y a des caractères accentués, voir le paragraphe dédié.
●
Si on a l'intention de déposer le package au CRAN,
❍
Le "maintainer" doit être un email individuel, et non pas une mailing-list. C'est à lui que s'adresseront les utilisateurs
qui ont besoin d'explications ou qui découvrent des bugs. C'est aussi lui qui est contacté par le CRAN en cas de
modifications à effectuer sur le package pour qu'il reste conforme aux évolutions de R. Le CRAN vérifie
périodiquement que l'email est valide. Les packages dont l'email du "maintainer" n'est plus actif sont classés parmi
les packages orphelins.
❍
Le "title" doit être sur une seule ligne, avoir au plus 65 caractères et ne pas se terminer par un point. La première
lettre des mots principaux doit être en majuscule. Voir les conventions sur les titres.
❍
Le champ "Imports" introduit les packages utilisés, y compris ceux qui sont chargés par défaut. Seul, le package
base n'a pas à être mentionné. Pour connaître quels sont les packages chargés par défaut:
> getOption("defaultPackages")
[1] "datasets" "utils" "grDevices"
"graphics"
"stats"
"methods"
Les champs obligatoires sont: "Package", "Title", "Version", "Author", "Maintainer", "Description", "License".
Les champs facultatifs sont: "Type", "Date", "Encoding", "URL", "BugReports", "Copyright" (qui peut faire référence à un fichier
inst/COPYRIGHTS), etc... Ils sont détaillés dans le paragraphe "The DESCRIPTION file" de Writing R extensions et dans la
CRAN Repository Policy.
page 5/44
Note.
Le squelette du fichier DESCRIPTION peut être recréé à tout moment par la fonction create_description() du package devtools.
Le fichier NAMESPACE
Le fichier NAMESPACE contient le nom des objets "exportés" et, si besoin, des objets "importés".
●
Les objets exportés sont ceux que l'on veut mettre à disposition de l'utilisateur (par opposition à ceux internes au package): fonctions
classes et méthodes, programmes, exception faite des données qui n'ont pas besoin d'être exportées explicitement.
Exemple.
export(mult, plus, mafct)
Les noms des objets exportés peuvent être exprimés en utilisant des expressions régulières.
Par exemple, pour tout exporter sauf les objets dont le nom commence par un point.
exportPattern("^[^\\.]")
NB. Pour un package à distribuer, une expression aussi permissive est à éviter. Cibler les objets exportés à l'aide d'un "pattern" dan
noms.
●
Les objets importés, s'il y en a, sont les objets des autres packages que le package en cours utilise. Il est possible de spécifier un pa
dans sa totalité, par une clause import(NomPackage), ou seulement certaines de ses fonctions, par une clause importFrom(NomPac
NomFonction1, NomFonction2, ...).
Exemple.
# Importation du package "methods" import(methods)
# Importation de 2 fonctions du package "mvtnorm": importFrom(mvtnorm, pmvnorm, dmvnorm)
Les importations doivent être déclarées aussi dans le fichier DESCRIPTION avec les mots-clés "Imports" ou "Depends". Voir ci-aprè
paragraphe "Dépendances".
Le répertoire man et ses fichiers Rd
Le répertoire man contient la documentation du package. Chaque objet exporté, --- c.-à-d. chaque objet déclaré "export" dans
le fichier NAMESPACE --- doit être accompagné d'un fichier en format Rd ("R documentation") expliquant son usage. Ces
fichiers Rd sont automatiquement convertis en divers formats à l'installation du package, et constituent le manuel et
l'aide-en-ligne du package. Voir le paragraphe "La documentation format Rd (détail)".
Le répertoire R
Le répertoire R contient les sources des fonctions. Celles-ci peuvent être réparties dans autant de fichiers que voulu. Le nom de
ces fichiers doit avoir le suffixe .R (ou l'un des suffixes reconnus .r, .S,...), .R étant recommandé.
Remarques sur la visibilité du code source R.
●
Les utilisateurs peuvent visualiser le code source d'une fonction, sans les commentaires, depuis leur session R (voir la
fiche R4Ciam "Voir le code source d'une fonction R").
●
Les fichiers du répertoire R sont inclus dans le fichier tar-archive du package et donc visibles par toute personne qui y a
accès. Les fichiers tar-archive des packages déposés sur le CRAN sont disponibles à une adresse de la forme
https://cran.r-project.org/web/packages/NomPackage et le source de la plupart d'entre eux est directement visible sur
GitHub.
Bonnes pratiques :
●
Formater le code, par exemple en utilisant la fonction tidy.source() du package formatR (voir la fiche "Formater un script
R" du le site R4Ciam et sa lettre d'actualité de janvier 2016).
page 6/44
●
Si le package est destiné à l'international, rédiger les commentaires en anglais.
●
Rajouter dans un commentaire au début de chacun des fichiers-sources, l'auteur, le copyright du propriétaire des droits,
le site officiel du package s'il existe, et l'en-tête de la licence.
(L'en-tête de la licence GPL peut être trouvé à la fin de la page opensource.org/licenses/gpl-license au paragraphe "How
to Apply These Terms to Your New Programs" et celui de la licence CeCiLL à www.cecill.info/placer.fr.html#entete-en.)
Exemple :
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
Package: monpkg
Author: Prenom Nom
URL: http://cran.r-project.org/web/packages/monpkg
Copyright 2015 INRA - MonUnité
This file is part of monpkg R package.
monpkg is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
See the GNU General Public License at:
http://www.gnu.org/licenses/
Vérifier le package
La commande R CMD check, ou bien, au sein d'une session R, la fonction check() du package devtools, vérifie le package. Les
éventuelles erreurs, messages et notes sont affichés au fur et à mesure de l'exécution.
Exemple. Vérification du package monpkg en se plaçant au-dessus du répertoire qui le contient.
1/ Par la commande R CMD check
$ R CMD check monpkg -l ~/pkgCheck -o ~/pkgCheck
Updating monpkg documentation
Loading monpkg
...
La commande essaie d'installer le package dans le répertoire spécifié par l'option "-l". Dans celui spécifié par l'option "-o",
elle crée un répertoire nommé monpkg.Rcheck, dans lequel elle stocke ses résultats.
Le répertoire ~/pkgCheck aura eté préalablement créé.
2/ Dans une session R, par la fonction check() du package devtools
> library(devtools)
> check(pkg="monpkg")
Par défaut, le répertoire créé par la fonction check() est de la forme /tmp/RtmpXXXXXX. Les résultats de la vérification y
seront stockés dans un sous-répertoire de nom monpkg.Rcheck.
Voir le paragraphe "La vérification du package (détail)".
Construire le fichier tar-archive
Le fichier "tar-archive" du package est la forme sous laquelle il est distribué et à partir de laquelle il peut être installé. On crée le
page 7/44
fichier "tar-archive" en utilisant la commande R CMD build, ou bien, au sein d'une session R, la fonction build() du package
devtools.
Exemple. Construction du fichier tar-archive du package monpkg en se plaçant au-dessus du répertoire qui le contient.
1/ Par la commande R CMD build
$ R CMD build monpkg
Pour connaître les options de la commande build, taper: R CMD build --help.
2/ Dans une session R, par la fonction build()à l'aide du package devtools
> build(pkg="monpkg")
Un fichier, dont le nom est de la forme NomPackage_version.tar.gz est créé (dans l'exemple, monpkg_0.0-0.tar.gz).
Installer le package
Installer le package est nécessaire avant de pouvoir l'utiliser. L'installation se fait à partir du fichier tar-archive en utilisant la
commande R CMD INSTALL, ou bien, au sein d'une session R, la fonction install() du package devtools.
Exemple. Installation du package monpkg dans le répertoire ~/ESSAI.
1/ Installation par la commande R CMD install
$ R CMD INSTALL -l ~/ESSAI monpkg_0.0-0.tar.gz
2/ Installation dans une session R, par la fonction install()à l'aide du package devtools
> install(pkg="monpkg", args="-l ~/ESSAI")
Un répertoire de même nom que le package et contenant sa version installée, est créé dans ESSAI (ou remplacé s'il existe
déjà). Par défaut, le package est installé dans le répertoire des librairies de R sur le site courant. Le droit de création y est
nécessaire.
Utiliser le package
Note préalable.
Avant d'essayer d'utiliser le package, pour qu'il n'y ait pas de confusion entre la version en développement et la version
installée, ouvrir une session R vierge ou nettoyer la session courante par :
> rm(list=ls(all.names=TRUE)) # destruction des objets de la session > unloadNamespace
("monpkg") # détacher le package
Le package est chargé dans une session R par la fonction library() ou require().
Exemple. Utilisation du package monpkg préalablement installé dans ~/ESSAI.
> library("monpkg" , lib.loc="~/ESSAI")
> help("mafct")
> mafct(3)
page 8/44
page 9/44
L'option lib.loc de la fonction library() introduit le nom du répertoire d'installation. Par défaut, le package est recherché dans le
répertoire standard des librairies de R.
Récapitulatif des étapes de création, vérification, installation du package
Exemple du package monpkg.
## CRÉER LE SQUELETTE DU PACKAGE > package.skeleton(code_files = c("multplus", "mafct"),
name="monpkg") ## SOUS EDITEUR DE TEXTE, MODIFIER LES FICHIERS DU RÉPERTOIRE monpkg : ## - LE
FICHIER DESCRIPTION ## - LE FICHIER NAMESPACE (restreindre les exportations ## aux objets à la
disposition de l'utilisateur, ajouter ## les importations) ## - LES FICHIERS DU RÉPERTOIRE man
## - LES FICHIERS DU RÉPERTOIRE R (rajouter un en-tête ## d'identification)
## VÉRIFIER LE PACKAGE > library(devtools) > check(pkg="monpkg", check_dir="~/pkgCheck",
cleanup=FALSE, document=FALSE) ## CONSTRUIRE LE FICHIER TAR-ARCHIVE DU PACKAGE > build
(pkg="monpkg") ## INSTALLER LE PACKAGE DANS UN RÉPERTOIRE LOCAL > install(pkg="monpkg",
args="-l ~/ESSAI") ## UTILISER LA VERSION INSTALLÉE > library("monpkg" , lib.loc="~/ESSAI") >
?mafct > mafct(3)
Les répertoires et fichiers facultatifs
Il est possible - et recommandé pour les packages à distribuer - de rajouter des répertoires et des fichiers à ceux obligatoires.
On rappelle que les fichiers obligatoires sont DESCRIPTION et NAMESPACE et que les répertoires obligatoires sont R, avec
ses fichiers de suffixe R, et man, avec ses fichiers de suffixe Rd. Si le package ne contient que des jeux de données, il n'y a
pas de répertoire R, mais un répertoire data.
●
Les fichiers facultatifs les plus courants sont .Rbuildignore, la liste des fichiers à exclure du package, LICENSE, la licence
du package, NEWS, la liste des modifications effectuées au cours des différentes versions du package.
●
Les répertoires facultatifs les plus courants sont :
●
❍
data, avec les fichiers de données à disposition de l'utilisateur, de suffixe Rda ou en format texte, de suffixe .tab, .txt
, .csv;
❍
demo, avec ses fichiers de démonstration, de suffixe R, et son index, 00Index.html;
❍
inst, lequel peut contenir,
■
les fichiers CITATION (la publication de référence du package), AUTHORS et COPYRIGHTS (quand le
fichier DESCRIPTION ne suffit pas à les décrire);
■
le répertoire extdata, avec les fichiers de données utilisés dans les exemples, tests ou la documentation,
fichiers de suffixe Rda ou en format texte, de suffixe .tab, .txt, .csv;
■
le répertoire doc, avec les fichiers de documentation supplémentaire, en général en format PDF, et
éventuellement son index, index.html;
❍
src, avec ses fichiers-sources C, Fortran ou autre langage;
❍
tests, avec ses fichiers de tests, de suffixe R;
❍
vignettes, avec ses fichiers-sources de suffixe Rnw, documents LaTeX contenant des exemples d'utilisation dont la
sortie est compilée dynamiquement. Les fichiers de style LaTeX ou de bibliographie qu'ils utilisent sont aussi dans
ce répertoire.
Il peut y avoir aussi les fichiers INDEX, configure, cleanup, INSTALL, README, ChangeLog, et les répertoires exec, po
et tools. Nous ne les décrivons pas ici. Voir le paragraphe "Package structure" de Writing R Extensions.
Les fichiers de documentation Rd (détail)
page 10/44
Chaque objet du package à la disposition de l'utilisateur (fonction, classe, méthode, donnée) doit être accompagné d'un fichier
qui explique sa syntaxe, ses fonctionnalités, et donne éventuellement des exemples d'utilisation. Ce fichier doit respecter une
certaine structure, le format de mise en page Rd, et être placé dans le répertoire man. Il peut être généré à partir de
commentaires inclus dans le source, ou bien créé à partir d'un squelette, que l'on complète ensuite sous éditeur de texte. Pour
visualiser l'affichage, convertir le format Rd en un autre format par R CMD Rdconv ou voir le manuel du package qui est créé
par la commande check.
1/ Générer la documentation à partir de commentaires inclus dans le source.
Plusieurs packages R sont disponibles, dont :
●
les packages basés sur Doxygen:
❍ roxygen (introduction en français sur R4Ciam),
❍ Rd2roxygen,
❍ roxygen2
●
inlinedocs (introduction en français sur R4Ciam)
●
mvbutils (manuel en PDF, introduction en français à la commande fixr de mvbutils sur R4Ciam)
2/ Générer la documentation à partir de squelettes.
1. Générer les squelettes.
Nous avons vu au paragraphe "Construire le package" qu'à l'initiation du package, la fonction package.skeleton() crée
les squelettes des fichiers de documentation de tous les objets du package. Pour créer ensuite le squelette de la
documentation d'un objet, utiliser les fonctions de la famille prompt.
Exemple.
●
Génération du squelette de la documentation de la fonction mafct. L'argument "force.function=TRUE" précise qu'il
s'agit de documenter une fonction.
> prompt(mafct, force.function=TRUE)
Un fichier mafct.Rd est alors créé dans le répertoire courant. S'il existe déjà, il est écrasé.
●
Génération du squelette du fichier qui décrit les fonctionnalités générales du package :
> promptPackage("monpkg")
Un fichier monpkg-package.Rd est créé dans le répertoire courant. Ce fichier est facultatif, mais il peut être utile
pour aiguiller l'utilisateur quand le package comporte beaucoup de fonctions.
S'il y a des classes, utiliser la fonction promptClass() et s'il y a des méthodes, la fonction promptMethods(). Voir le
paragraphe "Classes et méthodes".
2. Modifier les squelettes.
Sous éditeur de texte, remplacer dans ces fichiers Rd tout ce qui est précédé d'un tilde par le texte adéquat. Des
commentaires sont inclus dans ces fichiers qui expliquent ce qui est attendu. Eliminer au moins ceux qui ne sont pas
inclus dans une section.
3. Déplacer les fichiers Rd dans le répertoire man.
page 11/44
La syntaxe des fichiers Rd.
●
Les balises de mise en page les plus usuelles sont mentionnées dans le paragraphe "Quelques balises Rd". On
trouvera l'ensemble de toutes les balises au paragraphe "Marking text" de Writing R Extensions.
●
La balise \alias{} contient le nom de l'entrée dans l'index de la documentation. La commande R "help(mafct)" (ou
"?mafct") ouvre le fichier de documentation qui comporte la balise \alias{mafct}. On fait un lien sur ce fichier, depuis
un autre fichier Rd, par la balise "\link(mafct)".
Il est possible de rajouter une balise \concept{} dont le contenu sera utilisé par la commande "help.search()". Exemple
:
\concept{Kendall correlation coefficient}
●
Pour voir la liste des mots-clés acceptés dans les balises \keyword{} , taper sour R :
> file.show(file.path(R.home("doc"), "KEYWORDS"))
Mettre autant de balises \keyword{} que de mots-clés chisis.
●
Pour introduire des commentaires, utilisez le caractère "%" : ce caractère jusqu'à la fin de la ligne sera ignoré.
●
Pour protéger un caractère spécial ("%", "{", "\", ...), faites-le précéder par "\".
●
Pour introduire des figures, voir le paragraphe Figures de Writing R extensions.
●
L'utilisateur doit pouvoir exécuter la partie "examples" en la coupant-collant dans sa session R, sans avoir besoin
d'autre chose. Si des données sont nécessaires, les rendre disponibles dans les répertoires data ou inst/extdata (voir
le paragraphe "Les données").
Note.
Les exemples sont automatiquement exécutés par la commande check. Pour tester un exemple séparemment,
utiliser la fonction dev_example() du package devtools.
Exemple. En se plaçant dans le répertoire monpkg, exécution de l'exemple inclus dans le fichier man/mafct.Rd (la
notation "." désigne le répertoire courant).
> library(devtools)
> load_all(pkg = ".")
> dev_example("mafct")
●
Si une partie d'un exemple ne doit pas être exécutée par la commande check, par exemple parce qu'elle demande
une interaction avec l'utilisateur, ou parce que son exécution est trop longue, la mettre dans une balise \dontrun{}.
●
Si le package est destiné à être déposé sur le CRAN, voir les conventions sur les titres et Guidelines for Rd files, sur
le site R Developer Page.
Un exemple de fichier Rd.
Voir pour exemple le fichier LambertW.Rd, qui documente la fonction Lambert() du package spatstat. Il illustre en particulier
l'usage des balises \email, \url, \pkg et l'écriture d'expressions mathématiques à l'aide des balises \eqn et \deqn.
page 12/44
Convertir le format Rd pour visualiser l'affichage.
La commande R CMD Rdconv permet de convertir un fichier Rd en divers formats : HTML, LaTeX, texte, etc. La commande
R CMD Rdconv --help indique les formats disponibles.
Exemple. Conversion en HTML du fichier mafct.Rd :
$ R CMD Rdconv -t html mafct.Rd -o mafct.html
Le fichier mafct.html ainsi créé est visualisé sous un navigateur puis détruit ou exclus du package.
Notes.
●
●
La fonction dev_help() du package devtools permet aussi la conversion en divers formats des fichiers Rd d'un
package en développement, mais elle nécessite, avec la version 1.5 de devtools, l'installation du package rstudioapi.
La commande de vérification (R CMD check ou la fonction check()) crée la version PDF de l'ensemble des fichiers Rd
dans le fichier NomPackage-manual.pdf (voir le paragraphe "Le manuel du package").
page 13/44
Quelques balises Rd
Les balises de mise en page du format Rd sont recensées au paragraphe "Marking text" de Writing R Extensions
sur le site du CRAN. On indique ici quelques-unes des plus usuelles.
●
Les balises de mise en page :
\cr (passage à la ligne suivante),
\tab (tabulation).
●
Les balises de mise en gras, italique, "typewriter", respectivement :
\bold
\emph
\code
●
Les quotes :
\sQuote{terme entre simples quotes}
\dQuote{terme entre doubles quotes}
●
Pour indiquer le nom d'un fichier ou d'un package R :
\file{nomFichier}
\pkg{nomPackage}
●
Pour faire des listes:
\itemize{
\item blabla1
\item blabla2
}
Il ne faut pas de blanc entre \itemize et l'accolade qui suit.
Utiliser \enumerate selon la même syntaxe, pour faire des listes numérotées.
page 14/44
●
Pour faire des liens sur un autre fichier de documentation:
\link{nomfonction}
# lien sur une classe S4
# lien sur une fonction \linkS4class{nomclasse}
●
Ces instructions créent un lien "nomfonction" et "nomclasse" vers les fichiers Rd qui contiennent
respectivement \alias{nomfonction} et \alias{nomclasse}.
●
Il ne faut pas de blancs dans ces expressions.
●
Pour donner au lien un autre nom que ceux figurant dans les \alias du fichier cible, rajouter, en première
position, l'argument [=nom-alias].
Exemple. L'alias du fichier qui décrit une classe est \alias{nomclasse-class}. La notation:
The class \code{\link[=nomclasse-class]{nomclasse}}
apparaît sous la forme: "The class nomclasse".
●
Pour faire un lien sur le fichier Rd d'un autre package, rajouter, en première position, l'argument
[nom-package:nom-alias].
Exemple.
See the \code{\link[stats:p.adjust]{p.adjust}} function
apparaît ainsi: "See the p.adjust function".
●
Pour faire un lien sur un site Web :
\url{URL}
\href{URL}{texte}
●
Pour exprimer une formule mathématique, utilisez les balises \eqn{latex}{ascii} ou \deqn{latex}{ascii}.
latex est l'expression de la formule en utilisant les symboles LaTeX. ascii est le texte de l'expression dans les
formats où LaTeX n'est pas disponible.
\eqn fait apparaître la formule sur la ligne courante, tandis que \deqn est l'équivalent du LaTex displaymath.
Notes.
● Pas de caractères blancs entre la commande et son premier argument, ni entre les 2 arguments.
● Seules, les expressions basiques de LaTeX sont acceptées.
Exemple :
\deqn{p(x) = \frac{\lambda^x e^{-\lambda}}{x!}}{%
p(x) = \lambda^x exp(-\lambda)/x!}
for \eqn{x = 0, 1, 2, \ldots}.
correspond, en format texte simple, à :
p(x) = lambda^x exp(-lambda)/x!
for x = 0, 1, 2, ....
Référence : le paragraphe Mathematics de Writing R extensions.
page 15/44
La vérification du package (détail)
Pour vérifier la validité du package (respect des normes, bonne exécution des tests et exemples, compilation de la
vignette, etc), on dispose de la commande R CMD check ou de la fonction check() du package devtools.
Exemple. Vérification du package monpkg en se plaçant au-dessus du répertoire qui le contient.
Mise en oeuvre
1/ par la commande R CMD check.
●
Le premier argument, monpkg, est le répertoire qui contient le package source. Ce peut être aussi le nom
d'un fichier tar-archive créé avec la commande R CMD build.
●
Les options -l et -o introduisent respectivement le répertoire où est testée l'installation du package et le
répertoire contenant les résultats de la vérification. Ces répertoires devront avoir été préalablement
créées.
2/ par la fonction check() du package devtools.
> library(devtools)
> check(pkg="monpkg", check_dir="~/pkgCheck", cleanup=FALSE, document=FALSE)
●
L'option pkg introduit le nom du répertoire qui contient le package source.
●
L'option check_dir introduit le répertoire où la commande devra stocker ses fichiers. À défaut, il est de la
forme /tmp/RtmpXXXXXX.
●
L'option cleanup=FALSE permet de conserver le contenu de ce répertoire, qui, par défaut, est détruit en
fin d'exécution lorsqu'il n'y a pas d'erreur.
●
L'option document=FALSE demande de ne pas reconstruire la documentation à partir des commentaires
Roxygen inclus dans les sources R. Sans cette option, les fichiers Rd et le fichier DESCRIPTION sont
recréés en utilisant le package roxygen2.
Attention : même quand il n'y a pas de commentaires Roxygen dans les sources, le fichier DESCRIPTION
est modifié. En particulier, la clause Collate, si elle y était incluse, est supprimée.
Les options de vérification.
La commande R CMD check --help affiche les options de vérification disponibles. Certaines permettent
d'effectuer une vérification partielle. On les indique directement sur la ligne de commande de R CMD check.
Exemple :
$ R CMD check monpkg -l ~/pkgCheck -o ~/pkgCheck --no-tests
... et dans l'argument args de la fonction check() de devtools.
Exemple :
> check(pkg="monpkg", cleanup=FALSE, check_dir="~/pkgCheck",
+
args="--no-examples --no-tests --no-vignettes")
Pour vérifier les temps d'exécution des exemples et des tests, voir le paragraphe "Mesurer les temps
page 16/44
d'exécution".
page 17/44
Les répertoires créés.
Pour vérifier le package, la commande essaie de l'installer. La commande de l'exemple avec R CMD check
l'installe dans ~/pkgCheck/monpkg et celle avec devtools dans ~/pkgCheck/monpkg.Rcheck/monpkg. Dans les
deux cas, les résultats de la vérification sont dans le répertoire ~/pkgCheck/monpkg.Rcheck. Ces répertoires
sont remplacés s'ils existent déjà.
Le manuel du package : vérification des fichiers Rd
Dans le répertoire résultat de la commande de vérification (la commande R CMD check, ou la fonction check()
du package devtools), le fichier NomPackage-manual.pdf est le "reference manual" du package. Il contient la
version PDF du fichier DESCRIPTION et de l'ensemble des fichiers Rd. Ce manuel est, pour les packages
déposés sur le CRAN, directement visible depuis la page du package
(https://cran.r-project.org/web/packages/NomPackage).
Note.
Il est possible de rendre le manuel disponible depuis la page d'aide en ligne du package dans la rubrique "User
guides, package vignettes and other documentation.", à condition qu'aucune page d'aide, en particulier la page
NomPackage-package.Rd, ne contienne de directives \package*. Rendre le manuel disponible permet aux
utilisateurs d'avoir accès à l'ensemble des fichiers man sous une forme facilement imprimable. Pour cela,
recopier le fichier NomPackage-manual.pdf dans un répertoire nommé inst/doc (voir le paragraphe "Autres
fichiers de documentation"). Ne pas oublier de le remplacer à chaque version du package, même si les fichiers
Rd n'ont pas été modifiés, car le numéro de version et la date y sont mentionnées.
Les résultats de la vérification.
Au fur et à mesure de l'exécution de la commande de vérification, des messages et des "notes" apparaissent à
l'écran, indiquant ce qui n'est pas standard. Les erreurs sont signalées. Les "warnings" doivent être pris en
considération, en particulier si on a l'intention de soumettre le package au CRAN. Certains ne sont que des
messages d'information. On pourra ignorer ceux signalant la présence de fichiers dont le nom commence par
un point (.RData, .svn). Ces fichiers ne seront pas inclus dans le tar-archive.
Voir le paragraphe "Interprétation de quelques messages de 'check'".
Dans le répertoire résultat, sont créés les fichiers 00check.log, image de ce qui est apparu à l'écran, et
00install.out, détails des éventuelles erreurs.
Exemple. Visualisation des éventuelles erreurs.
more ~/pkgCheck/monpkg.Rcheck/00install.out
* installing *source* package monpkg ...
** R
...
** testing if installed package can be loaded
...
S'il y a des fichiers tests.
On vérifie que leur exécution est correcte, en examinant leurs résultats stockés dans le répertoire résultat de la
commande check.
Exemple. Visualisation du résultat de tous les tests.
more ~/pkgCheck/monpkg.Rcheck/tests/*.Rout
page 18/44
S'il y a des programmes C ou Fortran.
Il est conseillé d'utiliser l'option --use-valgrind de la commande check. Les exemples contenus dans les fichiers
Rd, les tests et les vignettes seront alors exécutés sous valgrind. Valgrind est un système qui débusque les
failles d'un programme au niveau de l'utilisation de la mémoire. Voir www.valgrind.org. On indiquera au
préalable les options de valgrind dans un fichier ~/.valgrindrc.
Exemple de fichier ~/.valgrindrc :
--leak-check=full
--track-origins=yes
Si le package est destiné au CRAN.
Il est conseillé de vérifier les temps d'exécution de chaque étape de la vérification et de l'installation, en
particulier les temps d'exécution de chacun des exemples et tests et le temps de construction de la vignette.
Voir le paragraphe Mesurer les temps d'exécution .
page 19/44
Interprétation de quelques-uns des messages produits par la commande check
●
Le message est :
* checking package vignettes in 'inst/doc' ... WARNING
Package vignette without corresponding PDF/HTML
Ce message apparaît quand il y a un répertoire inst/doc et une vignette en format Sweave, dont le PDF n'est
pas fourni dans inst/doc. Il peut être ignoré car, sauf option contraire, le PDF est automatiquement créé à la
construction du tar-archive.
●
Le message est :
Vignette sources only in 'inst/doc'
A 'vignettes' directory is required as from R 3.1.0
Le répertoire vignettes existe mais est exclus du package car cité dans le fichier .Rbuildignore. Pour que les
fichiers vignettes ne soient pas compilés, il faut aussi ajouter l'option --no-build-vignette à la commande
check.
●
Le message est :
No repository set, so cyclic dependency check skipped
La commande check a été invoquée avec l'option --as-cran qui implique la vérification des dépendances
cycliques entre packages. Si le package ne dépend d'aucun autre package, ce message pourra être ignoré.
Dans le cas contraire, il faut indiquer le dépôt des packages par rapport auxquels la dépendance est vérifiée.
Pour cela, créer un fichier .Rprofile dans le répertoire d'exécution de la commande check qui spécifie le
dépôt.
Exemple de fichier .Rprofile:
options(repos = c(CRAN="http://cran.r-project.org"))
●
Le message est :
These packages need to be imported from (in the NAMESPACE file)
for when this namespace is loaded but not attached.
Si le fichier DESCRIPTION contient une instruction de la forme "Imports: UnPackage", il faut mettre dans le
fichier NAMESPACE "import(UnPackage)" ou "importFrom(UnPackage, UneFonction)" Voir le paragraphe
"Fichier NAMESPACE".
●
Le message est :
no visible binding for global variable [variable name]
La variable a-t-elle bien été initialisée avant d'être utilisée en partie droite d'une affectation?
page 20/44
●
Le message est :
Error in setMethod("plus", signature(objet = "classeA"), function(objet) { :
no existing definition for function 'plus'
La méthode "plus" est définie pour la classe "classeA", mais sa fonction générique ne l'est pas. Vérifier que
celle-ci est bien définie, et qu'elle l'est avant la méthode. Si besoin, ajouter une instruction "Collate" dans le
fichier DESCRIPTION (voir le paragraphe "classes S4") pour préciser l'ordre de lecture des fichiers-sources.
Les caractères accentués
S'il y a des caractères accentués dans un des fichiers du package, rajouter dans le fichier DESCRIPTION :
Encoding: UTF-8
(UTF-8 en majuscules)
Classes et méthodes
Note préalable.
Pour les classes et méthodes, il existe la norme S3 et la norme S4. Quand on rajoute une méthode à une
fonction générique existante (par exemple, print ou show), il est nécessaire de savoir dans quel cas on se
trouve.
- Pour savoir si une fonction générique déjà existante est S3 ou S4, utiliser la fonction showMethods(). Si la
fonction générique est S4, toutes les classes pour lesquelles elle a une méthode sont affichées.
Exemple.
> showMethods(print) # "print" est une fonction S3 Function "print":
<not an S4 generic function> > showMethods(show) # "show" est une fonction S4
Function: show (package methods)
object="abIndex"
object="ANY"
object="BunchKaufman"
object="C++Class"
...
- Pour afficher toutes les méthodes d'une fonction générique S3, utiliser la fonction methods().
Exemple.
> showMethods(print)
Function "print":
<not an S4 generic function> > methods(print)
[2] print.addvar
....
[1] print.acf*
Nous allons expliquer le cas des classes et méthodes à l'aide d'un exemple de classes et méthodes S3, et d'un
exemple de classes et méthodes S4 successivement.
Classes et méthodes S3
page 21/44
Les fichiers sources de l'exemple
●
Dans le fichier classeX.R une classe nommée classeX est définie.
classeX = function(x, y) {
retour = list(x=x, y=y)
attr(retour, "class") = "classeX"
return(retour)
}
●
Dans le fichier meth.R une méthode nommée methS3 est définie pour la classe classeX.
methS3.classeX = function(x) {
cat("X:", x$x, " Y:", x$y, "\n")
invisible()
}
●
Dans le fichier generique.R la fonction générique methS3 est définie.
methS3 = function(x)
UseMethod("methS3")
page 22/44
Les fichiers Rd
●
Une classe S3 n'est pas formellement un objet R. Ce n'est donc pas la classe qui sera documentée mais
sa fonction constructeur, dans le fichier classeX.Rd.
❍
Si non déjà créé par package.skeleton(), on crée le squelette de ce fichier par:
> prompt("classeX", force.function =T)
❍
Il devra contenir:
\alias{classeX}
●
Le fichier methS3.classeX.Rd décrit la méthode methS3 spécifique à la classe classeX.
●
On crée le squelette de ce fichier par:
> prompt("methS3.classeX", force.function =T)
●
Il devra contenir:
\alias{methS3.classeX}
...
\usage{
\method{methS3}{classeX}(x)
}
À noter : l'utilisation de la balise method{} dans la clause "usage".
●
Le fichier facultatif methS3.Rd décrit la fonction générique:
●
Le squelette de ce fichier est créé par:
> prompt("methS3", force.function =T)
●
Il devra contenir:
\alias{methS3}
Le fichier NAMESPACE contient :
export(classeX)
export(methS3)
S3method(methS3, classeX)
page 23/44
Classes et méthodes S4
Les fichiers sources de l'exemple
●
Dans le fichier classeX.R une classe nommée classeX est définie.
setClass("classeX",
representation(x="numeric", y="numeric"))
●
Dans le fichier meth.R une méthode nommée methS4 est définie pour la classe classeX.
setMethod("methS4", signature(objet="classeX"),
function(objet) {objet@x + objet@y})
●
Dans le fichier generique.R, la fonction générique methS4 est définie.
setGeneric("methS4",
function(objet) {standardGeneric("methS4")})
L'appel à la fonction package.skeleton()
À l'initiation du package, le squelette du répertoire est créé par la fonction package.skeleton(). L'ordre des
fichiers dans l'argument code_files est ici important: les fonctions génériques doivent être définies avant les
méthodes.
>
+
package.skeleton(code_files =
name="monpkgS4")
c("generique.R", "classeX.R", "methS4.R"),
Les fichiers Rd
●
Quand il y a des méthodes S4, la fonction package.skeleton() génère des déclarations \alias{} identiques
dans plusieurs fichiers Rd. Or, les alias servant à créer les liens entre l'index de la documentation et les
fichiers, ils doivent être uniques (l'inverse n'est pas vrai: un fichier peut être la cible de plusieurs entrées).
La fonction package.skeleton() ne fait que nous indiquer tous les endroits possibles où documenter un
objet. C'est à nous de choisir le fichier dans lequel nous voulons le décrire et à nous de supprimer l'alias
correspondant des autres fichiers.
page 24/44
●
La documentation peut être répartie en autant de fichiers que voulu. On peut décrire plusieurs objets dans
un même fichier, par exemple une méthode dans le même fichier que celui de sa classe. Il suffit d'insérer
dans le fichier choisi un alias par objet documenté et de supprimer les fichiers devenus inutiles.
●
Lorsque la hiérarchie du package est déjà créée, on génère le squelette de la documentation d'une classe
par la fonction promptClass() et celui d'une méthode par promptMethods().
Exemple.
●
Le fichier qui décrit la classe classeX a pour nom classeX-class.Rd.
●
Si non déjà créé par package.skeleton(), le squelette de ce fichier est créé par :
> promptClass("classeX")
●
Il doit contenir :
\alias{classeX-class}
●
Le fichier qui décrit la méthode methS4 a pour nom methS4-methods.Rd.
●
On crée le squelette de ce fichier par :
> promptMethods("methS4")
●
Il décrit la méthode spécifique à la classe classeX et doit donc contenir :
\alias{methS4,classeX-method}
●
Le fichier qui décrit la fonction générique methS4 a pour nom methS4.Rd
●
On crée le squelette de ce fichier par :
> prompt("methS4", force.function=T)
●
Il doit contenir :
\alias{methS4}
page 25/44
Le fichier NAMESPACE contient :
import(methods)
exportMethods("methS4")
exportClasses("classeX")
Les classes et méthodes S4 nécessitent le package methods, ce qui explique l'importation de celui-ci.
Le fichier DESCRIPTION
Le fichier DESCRIPTION contient :
Depends: methods
Collate: generique.R classeX.R meth.R
À partir de R 3.2.0, methods devra être déclaré par : Imports: methods
Collate spécifie l'ordre des fichiers sources, sans en omettre aucun. Les fonctions génériques doivent être lues
avant leurs méthodes.
L'appel à la fonction check()
La fonction check() de devtools doit être invoquée avec l'argument "document=FALSE" pour que le fichier
DESCRIPTION, qui contient la commande Collate, ne soit pas reconstruit :
> check(pkg="monpkgS4", cleanup=FALSE, document=FALSE)
Dépendances : besoin d'un autre package
Les packages nécessaires au package courant, à l'exception du package base, doivent être déclarés dans le
fichier DESCRIPTION et dans le fichier NAMESPACE.
page 26/44
Dans le fichier DESCRIPTION
Dans le fichier DESCRIPTION, on introduit les packages nécessaires par un mot-clé qui précise le type de
dépendance. Les mots-clés les plus usuels sont :
❍
"Imports", qui introduit les packages nécessaires à l'exécution du package courant.
Exemple.
Imports:
mvtnorm, BH
❍
"Suggests", qui introduit les packages utilisés dans la vignette, les exemples ou les tests.
❍
"Enhances", qui introduit les packages que le package courant complète (un package en complète un
autre, par exemple parce qu'il ajoute des méthodes à des classes de celui-ci).
❍
"Depends", qui introduit les packages nécessaires au chargement du package courant. On l'utilisera, par
exemple, pour spécifier une version de R, ou, avec R < 3.2.0 et s'il y a des fonctions ou des classes S4,
pour déclarer le package methods.
Exemple.
Depends: R (>= 3.1.0), methods
À partir de la version R 3.2.0, methods pourra être déclaré Imports.
On remarque ici la spécification d'un numéro de version. Elle doit suivre le nom du package qu'elle qualifie
(ou "R"), être indiquée entre parenthèses, précédée d'un opérateur de comparaison, et correspondre à un
numéro de version valide.
En savoir plus. Voir tous les mots-clés et leur signification dans le paragraphe "Package-Dependencies" de
Writing R extensions.
Note. Un package ne peut être cité qu'une fois, derrière un seul mot-clé. Si un package est utilisé à la fois dans
les fonctions R et dans les vignettes, exemples ou tests, le déclarer "Depends".
page 27/44
Dans le fichier NAMESPACE
Les packages qui sont introduits par "Depends" dans le fichier DESCRIPTION, doivent être déclarés dans le
fichier NAMESPACE par import(NomPackage). Ceux introduits par "Suggests" ou "Enhances" n'ont pas à être
déclarés. Pour ceux de type "Imports", deux solutions:
❍
si beaucoup de fonctions du package sont utilisées, importer le package dans sa totalité, par la
déclaration import(NomPackage).
Exemple.
import(mvtnorm)
❍
si seulement quelques fonctions du package sont utilisées, les importer par importFrom(NomPackage,
NomFonction1, NomFonction2, ...).
Exemple.
importFrom(mvtnorm, pmvnorm, qmvnorm)
En savoir plus. Voir le paragraphe "Package namespaces" de Writing R Extensions.
Si on a l'intention de déposer le package au CRAN
Tous les packages utilisés, y compris ceux qui sont chargés par défaut ("datasets", "utils", "grDevices",
"graphics", "stats", "methods"), doivent être mentionnés.
Exemple. Dans le fichier DESCRIPTION :
Imports: graphics, stats
Dans le fichier NAMESPACE :
importFrom("graphics", "plot", "legend", "lines")
importFrom("stats", "var", "cor")
Note. Le système win-builder, en signalant les fonctions utilisées et non déclarées (voir Créer une version
compilée pour Windows), permet de vérifier les éventuels oublis.
page 28/44
Les programmes C ou Fortran
●
Les fichiers sources C ou Fortran doivent être placés dans un répertoire nommé src. Si nécessaire, un fichier
nommé Makevars indiquera des options de compilation ou d'édition de liens particulières.
Exemple de fichier src/Makevars. Les librairies LAPACK et BLAS sont utilisées.
PKG_LIBS= $(LAPACK_LIBS) $(BLAS_LIBS)
Voir détails au paragraphe "Using Makevars" de Writing R extensions.
●
Voir les contraintes de programmation et le processus de compilation dans la fiche R4Ciam "Appeler du C,
C++ ou Fortran depuis R".
●
La compilation et l'édition de liens sont automatiquement effectuées lors de la vérification et de l'installation
du package. Pour l'effectuer indépendamment, utiliser la commande R CMD SHLIB (voir la fiche R4Ciam
"Appeler du C, C++ ou Fortran depuis R", paragraphe "Compilation/édition de liens", ).
●
Dans le fichier NAMESPACE, rajouter une directive useDynLib. Elle est a pour premier argument le nom de
la librairie qui contient le code compilé - en général, le même nom que celui du package -, et, pour arguments
suivants, le nom des programmes qui sont appelés par les fonctions R.
Exemple.
useDynLib(NomPackage, NomFonction1, NomFonction2, ...).
●
Vérifier le package avec l'option --use-valgrind de la commande check qui permet de détecter les éventuels
problèmes dans l'utilisation de la mémoire (voir le paragraphe "La vérification du package (détail)").
Les programmes C++
Voir Interfacing C++ code, sur le site du CRAN et le package Rcpp.
page 29/44
Les données
On distingue plusieurs types de données, selon leur usage.
Les données à disposition de l'utilisateur.
●
●
Les stocker dans un répertoire nommé data. Plusieurs formats de fichiers sont acceptés (voir la
documentation de la fonction data()). Les plus usuels :
❍
les data-frames.
Les stocker par la fonction save() dans des fichiers dont le nom est de la forme NomDataset.RData
(ou .rda).
❍
les fichiers texte, de suffixe .tab, .txt, .csv.
Ils doivent être lisibles par la fonction read.table( ... header=TRUE) et peuvent être compressés par
gzip, bzip2 ou xz (ce qui ajoute à leur nom le suffixe .gz, .bz2 ou .xz). Il est conseillé de stocker les
gros fichiers plutôt dans des fichiers .RData.
Les documenter dans un fichier Rd dans le répertoire man. Le squelette de ce fichier est créé à
l'initialisation du package, par la fonction package.skeleton(), ou ensuite, après avoir chargé dans la
session R le data-frame ou le fichier, par la fonction promptData().
Le fichier Rd comprend les champs source et references. Le champ source indique où les données ont
été trouvées, par exemple un site Web que l'on indiquera dans une balise \url{}. Le champ references
indique où les données sont décrites ou utilisées (références d'article, sites, etc).
Exemple. Extrait du fichier man/butterfly.Rd du package ade4.1.6-2:
\source{
McKechnie, S.W., Ehrlich, P.R. and White, R.R. (1975)
Population genetics of Euphydryas butterflies.
I. Genetic variation and the neutrality hypothesis.
\emph{Genetics}, \bold{81}, 571--594.
}
\references{
Manly, B.F. (1994) \emph{Multivariate Statistical Methods. A primer.}
Second edition. Chapman & Hall, London. 1--215.
}
Noter, en particulier, la façon d'indiquer les auteurs dans les références.
●
Le chargement des données dans la session R de l'utilisateur, ou dans les exemples, tests, ou vignette du
package, se fait par la fonction data("NomDataset").
Toutefois, si le fichier DESCRIPTION contient la déclaration "LazyData: true", la commande data() n'est
même pas nécessaire: les données sont alors chargées dans la session à leur première utilisation. Elles
n'occupent ainsi pas de place mémoire tant qu'elles ne sont pas utilisées (d'où le terme "lazy").
Les données utilisées uniquement par des fonctions du package.
●
Les stocker dans un fichier R/sysdata.rda.
●
Ne pas leur associer de fichier de documentation Rd.
Les données utilisées dans les exemples, tests ou vignette.
page 30/44
●
Les stocker dans un répertoire nommé inst/extdata.
●
Ne pas leur associer de fichier de documentation Rd.
●
L'accès à ces données, dans les tests, démo ou vignettes, ou directement sous R, se fait en précisant leur
emplacement par la fonction system.file(). Exemple :
> read.table(system.file("extdata", "madonnee.txt", package="monpkg"),
+
header=TRUE )
En savoir plus. Voir le paragraphe "Data in packages" dans Writing R Extension.
Modifier un package récupéré sur le CRAN
Les fichiers tar-archive des packages déposés sur le CRAN sont disponibles à une adresse de la forme
https://cran.r-project.org/web/packages/NomPackage. Ils incluent un fichier nommé MD5 qui contient la "signature"
des fichiers, et qui est utilisé pour vérifier le tar-archive lorsqu'il est téléchargé sur Internet. En cas de modification
des sources, détruire ce fichier avant de procéder à l'étape de vérification.
Les parties de code issues d'un code préexistant
Lorsque le code du package inclut des parties développées ou dérivées d'un code créé par des personnes
extérieures au projet (y compris du code de R lui-même), mentionner ces personnes dans le fichier DESCRIPTION
, en tant que contributeurs avec l'attribut [ctb], comme indiqué dans la CRAN Repository Policy, et veiller à ce que
la licence de ces codes soit préservée.
Les fichiers de tests
Pour tester la bonne exécution du package, notamment au cours de ses évolutions, il est recommandé de créer
des fichiers tests. Par définition, ils contiennent des instructions R qui mettent en oeuvre les fonctions et classes du
package, en essayant de couvrir tous les types d'entrées. Ces fichiers doivent avoir pour suffixe .R et être situés
dans un répertoire nommé tests. Lors de la vérification du package par la commande check, les tests sont
exécutés et leurs sorties sont comparées à des fichiers de référence, lorsqu'ils existent. Les exemples contenus
dans les fichiers Rd peuvent aussi servir de tests: voir le paragraphe dédié.
À savoir :
●
Les fichiers tests ne sont pas inclus dans la version installée du package: les utilisateurs les voient uniquement
s'ils déchargent la version source, contrairement aux démos.
●
L'accès au package, bien qu'il soit encore en développement et non encore installé, se fait, dans les fichiers
tests, par la fonction library(NomPackage)
page 31/44
●
Les sorties des tests peuvent être comparées à des fichiers de référence.
La commande de vérification (R CMD check ou la fonction check()) exécute les tests et stocke leurs sorties dans
des fichiers de son répertoire résultat dont le nom est de la forme NomFichierTest.Rout. En transférant ces
fichiers dans le répertoire tests du package courant sous le nom NomFichierTest.Rout.save, on en fait la
référence par rapport à laquelle les résultats des tests seront comparés à la prochaine vérification: leurs
différences par rapport à ceux produits par l'exécution courante seront signalées. On pourra ainsi vérifier si ces
différences sont dûes à une erreur, ou si elles sont la conséquence des changements apportés dans le package.
Exemple. En se plaçant dans le répertoire parent de monpkg, vérification du package. On s'assure que la sortie
du test tmafct.R est valide. On la déplace dans le répertoire tests sous le nom tmafct.Rout.save pour qu'elle
serve de référence à la prochaine vérification du package.
$ # Vérification du package $ R CMD check monpkg -l ~/pkgCheck -o ~/pkgCheck $
# On regarde si le test donne le résultat attendu $ more
~/pkgCheck/monpkg.Rcheck/tests/tmafct.Rout $
# On met le résultat dans 'tests' pour qu'il serve de référence $ mv
~/pkgCheck/monpkg.Rcheck/tests/tmafct.Rout monpkg/tests/tmafct.Rout.save
●
Les sorties des exemples (c.-à-d. les parties "examples" contenues dans les fichiers Rd) peuvent être
comparées à des fichiers de référence.
La commande de vérification exécute les exemples contenus dans les fichiers Rd et stocke leurs résultats dans
un fichier de son répertoire résultat nommé NomPackage-Ex.Rout. En créant un répertoire Examples dans le
répertoire tests du package courant et en y déplaçant ce fichier sous le nom NomPackage-Ex.Rout.save, on en
fait la référence par rapport à laquelle les résultats des exemples seront comparés à la prochaine vérification.
Exemple. En se plaçant dans le répertoire parent de monpkg, vérification du package. Le fichier contenant les
sorties de tous les exemples est déplacé dans le répertoire tests/Examples en y ajoutant le suffixe .save. Il
servira de référence à la prochaine vérification du package.
$ # Vérification du package $ R CMD check monpkg -l ~/pkgCheck -o ~/pkgCheck $
# Création du répertoire monpkg/tests/Examples $ mkdir monpkg/tests/Examples $
# On met la sortie des exemples dans ce répertoire $ cd monpkg/tests/Examples $ mv
~/pkgCheck/monpkg.Rcheck/monpkg-Ex.Rout monpkg-Ex.Rout.save
Attention. L'option --timings de la commande check ne doit pas être positionnée pour cette comparaison. Noter
qu'elle l'est implicitement avec l'option --as-cran et toujours avec la fonction check() de devtools.
page 32/44
●
Pour une mise à disposition du package sur le CRAN,
❍
vérifier les temps d'exécution des tests.
❍
ne pas faire exécuter par le CRAN des tests effectuant du code en parallèle car, les machines du CRAN
testant plusieurs packages en parallèle, des confusions sont possibles.
❍
ne pas faire afficher, dans les fichiers tests, des temps d'exécution ou des résultats d'opérations complexes
avec une trop grande précision car ils varient selon les plateformes.
❍
pour qu'un test ne soit pas exécuté par le CRAN, mais seulement lorsque nous-mêmes faisons les
vérifications, inclure son nom dans le fichier .Rbuildignore.
❍
pour qu'une partie de test ne soit pas exécutée par le CRAN, mais seulement lorsque nous-mêmes faisons
les vérifications, utilisons la fonction check() du package devtools et la variable d'environnement
NOT_CRAN, que devtools positionne à la valeur TRUE. Sachant que le CRAN utilise R CMD check pour
valider les packages qu'on lui soumet, on conditionne le test à n'être exécuté que par la fonction de
devtools en testant la variable d'environnement NOT_CRAN.
Exemple. Le fichier test skiponcran.R.
library("monpkg")
if (!identical(Sys.getenv("NOT_CRAN"), "true"))
quit()
... instructions du test ...
Les instructions du test ne sont exécutées que si la variable NOT_CRAN est TRUE, c'est-à-dire que si le
fichier est exécuté via devtools. Elles sont ignorées par la commande R CMD check, donc notamment lors
de la vérification du package par le CRAN.
Voir aussi, les packages R:
●
testthat, "Tools to make testing fun", qui comporte des fonctions pour tester facilement la valeur de données
ou résultats. Voir son utilisation pour vérifier des données dans la fiche R4Ciam "Validation des données
avec testthat".
●
RUnit, pour faire des tests unitaires. Voir sa vignette: "RUnit primer"
●
svUnit, "A complete unit test system and functions to implement its GUI part". Voir sa vignette: "svUnit - A
framework for unit testing in R"
Le fichier CITATION : l'article de référence du package
Le fichier inst/CITATION, quand il existe, contient la référence que l'utilisateur doit citer quand il publie des
résultats obtenus avec le package.
●
Voir exemples et explications au paragraphe "CITATION files" de Writing R Extensions.
Attention: la fonction citEntry() ne doit plus être utilisée. bibentry() la remplace.
●
Le fichier CITATION peut contenir les références de plusieurs articles ou ouvrages.
page 33/44
●
Le contenu du fichier CITATION est affiché par la fonction R citation(). À défaut, la référence est construite
automatiquement à partir des informations contenues dans le fichier DESCRIPTION.
Exemple de citation créée à partir du fichier DESCRIPTION.
> citation.("BH")
Pour citer le package BH dans une publication, utilisez :
Dirk Eddelbuettel, John W. Emerson and Michael J. Kane (2014).
BH: Boost C++ header files. R package version 1.54.0-2.
http://CRAN.R-project.org/package=BH
...
ATTENTION : Cette information de citation a été générée automatiquement
depuis le fichier DESCRIPTION ...
●
Pour ne pas avoir à répéter la citation dans les fichiers Rd, on pourra simplement y rappeler son existence
dans la clause \references.
Exemple dans le fichier GGMselect-package.Rd :
\references{To cite GGMselect, please use \code{citation("GGMselect")}.}
La vignette
Une vignette est un document LaTeX qui inclut des exemples d'utilisation du package. Elle est compilée par un
"moteur de vignette" qui reconnaît les parties de code R, les exécute et insère leurs résultats dans le fichier LaTeX
produit en sortie. Le moteur est activé automatiquement à la vérification et à la construction du package, et le PDF
généré est inclus dans le répertoire doc du tar-archive délivré. Cette création dynamique de la vignette assure que
les exemples qu'elle comporte sont toujours à jour, même lorsque le package évolue.
L'utilisateur a accès à la vignette via le lien "User guides, package vignettes and other documentation" dans l'aide
en ligne du package. Il peut aussi utiliser la fonction vignette() du package utils pour avoir accès aux vignettes d'un
package (voir la fiche R4Ciam "Afficher des vignettes").
Le moteur par défaut est Sweave. D'autres "moteurs de vignette" sont acceptés par R, par exemple knitr (voir le
paragraphe "Non-Sweave vignettes" de Writing Extensions).
●
Pour une aide sur Sweave, voir la fiche R4Ciam: "Introduire du code et des sorties R dans un document
LaTeX avec Sweave".
●
Les fichiers sources doivent être placés dans un répertoire nommé vignettes et avoir le suffixe .Rnw ou .Rtex
(fichiers Sweave) ou .Rmd (fichiers knitr).
Les éventuels styles LaTeX ou autres fichiers nécessaires doivent être placés aussi dans le répertoire
vignettes.
page 34/44
●
Dans le fichier source, un commentaire indique le moteur utilisé, par exemple :
%\VignetteEngine{knitr::knitr}
et, éventuellement l'encodage, si non déjà indiqué dans le fichier le fichier DESCRIPTION (voir le
paragraphe Caractères accentués) :
%!\VignetteEncoding{UTF-8}
ou
\usepackage[utf8]{inputenc}
●
Les fichiers Sweave contiennent :
\usepackage{Sweave}
et les fichiers knitr, dans le premier "chunk" d'exécution :
library(knitr)
●
Lorsque les vignettes ne sont pas Sweave, le moteur doit être indiqué dans le fichier DESCRIPTION.
Exemple :
VignetteBuilder: knitr
Suggests: knitr
●
L'accès au package, même s'il est encore en développement et non encore installé, se fait, dans les fichiers
sources Sweave, par la fonction library(NomPackage)
●
La vignette est compilée automatiquement à la vérification et à la construction du package. Pour la compiler
séparemment, utiliser la fonction build_vignettes() du package devtools ou la fonction buildVignette().
Exemple. En se plaçant dans le répertoire parent de monpkg, chargement du package comme s'il était
installé, et compilation de la vignette par build_vignettes().
> library(devtools)
> load_all(pkg = "monpkg")
> build_vignettes(pkg = "monpkg")
Le fichier PDF est créé dans le répertoire inst/doc de monpkg. Le visualiser puis le détruire par :
> clean_vignettes(pkg = "monpkg")
●
À l'installation du package, en l'absence de fichier inst/doc/index.html (voir Créer soi-même l'index du
répertoire doc), un lien sur la vignette est automatiquement rajouté dans l'index de la documentation. Il a pour
label la valeur de la déclaration \VignetteIndexEntry{}, ou, à défaut, le nom du fichier vignette avec le suffixe
".pdf".
page 35/44
●
Pour un dépôt sur le CRAN:
❍
Le PDF doit être compressé : ajouter l'option "--compact-vignettes" à la commande R CMD build. Les
outils de compression disponibles sont indiqués par la commande R CMD build --help.
❍
Le PDF ne doit pas être trop gros (< 5MB) et le temps de compilation (exécution du code R et création
du PDF) ne doit pas excéder quelques secondes.
❍
La déclaration "BuildVignettes: no" dans le fichier DESCRIPTION ne doit être utilisée
qu'exceptionnellement. Elle peut être incompatible avec certaines licences (GPL > 2, par exemple). La
commande R CMD check émet un warning si c'est le cas.
Les autres fichiers de documentation
La documentation constituée des fichiers Rd et des vignettes peut être complétée par d'autres fichiers, en général
en format PDF. Il suffit de les placer dans le répertoire inst/doc.
Attention: On a constaté avec R 3.1.1 que
❍
les liens sur les fichiers situés dans inst/doc ne sont rajoutés dans l'index de la documentation que s'il y a
AUSSI une vignette. S'il y a des fichiers dans inst/doc et pas de répertoire vignettes (ou s'il est vide), le lien
sur "User guides ... other documentation" dans l'aide en ligne du package ouvre une page vide. Si c'est le
cas, créer soi-même l'index de la documentation.
❍
le fichier de nom Vignette.pdf est automatiquement éliminé du package, lors de la construction de celui-ci.
Les "démos"
Les "démos" sont des scripts R illustrant des fonctionnalités du package. L'utilisateur les voit dans l'aide en ligne du
package ou par la fonction demo(package="NomPackage"). Il les exécute par la fonction demo("NomDemo").
●
Les démos doivent être dans un répertoire nommé demo. Le nom des fichiers doit être de la forme
NomDemo.R.
Exemple. Le fichier monpkg/demo/dmafct.R :
# Basic use of function "mafct" print(mafct(3))
●
Les démos doivent être décrites dans un fichier nommé 00Index dans le répertoire demo.
Exemple. Le fichier monpkg/demo/00Index :
dmafct
Basic use of function mafct
Une ligne par démo : le nom de celle-ci, un tabulate ou au moins 3 caractères blancs, sa description.
Fichier LICENSE
Un fichier LICENSE, placé à la racine de la hiérarchie, permet de spécifier une licence particulière. Il doit la décrire
complètement. Voir un modèle à http://www.r-project.org/Licenses/MIT.
Dans le fichier DESCRIPTION, modifier alors la déclaration "License":
page 36/44
License:
file LICENSE
ou
License: GPL-3 + file LICENSE
Fichier NEWS
Le fichier NEWS, placé à la racine de la hiérarchie, décrit les évolutions du package. Voir le paragraphe Gérer les
versions successives.
Faire un package de données
Organiser ses données en package permet de les partager, de les retrouver et de les documenter d'une façon
normalisée. La démarche, pour faire un package constitué uniquement de données, est quasi-similaire à celle du
cas général.
●
Pas de répertoire R, mais un répertoire data qui contient les jeux de données sous forme de fichier .RData
(ou .rda) ou sous forme de fichier texte. Voir le paragraphe Les données à disposition de l'utilisateur.
●
Le fichier NAMESPACE peut être vide ou contenir n'importe quelle expression d'exportation valide, mais il
doit exister.
●
Chaque jeu de données est décrit dans un fichier Rd du répertoire man. Le squelette de ce fichier est créé à
l'initialisation du package, par la fonction package.skeleton(), ou ensuite, par la fonction promptData().
●
Les fichiers et répertoires facultatifs sont les mêmes que dans le cas général.
●
Les procédures de création du package, vérification construction du tar-archive, installation sont identiques à
celles du cas général.
●
Le chargement des données dans la session utilisateur se fait par la fonction data() ou, si le fichier
DESCRIPTION contient la déclaration "LazyData: true", à la première utilisation (voir l'accès aux données).
Illustration sur un exemple.
1. Création du package monpkgD qui contient le data-frame madonnee.
> madonnee <- data.frame(x=1:3, nom=paste("n", 1:3, sep="-"))
> package.skeleton(name = "monpkgD", list="madonnee")
2. Modification des fichiers créés dans le répertoire monpkgD: DESCRIPTION, NAMESPACE (ce fichier peut
être rendu vide), et des fichiers Rd du répertoire man.
page 37/44
3. Création de tests (facultatif).
On crée un répertoire tests et dans celui-ci, le fichier madonnee.R, qui vérifie la validité des données en
utilisant des fonctions du package testthat (voir la fiche R4Ciam "Validation des données avec testthat").
library(testthat)
library(monpkgD)
data(madonnee)
expect_true(is.numeric(madonnee$x))
expect_false(anyNA(madonnee$x), info="Présence de valeurs manquantes")
Le package testthat étant utilisé dans les tests, on rajoute sa déclaration dans le fichier DESCRIPTION.
Suggests: testthat
4. Vérification du package par la fonction check() de devtools.
> library(devtools)
> check(pkg="monpkgD")
5. Construction du tar-archive :
> build(pkg="monpkgD")
6. Installation du package dans un répertoire local.
> install(pkg="monpkgD", args="-l ~/ESSAI")
7. Le package peut maintenant être utilisé :
>
>
>
>
library(monpkgD, lib.loc="~/ESSAI")
help(madonnee)
data(madonnee)
print(madonnee)
page 38/44
8. On décide ensuite d'y rajouter un fichier de données.
1. Dans le répertoire data, création du fichier monfic.txt.
V1 V2
1 2
11 22
13 14
2. Création de sa documentation, en se plaçant dans le répertoire monpkgD.
> monfic <- read.table("data/monfic.txt", header=TRUE)
> promptData(monfic)
Le fichier monfic.Rd est complété et déplacé dans le répertoire man.
3. Vérification du package, reconstruction du tar-archive et réinstallation dans le répertoire local.
>
>
>
>
library(devtools)
check(pkg=".")
build(pkg=".")
install(pkg=".", args="-l ~/ESSAI")
4. Utilisation.
>
>
>
>
library(monpkgD, lib.loc="~/ESSAI")
help(monfic)
data(monfic)
print(monfic)
Mesurer les temps d'exécution
Pour un dépôt au CRAN, le temps passé dans chaque étape de vérification/installation ne doit pas dépasser
quelques secondes "on a rather fast machine", y compris le temps d'exécution de chaque test et exemple (un
exemple est le contenu de la clause "examples{}" des fichiers Rd). La commande R CMD check (ou la fonction
check() du package devtools) permet de mesurer ces temps.
●
Le temps d'exécution des tests est indiqué à la fin de leurs fichiers de sortie.
Exemple. En se plaçant dans le répertoire parent de monpkg, vérification du package. On visualise les 5
dernières lignes des fichiers de sortie des tests, dans lesquelles sont consignés les temps d'exécution.
$ tail -n 5 ~/pkgCheck/monpkg.Rcheck/tests/*.Rout
page 39/44
●
Pour mesurer le temps d'exécution de chaque exemple, utiliser l'option --timings de la commande R CMD
check. Cette option est implicitement positionnée par l'option --as-cran et par la fonction check() de devtools.
Exemple. En se plaçant dans le répertoire parent de monpkg, vérification du package. On visualise le fichier
~/pkgCheck/monpkg.Rcheck/monpkg-Ex.timings où sont stockés les temps d'exécution des exemples.
$ R CMD check monpkg -l ~/pkgCheck -o ~/pkgCheck --timings
$ more ~/pkgCheck/monpkg.Rcheck/monpkg-Ex.timings
Si l'exécution d'une partie d'un exemple est particulièrement longue, on peut la mettre dans une balise
\dontrun{}, mais seulement si cela se justifie.
●
Pour mesurer le temps passé dans chaque étape, positionner une variable d'environnement,
_R_CHECK_TIMINGS_ à la valeur 0 avant de lancer la commande R CMD check.
Exemple.
$ _R_CHECK_TIMINGS_=0
$ export _R_CHECK_TIMINGS_
Les temps d'exécution des étapes apparaissent à l'écran, au fur et à mesure de l'exécution de la commande,
entre crochets, arrondis à la seconde (CPU et elapsed times).
Note. Ceci n'est valable que pour la commande R CMD check. Positionner _R_CHECK_TIMINGS_ est
ineffectif lorsqu'on utilise la fonction check() de devtools.
Voir explications détaillées dans le paragraphe "Check-timing" de Writing Extensions sur le site du CRAN.
Effectuer des actions au chargement du package
Les actions à effectuer au chargement du package doivent être indiquées dans une fonction .onLoad() ou
.onAttach(). Il est d'usage de stocker ces fonctions dans un fichier nommé zzz.R.
Exemple. Le fichier monpkg/R/zzz.R demande l'impression d'un message au chargement du package. Le message
indique le nom du package courant et son numéro de version.
.onLoad <- function(libname, pkgname)
{
packageStartupMessage(paste("Loaded", pkgname),
as.character(utils::packageVersion(pkgname)),"\n")
}
Au chargement du package monpkg, le message apparaît.
> library(monpkg)
Loaded monpkg0.0-0
●
Utiliser .onLoad() pour afficher une bannière de démarrage, et .onAttach() pour positionner des options ou
charger des objects partagés.
●
Ne pas documenter ces fonctions dans le répertoire man. Ne pas les exporter dans le fichier NAMESPACE.
En savoir plus. Voir le paragraphe "Load hooks" de Writing R Extensions.
Délivrer le PDF de la documentation
page 40/44
Le manuel du package est la version PDF du fichier DESCRIPTION et des fichiers .Rd, réunis en un seul fichier. Il
est créé par la commande R CMD check (ou la fonction check() du package devtools). On le rend disponible aux
utilisateurs en le recopiant dans le répertoire inst/doc. Voir le paragraphe Le manuel du package.
Créer soi-même l'index du répertoire doc
À l'installation du package, un fichier nommé index.html est créé dans le répertoire doc (recopie du répertoire
inst/doc). C'est le fichier qui s'ouvre quand l'utilisateur clique sur le lien "User guides, package vignettes and other
documentation" dans l'aide en ligne du package. Cet index contient la liste cliquable des fichiers du répertoire doc:
vignette et autres fichiers PDFs. Les liens sur les vignettes ont pour label la valeur de la déclaration
\VignetteIndexEntry{} incluse dans les fichiers Rnw, ou, à défaut, les noms des fichiers Rnw, où le suffixe est
remplacé par ".pdf". Les liens sur les autres fichiers ont pour label leurs noms.
S'il existe un fichier index.html dans inst/doc, il supplante cet index par défaut.
Exemple de fichier inst/doc/index.html :
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>monpkg: documentation index</TITLE>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</HEAD>
<BODY>
<H2>monpkg: documentation index</H2>
<a href="Vignette.pdf">Vignette</a> (18 p.)
<a href="monpkg-manual.pdf">Manual</a> (6p.)
</body></html>
Exclure des fichiers du package
Le package source peut contenir des fichiers et des répertoires que l'on ne souhaite pas inclure dans le package
délivré. Pour les exclure, citer leurs chemins d'accès dans un fichier nommé .Rbuildignore, situé à la racine du
répertoire.
Exemple de fichier .Rbuildignore:
man/.*.html
R/ARCHIVES
Attention. Citer les fichiers Sweave dans .Rbuildignore ne suffit pas à les ignorer. Il faut aussi positionner l'option
--no-build-vignettes dans les commandes check et build pour qu'ils ne soient pas compilés.
Rajouter des fichiers non standard dans le package délivré
Pour ajouter dans le package délivré des fichiers et des répertoires non prévus par R, les mettre dans un répertoire
nommé inst, situé à la racine du package.
Attention: à l'installation du package, le contenu de ce répertoire est remonté d'un niveau. Par conséquent, ne pas
y mettre des fichiers ou répertoires dont le nom entrerait en conflit avec ceux de R.
Exemples de cas où on a besoin de créer un répertoire inst: il y a un fichier CITATION, ou un répertoire doc,
lequel contient la documentation supplémentaire.
Créer une version compilée pour Windows
Le système win-builder du CRAN (win-builder.r-project.org) vérifie et construit la version Windows d'un package.
On l'utilise soit via la fonction build_win() du package devtools, soit par un dépôt ftp. Le "maintainer" mentionné
dans le fichier DESCRIPTION reçoit 1/2h après environ, un mail lui indiquant où il peut récupérer le binaire
Windows et les résultats de la vérification. Le délai de récupération est d'environ 72 heures.
page 41/44
Exemple. Soumission du package monpkg à win-builder, après avoir vérifié le monpkg_0.0-0.tar.gz avec l'option
--as-cran.
ftp win-builder.r-project.org
Name (cran.r-project.org:jdupont): anonymous
Password: [email protected]
binary
cd R-release
put monpkg_0.0-0.tar.gz
quit
Le tar.gz peut être déposé dans le répertoire R-release, comme dans cet exemple, pour être testé avec la dernière
version distribuée de R ou dans le répertoire R-devel pour être testé avec la prochaine version à venir de R.
Gérer les versions successives
Quand on délivre une nouvelle version du package, il ne faut pas oublier de :
●
Mettre à jour la date et la version dans le fichier DESCRIPTION.
●
Indiquer les différences entre versions dans un fichier nommé NEWS. Ce fichier est facultatif mais
recommandé pour garder une trace et informer les utilisateurs des apports de chaque version (voir les
standards GNU quant à son format). L'utilisateur le visionnera par la fonction news().
Exemple. Affichage du fichier NEWS du package R.methodsS3.1.6.1 :
> news(package="R.methodsS3")
Changes in version 1.6.1 (2014-01-04):
o
CLEANUP: Dropped obsolete argument 'ellipsesOnly' from setGenericS3().
It was not used. Thanks Antonio Piccolboni for reporting on this.
o
BUG FIX: Generic function created by setGenericS3("foo<-") would not
have a last argument name 'value', which 'R CMD check' complains about.
o
ROBUSTNESS: .... etc ...
Note. Les différences entre versions peuvent être également notées dans un fichier nommé ChangeLog.
Contrairement au fichier NEWS, il n'y a pas de lien sur ce fichier depuis la page d'aide en ligne du package. Il n'est
visible que dans le package source. Le fichier ChangeLog est plutôt destiné à un public de développeurs (ou à
soi-même !).
●
Si nécessaire, mettre à jour
❍
les résultats des tests, s'ils ont été stockés dans des fichiers de référence (fichiers NomTest.Rout.save
du répertoire tests),
❍
les résultats des exemples, s'ils ont été stockés dans un fichier de référence (fichier
NomPackage-Ex.Rout.save du répertoire tests/Examples),
❍
le PDF des documents du répertoire inst/doc, s'ils contiennent des exemples d'utilisation (le PDF des
vignettes, sauf indication contraire, est reconstruit automatiquement),
❍
le PDF du manuel, si celui-ci est recopié dans inst/doc.
page 42/44
Avant d'envoyer le package au CRAN
Vérifier les titres dans le fichier DESCRIPTION et dans les fichiers Rd
La première lettre des mots principaux doit être en majuscule. Ne pas mettre de point final. Ne pas indiquer
quelque chose de redondant du genre This package ..., ou monpkg ...
Pour vérifier que les titres ne dépassent pas 65 caractères, ouvrir le manuel PDF : les titres qui s'affichent sur
plusieurs lignes sont presque certainement trop longs.
Respecter les conventions pour les fichiers Rd
Voir celles-ci dans Guidelines for Rd files, sur le site R Developer Page.
Respecter les bonnes pratiques pour les fichiers R
Voir le paragraphe Bonnes pratiques.
Vérifier que le tar-archive ne contient pas de fichiers superflus.
Lister par la commande Unix "tar tf" le contenu du fichier tar.gz et vérifier qu'il ne contient pas de fichiers
superflus, car la procédure de vérification ne les signale pas tous. Détruire ces fichiers ou les exclure du
package.
Vérifier que les fichiers sont dans un encodage standard
UTF-8 par exemple, mais pas iso-8859-1, comme c'est souvent automatiquement le cas quand ils comportent
des caractères accentués ou des quotes.
Pour vérifier l'encodage d'un fichier sous Unix, utiliser la commande "file --mime-encoding" et pour convertir un
encodage en un autre, la commande "iconv".
Vérifier les temps d'exécution.
Chacune des étapes de vérification, création, installation du package, et le temps d'exécution de chaque
exemple et test ne doit pas dépasser quelques secondes. Voir le paragraphe "Mesurer les temps d'exécution".
Vérifier la taille des fichiers de documentation et de données.
Les répertoires vignettes et inst/doc ne doivent pas contenir de gros fichiers, même s'ils sont compressés. Le
PDF correspondant à la vignette compilée ne doit pas non plus être trop gros. Voir le paragraphe "Writing
package vignettes" dans Writing R Extensions sur le site du CRAN : "Do watch that PDFs are not too large" et
la CRAN Repository Policy : "neither data nor documentation should exceed 5MB".
Vérifier le tar-archive avec l'option as-cran.
Vérifier le fichier tar.gz avec la version de R la plus récente possible et avec les options qui assurent le
maximum de vérifications dont --as-cran. Exemple.
R CMD check monpkg_0.0-0.tar.gz --as-cran -o ~/pkgCheck -l ~/pkgCheck
S'il y a des programmes C ou Fortran, ajouter l'option --use-valgrind (voir le paragraphe "La vérification du
package (détail)").
Si la vérification avec l'option --as-cran émet des warnings qu'on juge acceptables, il faudra les justifier dans
une note explicative lors de la soumission.
Créer une version compilée pour Windows.
Même si on n'en a personnellement aucune utilité, créer une version Windows permet de s'assurer que le
package est compatible avec ce système.
Lire le paragraphe "Submission" de la CRAN Repository Policy.
page 43/44
Comment soumettre au CRAN
Ouvrir cran.r-project.org/submit.html et attendre un email de confirmation. Un lien est envoyé au "maintainer" du
package. L'ouvrir, ne pas oublier de cocher la case "Read policy" et confirmer la soumission.
Le "maintainer" reçoit au bout de quelques jours deux courriers: l'un lui indique si le package a passé les tests de
validité, l'autre si sa compilation Windows a réussi. Les résultats de ces tests sur divers systèmes sont disponibles
à l'URL http://cran.r-project.org/web/checks/check_results_NomPackage.html.
Attention. Le package n'est pas testé sur tous les systèmes en même temps. Ne pas resoumettre avant que les
tests soient terminés sur tous les systèmes et avant d'avoir corrigé les erreurs constatées sur un maximum d'entre
eux.
Toute resoumission est considérée comme la soumission d'une nouvelle version. Voir le paragraphe "Gérer les
versions successives". En particulier, le numéro de version doit être incrémenté, même si la version précédemment
soumise n'a jamais été publiée.
Exemples
Voir, à titre d'exemple, les packages déposés sur le CRAN. La plupart des sources est également visible
directement sur GitHub.
Références
●
Writing R Extensions, sur le site du CRAN
●
Creating R package: A Tutorial, par F. Leisch: PDF (14/9/2009, 19 pages)
●
Construire un Package, Classic et S4, par C. Genolini: PDF (9/9/2009, 53 pages)
●
Package Development in Windows, par D. Murdoch: PDF (13/08/2008, 21 pages).
●
R packages, Hadley Wickham (2015). O'Reilly Ed. Order from amazon. HTML
●
R package primer, a minimal tutorial, par Karl Broman. Cours en ligne.
●
●
Writing an R package from scratch, par Hilary Parker. Comment faire un package personnel.
Le package R devtools.
page 44/44

Guide packages R sous Unix - Informatique de MIA

Transcription

Documents pareils

Window Sticker - FordDirect.com

LAMBORGHINI 184000 € Murcielago Roadster LP 640

Fiche Cours PDF

Le Youth Package, un programme innovateur de la Banque Libano

HOTEL Packages

package codeFourni.typesBasiques

brochure-defis-du-chott-2010

Compte rendu d`Activité CREATION DE PACKAGES MSI ET

comment créer son propre package sous R