Modifier Tutoriel : Introduction à Rmarkdown

Free text:

{{ En construction }} == Introduction == [https://rmarkdown.rstudio.com/ Rmarkdown] (ou R Markdown) est une syntaxe qui permet de créer des documents en appliquant le principe de la [https://fr.wikipedia.org/wiki/Programmation_lettr%C3%A9e programmation lettrée], ou ''literate programming'' en anglais. Cette technique permet de combiner la narrative du document et la computation de code afin de générer ''dynamiquement'' des documents en différents formats. En ''Data Science'', ceci permet notamment de créer des reports scientifiques qui combinent des éléments textuels écrits par les auteurs avec des éléments computés, comme par exemple [[Introduction à la visualization des données avec R|les représentations visuelles]] ou [[Introduction à la modélisation des données avec R|les résultats d'une analyse statistique ou modélisation de données]]. Dans cet article nous proposons un aperçu du fonctionnement de Rmarkdown appliqué au contexte de la [[Pensée computationnelle avec R]], en sachant que le même principe peut être adopté avec des technologies différentes, comme par exemple le [https://jupyter.org/ projet juypter] avec Phyton, ou [https://github.com/fonsp/Pluto.jl Pluto] avec [[Julia]]. Nous aborderons d'abord quelques éléments techniques qui permettent d'intégrer du code dans la génération d'un document, pour ensuite fournir quelques exemples de référence. Pour des applications plus poussées, des liens à d'autres ressources plus spécifiques seront fournis. === Cadres d'utilisation de Rmarkdown === Rmarkdown peut être utilisé pour générer [https://rmarkdown.rstudio.com/formats.html différents types et formats de documents], comme par exemple : * Article scientifiques déjà mise en page, souvent avec le template correspondant à des normes (e.g. APA) ou le layout d'un journal spécifique * Pages, site ou blog web qui présentent des éléments scientifiques ou académiques (e.g. citations, ...) * Documentation technique, par exemple pour un paquet de [[R]] * [[Livre numérique|Livres numériques]] en différents formats ([[Epub]], [[HTML5]], ...) * Tutoriels interactifs * Mémoires ou thèses académiques * Présentations/diaporama * ''Dashboard'' ou documents interactifs * ... Ce type d'approche favorise la transparence et reproductibilité des report scientifiques, car tous les passages nécessaires à leur création sont directement documentés à l'intérieur du document ''source'', qui présente les passages computationnels correspondant. De cette manière, les auteurs eux-mêmes peuvent regrouper toutes les informations nécessaires et peuvent y accéder dans le temps, tandis que les reviewers peuvent scruter les différents éléments qui composent une contribution scientifique dans un seul endroit. === Prérequis === Rmarkdown peut être utilisé indépendamment de l'expérience préalable avec [[R]]. La complexité des documents créés ne dépend cependant pas seulement de la maîtrise de Rmarkdown en soi, mais également - et surtout - de la capacité de créer les contenus à insérer (e.g. analyses, graphiques, ...). Une expérience limitée avec [[R]] ne doit donc pas décourager la découverte et l'adoption précoce de Rmarkdown, mais les bénéfices de cette technique sont plus évidents avec une certaine maîtrise de l'écosystème [[R]]. Pour créer des documents en formats PDF, il est nécessaire d'installer un compilateur de [[LaTeX]] (voir la page correspondante ou directement le site [https://yihui.org/tinytex/ TinyTeX]). Dans l'article, nous utiliserons davantage des exemples en [[HTML5]] pour contourner cette nécessité, et aussi parce que la transformation en HTML5 est plus rapide. La connaissance de HTML5 n'est cependant pas nécessaire pour comprendre ou visualiser les documents. == Principes du fonctionnement de Rmarkdown == Rmarkdown est basé sur un ''flux'' de conversion entre formats qui abouti au document finalisé, c'est-à-dire le format jugé par les auteurs comme celui à partager ou à garder comme référence finale. Il est utile à cet effet de faire une distinction qui n'est souvent pas nécessaire lorsqu'on est habitué-es à travailler avec un éditeur de texte ''classique'' (comme par exemple Word ou équivalent). En effet, lorsqu'on utilise un document de texte ''classique'', le document de travail et le document finalisé sont pratiquement la même chose. Au contraire, lorsqu'on travail avec Rmarkdown, on peut faire la distinction entre deux documents : # '''Document de travail''' #: Il s'agit du document/manuscrit qui sert à créer le contenu. Les auteurs modifient ce document afin d'atteindre le résultat final souhaité. On peut imaginer ce document de travail sous forme de '''Input''' dans un ''flux'' de travail. # '''Document finalisé''' #: Il s'agit du rendu final, le ''camera-ready'', qui sert généralement à des finalités de communication, partage ou archivage du produit final. On peut imaginer ce document finalisé sous forme de '''Output''' dans un ''flux'' de travail. Rmarkdown met en place les conditions pour créer un ''flux'' de travail qui permet de passer du document de travail au document finalisé. Ce ''flux'' peut être adapté de manière précise et ciblée, ce qui permet notamment d'atteindre deux objectifs : # Pouvoir travailler dans le même environnement indépendamment du format du produit finalisé # Pouvoir produire, depuis le même document de travail, plusieurs formats du produit finalisé Le schéma suivant, adapté du livre en accès libre [https://bookdown.org/yihui/rmarkdown-cookbook/rmarkdown-process.html R Markdown Cookboox] (Xie, Dervieux, Riederer, 2021) illustre ce mécanisme avec les formats et logiciels impliqués dans le flux. [[Fichier:Rmarkdown workflow.png|600px|vignette|néant|''Flux'' de travail en Rmarkdown qui permet de passer du document de travail au document finalisé. Adapté du livre en accès libre [https://bookdown.org/yihui/rmarkdown-cookbook/rmarkdown-process.html R Markdown Cookboox] (Xie, Dervieux, Riederer, 2021)]] Sur le côté gauche du schéma on retrouve le document de travail au format '''Rmarkdown'''. Il s'agit du document qui intègre du texte narratif avec du code en [[R]] (ou éventuellement d'autres langages) qui permet de créer des éléments d'intérêt dans le document (e.g. graphiques, analyses statistiques, ...). Lorsque ce document de travail est prêt pour la finalisation, le paquet '''knitr''' s'occupe de ''tricoter'' le document pour le transformer dans un format intermédiaire : '''Markdown'''. Ce format intermédiaire est ensuite converti, grâce à [[Pandoc]], dans le format ou le'''s''' format'''s''' souhaité-s par les auteurs. Il peut s'agir de formats pour le web, de documents PDF, même des documents de la suite Officie qui peuvent ensuite être modifiés davantage de manière plus ''classique'', ou d'autres formats encore. == Installation == La création de document avec Rmarkdown utilise les paquets [https://cran.r-project.org/web/packages/rmarkdown/index.html '''rmarkdown'''] et [https://cran.r-project.org/web/packages/knitr/index.html '''knitr''']. Ces paquets sont déjà disponibles dans le logiciel [[RStudio]], dont l'utilisation n'est pas obligatoire, mais conseillée, notamment pour suivre le contenu de cet article qui utilise l'interface du logiciel pour ''compiler'' les documents. === Avec RStudio === Si vous utilisez [[RStudio]], les paquets '''rmarkdown''' et '''knitr''' sont déjà installés de base. De plus, l'interface du logiciel s'adapte lors de l'utilisation de fichiers avec extension '''.Rmd''' afin de faciliter la compilation du document, l'exécution des bouts de code mélangés à la narrative du document (voir plus bas), ou encore la navigation dans les parties du document. L'image ci-dessous signale les éléments dans l'interface qui peuvent être utiles à ces effets : * Le bouton '''knitr''' permet de compiler l'ensemble du document et créer le(s) fichier(s) nécessaire(s) au format de output (e.g. [[HTML5]], PDF, Microsoft Word, etc.). Le menu déroulant dans le bouton permet d'afficher différentes options de compilation. Si vous utilisez un projet RStudio (conseillé), le output figure directement à l'intérieur du dossier du projet. * Le bouton '''Insert''' permet d'ajouter des bouts de code. Le menu déroulant dans le bouton permet d'afficher différents langages pour le bout de code ([[R]], Python, ...). * Sur la droite du panneau d'un document .Rmd, il est possible d'afficher le outline du document en fonction des titres- * En bas du panneau, il est possible d'afficher un menu contextuel pour voir la liste des titres ainsi que les bouts de code présents dans le document. [[Fichier:RStudio Rmarkdown interface.png|700px|vignette|néant|Interface de [[RStudio]] avec un document Rmarkdown ouvert.]] Lors de la première utilisation de knitr en [[RStudio]], il est possible que le logiciel demande une mise à jour du paquet à la dernière version. Mais si non, les fonctionnalités liées à Rmarkdown sont disponibles ''out of the box'', à l'exception de la transformation en PDF, pour laquelle il est nécessaire de disposer d'un interprète [[LaTeX]]. La manière la plus simple consiste à installer [https://yihui.org/tinytex/ TinyTeX]. Si vous avez une version assez récente de RStudio (à partir de 2021), il est possible d'utiliser Rmarkdown directement en modalité ''What You See Is What You Get'' (WYSIWYG). Cette modalité peut-être intéressante, notamment pour les parties écrites du document, ainsi que comme transition depuis des éditeurs de texte ''classiques''. L'image suivant montre un document Rmarkdown ouvert en modalité WYSIWYG. [[Fichier:RStudio Rmarkdown WYSIWYG.png|800px|vignette|néant|Interface WYSIWYG d'un document Rmarkdown en [[RStudio]].]] === Sans RStudio === Sans [[RStudio]], l'installation des paquets se fait de la manière habituelle : <source lang="R"> install.packages("rmarkdown") install.packages("knitr") </source> Pour compiler les documents, il faudra connaître les commandes des paquets et les exécuter selon l'interface de programmation que vous utilisez. == Exemple de base == == Créer des documents/projets avec Rmarkdown == Rmarkdown peut être utilisé avec des finalités différentes qui vont du ''simple'' fichier à un projet conséquent tel qu'un article scientifique, un livre, un mémoire ou une thèse. Selon le type et la complexité du document ou projet, il existe par conséquent différentes manières de créer des documents et/ou projets qui s'appuient sur Rmarkdown. === Créer un document individuel === [[Fichier:RStudio types de nouveaux fichiers.png|vignette|droite|Créer un nouveau fichier depuis le bouton + ]] La manière la plus simple de créer un document Rmarkdown consiste à créer un fichier, par exemple à l'intérieur d'un projet [[RStudio]], ce qui permet notamment de définir le dossier de travail - un choix très important en général lorsqu'on travaille avec [[R]]. Pour plus d'informations sur les projets, se référer à la page [[RStudio]]. Pour créer un document individuel en [[RStudio]], utilisez le menu principale <code>File > New file > R markdown...</code>. En alternative, il est possible de choisir le même type de fichier directement depuis le bouton avec un + dans un cercle vert en haut à gauche de l'interface (voir image à côté). RStudio propose à ce moment une fenêtre modale qui permet de définir certaines caractéristiques du document. D'abord, on a le choix entre différentes types de document : # '''Document''', le premier choix, permet de créer une page HTML, un document PDF, ou encore un document Word. Cette choix prédispose déjà le document avec quelques contenus, ainsi que le type de transformation envisagée. # '''Presentation''' permet de créer des slides/diaporama avec différentes techniques # '''Shiny''' permet de créer des documents interactifs (plus avancé) # '''From template''' permet de choisir parmi des structures pré-existantes (voir section suivante) # '''Create Empty Document''' permet de créer un document Rmarkdown sans aucun contenu pré-établi [[Fichier:Rmarkdown differents types de documents.png|400px|vignette|néant|Différentes types de documents qui exploite la technique du Rmarkdown]] Selon le type choisi, l'interface s'adapte pour fournir des éventuels détails, tels quel le titre et l'auteur. Il s'agit en tout cas d'informations qui peuvent être modifiées dans un deuxième temps. Une fois le document créé, le fichier qui s'ouvre dans la partie d'édition de [[RStudio]] peut déjà proposer une structure pré-existante qu'on peut par la suite adapter en fonction des objectifs du document (voir l'exemple de base plus haut). === Utiliser un template === L'un des intérêts principaux d'utiliser Rmarkdown consiste à pouvoir exploiter des templates pré-existants. Ces templates sont disponibles depuis la fenêtre modale qui s'ouvre lors de la création d'un document Rmarkdown (voir section précédente pour les détails). L'image suivante montre quelques unes des choix disponibles, en sachant que des templates ultérieurs peuvent être installés à travers des paquets : [[Fichier:Rmarkdown templates.png|400px|vignette|néant|Choix de templates pré-existants avec Rmarkdown. L'installation de paquets permet d'ajouter d'autres templates.]] Un template fourni en général deux fonctions interdépendantes : # '''Une structure du document Rmarkdown''' #: Ceci équivaut en général dans un entête en language [https://fr.wikipedia.org/wiki/YAML YAML] avec des options, ainsi que des sections en Rmarkdown pour structurer le contenu du document. # '''Des règles de transformation du contenu dans un ou plusieurs formats ''finaux''''' #: Il s'agit de l'élément le plus intéressant des templates, car cette fonctionnalités permet par exemple de mettre en page le contenu selon des guidelines d'une revue scientifique, de créer une page [[HTML5]] avec déjà des règles de style [[CSS]], etc. {{ bloc important | Selon le type de template choisi, la première transformation peut nécessiter du temps, car [[RStudio]] s'occupe de télécharger en arrière plan des éventuels fichiers ou éléments nécessaires à la conversion du document Rmarkdown dans le format finalisé. Ceci est surtout le cas avec des transformations en PDF qui nécessitent souvent d'extensions [[LaTeX]] pour créer des mises en page complexes. }} La démarche est néanmoins lente seulement la première fois et s'accélère dans les conversions suivantes. === Créer un projet basé sur Rmarkdown === Souvent, un seul document Rmarkdown n'est pas suffisant pour afficher tous les contenus souhaités. C'est le cas notamment des sites web, des livres, des mémoires ou thèses. Ces types de document sont composés souvent de plusieurs fichiers, ce qui permet notamment de décomposer un long manuscript en plusieurs fichiers plus simples à gérer. Pour ces cas, il est donc très probable qu'on puisse passer directement par un '''projet''' de [[RStudio]], plutôt que par la création de fichiers individuels comme illustré dans les sections précédentes. Pour créer un projet en [[RStudio]], passez par le menu principale <code>File > New project</code>. Une fenêtre modale permet de choisir si créer le projet dans un nouveau dossier, choisir un dossier existant, ou même cloner un projet depuis un gestionnaire de versions comme par exemple [[GitHub]]. Pour les projets basés sur Rmarkdown, en général, l'option de créer un projet dans un nouveau dossier est la plus probable. La fenêtre modale offre à ce moment plusieurs choix selon les paquets installés : [[Fichier:Rmarkdown projets.png|400px|vignette|néant|Créer un nouveau projet avec une technique qui s'appuie sur Rmarkdown, comme par exemple Bookdown.]] Selon les paquets installés, plusieurs projets s'appuient directement sur Rmarkdown, comme c'est le cas à l'image de : * [https://bookdown.org/yihui/bookdown/ Book project using bookdown] * [https://rstudio.github.io/distill/ Distill Blog et Distill Website] * [https://github.com/ismayc/thesisdown Thesis Project using thesisdown] {{ bloc important | Certains types de projets peuvent être plus ou moins maintenus par les auteurs. Il faut donc bien veiller à choisir des projets qui ne risquent pas de créer des incompatibilité lors que vous installez des versions de [[R]] et/ou [[RStudio]] plus récentes. }} Lorsque vous créez un projet de ce type, en général vous trouverez déjà dans l'interface [[RStudio]] plusieurs fichiers qui sont nécessaires au fonctionnement, ainsi que quelques exemples de contenus à adapter. == Formatage de texte == Pour les parties narratives/textuelles des documents, Rmarkdown met à disposition principalement deux modalités de formatage ou décoration du texte : * '''Markdown''' : un langage simple qui permet de créer des décorations de base (titres, paragraphes, ...) * '''[[LaTeX]]''' : un langage complexe qui permet de créer des éléments avancés comme des équations ou théorèmes Cette section propose un survol des deux options. === Markdown === Markdown est un langage de marquage créé par [https://daringfireball.net/projects/markdown/ John Gruber] qui se différencie d'autres langages de marquage, comme par exemple [[HTML5]] ou [[LaTeX]], pour sa simplicité. L'avantage est principalement celui de rendre la lecture du document de travail, c'est-à-dire celui avec le marquage, plus fluide. La complexité du document final est déléguée à des règles de transformation qui peuvent varier en fonction de (1) le format de sortie du document (PDF, [[HTML]], ...), ou (2) le ''template'' qui est utilisé pour la mise en page. Il existe différentes implémentations de Markdown ou qui ressemblent à Markdown. Rmarkdown utilise la version [https://pandoc.org/MANUAL.html#pandocs-markdown Pandoc's Markdown], c'est-à-dire la version de [https://pandoc.org/ pandoc], le ''moteur'' qui permet de migrer entre différents formats. Si vous utilisez [[RStudio]], pandoc est directement installé avec le logiciel. Dans cette section, nous proposons une liste non exhaustive des éléments de marquage les plus utilisés. Certains formatages disponibles en Markdown peuvent être gérés également avec des fonctions de [[R]], comme par exemple pour les images ou les tables. Voir plus bas dans cet article pour plus d'informations. ==== Paragraphes ==== Pour créer des paragraphes, laissez une ligne blanche entre les deux blocs de texte : <source lang="md"> Ceci est le premier paragraphe du document. Il est très court. Et voici le deuxième. Il est encore plus court. </source> On peut appliquer des formatages à une partie du texte en contournant les éléments avec <code>*texte*</code> pour l'''italique'', et <code>**texte**</code> pour le '''gras''' : <source lang="md"> Ce *texte est en italique*, tandis que **celui-ci est en gras**. On peut combiner les deux pour avoir un ***texte en gras et italique***. </source> ==== Titres ==== Les titres se forment en utilisant un nombre de # relatifs au niveau du titre. Le texte du titre doit laisser un espace après le # : <source lang="md"> # Titre de premier niveau ## Titre de deuxième niveau ### Titre de troisième niveau </source> ==== Listes ==== Pour une liste non ordonnée, utilisez le * ou le - au début de chaque item : <source lang="md"> Voici une liste d'éléments : * Item * Item * Item Une autre alternative : - Item - Item - Item </source> Pour une liste ordonnée, il faut mettre un chiffre suivi par un point. Il est important de noter que seulement le premier chiffre utilisé dans la liste joue un rôle important, car il détermine le début du comptage. Les chiffres suivants n'ont aucune influence : <source lang="md"> Cette liste : 1. Lire 2. Écrire 3. Imprimer Est égale à cette liste : 1. Lire 1. Écrire 1. Imprimer Mais pas à celle-ci qui commence à 4 : 4. Lire 2. Écrire 1. Imprimer </source> Il existe une notation alternative <code>#.</code>, mais que nous déconseillons, car elle peut se confondre assez facilement avec les titres : <source lang="md"> Notation alternative, mais qui peut se confondre avec les titres #. Lire #. Écrire #. Imprimer </source> ==== Images (simple) ==== L'insértion d'image avec Markdown est conseillée exclusivement dans le cadre de document simple, surtout en relation avec [[HTML5]]. Pour des mises en page plus complexe, il existe plus d'options en utilisant la fonction <code>include_graphics()</code> de '''knitr''' (voir plus bas dans l'article). Le code pour insérer une image en Markdown est le suivant : <source lang="md">  </source> Par exemple : <source lang="md">  </source> ==== Liens ==== Pour créer un lien hypertextuel à une ressource sur le web, utile surtout dans l'output de type [[HTML5]] mais valable aussi pour d'autres formats, la notation est la suivante : <source lang="md"> [Label du lien](url de la ressource) </source> Par exemple : <source lang="md"> [EduTech Wiki en français](https://edutechwiki.unige.ch/fr/Accueil) </source> ==== Citations de texte ==== Pour citer un passage, on peut délimiter le début du texte avec le symbole <code>></code>. Par exemple : <source lang="md"> > "Ceci est le texte de la citation" > > --- Auteur et date </source> Pour la citation de références académiques, voir plus bas dans l'article. === LaTeX === [[LaTeX]] est un langage et un système de préparation de documents techniques, gratuit et multi-plateforme, souvent destinés à des utilisations scientifiques. Rmarkdown s'intègre avec LaTeX à plusieurs niveaux, notamment pour la création de documents en PDF. Cette section se limite à illustrer l'utilisation de la syntaxe LaTeX pour ajouter des caractères spéciaux, équations ou formules mathématiques dans les documents Rmarkdown. Pour plus de détails sur la syntaxe se référer à la page [[LaTeX]]. L'intégration de la syntaxe [[LaTeX]] peut se faire de deux manières : * En ligne avec le reste du texte Rmarkdown * Dans un bloc de texte/code séparé ==== Intégrer LaTeX en ligne avec le texte ==== Pour intégrer la syntaxe [[LaTeX]] directement en ligne avec le texte Rmarkdown, il suffit de délimiter le code avec un signe du dollar au début et à la fin : <code>$ .... $</code>. Voici de suite quelques exemples qui montrent d'abord le code Rmarkdown et ensuite le résultat (en exploitant le fait que [[Mediawiki]] permet aussi d'écrire avec la syntaxe [[LaTeX]]. <source lang="md"> L'échantillon de l'étude est composé par $N = 45$ participant-es avec un âge moyen de $M_{age} = 27.45$ ans ($SD_{age} = 9.23$). </source> '''Résultat''' : L'échantillon de l'étude est composé par <math>N = 45</math> participant-es avec un âge moyen de <math>M_{age} = 27.45</math> ans (<math>SD_{age} = 9.23</math>). <source lang="md"> L'analyse de puissance statistique a été menée avec un seuil de significativité pour l'erreur de Type I de $\alpha = 0.05$ et de contrôle pour l'erreur de Type II de $\beta = 0.9$. </source> '''Résultat''' : L'analyse de puissance statistique a été menée avec un seuil de significativité pour l'erreur de Type I de <math>\alpha = 0.05</math> et de contrôle pour l'erreur de Type II de <math>\beta = 0.9</math>. <source lang="md"> La différence observée entre les deux moyennes a été de $M_\Delta = 0.67$. </source> '''Résultat''' : La différence observée entre les deux moyennes a été de <math>M_\Delta = 0.67</math>. ==== Créer un bloc de texte/code séparé ==== Pour créer un bloc de texte/code avec synataxe [[LaTeX]], il faut séparer le contenu avec une ligne de séparation (comme pour un paragraphe Markdown) et délimiter le bloc de code avec deux signes du dollar au début, et deux à la fin : <source lang="md"> $$ ... $$ </source> Par exemple, la loi de Fitts, utilisée souvent dans l'interaction personne-machine, est codée de la manière suivante en Rmarkdown : <source lang="md"> $$ \text{ID} = \log_2 \Bigg(\frac{D}{W}+1\Bigg) $$ </source> '''Résultat''' : <math>\text{ID} = \log_2 \Bigg(\frac{D}{W}+1\Bigg)</math> == Intégration du code R == Le code [[R]] à exécuter dans un ficher Rmarkdown peut être inséré de différentes manières : # '''Dans du code inline''' #: Il s'agit en général de brefs instructions qui consistent, souvent, tout simplement à imprimer une référence symbolique ou le résultat d'une fonction à l'intérieur d'un passage de texte. # '''Dans des bouts de code, ou ''code chunks'' en anglais''' #: Il s'agit de bloc de code qui peuvent être nommés et définis avec des options. Ils incluent normalement plusieurs instructions de code. # '''Importer du code source depuis d'autres fichiers RScript''' #: Dans le cas de projets complexes, il est utile d'organiser le code dans des fichiers séparés et les importer au besoin. Les différentes stratégies sont très souvent combinées. Par exemple, le bout de code importe un script plus complexe depuis un ficher et applique quelques transformations nécessaires dans le cadre du report scientifique, par exemple pour calculer un indice d'intérêt (e.g. le résultat d'un test statistique). Cet indice est associé à une référence symbolique qui est ensuite utilisée dans du code inline pour imprimer l'indice à l'intérieur d'une phrase du report scientifique. === Code inline === Le code inline s’insère en contournant le code avec deux accents graves <code>`</code> (i.e. des ''backticks'' en anglais) et en utilisant la lettre <code>r</code> au début : `r [code à exécuter]` Voici quelques exemples de notation suivi par le résultat qui s'affiche dans le document compilé : * <source lang="md"> La somme de 19 et 54 est `r 19 + 54` </source> *: La somme de 19 et 54 est 73''' * <source lang="md"> Ce document a été mis à jour `r format(Sys.Date(), "%A %d %B %Y")`. </source> *: Ce document a été mis à jour dimanche 27 septembre 2020. (n.b., la date va varier) * <source lang="md"> L'alphabète a `r length(letters)` lettres : `r letters`. </source> *: L’alphabète a 26 lettres : a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z. === Bouts de code === Un bout de code permet d'injecter plusieurs instructions de code en [[R]] dans le document Rmarkdown. Un bout de code se caractérise par la notation suivante : <source lang="R"> ```{r [identifiant du bout], [option = valeur, options = valeur, ...]} # Instruction 1 # Instruction 2 ``` </source> Par exemple : <source lang="R"> ```{r random-plot, echo=TRUE, fig.align="center", fig.cap="Exemple de scatterplot" } x = runif(100, 50, 150) y = runif(100, 500, 1000) plot(x, y) ``` </source> Ce bout de code construit un scatterplot avec des chiffres aléatoires, créés avec la fonction <code>runif()</code>, et l'affiche dans le document. Les éléments du code sont les suivants : * '''random-plot''' est l'identifiant du bout du code. Nommer un bout de code est optionnel, mais peut être utile par exemple pour le retrouver dans la liste de l'interface [[RStudio]] (voir section Installation) ou pour des utilisations plus poussées. * '''echo=TRUE''' est la première option du bout du code est détermine que le code du bout soit affiché dans le document. Ceci peut être utile par exemple pour des finalités pédagogiques, même si en général on ne veut pas montrer le code mais seulement le résultat. Dans ce cas on peut écrire '''echo=FALSE''' dans le bout de code, ou definir une option au niveau du document, par exemple dans un bout de code de ''setup'', avec l'instruction <code>knitr::opts_chunk$set(echo = FALSE)</code>. * '''fig.align''' est la deuxième option du bout et détermine l'affichage du scatterplot. Cette option s'applique dans le cas de notre exemple car le bout de code est un graphique. * '''fig.cap''' est la troisième option du bout et détermine la legende du graphique. Encore une fois, il s'agit d'une option qui s'applique lorsque le résultat du bout est une représentation graphique. === Importer du code source === Dans des projets qui utilisent beaucouo de code, souvent divisé en plusieurs fichiers, il est utile de pouvoir importer du code source plutôt que de l'injecter verbatim à l'intérieur du document Rmarkdown. Dans ces cas, il est utile d'utiliser la fonction <code>source("path/to/file.R")</code> mise à disposition par [[R]]. {{ bloc important | Comme dans le fonctionnement de [[R]] en général, le chemin (ou ''path'') au fichier est relatif au dossier de travail (''working directory''). Une bonne pratique à cet effet est d'utiliser les projets en [[RStudio]] et le paquet [https://here.r-lib.org/ here] }} Voici un example qui tient compte de l'arborescence des dossiers suivante : |- dossier-du-projet |- fichier-rmarkdown.Rmd |- scripts |- mon-code.R Pour intégrer le code source du fichier <code>mon-code.R</code> à l'intérieur du fichier <code>fichier-markdown.Rmd</code> on peut procéder de la manière suivante : # Installer le paquet '''[https://here.r-lib.org/ here]''' s'il n'est pas encore disponible avec la commande <code>install.packages("here")</code> # Créer un bout de code '''setup''' au début du document Rmarkdown (souvent déjà créé par le template) : #: <source lang="R"> ```{r setup, include=FALSE} knitr::opts_chunk$set(echo = TRUE) ``` </source> # Incorporer dans ce bout de code le paquet '''here''' et ajouter la référence au fichier Rscript avec la fonction <code>source()</code> : #: <source lang="R" line highlight="4,7"> ```{r setup, include=FALSE} knitr::opts_chunk$set(echo = TRUE) # Incorporer le paquet here pour faciliter les chemins library(here) # Incorporer le fichier avec le code R source(here::here("scripts", "mon-code.R"), local = knitr::knit_global(), encoding = "UTF-8") ``` </source> À ce moment, lorsque ce bout de code est exécuté, vous aurez à disposition dans le document toutes les références symboliques disponibles dans le fichier <code>scripts/mon-code.R</code>, y compris des éventuels paquets ou autre sources qui sont incorporés depuis ce même fichier. À noter que en cas d'utilisation d'autres sources, celles-ci doivent également utiliser une référence par rapport au dossier de travail de [[R]]. Les attributs <code>local = knitr::knit_global()</code> et <code>encoding = "UTF-8"</code> servent à garantir que l'incorporation soit faite dans l'environnement de knitr et en utilisant un système d'encodage. Ce dernier argument est particulièrement important si dans vos données figurent des accents ou caractère spéciaux. Il est donc conseillé d'ajouter les deux arguments dans l'incorporation de scripts R. == Éléments ''scientifiques'' en Rmarkdown == Rmarkdown a été conçu pour l'écriture technique/académique et permet donc d'inclure des éléments qui figurent souvent dans ce type de document : tableaux, graphiques ou images (combinée dans la sous-section Figures) avec légendes, citations, et références croisées. Il faut néanmoins tenir compte de deux éléments importants lors qu'on utilise ce type d'éléments plus avancées : # '''Il peut y avoir des différences selon le format de sortie/finalisé du document''' #: Certaines fonctionnalités peuvent marcher mieux ou exclusivement si le document finalisé est en HTML5 plutôt que en PDF ou vice-versa. # '''Paquets supplémentaires''' #: Rmarkdown ''de base'' met déjà à disposition plusieurs éléments utiles pour la création de documentation technique/académique, mais un vaste écosystème de paquets permet d'ajouter souvent des fonctionnalités ultérieurs ou améliorer les fonctionnalités de base. === Tableaux === === Figures === === Citations === === Références croisées === == Ressources == * [https://bookdown.org/yihui/rmarkdown/ R Markdown: The Definitive Guide] par Yihui Xie, J. J. Allaire et Garrett Grolemund * [https://bookdown.org/yihui/rmarkdown-cookbook/ R Markdown Cookbook] par Yihui Xie, Christophe Dervieux et Emily Riederer * [https://rstudio.github.io/visual-markdown-editing/ Visual Markdown Editing] sur le site de RStudio * [https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf R Markdown Cheat Sheet] [[Catégorie: R]]

Enregistrer Prévisualiser Voir les modifications Annuler