Utilisation avancée de R avec RStudio

UTILISATION AVANCÉE
DE R AVEC R STUDIO
Eric Marcon
21/09/2014
1
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.
UTILISATION AVANCÉE DE R AVEC
RSTUDIO
Package R...............................................19
Sommaire
Création d’un package ......................... 19
Structure d’un package ........................ 19
Objectifs .................................................... 5
Fichier DES CRIP TION
20
Projet R ..................................................... 7
Fichier NAMESPA CE
20
Fichier NEWS
21
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 .......................... 10
Portfolio
10
Rapport Markdown
12
Rapport Sweave
13
Rapports knitr
16
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/CITA TION
27
Vignettes
28
Répertoire .#Extra
29
Compilation ........................................... 29
Publication ............................................ 30
Conclusion ..............................................31
3
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
PROJET R
Logiciels nécessaires
R
R1 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.
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 R2 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 à 0.98.
1
2
http://cran.r-project.org/
http://cran.rstudio.com/bin/windows/Rtools/
7
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.
3
4
https://www.rstudio.com/
http://miktex.org/
8
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
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
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
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
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.
5
http://en.wikipedia.org/wiki/Reproducibility#Reproducible_research
13
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 LaTeX6 , les chunks sont insérés dans le code avec la syntaxe suivante :
<<>>=
2+2
@
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:
<<>>=
2+2
@
\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>>=
2+2
@
●
●
6
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.
Documentation complète : http://fr.wikibooks.org/wiki/Latex
14
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
<<Addition>>
@
est équivalent à :
<<Inclusion>>=
1
2+2
@
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
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 = FALSE)
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
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, out.width='0.7\\maxwidth')
@
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 :



7
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.
Documentation complète : http://yihui.name/knitr/options
17
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
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: 2013-03-08
Author: Who wrote it
Maintainer: Who to complain to <[email protected]>
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:]]+")
8
http://obeautifulcode.com/R/How-R-Searches-And-Finds-Stuff/
20
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
Utilisation avancée de R avec RStudio
\tabular{ll}{
Package: \tab MonPackage\cr
Type: \tab Package\cr
Version: \tab 1.0\cr
Date: \tab 2013-03-08\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 <[email protected]>
~~ 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
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 2 3 4 5
[1] 1
1.000000
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
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
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
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
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
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
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
Utilisation avancée de R avec RStudio
Publication
Un package terminé peut être publié sur CRAN par une interface web simple à utiliser 9 . La
phase de validation dure quelques jours : toutes les corrections demandées doivent être apportées
et le package corrigé soumis à nouveau par la même voie.
9
http://xmpalantir.wu.ac.at/cransubmit/
30
CONCLUSION
L’utilisation de RStudio et knitr en complément de R permet de travailler plus rapidement et de
poduire du code mieux documenté. La création de packages est extrêment simplifiée par une
interface graphique simple.
31

Download Report