Sweave : introduire du code et des sorties R dans un document LaTeX

Auteur.e.s
Brigitte Schaeffer, Claire Chabanet, Julie Aubert
Résumé

Sweave est un outil qui permet d’introduire du code et des sorties R dans des documents LaTeX.

Définition, références

Sweave a été créé par Friedrich Leisch en 2002. Il est intégré dans les utilitaires de R (package utils) et donc chargé automatiquement au lancement de R.

Utilisation de Sweave

  • Créer un document latex (monFichier.tex) mais changer l’extension .tex du fichier source latex en .rnw
  • Insérer en début de document, l’instruction suicante pour charger le package Sweave :

    \usepackage{Sweave}
  • Dans le document monFichier.rnw, introduire le code R en utilisant les balises <<, >>= et @, de la façon suivante :

<< nomScriptR [, options] >>=
codeR
@

Attention: les balises doivent débuter en colonne 1 (pas de blanc avant).

  • Dans R, lancer la commande
Sweave("monFichier.rnw")

Un fichier monFichier.tex sera créé dans le même répertoire. Ce fichier contiendra le code et les sorties de R.

  • Plusieurs options sont possibles dont les principales sont listées ci-dessous. Elles devront être séparées par une virgule.
Options Valeur Effet
echo TRUE/FALSE indique si le code doit apparaître ou non. Par défaut echo = TRUE
eval TRUE/FALSE indique si le code doit être exécuté ou non. Par défaut eval = TRUE
fig FALSE/TRUE indique si la figure doit être générée ou non. Par défaut fig = FALSE
pdf FALSE/TRUE indique si un pdf de la figure doit être généré ou non. Par défaut pdf = FALSE

Exemple

Un fichier simple au format .rnw

\documentclass[a4paper]{article}
\usepackage{Sweave}
\begin{document}
\title{Exemple d'utilisation de Sweave}
\author{R4CIAM\\ INRA, Applied Mathematics
  and Informatics Unit \\ 78352 Jouy-en-Josas Cedex\\ France}
\date{January 2011}
\maketitle
\section{Exemple avec graphiques}
Voici un exemple simple:
<< exemple, echo=FALSE, fig=TRUE, width=10, height=4 >>=
par(mfrow=c(1,2))
hist(rnorm(100), main="")
hist(rnorm(1000), main="")
@
\end{document}

Comment obtenir des figures en png au lieu de pdf avec Sweave ?

Il suffit de préciser

<< exemple, echo=FALSE, fig=TRUE, pdf=FALSE, png=TRUE, width=10, height=4 >>=
par(mfrow=c(1,2))
hist(rnorm(100), main="")
hist(rnorm(1000), main="")
@

A noter

  • Pour obtenir une sortie couleur des commandes, il faut définir l’environnement verbatim. En ajoutant ces lignes :
\DefineVerbatimEnvironment{Sinput}{Verbatim}{formatcom={\color[rgb]{0.56,0,0}}}
\DefineVerbatimEnvironment{Soutput}{Verbatim}{formatcom={\color[rgb]{0,0,0.56}}} 

le code R apparaitra en rouge et la sortie R en bleu dans le document final.

  • Sweave n’autorise qu’un graphique par commande de figure. Il n’est pas possible de produire plusieurs graphiques dans une boucle. Une solution est proposée à la fin du manuel Sweave: Sweave-manual.

  • Il est aussi possible d’ajouter du code R dans un document html avec le package R2HTML de R.

  • Les versions de Sweave <=2.7.1 ne font pas apparaitre les warnings d’exécution parmi les sorties. Une solution est à l’étude par les auteurs (2010). En attendant, on peut contourner le problème en masquant la fonction warning de R par une fonction qui écrit le message sur l’unité de sortie, par exemple:

warning <- function(mess) {
    print(mess)
}

Cas de la notice associée à un package R

Les notices d’utilisation des packages R — les vignettes dans la terminologie R - ont intérêt à être écrites à l’aide de Sweave, pour que le code et les sorties R soient toujours à jour en cas de modification du package. Dans ce cas:

  • Le fichier rnw doit être placé dans le répertoire vignettes dans la hiérarchie du package. Les commandes R CMD check et R CMD build génèrent les fichiers TeX et pdf.

  • Pour accéder aux fonctions du package en cours de création, mettre une instruction du type suivant, au sein du code R:

library("MONPACKAGE")
  • Pour créer un index de la documentation, insérer une instruction \VignetteIndexEntry dans un commentaire LaTeX. Exemple :
%\VignetteIndexEntry{MONPACKAGE: un package formidable} 

Un fichier index.html sera créé par Sweave. Il contiendra un lien sur chacun des fichiers pdf, suivi par le libellé choisi dans VignetteIndexEntry.

Publier un article généré avec Sweave

J.R. Lobry a noté quelques trucs bien utiles quand on veut soumettre à une revue un article généré avec Sweave. Voir ici

Utilisation avancée

Quelques petits “trucs” utiles:

  • Créer le fichier pdf au sein de la session R: Utiliser la commande tools::texi2dvi. Exemple:
tools::texi2dvi("monFichier.tex", pdf = TRUE)
  • Positionner les options pour l’ensemble du document: Mettre dans le préambule une instruction LaTeX \SweaveOpts. Exemple :
\SweaveOpts{prefix.string=dessin}

spécifie que tous les noms des fichiers graphiques auront pour préfixe par défaut dessin.

  • Insérer un résultat R dans une phrase de texte. A l’intérieur d’une phrase LaTeX, un résultat R peut être inséré, via la balise Sexpr. Exemple :
@
The first data are \Sexpr{print(airquality[1,])}. We analyze ...

Attention : il ne faut pas de { dans l’expression.

  • Extraire les parties de code R d’un fichier rnw. La fonction R Stangle() permet d’extraire toutes les parties de code contenues dans un fichier rnw.
Stangle("monFichier.rnw")

ou, en dehors d’une session R :

R CMD Stangle monFichier.rnw

Un fichier nommé monFichier.R contenant les parties code du fichier monFichier.rnw est créé.

Attention : les parties de code incluses dans des \Sexpr sont ignorées.

Voir aussi

  • Le TD de JR Lobry : tdr78.pdf
  • Le package R knitr
  • Le tutoriel Automatiser la production de documents: Sweave()
Versions des outils utilisés
R version 3.4.2 (2017-09-28)
Thèmes de la fiche
Thèmes