UTILISATION AVANCÉE DE R AVEC RSTUDIO. Eric Marcon 21/09/2014 1

Transcription

1 UTILISATION AVANCÉE DE R AVEC RSTUDIO Eric Marcon 21/09/2014 1

2 Utilisation avancée de R avec RStudio Ce document évolue avec les avancées de la recherche. Il est susceptible de contenir des erreurs ou des inexactitudes qui sont corrigées dès que l auteur en a connaissance. Les opinions émises par les auteurs sont personnelles et n engagent pas l UMR EcoFoG ou ses tutelles.

3 UTILISATION AVANCÉE DE R AVEC RSTUDIO Sommaire Objectifs... 5 Projet R... 7 Logiciels nécessaires... 7 R 7 R Tools 7 R Studio 7 Packages R 8 LaTeX 8 Options de RStudio... 8 Options générales 8 Création d un projet... 9 Documentation rapide Portfolio 10 Rapport Markdown 12 Rapport Sweave 13 Rapports knitr 16 Package R...19 Création d un package Structure d un package Fichier DES CRIP TION 20 Fichier NAMESPACE 20 Fichier NEWS 21 Répertoire Man : description du package21 Répertoire R : code des fonctions 23 Code des fonctions C 23 Répertoire man : aide des fonctions 24 Répertoire data : données 26 Répertoire man : description des données 26 Fichier inst/citation 27 Vignettes 28 Répertoire.#Extra 29 Compilation Publication Conclusion

4

5 OBJECTIFS L objectif de ce document est de montrer comment utiliser efficacement R et RStudio pour la production de code et sa documentation, dans le cadre d un projet R (au sens de RStudio). La création d un package est traitée dans un deuxième temps comme un projet particulier. Les prérequis sont : La connaissance de R, la maîtrise de son fonctionnement courant ; syntaxe, création de fonctions, scripts. La connaissance de l utilisation basique de RStudio : organisation des fenêtres, installation de packages, exécution de code, création de figures. La connaissance de base de LaTeX pour la documentation avec Sweave ou knitr : syntaxe, création d un document avec une bibliographie. La connaissance de base du langage C pour l utilisation de code C++ dans les projets. 5

6

7 PROJET R Logiciels nécessaires R doit être installé en version supérieure à 3.0. Utiliser la version 64 bits si le système d exploitation de l ordinateur le permet. R 1 Après l installation, modifier les droits du dossier library de R : Autoriser la modification aux utilisateurs de l ordinateur. Les packages pourront ensuite être installés dans le dossier du programme (et mutualisé entre les utilisateurs de l ordinateur), sans nécessiter de lancer R en tant qu administrateur. R Tools Les outils de développement de R 2 doivent être installés en version correspondant à celle de R pour permettre la compilation du code C++. R Studio Installer RStudio 3 Desktop en version supérieure à

8 Utilisation avancée de R avec RStudio Packages R Installer les packages : knitr pour la documentation. Rcpp pour l intégration de code C++. LaTeX Une chaîne de production LaTeX doit être installée sur le poste de travail pour l utilisation de Sweave dans le but de documenter les packages principalement. MiKTeX 4 est une solution performante pour Windows. Options de RStudio Les options importantes de RStudio doivent être fixées avant de commencer à travailler en utilisant le menu Tools / Global Options. Options générales R est détecté automatiquement

9 Projet R Le dossier de travail par défaut est placé dans le répertoire personnel de l utilisateur (noté ~), dans un sous dossier R. L encodage par défaut des fichiers doit être UTF-8 pour permettre l utilisation des caractères spéciaux (accents notamment). Création d un projet Lancer RStudio et utiliser le menu File / New Project, puis New Directory/Empty Project. Sélectionner le dossier (existant) dans lequel le projet sera créé, et le nom du projet (qui sera celui du dossier créé) : Un projet est un répertoire qui contiendra les fichiers (code, données, ) et un fichier de paramètres Projet RStudio.Rproj qui contient les options du projet. Le projet peut être ouvert à partir du fichier.rproj ou en utilisant le menu Projets qui se trouve en haut à droite de la fenêtre principale de RStudio : Quand le projet est fermé, l environnement de R est sauvegardé (après confirmation, selon les options du projet) comme son historique dans les fichiers.rdata et.rhistory. Quand le projet est ouvert, l environnement et l historique sont restaurés. Les options du projet sont par défaut héritées des options globales. Elles peuvent être modifiées avec le menu Tools / Projet options 9

10 Utilisation avancée de R avec RStudio Un fichier.rprofile peut être placé dans le dossier. Le script R qu il contient est exécuté systématiquement à l ouverture du projet, ce qui permet par exemple de charger les packages nécessaires. Le projet est prêt à être utilisé, il ne reste qu à créer les fichiers de script R. Documentation rapide Les scripts doivent être documentés par des commentaires (introduits par #). La création d un rapport de résultat d un script est fait basiquement en copiant les lignes de la console R, incluant le code lignes préfixées par un chevron >) et les résultats, les figures étant copiées manuellement : Export puis Copy Plot to clipboard, Cliquer sur MetaFile pour copier une image vectorielle, en évitant Bitmap, qui crée une image raster. Fixer la taille : pour une image vectorielle, la taille détermine le rapport hauteur/largeur et la taille relative des textes (légendes). R essaie de maintenir une taille constante des textes, qui sont donc relativement plus petits si l image est plus grande. Il est possible d automatiser la création de rapports simples avec les outils fournis par le package knitr. Portfolio À partir d un script R (sauvegardé dans un fichier.r), utiliser simplement le menu File / Compile Notebook... Le script suivant : # Résumé des données summary(cars) # Figures 10

11 Projet R plot(cars) produit un fichier (PDF, Word ou HTML au choix) qui peut être enregistré et diffusé (les images sont intégrées, le rapport est contenu dans un seul fichier) : Il est possible de formater mieux le rapport : les commentaires préfixés par # seront traités comme du texte, et les formatages Markdown (voir plus bas) sont traités : voir la ligne de titre dans l exemple ci-dessous. Le code est traité comme des chunks de knitr (voir plus bas) dont les options peuvent être spécifiées dans les lignes de commentaires préfixées par #+ (ici, la taille de l image). Le script devient : #' Titre #' ====== #' Résumé des données, avec formules mathématiques en TeX : $\beta$ summary(cars) #' Figures #+ image, fig.width=4, fig.height=4 plot(cars) et produit le rapport suivant : 11

12 Utilisation avancée de R avec RStudio Rapport Markdown Cette approche est intermédiaire entre un portfolio et un rapport Sweave écrit en LaTeX (paragraphe suivant). Utiliser le menu File / New File / R Markdown. Un fichier Markdown est un rapport rédigé dans un langage plus simple que LaTeX mais dans le même esprit. Utiliser le menu d aide de la barre pour la documentation de référence. Il contient du texte, au format Markdown, et des morceaux de code (chunks) délimités par des marques spécifiques : Title ======================================================== This is an R Markdown document. Markdown is a simple formatting syntax for authoring web pages (click the **Help** toolbar button for more details on using R Markdown). When you click the **Knit HTML** button a web page will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this: ```{r 12

13 Projet R summary(cars) ``` You can also embed plots, for example: ```{r fig.width=7, fig.height=6 plot(cars) ``` Le bouton Knit HTML produit un rapport au format HTML : Rapport Sweave Un rapport Sweave est un document élaboré, écrit en LaTeX avec intégration de morceaux de code R exécutés au moment de la compilation, qui permettent d assurer que les résultats du rapport (sorties de R, figures) sont bien le résultat du code, suivant le modèle de la recherche reproductible 5. Utiliser le menu File / New File / R Sweave. Le document est sauvegardé avec l extension.rnw. Sa syntaxe est celle de LaTeX. Il est possible d utiliser des packages, la bibliographie, des modèles La compilation du document se fait en deux temps : Sweave (qui était un package mais a été intégré à R) produit un fichier.tex à partir du fichier.rnw, le relais est ensuite passé à la chaîne de production de LaTeX pour produire un document pdf

14 Utilisation avancée de R avec RStudio Deux outils sont disponibles pour traiter les fichiers.rnw : Sweave et knitr. Le choix se fait dans les options du projet. Chunks En plus de la syntaxe LaTeX 6, les chunks sont insérés dans le code avec la syntaxe suivante : <<>>= Le chunk précédent sera intégré dans le texte : code et résultat. Le fichier suivant : \documentclass{article \begin{document \SweaveOpts{concordance=TRUE Texte \LaTeX et chunks: <<>>= \end{document produit le fichier pdf : Les options des chunks sont saisies entre les crochets de la première ligne : <<Addition, echo=true, eval=true>>= Le nom du chunk, Les options (au format Sweave) : echo (=TRUE par défaut) : affichage du code dans le document eval (=TRUE par défaut) : exécution du code (et donc affichage des résultats dans le document). include (=TRUE par défaut) : affichage du résultat du code. 6 Documentation complète : 14

15 Projet R Tous les chunks sont exécutés dans l ordre comme un seul script R. Les librairies doivent être chargées, les variables créés par un chunk sont disponible pour les suivants. Enfin, un chunk peut inclure le code d un autre : <<Inclusion>>= 1 est équivalent à : <<Inclusion>>= 1 Figures Un chunk produit une figure s il contient l option fig=true, par exemple : <<fig =TRUE, echo =FALSE >>= boxplot ( Ozone ~ Month, data = airquality Dans le fichier.rnw, le chunk remplace la commande : \includegraphics{figozone.pdf Le code complet pour afficher une figure est par exemple : \begin{figure \begin{center <<figozone, fig =TRUE, echo =FALSE >>= boxplot ( Ozone ~ Month, data = airquality \end{center \caption{légende \label{figozone \end{figure echo =FALSE permet de cacher le code et n afficher que la figure. Les options utiles pour les figures sont la largeur et la hauteur du fichier.pdf produit : width = 4 : largeur en pouces, height = 3 : hauteur en pouces. Ces tailles influent sur l aspect du texte dans le fichier : si la taille des caractères des légendes n est pas précisé dans le code R, le texte est dimensionné pour être lisible en fonction de la taille de la figure. Augmenter la taille revient à réduire la taille relative du texte. D autre part, changer le rapport hauteur / largeur modifie l aspect de la figure. La taille de la figure dans le document final est fixée par le code TeX, pas par les options de chunk. Pour afficher le code de la figure dans le texte et la figure à part, utiliser fig =TRUE et include=false dans le chunk de code. Il sera affiché, évalué, et produira une figure du nom du chunk avec l extension.pdf, préfixé par le nom du fichier.rnw suivi d un tiret (voir l exemple). La commande \includegraphics{ de TeX permettra d utiliser la figure : Le code de la figure~\ref{figozone est le suivant : <<Ozone, fig =TRUE, include =FALSE >>= boxplot ( Ozone ~ Month, data = airquality 15

16 Utilisation avancée de R avec RStudio \begin{figure \begin{center \includegraphics{nomfichierrnw-ozone.pdf \end{center \caption{légende \label{figozone \end{figure Options de Sweave Des options peuvent être fixées au niveau du document entier en incluant la commande suivante dans le fichier.rnw, juste après le début du document : \begin{document \SweaveOpts{concordance=TRUE, keep.source=false, width=5, height=4 Les deux dernières options sont la taille par défaut des graphiques, utilisée si elle n est pas modifiée au niveau de chaque chunk. keep.source=false demande à Sweave d interpréter toutes les commandes et de les réécrire, ce qui permet d automatiser leur formatage (retours à la ligne, espaces entres les signes ) au prix de la perte des commentaires. concordance=true est une option ajoutée par Rstudio (modifiable dans les options générales) pour la création d un fichier de concordance des numéros de lignes entre le fichier.rnw et le fichier.tex produit, ce qui permet de retrouver l emplacement des erreurs de compilation en convertissant les numéros de lignes du fichier.tex en numéros de lignes du fichier.rnw. Ces options peuvent être complétées par les options de R, insérées dans le premier chunk par exemple, pour modifier l aspect du code : <<Declarations, echo=false>>= options(prompt = "R> ", continue = "+ ", width = 70, usefancyquotes = Le code sera préfixé par «R>» au lieu de «>», coupé à 70 caractères pour un retour à la ligne préfixé par «+» suivi de deux espaces. Les guillemets produits par la fonction squote par exemple seront unidirectonnels et non bidirectionnels en Anglais comme le prévoit la grammaire. Rapports knitr knitr apporte des nouvelles fonctionnalités, principalement la gestion du cache des chunks : un chunk n est pas réévalué à chaque compilation du document. Un dossier cache est créé pour stocker les données nécessaires. Les figures sont stockées dans un dossier figure, et leur nom est celui du chunk, sans préfixe. La syntaxe est un peu différente. Un fichier Sweave peut être rapidement converti en fichier knitr avec la commande Sweave2knitr, utiliser l aide pour obtenir sa syntaxe : >?Sweave2knitr 16

17 Projet R Options de knitr Les options 7 ne sont pas déclarées dans une commande du fichier.rnw comme pour Sweave, mais dans une commande R dans le premier chunk : <<Declarations, echo=false, include=false>>= library(knitr) # set global chunk options opts_chunk$set(cache=true, warning=false, tidy=false, fig.width=8, fig.height=6, Les options principales sont : cache=true : demande que tous les chunks soient mis en cache, et recalculés seulement si leur code est modifié. warning=false : n affiche pas les avertissements renvoyés par le code. tidy=false : ne conserve pas le code R tel quel mais le reformate. fig.width=8 : largeur des figures, en pouces (idem fig.height). out.width='0.7\\maxwidth' : commande de formatage de la figure qui sera écrite dans le fichier.tex (idem out.height). La chaîne entre guillemets est passée au fichier TeX, entre les crochets de la commande \includegraphics. L antislash est utilisé pour protéger le caractère suivant : \\ est nécessaire pour obtenir \ : \includegraphics[0.7\maxwidth]{ prompt(=false par défaut) : n affiche pas de chevron avant les commandes R, pour simplifier leur copie depuis le document final comment (=## par défaut) : affiche un double dièse devant les résultats du code, pour les différencier et permettre leur copie en tant que commentaires. highlight (=TRUE par défaut) : afficher le code en couleur pour simplifier sa lecture. background (='#F7F7F7' par défaut) :couleur de fond des chunks. L aspect des zones de code est donc très différent de celui de Sweave par défaut. Ces options peuvent être fournies à chaque chunk. Options des chunks Les options de base des chunks sont les mêmes que pour Sweave : echo (=TRUE par défaut) : affichage du code dans le document eval (=TRUE par défaut) : exécution du code (et donc affichage des résultats dans le document). include (=TRUE par défaut) : affichage du résultat du code. 7 Documentation complète : 17

18

19 PACKAGE R Un package R est un ensemble de code et de données, complété par une documentation, qui permet de rassembler un ensemble de fonctions dans un tout cohérent, qui peut être diffusé. La structure d un package obéit à des règles strictes présentées ici. Création d un package La façon la plus rapide pour créer un package consiste à rassembler le code déjà écrit dans un ou plusieurs fichiers.r et d utiliser le menu File / New Project, puis New Directory/R Package. Compléter ensuite le formulaire de création : Le type de package est Package w/rcpp s il doit contenir du code C. Ce choix est définitif : si du code C doit être ajouté à un package existant, le plus simple sera d en créer un nouveau et d y transférer tous les fichiers de l ancien. Le nom du package doit être court, sans espaces ni caractères spéciaux. Tous les fichiers de code sont ajoutés avec la commande Add. Un nouveau dossier est créé dans le répertoire sélectionné. C est un projet R (il contient un fichier.rproj) et il contient la structure de base d un package. Structure d un package La liste des dossiers et fichiers nécessaires est détaillée ici. Les dossiers ou fichiers supplémentaires placés dans le répertoire de projet causeront des avertissements au moment de la vérification du package. Pour éviter que certains dossiers créés par RStudio par exemple ne soient pris en compte, il est possible de créer un fichier.rbuildignore à la racine du projet. Chaque 19

20 Utilisation avancée de R avec RStudio ligne est une expression régulière qui décrit les fichiers à ignorer. Le modèle suivant permet d éliminer les fichiers de projet de RStudio, quelques résultats de la compilation des vignettes et le dossier de travail de Mercurial. Il peut être utilisé dans la majorité des situations, quitte à le compléter. ^.*\.Rproj$ ^\.Rproj\.user$ ^\_sgbak$ ^\.hg$ \.synctex\.gz$ \.tex$ \.log$ \.blg$ Les fichiers de travail utilisés pour le développement du package doivent être placés dans le répertoire.#extra qui est toujours ignoré, plutôt que d ajouter des lignes à.rbuildignore. Fichier DESCRIPTION Le fichier contient la description du package sous une forme normalisée : Package: MonPackage Type: Package Title: What the package does (short line) Version: 1.0 Date: Author: Who wrote it Maintainer: Who to complain to <yourfault@somewhere.net> Description: More about what it does (maybe more than one line) License: What license is it under? Les package nécessaires au fonctionnement du package actuel doivent être déclarés sous la forme d une commande Imports ou Depends. La différence entre les deux commandes est que l ordre de recherche des fonctions des packages importés sera différent 8. Imports : package implique que le package sera chargé en même temps que le package actuel (comme si la commande library(package) était exécutée). Import n importe que l espace de noms sans charger le package : tout appel à une commande de package échouera si package n est pas appelé explicitement avant de l utiliser. Import présente en revanche l avantage de ne pas risquer que des commandes du package actuel soient masquées par des commandes du même nom d un autre package chargé plus tard. Utiliser Import de préférence : Imports : package Fichier NAMESPACE Le fichier précise comment l espace de nom du package est exporté vers R. Si toutes les fonctions du package doivent être accessibles (cas général), la commande suivante est utilisée exportpattern("^[[:alpha:]]+")

21 Package R Les espaces de nom des packages dont le package actuel dépend doivent être importés pour permettre à un éventuel package dépendant de trouver toutes les fonctions du package actuel mais aussi de ceux dont il dépend : import(package) Fichier NEWS Ce fichier optionnel contient les informations concernant les mises à jour du package. Il apparaît dans l index de l aide du package. Son format est libre, par exemple : CHANGES IN package VERSION 1.1 ============================== OVERVIEW o First version. Répertoire Man : description du package Un fichier portant le nom du package suffixé par package est créé dans le dossier man. Il contient des données identiques à celles de DESCRIPTION et d autres informations formatées pour l aide du package. name, alias, doctype Créés automatiquement. \name{monpackage-package \alias{monpackage-package \alias{monpackage \doctype{package title Description du package en une ligne courte, sans formatage. \title{ What the package does (short line) ~~ package title ~~ description Description du contenu du package. Le formatage est possible en utilisant la syntaxe de LaTeX. \description{ More about what it does (maybe more than one line) ~~ A concise (1-5 lines) description of the package ~~ details Description standardisée du package, sous la forme d un tableau (compléter la version, la date et la licence choisie), complétée par des informations complétant celles de description. \details{ 21

22 Utilisation avancée de R avec RStudio \tabular{ll{ Package: \tab MonPackage\cr Type: \tab Package\cr Version: \tab 1.0\cr Date: \tab \cr License: \tab What license is it under?\cr ~~ An overview of how to use the package, including the most important functions ~~ author Auteurs du package. \author{ Who wrote it Maintainer: Who to complain to <yourfault@somewhere.net> ~~ The author and/or maintainer of the package ~~ references Références bibliographiques, saisies et formatées manuellement. \references{ ~~ Literature or other references for background information ~~ keyword Mots-clés. Utiliser la commande RShowDoc("KEYWORDS") pour obtenir la liste des mot-clés recommandée. Conserver le mot-clé package par défaut. ~~ Optionally other standard keywords, one per line, from file KEYWORDS in the R documentation ~~ ~~ directory ~~ \keyword{ package seealso Renvois vers d autres fichiers d aide, par exemple d autres packages. La commande \link{ permet de créer un lien hypertexte vers tout objet R. \seealso{ ~~ Optional links to other man pages, e.g. ~~ ~~ \code{\link[<pkg>:<pkg>-package]{<pkg> ~~ examples Exemples. Le code doit être exécutable sans erreur, et en quelques secondes pour passer les tests de validation de CRAN. \examples{ ~~ simple examples of the most important functions ~~ 22

23 Package R Répertoire R : code des fonctions Le répertoire contient des fichiers R qui contiennent le code des fonctions. Le plus simple est de créer un fichier par fonction, dont le nom est celui de la fonction, mais n importe quelle organisation est possible : tous les fichiers R sont pris en compte, quel que soit leur nom et leur contenu. Code des fonctions C RStudio ajoute un répertoire src pour le code C. Il contient par défaut trois fichiers : Makevars, Makevars.win (sous Windows) et RcppExports.cpp. Ces fichiers sont maintenaus automatiquement par RStudio. Le code utilisateur doit être ajouté dans d autres fichiers avec l extension.cpp. Plusieurs fonctions peuvent être placées dans le même fichier. L entête du fichier ne doit pas être modifiée, et le code ajouté en-dessous : #include <Rcpp.h> using namespace Rcpp; // [[Rcpp::export]] void MonCode(SEXP Rx) { NumericVector x(rx); x = 2*x; La fonction MonCode ci-dessus ajoute 1 au vecteur numérique Rx (directement modifié par le code C). Une fonction R du même nom acceptant les mêmes arguments est exportée (automatiquement). Elle doit être documentée dans un fichier.rd : une entrée d alias doit exister dans un fichier de documentation. Si le code C n est utilisé que pour des calculs intermédiaires, toutes les fonctions écrites en C peuvent être documentées dans le même fichier.rd incluant le mot-clé internal. Le débogage des fonctions C n est pas facile. Le principal outil permettant de suivre le déroulement du code est la fonction Rf_PrintValue qui permet d écrire dans la console de R à partir de C : void TestPrint(SEXP Rx) { NumericVector x(rx); Rf_PrintValue(x); Rf_PrintValue(wrap(x[0])); printf("%f", x[0]); En exécutant TestPrint(1:5) dans R, on obtient : [1] [1] Les couleurs du code et de la sortie correspondent : Rf_PrintValue() permet d afficher dans la console R un objet R. Si l objet n est pas un objet R mais un réel par exemple, on peut utiliser wrap() pour en faire un objet R. 23

24 Utilisation avancée de R avec RStudio On peut aussi utiliser printf() plutôt que Rf_PrintValue(wrap()), mais le résultat est formaté. Répertoire man : aide des fonctions Le dossier contient les fichiers de documentation.rd. Leur syntaxe est la suivante : name Nom du fichier de documentation qui sera affiché comme titre : celui de la fonction en général, ou un nom résumant l ensemble du contenu du fichier de documentation. \name{mafonction alias Une entrée d alias est nécessaire pour toutes les fonctions trouvées dans le répertoire R. Un fichier.rd peut en documenter plusieurs : ajouter autant d alias que nécessaire. \alias{mafonction %- Also NEED an '\alias' for EACH other topic documented here. title Le titre du fichier de documentation, sans formatage. \title{ %% ~~function to do... ~~ description Description de ce que font les fonctions documentées. Le formatage est possible. \description{ %% ~~ A concise (1-5 lines) description of what the function does. ~~ usage La syntaxe de chaque fonction doit être rappelée, exactement comme elle apparaît dans le fichier.r. \usage{ MaFonction(x) Les méthodes génériques nécessitent une syntaxe particulière, par exemple pour la méthode print.maclasse : \method{summary{maclasse(object, \dots) arguments Chaque argument apparaissant dans une des fonctions de la section usage doit être décrit. \arguments{ 24

25 Package R \item{x{ %% ~~Describe \code{x here~~ details Cette section permet de décrire plus en détail l intérêt des fonctions, ou bien de donner des précisions techniques, des références... \details{ %% ~~ If necessary, more details than the description above ~~ value Description des résultats des fonctions, notamment leur structure si ce ne sont pas seulement des nombres. \value{ %% ~Describe the value returned %% If it is a LIST, use %% \item{comp1 {Description of 'comp1' %% \item{comp2 {Description of 'comp2' %%... references Références bibliographiques, saisies et formatées manuellement. \references{ %% ~put references to the literature/web site here ~ author Auteur du code. \author{ %% ~~who you are~~ note Remarques, au-delà de ce qui est présenté dans la section details. \note{ %% ~~further notes~~ seealso Renvois vers les autres fonctions relatives à celles qui sont décrites. La commande \link{ permet de créer un lien hypertexte vers tout objet R. \seealso{ %% ~~objects to See Also as \code{\link{help, ~~~ 25

26 Utilisation avancée de R avec RStudio examples Exemples. Le code doit être exécutable sans erreur, et en quelques secondes pour passer les tests de validation de CRAN. \examples{ ##---- Should be DIRECTLY executable!! ---- ##-- ==> Define data, use random, ##-- or do help(data=index) for the standard data sets. ## The function is currently defined as function (x) { keyword Mots-clés. Le mot-clé internal permet de cacher les fonctions dans l index de l aide. % Add one or more standard keywords, see file 'KEYWORDS' in the % R documentation directory. \keyword{ ~kwd1 \keyword{ ~kwd2 % ONLY ONE keyword per line Répertoire data : données Le répertoire data contient les données fournies avec le package, sous la forme d un ou plusieurs fichiers.rdata. Pour créer un fichier.rdata, ouvrir une session R, créer toutes les variables nécessaires. Vérifier le contenu de l environnement de R, c'est-à-dire la liste des variables en mémoire, dans la fenêtre Environnement de RStudio. Supprimer les variables excédentaires avec la fonction rm(nomvariable) puis sauvegarder l environnement. Pour utiliser les données dans le package, c'est-à-dire les recharger dans l environnement de R, le fichier de données sera chargé par la commande data(nomfichier), sans l extension.rdata. Répertoire man : description des données Une entrée d alias dans un fichier d aide est nécessaire pour chaque variable (indépendamment des fichiers.rdata). name Nom du fichier de documentation qui sera affiché comme titre. Peut contenir le nom de la variable ou un nom plus explicite si plusieurs variables sont regroupées dans un seul fichier d aide. \name{nom alias Une entrée d alias est nécessaire pour toutes les variables trouvées dans le répertoire R. Un fichier.rd peut en documenter plusieurs : ajouter autant d alias que nécessaire. 26

27 Package R \alias{nomvariable usage Contient la commande de chargement du fichier.rdata qui contient les variables. \usage{ data(nomfichier) doctype doctype doit contenir le type data. \doctype{data source Description de l origine des données, en texte libre. À compléter par les références bibliographiques dans la section reference. \source{ %% ~~ reference to a publication or URL from which the data were obtained ~~ title, description, details, reference, examples, keyword Identiques aux fichiers d aides de fonctions. Fichier inst/citation Informations pour citer le package, utilisées par la fonction citation("nompackage"). Ce fichier est optionnel mais recommandé : en son absence, R va chercher les informations dans DESCRIPTION. Exemple tiré du package entropart : citheader("to cite entropart in publications use this reference:") citentry ( entry="article", title = "entropart, an R package to partition diversity", author = personlist(as.person("e. Marcon"), as.person("b. Herault")), journal = "Methods in Ecology and Evolution", year = "submitted", volume = "0", number = "0", pages = "1-2", textversion = paste("marcon, E. and Herault, B.", "(sumitted): ", "entropart, an R package to partition diversity.", "Methods in Ecology and Evolution.", "0(0): 1-2", sep="") ) citheader contient un texte libre, citentry est structuré en éléments correspondant à peu près à une syntaxe bibliographique BibTeX (pour produire une référence directement copiable), 27

28 Utilisation avancée de R avec RStudio mais les valeurs respectent la syntaxe de R. Les auteurs doivent être déclarés sous forme de chaînes de caractères converties par la fonction as.person et compilées par personlist. Une version texte est ajoutée dans textversion. Vignettes Les fichiers.rnw des vignettes doivent être placés dans le répertoire vignettes, avec tous les fichiers nécessaires (données non incluses dans le package, images non générées par les chunks par exemple). Pour être reconnu comme une vignette et donc apparaître dans la table des matières de l aide du package, le fichier.rnw doit contenir la commande suivante, généralement en début de fichier : % \VignetteIndexEntry{User manual Le texte entre les accolades sera le descritptif du contenu de la vignette. Le choix du moteur de création des vignettes est fait dans les options du projet. Pour un fichier donné, il peut être modifié en utilisant la commande : % \VignetteEngine{knitr::knitr ou % \VignetteEngine{utils::Sweave Pour qu une vignette knitr soit intégrée correctement dans le package, le fichier DESCRIPTION du package doit contenir les deux lignes suivantes : VignetteBuilder: knitr Suggests: knitr Et la déclaration du moteur de vignette doit être explicite dans les fichiers.rnw. Après compilation du package, les vignettes sont accessibles depuis l aide du package. À partir de l index : La page des vignettes s affiche. Le fichier pdf peut être chargé, comme les chunks : 28

29 Package R Répertoire.#Extra Ce répertoire est ignoré au moment de la compilation du package : il peut donc être utilisé pour tester du code, stocker des données avant leur inclusion dans le package : c est un répertoire de travail. Compilation Dès qu un minimum de contenu est disponible, il est utile de compiler le package pour vérifier qu il ne contient pas d erreurs. L organisation présentée ici suppose que l utilisateur a le droit d écriture dans le dossier library de R. Les outils de R (Rtools) doivent être installés. Utiliser le bouton Build & Reload dans la fenêtre Build de Rstudio pour lancer la compilation. Le package est compilé, réinstallé dans la librairie de R (comme s il était chargé depuis CRAN) et R est redémarré. Attention : la commande échoue si le package n est pas déjà installé et que le fichier.rprofile contient la commande libray(package). Dans ce cas, renommer temporairement.rprofile pour le désactiver le temps de la première compilation. Build & Reload permet d utiliser en permanence la version à jour du package en cours de développement. Quand le package est prêt, utiliser la commande Check pour lancer une vérification complète du code, des exemples, et de la conformité aux standards. Corriger les erreurs, avertissements et notes jusqu à ce que la vérification n en renvoie plus aucun, sinon le package sera rejeté par CRAN. Enfin, créer les fichiers d installation : More / Build Source Package : crée le fichier source au format.tar.gz. Le fichier pourra être publié sur CRAN ou installé avec la commande Tools / Install Packages (Install from Package Archive File) de RStudio. More / Build Binary Package : crée un fichier zip pour les utilisateurs de Windows qui ne disposent pas des outils de R installer un fichier source (ceux qui n utilisent pas RStudio ont un menu pour installer un package à partir d un fichier zip dans l interface graphique standard de R). 29