Comment rédiger un rapport avec la commande Sweave() de R

La fonction Sweave() est une commande standard de R qui permet d'automatiser la production de documents en intégrant directement le code source R dans le document, la cohérence globale est alors automatiquement assurée. Comme Sweave() est une commande standard, il n'y a rien de particulier à installer si vous avez déjà R d'installé. Cependant, ceux qui travaillent sous Windows doivent être avertis de la note importante suivante :

En effet, Sweave() va générer un fichier intermédiaire LATEX qui comportera juste avant \begin{document} une directive du type(4) :

\usepackage{/Library/Frameworks/R.framework/Resources/share/texmf/Sweave}
\begin{document}

Pour utiliser le fichier Sweave.sty qui est distribué avec R. Si R a été installé dans le dossier Program Files, cela posera un problème à LaTeX pour retrouver ce fichier parce qu'il y aura une espace dans le chemin d'accès. D'une façon générale, il est beaucoup plus simple de travailler sous des systèmes d'exploitations de type unix que sous Windows dès que l'on veut utiliser R de façon professionnelle. Ce n'est pas que cela soit impossible, le présent document est compilable sous Windows, mais il y a des analyses coût bénéfice à prendre en compte. Ces dernières sont assez bien résumées de façon humoristique dans le folklore de R :

library(fortunes)
fortune("Knoppix")
Benjamin LloydHughes: Has anyone had any joy getting the rgdal package to compile
under windows?
Roger Bivand: The closest anyone has got so far is Hisaji Ono, who used MSYS
(http://www.mingw.org/) to build PROJ.4 and GDAL (GDAL depends on PROJ.4, PROJ.4
needs a PATH to metadata files for projection and transformation), and then
handpasted the paths to the GDAL headers and library into src/Makevars, running
Rcmd INSTALL rgdal at the Windows command prompt as usual. All of this can be
repeated, but is not portable, and does not suit the very valuable standard binary
package build system for Windows. Roughly: [points 1 to 5 etc omitted]
Barry Rowlingson: At some point the complexity of installing things like this for
Windows will cross the complexity of installing Linux... (PS excepting liveLinux
installs like Knoppix)
 Benjamin LloydHughes, Roger Bivand, and Barry Rowlingson
Rhelp (August 2004)

Dans la suite de ce document, nous supposerons que vous travaillez sous un système de type unix. Il en existe des distributions libres.

Vous n'avez pas besoin de connaître LaTeX pour utiliser Sweave(), mais vous avez besoin d'avoir les outils nécessaires pour transformer un fichier source LaTeX en un document PDF, par exemple pdfLaTeX, qui est fourni avec la plupart des distributions LATEX. Vérifiez que vous êtes capable de compiler le petit fichier (mini.tex) source LaTeX suivant :

\documentclass[a4paper]{article}
\usepackage[latin1]{inputenc}
\begin{document}
\begin{Huge}Bonjour, ô mon$\delta$e !\end{Huge}
\end{document}

Pour ce faire suivez les étapes suivantes :

1. Allez sur le site http://pbil.univlyon1.fr/R/donnees/ pour enregistrer une copie du fichier mini.tex dans votre dossier de travail. Si vous n'avez pas de dossier de travail, créez en un.
2. Ouvrez le fichier mini.tex présent dans votre dossier de travail avec votre éditeur de texte favori. Le codage des caractères est en latin1 (ISO88591), il peut être nécessaire de l'indiquer au moment de l'ouverture du fichier.
3. Vérifiez que dans votre éditeur de texte que le caractère 'ô' est bien présent dans la quatrième ligne : \begin{Huge}Bonjour, ô mon$\delta$e !\end{Huge}. Si ce n'est pas le cas, c'est sans doute que votre éditeur de texte n'a pas ouvert le fichier en latin1. Essayez encore.
4. Lancez la compilation en entrant la commande pdflatex mini.tex dans un terminal(5).

Vous devez obtenir un document PDF d'une page au format A4, numérotée 1 en bas, et sur le haut de laquelle est écrit en gros caractères :

Ce petit test vous permet de vérifier deux choses :

1. Vous êtes capable de compiler un fichier source LaTeX qui contient des caractères accentués, comme ici le ô.
2. Le caractère grec delta minuscule, δ, est plaisant à lire. En effet, par rapport à la version initiale de 1986, le rendu du caractère δ a été fortement amélioré en 1992. Si le rendu du caractère n'est pas bon (cf ci-dessous), c'est sans doute que votre version de LATEX est légèrement obsolète et qu'il faut absolument faire une mise à jour.

R contient en standard un fichier d'exemple pour Sweave() qui s'appelle Sweavetest1.Rnw. Lancez les exemples de Sweave() avec :

example(Sweave)
Sweave testfile < system.file("Sweave", "Sweavetest1.Rnw", package = "utils")
Sweave ## enforce par(ask = FALSE)
Sweave options(device.ask.default = FALSE)
Sweave ## create a LaTeX file
Sweave Sweave(testfile)
Writing to file Sweavetest1.tex
Processing code chunks with options ...
1 : keep.source print term verbatim (Sweavetest1.Rnw:15)
2 : keep.source term hide (Sweavetest1.Rnw:17)
3 : echo keep.source print term verbatim (Sweavetest1.Rnw:22)
4 : keep.source term verbatim (Sweavetest1.Rnw:30)
5 : echo keep.source term verbatim (Sweavetest1.Rnw:45)
6 : echo keep.source term verbatim pdf (Sweavetest1.Rnw:53)
7 : echo keep.source term verbatim pdf (Sweavetest1.Rnw:63)
You can now run (pdf)latex on
Sweave ## This can be compiled to PDF by
Sweave ## tools::texi2pdf("Sweavetest1.tex")
Sweave ## or outside R by
Sweave ## R CMD texi2pdf Sweavetest1.tex
Sweave ## which sets the appropriate TEXINPUTS path.
Sweave ## create an R source file from the code chunks
Sweave Stangle(testfile)
Writing to file Sweavetest1.R
Sweave ## which can be sourced, e.g.
Sweave source("Sweavetest1.R")
[1] 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
[1] 0.21735587 1.04925502 0.36035725 0.17593593 0.06757618 0.83353936
[7] 0.76524186 0.53411880 0.11991532 1.82927549 0.52521495 1.03955692
[13] 0.36515148 0.84124559 0.61239564 1.78831195 1.24186009 0.19388929
[19] 1.51002392 1.44636428
One Sample ttest
data: x
t = 1.4362, df = 19, pvalue = 0.1672
alternative hypothesis: true mean is not equal to 0
95 percent confidence interval:
0.1356280 0.7287722
sample estimates:
mean of x
0.2965721
Sweave ## Don't show:
Sweave if(!interactive()) unlink("Sweavetest1*")
Sweave ## End Don't show
Sweave
Sweave
Sweave

Si tout s'est bien passé, vous devez avoir maintenant dans votre dossier courant un fichier Sweavetest1.tex, ainsi qu'un certain nombre de fichiers graphiques au format pdf et un fichier de commandes R. Utilisez pdfLaTeX pour compiler le fichier Sweavetest1.tex, vous devez obtenir un fichier au format pdf de trois pages ressemblant à ceci :

Si vous êtes arrivé à produire ce fichier, c'est que vous avez tous les outils nécessaires pour utiliser Sweave() pour produire un rapport.

Enregistrez une copie du fichier mini2.rnw dans votre dossier de travail, disponible au même endroit à http://pbil.univlyon1.fr/R/donnees/.

\documentclass[a4paper]{article}
\usepackage[latin1]{inputenc}
\begin{document}
Essayons de calculer 2 + 2 :
<<essai2plus2>>=
2 + 2
@
\end{document}

L'extension rnw désigne par convention un fichier destiné à être traité par la commande Sweave() de R. Lancez la commande Sweave() en lui donnant comme argument le nom de ce fichier :

Sweave("mini2.rnw")
Writing to file mini2.tex
Processing code chunks with options ...
1 : echo keep.source term verbatim (label = essai2plus2, mini2.rnw:5)
You can now run (pdf)latex on

Vous pouvez alors compiler le fichier intermédiaire mini2.tex qui a été généré par Sweave() pour générer un document PDF contenant le texte suivant :

Le fragments de code R à intégrer dans le document final (ici 2 + 2) doit être encadré au minimum par <<>>= au début et @ à la fin, et il ne doit pas il y avoir de caractères en début de ligne. Le résultat (ici [1] 4) sera automatiquement intégré dans le document final. Ici, nous avons en plus donné un nom au fragment de code R en utilisant <<essai2plus2>>= pour pouvoir le repérer facilement lors de la phase de compilation avec Sweave().

Pour y voir plus clair, on décide de supprimer le caractère d'invite de commande de la console R(>) et de colorier les entrées et sorties de façon différente.

Récupérez le fichier « mini3.rnw » :

\documentclass[a4paper]{article}
\usepackage[latin1]{inputenc}
\usepackage{color}
\usepackage{pdfcolmk}
\begin{document}
\DefineVerbatimEnvironment{Sinput}{Verbatim}{formatcom = {\color[rgb]{0, 0, 0.56}}}
\DefineVerbatimEnvironment{Soutput}{Verbatim}{formatcom = {\color[rgb]{0.56, 0, 0}}}
<<options, echo = FALSE>>=
options(prompt = " ", continue = " ", width = 85)
@
Essayons de calculer 2 + 2 en couleur :
<<essai2plus2>>=
Logiciel R version 3.1.0 (20140410) { tdr78.rnw { Page 8/16 { Compilé le 20140602
Maintenance : S. Penel, URL : http://pbil.univlyon1.fr/R/pdf/tdr78.pdf
J.R. Lobry
2 + 2
@
\end{document}

Lancez Sweave() sur ce fichier :

Sweave("mini3.rnw")
Writing to file mini3.tex
Processing code chunks with options ...
1 : keep.source term verbatim (label = options, mini3.rnw:11)
2 : echo keep.source term verbatim (label = essai2plus2, mini3.rnw:16)
You can now run (pdf)latex on

Notez qu'il y a maintenant deux fragments de code :

1. Le premier qui s'appelle options et qui sert en autres à supprimer le caractère d'invite de commande.
2. Le deuxième qui s'appelle essai2plus2 et qui calcule 2 + 2 comme précédemment.

Compilez le fichier « mini3.tex », vous devez obtenir le résultat suivant :

Notez que le premier fragment de code (options) n'apparaît pas dans le document final, c'est parce que nous l'avons commencé avec <<options, echo = FALSE>>=, et que echo = FALSE signifie que l'on ne veut pas que le code apparaisse dans le document final.

Les autres modifications que nous avons apportées s'adressent à LATEX, nous avons demandé à utiliser les bibliothèques color et pdfcolmk pour pouvoir avoir des couleurs dans le document final. Nous avons aussi redéfini les styles Sinput et Soutput pour formater les entrées et sorties de code.

Il est possible avec la commande \Sexpr{} d'insérer dans du texte la valeur d'une variable. Par exemple, le fichier source « mini4.rnw » :

\documentclass[a4paper]{article}
\usepackage[latin1]{inputenc}
\usepackage{color}
\usepackage{pdfcolmk}
\begin{document}
\DefineVerbatimEnvironment{Sinput}{Verbatim}{formatcom = {\color[rgb]{0, 0, 0.56}}}
\DefineVerbatimEnvironment{Soutput}{Verbatim}{formatcom = {\color[rgb]{0.56, 0, 0}}}
<<options, echo = FALSE>>=
options(prompt = " ", continue = " ", width = 85)
@
Le volume $V$ d'une sphère de rayon $r$ est donné par :
$$
V(r) = \frac{4}{3}\pi r^3
$$
<<volsphere>>=
V < function(r) 4/3*pi*r^3
V(1)
@
Le volume d'une sphère de rayon unité est donc de \Sexpr{V(1)}.
\end{document}

donne le résultat suivant :

Sweave("mini4.rnw")
Writing to file mini4.tex
Processing code chunks with options ...
1 : keep.source term verbatim (label = options, mini4.rnw:11)
2 : echo keep.source term verbatim (label = volsphere, mini4.rnw:19)
You can now run (pdf)latex on

Si tout s'est bien passé, tout ne devrait pas s'être bien passé, vous devriez normalement souffrir ici du syndrome de l'encodage la mort qui tue. Corrigez le problème si besoin est (cf figure 1).

Vous pouvez utiliser la fonction round() pour arrondir les résultats, par exemple \Sexpr{round(V(1), 2)} donnerait 4.19 dans le document final. Ceci permet donc d'insérer une, et une seule, valeur obtenue par le calcul dans directement dans le document final. Mais il est également possible d'insérer dans le document final des tableaux, donc un grand nombre de valeurs, grâce au package xtable. Nous ne donnerons qu'un exemple simple. Le fichier source suivant :

\documentclass[a4paper]{article}
\usepackage[latin1]{inputenc}
\begin{document}
<<options, echo = FALSE>>=
library(xtable) # pour pouvoir produire des tables LaTeX dans R
data(crimtab) # pour charger le jeu de données (voir ?crimtab)
colnames(crimtab) < as.numeric(colnames(crimtab))/2.54 # taille en pouces
rownames(crimtab) < as.numeric(rownames(crimtab))*10 # majeur en mmm
crimtab[which(crimtab == 0, arr.ind = TRUE)] < NA # pour virer les 0
crimtab < crimtab[nrow(crimtab):1, ] # pour inverser l'ordre des lignes
matable < xtable(x = crimtab, label = "Student",
caption = "Les données utilisées par William Sealy Gosset,
plus connu sous le nom de plume de 'Student' et du test statistique éponyme,
en 1908 (\\textit{Biometrika} \\textbf{6}, 125). La collecte des
données a été faite par MacDonell en 1902 (\\textit{Biometrika}
\\textbf{1}, 177227). Il s'agit d'une table de contingence obtenue
en discrétisant la taille (exprimée ici en pouces, soit 2.54 cm, et
portée en colonne) et la longueur du majeur de la main gauche
(exprimée ici en mm et portée en ligne) de 3000 criminels adultes
de sexe m^ale écroués au pays de Galle et en Angleterre à la fin
du XIX$\\mathrm{ê}$ siècle. Voir \\texttt{?crimtab} pour plus
d'informations.")
# Notez les doubles \\ nécessaires dans R, c'est la "double escape rule"
print(matable, file = "Student.tex", size = "tiny", NA.string = ".")
# On veut des '.' au lieu des des NA
@
\input{Student.tex}
Les fameuses données utilisées par Student sont présentées dans la table \ref{Student}.
\end{document}

permet d'obtenir ceci :

Sweave("mini5.rnw")
Writing to file mini5.tex
Processing code chunks with options ...
1 : keep.source term verbatim (label = options, mini5.rnw:5)
You can now run (pdf)latex on

Il se peut que dans votre document final vous ayez table ?? au lieu de table 1. C'est normal, nous avons fait référence à la table dans le texte avec \ref{Student} pour ne pas avoir à nous préoccuper de la numérotation des tables, c'est le travail de LaTeX, pas le nôtre. Mais pour pouvoir faire son travail correctement, LaTeX a besoin de compiler le document une première fois pour générer les tables, puis une deuxième fois pour résoudre les références. Il nous suffit donc d'invoquer LaTeX une deuxième fois et les références seront résolues.

Sweave() permet d'inclure automatiquement des graphiques dans le document final (yes !). Commencez par créer dans votre dossier de travail courant un dossier nommé figs pour rassembler toutes les figures au même endroit et éviter d'encombrer votre répertoire avec trop de fichiers(6).

Le fichier source suivant :

\documentclass[a4paper]{article}
\usepackage[latin1]{inputenc}
\usepackage{color, pdfcolmk}
\begin{document}
\DefineVerbatimEnvironment{Sinput}{Verbatim}{formatcom = {\color[rgb]{0, 0, 0.56}}}
\SweaveOpts{prefix.string = figs/essai, eps = FALSE, pdf = TRUE}
\setkeys{Gin}{width=0.8\textwidth}
Essayons de faire un histogramme :
<<essaifig, echo = T, fig = T>>=
hist(rnorm(1000), col = "pink")
@
\end{document}

devrait vous permettre d'obtenir ceci :

Sweave("mini6.rnw")
Writing to file mini6.tex
Processing code chunks with options ...
1 : echo keep.source term verbatim pdf (label = essaifig, mini6.rnw:9)
You can now run (pdf)latex on

Essayons de faire un histogramme :

hist(rnorm(1000), col = "pink")

Quelques commentaires sur les instructions utilisées ici. La ligne \SweaveOpts{prefix.string = figs/essai, eps = FALSE, pdf = TRUE} sert à dire que nous voulons ranger les fichiers contenant les figures dans le dossier figs et que leur nom commence par essai, vous devez normalement avoir dans ce dossier un fichier s'appelant « essaiessaifig.pdf » :

list.files(path = "figs", pattern = "essaifig")
[1] "essaiessaifig.pdf"

le nom du fichier a été complété en ajoutant le nom du fragment de code (essaifig), puis l'extension .pdf pour signifier qu'il s'agit d'un fichier au format PDF. Notez que nous avons demandé à Sweave() de ne générer que des fichiers PDF avec l'option eps = FALSE, pdf = TRUE, parce que nous utilisons ici pdfLATEX et que nous n'avons pas l'utilité des fichiers au format EPS.

Le fragment de code commence ici avec la ligne

<<essaifig, echo = T, fig = T>>=

qui signifie que le fragment de code produit une figure (fig = T).

Enfin, la ligne

\setkeys{Gin}{width=0.8\textwidth}

sert à contrôler la taille du graphique dans le document final. On signifie à LaTeX que l'on veut que le graphique occupe en largeur 80 % de la largeur d'une ligne courante.

Voici une façon de procéder pour contrôler de façon fine et reproductible la dimension de vos graphiques. Commencez par mettre au point dans le mode interactif sous R votre graphique. Le plus simple pour cela est de créer un fichier source de code R appelé par exemple mafigure.R que vous exécutez avec source("mafigure.R"). Par exemple avec le fichier suivant :

mafigure.R
par(mfrow = c(1,2))
x < rnorm(1000)
hist(x, col = "lightblue", main = "Histogramme")
boxplot(x, col = "lightblue", horizontal = TRUE, main = "Boîte à moustaches")

vous devez obtenir le résultat suivant :

source("mafigure.R")

Les dimensions générales du graphique ne sont pas très adaptées, on préférerait avoir quelque chose de moins haut et de plus large. Quelque chose dans ce goût :

Toujours dans le mode interactif sous R, modifiez à la souris les dimensions de la fenêtre graphique, peaufinez le code source dans le fichier mafigure.R, jusqu'à ce que vous soyez satisfait du résultat. Utilisez alors la commande par("din") pour connaître les dimensions de la fenêtre graphique.

par("din")
[1] 7 7

La première valeur correspond à la largeur, la deuxième à la hauteur. Supposons que vous soyez satisfaits avec une largeur de 8 et une hauteur de 4. Le code source suivant :

\documentclass[a4paper]{article}
\usepackage[latin1]{inputenc}
\begin{document}
\SweaveOpts{prefix.string = figs/essai, eps = FALSE, pdf = TRUE}
\setkeys{Gin}{width=\textwidth}
Je veux une figure de 8 unités de large par 4 unités de haut
et qui tienne toute la largeur de la page dans le document final.
<<essaifig, echo = F, fig = T, width = 8, height = 4>>=
par(mfrow = c(1,2))
x < rnorm(1000)
hist(x, col = "lightblue", main = "Histogramme")
boxplot(x, col = "lightblue", horizontal = TRUE, main = "Boîte à moustaches")
@
\end{document}

devrait vous permettre d'obtenir ceci :

Sweave("mini7.rnw")
Writing to file mini7.tex
Processing code chunks with options ...
1 : keep.source term verbatim pdf (label = essaifig, mini7.rnw:9)
You can now run (pdf)latex on