SWEAVE – R MARKDOWN Diane Beldame - Margot Brard - Alexia Cariou - Thomas Cloatre – Camille Lautret - Marie Le Lay - Cécile Natchez Exposé projet R octobre 2013

Introduction Objectif : créer des rapports dynamiques qui peuvent être mis à jour automatiquement si les données ou l'analyse changent Au lieu d'insérer un graphique préfabriqué ou une table dans le rapport, le document maître contient le code R nécessaire pour l'obtenir Lorsqu'il est exécuté par R, toutes les sorties de l'analyse des données (tableaux, graphiques, etc) sont insérées dans un document final Document final = PDF  Sweave Document final = Page HTML  R Markdown

Sommaire Partie 1 : Sweave Partie 2 : R Markdown I. Présentation de Latex II. Présentation de R Sweave III. Utilisation de R Sweave IV. Discussion et limites Partie 2 : R Markdown I. Présentation de R Markdown II. Installation de R Markdown III. Utilisation de R Markdown IV. Exemple d’utilisation V. Présentation de la fonction Pandoc VI. Critique & points forts

PARTIE I : SWEAVE

1. Présentation de Latex

Passer du temps sur le fond plutôt que sur la forme Présentation de Latex Présentation de R Sweave Utilisation de R Sweave Discussion et limites 1. Intérêts de Latex Methode privilégiée d’écriture de documents scientifiques et techniques Intérêt : mise en forme automatique selon des paramètres prédéfini ou configurés utilisateurs Passer du temps sur le fond plutôt que sur la forme Langage et format largement reconnu et utilisé dans les sciences

Présentation de Latex Présentation de R Sweave Utilisation de R Sweave Discussion et limites 2. Comment s’écrit Latex ? Proche du HTML dans le sens qu’il fonctionne avec des balises Personnalisable à souhait avec des packages Libre donc possibilité de créer et distribuer son propre package Exemple : \documentclass{article} \begin{document} Je lis actuellement un script en LaTeX et je me demande bien comment ce charabia peut produire des documents PDF digne de ce nom \end{document}

Présentation de Latex Présentation de R Sweave Utilisation de R Sweave Discussion et limites 2. Comment s’écrit Latex ? \documentclass[a4paper]{article} \usepackage{Sweave} \begin{document} \title{Exemple d'utilisation de Sweave} \maketitle \section{Exemple} Voici un exemple simple: bonjour \end{document}

3. Installation classique Latex Présentation de Latex Présentation de R Sweave Utilisation de R Sweave Discussion et limites 3. Installation classique Latex un éditeur : bloc-note peut faire l’affaire, Sinon Notepad++ (éditeur multi-langage dont R et Latex) par exemple une distribution Latex (Miktex, TeXLive, proTex...en fonction de l’OS) un lecteur de postscripts et pdf (Ghostscript, Ghostview, Adobe Reader…) Comment ces outils s’articulent ? la compilation : c’est l’étape qui transforme le code en résultat escompté les sorties sont de 3 natures (expliciter)

2. Présentation de Sweave dans R

1. Mode opératoire Présentation de Latex Présentation de R Sweave Utilisation de R Sweave Discussion et limites 1. Mode opératoire Créer un rapport Latex (extension .tex) Changer l’extension .tex en .Rnw exemple : monrapport.tex => monrapport.Rnw Ecrire la structure du rapport ou de l’article Lorsqu’on a besoin de faire appel à R (lignes de codes, sorties graphiques etc..), on utilise les balises (=chunks) suivantes : << options >>= (début du chunk) @ (fin du chunk) Dans R, on exécute Sweave(“monrapport.Rnw”) (le fichier doit être dans le répertoire courant) Cette instruction rend un fichier intitulé monrapport.tex dans le répertoire courant Compiler le fichier monrapport.tex pour obtenir le .pdf (ou .ps ou .dvi)

2. Quelques options des chunks Présentation de Latex Présentation de R Sweave Utilisation de R Sweave Discussion et limites 2. Quelques options des chunks echo = TRUE/FALSE : on duplique la ligne de code utilisée dans R, c’est comme si elle était executée dans le rapport, on a un “écho” de la commande (TRUE par défaut) fig = TRUE/FALSE : on trace les graphiques produits par la commande R (par défaut FALSE) label=... : on peut donner un nom à chaque chunk eval = TRUE/FALSE : on “run” le chunk (par défaut TRUE). FALSE équivaut à un copier/coller du code en quelque sorte pdf=TRUE/FALSE : on crée un pdf de la figure dans le répertoire courant. Son nom est celui du label s’il existe (par défaut FALSE)

3. Utilisation de Sweave dans R Studio

4. Discussion et limites

Difficulté d’utiliser Sweave dans R ou dans R cmdr Présentation de Latex Présentation de Rsweave Utilisation de R Sweave Discussion et limites Apprentissage du langage Latex indispensable : investissement nécessaire Etape de compilation n’est pas instantanée, on ne peut pas voir instantanément ce que l’on code ( pas de WYSIWYG, “what you see is what you get” comme sur Word ou OOWriter) Difficulté d’utiliser Sweave dans R ou dans R cmdr

PARTIE II : R MARKDOWN

1. Présentation de R Markdown

Sur la page web, on peut mettre : Code R Résultat de l’exécution Présentation de R Markdown Utilisation de R Markdown Installation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts Package de R qui permet de créer de manière simplifiée des pages web reproductibles à partir de R. Utilise un langage simple dans lequel sont insérées des parties de code R. Sur la page web, on peut mettre : Code R Résultat de l’exécution Graphiques Images Formules …

Dans notre dossier on obtient : Présentation de R Markdown Utilisation de R Markdown Installation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts Dans notre dossier on obtient : Un fichier .rmd : fichier où l’on met en forme le contenu de la page web. Un fichier .md : fichier généré à l’exécution du fichier .rmd qui permet de compiler le code R et de le traduire pour pouvoir ensuite générer la page html. Un fichier .html : page web créée.

2. Installation de R Markdown

Présentation de R Markdown Utilisation de R Markdown Installation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts 1. Via R Studio Installer le package knitr (version 0.5 ou version postérieure). Charger le package knitr. « tools » « options » « sweave » « weave rnw files using » : knitr (par défaut : sweave)

2. Via Rcmdr Avec la dernière version de R. Présentation de R Markdown Utilisation de R Markdown Installation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts 2. Via Rcmdr Avec la dernière version de R. Installer puis charger le package markdown. Charger le package Rcmdr. Charger le package knitr. La fenêtre Rmarkdown se trouve à côté de la fenêtre Rcmdr :

3. Utilisation de R Markdown Sommaire 3. Utilisation de R Markdown R markdown permet de créer de manière simplifiée des pages web reproductibles à partir de R. On va donc vous présenter le langage markdown, assez simple dans lequel sont insérées des parties de code R. Pour utiliser R markdown : deux interfaces

1. Ecriture dans R Markdown Présentation de R Markdown Installation de R Markdown Utilisation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts 1. Ecriture dans R Markdown Changer la taille selon le titre : utiliser le signe dièse # # Titre I ## Titre II ### Titre III Ecrire en italique : *astérisque simple accolé* Ecrire en gras : **double astérisque**. Créer une liste : utiliser "l'astérisque" - *( mettre un espace entre astérisque et le texte qui suit) Créer des liens hypertexte : utiliser le point d'exclamation, les crochets et les parenthèses dans l'ordre suivant : 

1. Ecriture dans R Markdown Présentation de R Markdown Installation de R Markdown Utilisation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts 1. Ecriture dans R Markdown Mettre de la couleur dans le texte : utiliser les balises <span style="color: #fb4141"> texte à colorer</span> : (fb4141 est le code pour la couleur rouge) http://www.code-couleur.com/dictionnaire/couleur-b.html Mettre des équations : encadrer l’équation par $$ équation $$ $$ y_i = \alpha + \beta x_i + e_i $$ Mettre des tableaux

Présentation de R Markdown Installation de R Markdown Utilisation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts 2. Via R Studio Pour créer un nouveau fichier R Markdown : <File> <New> <Sélectionner R Markdown>. Un nouveau fichier se crée avec le modèle par défaut pour guider l’utilisateur. Enregistrement du fichier en appuyant sur Knit HTML car le fichier doit porter un nom pour être transformer en un format .html.

Présentation de R Markdown Installation de R Markdown Utilisation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts 2. Via R Studio Majorité des fonctions nécessaires pour travailler avec R Markdown  barre d’outil de R Studio : Quick Reference : cliquer sur le bouton MD pour ouvrir le guide Markdown. Knit HTML : cliquer sur knit pour enregistrer le document et voir en HTML la page HTML générée. Run : lancer la ligne de code sélectionnée dans la console R. Chunks : founit une aide pour insérer et lancer correctement des morceaux de code R dans le document HTML : DEMO RAPIDE SUR UN SUMMARY

Présentation de R Markdown Installation de R Markdown Utilisation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts 2. Via R Studio Intégration de morceaux de code R : intégration de morceaux de code R en utilisant la syntaxe Markdown natif : Nécessaire d’insérer des chunks (avec des arguments) Ajouter echo=FALSE dans le chunk pour les affichages non souhaités dans la page HTML Ajouter eval=FALSE dans le chunk pour que le code R ne soit pas appliqué ````{r} chunkLabel # Code R ```` DEMO RAPIDE SUR UN SUMMARY

3. Via Rcmdr Saisir le code dans la fenêtre « Script R » de Rcmdr. Présentation de R Markdown Installation de R Markdown Utilisation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts 3. Via Rcmdr Saisir le code dans la fenêtre « Script R » de Rcmdr. Le soumettre  copie automatique du code R dans la fenêtre R Markdown en langage R Markdown (c’est-à-dire avec les chunks). Ajouter echo=FALSE dans le chunk pour les affichages non souhaités dans la page HTML. Ajouter eval=FALSE dans le chunk pour que le code R ne soit pas appliqué. Cliquer sur « Générer un rapport HTML ».

4. Exemple d’utilisation

5. Présentation de la fonction Pandoc

Fonction pandoc() (package knitr) Présentation de R Markdown Installation de R Markdown Utilisation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts Fonction pandoc() (package knitr) Convertir des documents Markdown en formats : Latex/pdf Html Word (odt, docx). Minimiser l’appel en ligne de commande en enveloppant ces commandes dans un fichier de configuration ou des configurations intégrées. Utilisation : 1. Installation de Pandoc à partir du site : http://johnmacfarlane.net/pandoc/ ou à partir de la fonction installr, puis de la ligne de commande install.pandoc() 2. Chargement de la librairie knitr

6. Critique & points forts

R Markdown : package très pratique pour la présentation de résultats Présentation de R Markdown Installation de R Markdown Utilisation de R Markdown Exemple d’utilisation Présentation de Pandoc Critique & Points forts R Markdown : package très pratique pour la présentation de résultats Avantage : modification des pages html générées automatique R Studio plus complet que Rcmdr Mais mieux de commencer par Rcmdr car plus intuitif Difficulté d’utilisation de la fonction pandoc : possibilité de télécharger la fonction mais pas de l’utiliser.

Conclusion Sweave et R Markdown permettent de créer des documents reproductibles Insertion de code R Mais paraissent difficiles à utiliser aux premiers abords Nombreuses aides disponibles sur internet

Références Partie R Markdown : Jean-Daniel Bonjour (2013), « Élaboration et conversion de documents avec Markdown et Pandoc », disponible sur le site internet http://enacit1.epfl.ch/markdown-pandoc/ consulté le 28/09/2013 Sophie Lamarre (juillet 2013), « Présentation R Markdown », disponible sur le site internet http://www-gremaq.univ-tlse1.fr/ consulté le 30/09/2013 R Studio Inc (2013), « R Markdown », disponible sur le site internet http://www.rstudio.com/ide/docs/r_markdown consulté le 20/09/2013 R Studio Inc (2013), « Using R Markdown with R Studio », disponible sur le site internet http://www.rstudio.com/ide/docs/authoring/using_markdown consulté le 20/09/2013 Yihuie Xie (2013), « Knitr - Elegant, flexible and fast dynamic report generation with R », disponible sur le site internet http://yihui.name/knitr/ consulté le 21/09/2013

Références Partie Sweave : Brigitte Schaeffer (2011), « Introduire du code et des sorties R dans un document LaTeX avec Sweave », disponible sur le site internet http://ciam.inra.fr/r4ciam/node/184 consulté le 02/10/2013 J.R. Lobry (2009), « Comment rédiger un rapport avec la commande Sweave() de R », disponible sur le site internet http://pbil.univ-lyon1.fr/R/pdf/tdr78.pdf consulté le 03/10/2013 Nicola Sartori, « Sweave = R · LATEX² », disponible sur le site internet http://diskworld.wharton.upenn.edu/~foster/teaching/471/sweave-intro.pdf consulté le 30/09/2013 Openclassrooms (2013), « Tutoriel Latex », disponible sur le site internet http://fr.openclassrooms.com/informatique/cours/redigez-des-documents-de-qualite- avec-latex consulté le 28/09/2013