Guide packages R sous Unix - Informatique de MIA

Transcription

Version HTML
Introduction à la création de packages R sous Unix
A. Bouvier
Version 2_6 - mai 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 ?
L'essentiel
..................................................................................................................................................................................................................................................
p. 3
..................................................................................................................................................................................................................................................................................
p. 3
Qu'est-ce qu'un package R ?
.......................................................................................................................................................................................................................................
Préliminaire à la diffusion sur le CRAN
p. 3
........................................................................................................................................................................................................................
p. 3
Choisir une licence .......................................................................................................................................................................................................................................................
p. 3
La démarche de construction .......................................................................................................................................................................................................................................
p. 3
Fichier DESCRIPTION .................................................................................................................................................................................................................................................
p. 4
Fichier NAMESPACE ...................................................................................................................................................................................................................................................
p. 5
Répertoire man et fichiers Rd
......................................................................................................................................................................................................................................
p. 5
Répertoire R .................................................................................................................................................................................................................................................................
p. 5
Vérifier le package
p. 5
.......................................................................................................................................................................................................................................................
Construire le fichier tar-archive
....................................................................................................................................................................................................................................
p. 6
Installer/utiliser le package ...........................................................................................................................................................................................................................................
p. 6
Récapitulatif des étapes ...............................................................................................................................................................................................................................................
p. 7
Autres répertoires et fichiers
........................................................................................................................................................................................................................................
p. 7
Détails ........................................................................................................................................................................................................................................................................................
p. 7
Les fichiers de documentation Rd (détail) ....................................................................................................................................................................................................................
p. 7
Quelques balises Rd
.................................................................................................................................................................................................................................................... p. 10
La vérification du package (détail)
............................................................................................................................................................................................................................... p. 11
Interprétation de messages de la commande 'check'
Situations particulières
.................................................................................................................................................................................................. p. 13
.............................................................................................................................................................................................................................................................. p. 13
Caractères accentués
.................................................................................................................................................................................................................................................. p. 13
Classes et méthodes
................................................................................................................................................................................................................................................... p. 13
Dépendances (besoin d'un autre package)
Programmes C, Fortran, C++
................................................................................................................................................................................................................. p. 18
...................................................................................................................................................................................................................................... p. 19
Données ....................................................................................................................................................................................................................................................................... p. 19
Package récupéré sur le CRAN
................................................................................................................................................................................................................................... p. 20
Code issu d'un code préexistant
.................................................................................................................................................................................................................................. p. 20
Facultatif
.................................................................................................................................................................................................................................................................................... p. 20
Fichiers de tests
........................................................................................................................................................................................................................................................... p. 20
Fichier CITATION (article de référence)
Vignette
...................................................................................................................................................................................................................... p. 21
........................................................................................................................................................................................................................................................................ p. 21
Autres fichiers de documentation ................................................................................................................................................................................................................................. p. 22
Démos .......................................................................................................................................................................................................................................................................... p. 22
Fichier LICENSE
Fichier NEWS
Comment faire pour
.......................................................................................................................................................................................................................................................... p. 23
.............................................................................................................................................................................................................................................................. p. 23
................................................................................................................................................................................................................................................................... p. 23
Faire un package de données
..................................................................................................................................................................................................................................... p. 23
Mesurer les temps d'exécution
.................................................................................................................................................................................................................................... p. 24
Effectuer des actions au chargement du package
Délivrer le PDF de la documentation
Créer l'index du répertoire doc
....................................................................................................................................................................................................... p. 25
........................................................................................................................................................................................................................... p. 25
..................................................................................................................................................................................................................................... p. 25
Exclure/ajouter des fichiers du package
...................................................................................................................................................................................................................... p. 25
Faire une version Windows .......................................................................................................................................................................................................................................... p. 26
Gérer les versions successives
Soumettre au CRAN
................................................................................................................................................................................................................................... p. 26
.................................................................................................................................................................................................................................................................. p. 26
Références et exemples
............................................................................................................................................................................................................................................................ p. 27
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.
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").
Copyright © 2016 INRA - CaSciSDI
page 3/27
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.
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.
Note.
Le squelette du fichier DESCRIPTION peut être recréé à tout moment par la fonction create_description() du package devtools.
page 4/27
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" dans leurs 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 package dans sa totalité, par une clause
import(NomPackage), ou seulement certaines de ses fonctions, par une clause importFrom(NomPackage, 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ès le 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).
●
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
page 5/27
à 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 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.
page 6/27
> library("monpkg" , lib.loc="~/ESSAI")
> help("mafct")
> mafct(3)
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)
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.
page 7/27
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.
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")
page 8/27
●
●
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.
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 9/27
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.
●
Pour faire des liens sur un autre fichier de documentation:
\link{nomfonction}
\linkS4class{nomclasse}
# lien sur une fonction
# lien sur une classe S4
●
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}
page 10/27
●
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.
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 d'exécution".
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
page 11/27
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
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 12/27
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?
●
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.
page 13/27
- 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)
[1] print.acf*
[2] print.addvar
....
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
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 14/27
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 15/27
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 16/27
●
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}
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)
page 17/27
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.
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".
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 18/27
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.
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 19/27
●
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)
●
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 20/27
●
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.
●
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 21/27
●
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".
●
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").
page 22/27
●
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":
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.
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
page 23/27
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)
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 24/27
●
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
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:
page 25/27
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.
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.
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
page 26/27
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.
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 27/27

Guide packages R sous Unix - Informatique de MIA

Transcription

Documents pareils

Window Sticker - FordDirect.com

MEDParts : Bibliothèque de composants CAO

LAMBORGHINI 184000 € Murcielago Roadster LP 640

5e année - École Joseph

Fiche Cours PDF

PPT Conf RH Skema

Le Youth Package, un programme innovateur de la Banque Libano

HOTEL Packages

package codeFourni.typesBasiques