--- title: 'Mettre en ligne son rapport d’analyse R markdown' disqus: hackmd tags: tutoriel, migale, bonnes pratiques description: https://hackmd.io/@migale/rapport-analyse --- ###### tags: `tutoriel` `Bonnes pratiques` Mettre en ligne son rapport d’analyse R markdown === :::info metadata :fr: Olivier Rué 27/10/2021 (mise à jour 27/10/2021) Cette vignette propose différentes méthodes pour générer, organiser et rendre accessibles ses rapports d'analyse sur le web en utilisant Rstudio [^rstudio]. Les principaux avantages des méthodes proposées sont 1) la facilité de mise en oeuvre, 2) la traçabilité avec git et Gitlab, 3) favoriser la reproductibilité avec R markdown [^rmarkdown] et 4) générer des rapports esthétiques et dynamiques. ::: # Introduction Dans le monde de la recherche, il est essentiel de présenter le travail effectué sous la forme de rapports, que ce soit en cours de projet pour présenter les avancées, les analyses déjà effectuées, ou en fin de projet pour synthétiser tout le travail effectué. Il est important que toutes les étapes y soient indiquées pour que le travail puisse être compris et reproduit. Le cahier de laboratoire électronique se doit donc d'être facile d'utilisation et complet pour pouvoir y recenser: - des lignes de commandes dans les languages utilisés pour l'analyse - des tableaux - des graphiques mais aussi éventuellement: - de la bibliographie - de l'interactivité dans les tableaux et graphiques ==**R markdown**== est le language de prédilection pour répondre à toutes ces problématiques. Son apprentissage est relativement simple. Ce language permet d'exécuter du code, d'afficher les résultats obtenus et d'ajouter du texte formaté. C'est le cahier de laboratoire intéractif par excellence. Une fois adopté, vous ne pourrez plus vous en passer ! Si le rapport est amené à évoluer, il faut également que la mise à jour du document soit facile et si possible que l'historique des modifications soit gardé. L'outil ==**git**== permet d'avoir un historique des versions des différents fichiers centralisés dans un dépôt. En mode collaboratif, finis les échanges de fichiers par clés ou par pièces jointes ! Là encore, pour un usage basique, l'apprentissage est assez simple. ==**Rstudio**== est l'environnement de développement idéal pour gérer vos rapports d'analyse. Vous verrez que dans une seule interface, vous aurez la possibilité d'éditer votre rapport, le compiler et le publier sur un site web ! # Le language R Markdown L’extension rmarkdown permet de générer des documents de manière dynamique en mélangeant texte mis en forme et résultats produits par du code R (ou autres languages !). Les documents générés peuvent être au format HTML, PDF, Word, et bien d’autres. C’est donc un outil très pratique pour l’export, la communication et la diffusion de résultats d’analyse. Il est installé par défaut dans Rstudio. R Markdown offre une syntaxe simplifiée pour mettre en forme des documents contenant à la fois du texte, des instructions R et le résultat fourni par R lors de l’évaluation de ces instructions. En ce sens, il s’agit d’un outil permettant de produire des rapports d’analyse détaillés et commentés, plutôt que de simples scripts R incluant quelques commentaires. Ce langage est basé sur Markdown. Il s’apprend très rapidement, ne nécessite rien d’autre qu’un éditeur texte. Pour apprendre les bases du language R markdown, lisez [le tutoriel dédié](https://pkgs.rstudio.com/rmarkdown/articles/rmarkdown.html). Et bien sûr le <a href="https://rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf">cheatsheet</a> à toujours garder à portée de main ! ## Créer un nouveau document Un document R Markdown est un simple fichier texte enregistré avec l’extension `.Rmd`. Sous RStudio, on peut créer un nouveau document en allant dans le menu File puis en choisissant New file puis R Markdown…. Les boîtes de dialogue suivantes s’affichent et permettent de renseigner les métadonnées du nouveau fichier : ![](https://i.imgur.com/JT7W7YS.png =x300) On peut indiquer le titre, l’auteur du document ainsi que le format de sortie par défaut (il est possible de modifier facilement ses éléments par la suite). Un fichier comportant un contenu d’exemple s’affiche alors. Vous pouvez l’enregistrer où vous le souhaitez avec une extension .Rmd. ![](https://i.imgur.com/I2Uf1Ha.png =x400) ## Compiler un fichier Rmd en html Le document Rmd se compile grâce au bouton `Knit`. On peut choisir le format de sortie. De base il est possible de choisir HTML, PDF ou Word. ![](https://i.imgur.com/1GJk6oE.png) <br> Voici un exemple basique de fichier R markdown ...: ![](https://i.imgur.com/eY8ushi.png) ... et le rendu au format html : ![](https://i.imgur.com/rLLMiS2.png) Il est également possible de générer des fichiers au format PDF : ![](https://i.imgur.com/xzfa29y.png) et docx : ![](https://i.imgur.com/9oIx49t.png) # Publier son rapport avec Rpubs ![](https://i.imgur.com/O9B938k.png) Rstudio donne la possibilité, très facilement, de mettre à disposition le document compilé sur le site rpubs.com. Pour créer un compte sur Rpubs, il suffit de suivre ces étapes : - Se rendre à l'adresse https://rpubs.com/ - Cliquer sur le bouton Register en haut à droite - Renseigner les champs requis ![](https://i.imgur.com/jlKKZR4.png) Ensuite, une fois le rapport généré, un bouton est accessible dans l'interface de Rstudio pour publier le rapport. Il suffit ensuite de cliquer sur le bouton Publier pour que le rapport web soit déployé sur Rpubs. ![](https://i.imgur.com/grwNJwM.png) --- ![](https://i.imgur.com/kwrXULq.png =x300) --- ![](https://i.imgur.com/TjHrNmo.png =x300) Le document que j'ai nommé *test* est alors accessible à tous à cette adresse : https://rpubs.com/orue/test. Pour le mettre à jour, rien de plus simple, il suffit de modifier le document, de le regénérer avec Knitr et de le publier à nouveau. # Publier son rapport avec Gitlab ![](https://i.imgur.com/JfsTaW7.png =x100) Gitlab est une plateforme de développement à la fois open source et collaborative, qui se base sur **git**. Il tend à remplacer Github depuis son rachat par Microsoft en 2018. À l'échelle d'INRAE, le département MathNUM (anciennement MIA) utilise Gitlab comme <a href="https://informatique-mia.inra.fr/Forgemia">forge logicielle</a> pour y stocker des projets menés par les membres des équipes du département. Elle est ouverte à tous les collaborateurs, même hors INRAE. Utiliser un logiciel de gestion de versions (Gitlab, Github ou un autre) est toujours une bonne pratique. Les raisons suivantes vous convaincront sûrement : - documents centralisés (on évite de tout perdre si l'ordinateur lâche ou si on fait une mauvaise manipulation) - docuements versionnés (on garde une trace de toutes les modifications) - facile et pratique pour le travail collaboratif :::warning :warning: Il est indispensable de bien comprendre la philosophie et le vocabulaire spécifique de Git pour utiliser Gitlab au quotidien. Dans le cas d'une utilisation basique, mono-utilisateur, vous verrez que seules quelques actions sont essentielles ::: - `clone` : rappatrier le dépôt - `commit` : enregistrer des modifications - `push` : envoyer les modifications au dépôt - `pull` : récupère les modifications faites sur le dépôt sur la version locale Enfin, ces outils proposent souvent une fonctionnalité pour pouvoir y déployer et rendre accessible sur le web des fichiers HTML. Elle s'appelle `Pages`. ## Gitlab Pages ![](https://i.imgur.com/3r517Qh.png =100x100) Gitlab Pages est un service pour générer des sites web statistique à partir de votre repository Git via les outils d'intégration continue de Gitlab. Pour les utilisateurs de la forge du département MathNum, l'url d'accès au site web sera en https://username.pages.mia.inra.fr/nom_projet ou https://groupe.pages.mia.inra.fr/nom_projet. ### Création d'un projet Pour créer un projet sur Gitlab, il suffit de cliquer sur le bouton <code>New project</code> et de rentrer les informations demandées. Je choisis ici de créer un projet nommé rmd-reports dans le projet `Gitlab pages`. ![](https://i.imgur.com/EYGZDT5.png) Ensuite il faut cloner le dépôt depuis l'adresse du projet, en local (ordinateur personnel par exemple). Cette adresse est indiquée lorsqu'on clique sur le bouton `Clone`. Les commandes suivantes sont à exécuter dans un terminal. ```bash= git clone git@forgemia.inra.fr:CATI-Boom/gitlab-pages/rmd-reports.git cd rmd-reports touch README.md git add README.md git commit -m "add README" git push -u origin master ``` Un fichier :page_facing_up: README (vide) a été ajouté au dépôt puis déployé grâce à la commande push. Ce fichier est visible depuis l'interface Gitlab : ![](https://i.imgur.com/9fxg82a.png) Il est possible de modifier les fichiers depuis l'interface. Par exemple, pour modifier le fichier README, il suffit de cliquer dessus et de clique sur le bouton Edit. ### Ajout du fichier .gitlab-ci.yml Ce fichier servira à déployer le site web à partir de ce dépôt. Voici un exemple basique qui va nous servir pour ce premier exemple: ```yaml= # This file is a template, and might need editing before it works on your project. pages: stage: deploy script: - mkdir .public - cp -r * .public - mv .public public artifacts: paths: - public only: - master ``` ![](https://i.imgur.com/tSUzmA6.png) De façon très simplifiée, ces lignes permettent d'activer le mode Pages et de déployer le contenu à chaque modification du dépôt. Dès qu'une modification est apportée, les commandes qui suivent l'instruction script sont exécutées, à savoir ici la création d'un répertoire `.public` :file_folder: et la copie de tout le dépôt dans ce répertoire. Enfin ce répertoire .public est renommé en public. C'est le contenu de ce répertoire qui sera accessible depuis la page gitlab. :::danger :bangbang: Pour les projets créés depuis l'été 2021, le nom de la branche master a été renommé en main ! Il faut donc modifier le fichier .gitlab-ci.yml en conséquence. ::: ### Organisation du dépôt Je crée un fichier Rmd que je nomme first.Rmd. Je le compile ensuite avec le bouton Knit pour générer le fichier html. Le bouton Git indique que les fichiers n'ont pas été ajoutés au dépôt. Il faut tous les sélectionner et les cocher. ![](https://i.imgur.com/h5vqFMW.png) Ensuite il faut appuyer sur le bouton Commit et indiquer un message expliquant les modifications effectuées puis sur le bouton Push. Les fichiers sont ajoutés au dépôt et visibles sur l'interface Gitlab. L'adresse de déploiement de la page peut être retrouvée sur la forge dans Settings / Pages. ![](https://i.imgur.com/mF18NYN.png) Ce lien <a href="https://cati-boom.pages.mia.inra.fr/gitlab-pages/rmd-reports/first.html">https://cati-boom.pages.mia.inra.fr/gitlab-pages/rmd-reports/first.html</a> est donc la nouvelle adresse du rapport ! On va faire le même travail avec un deuxième rapport appelé second.Rmd. Je colle un contenu trouvé sur le web. Je le compile et déploie les fichiers avec git. Il est possible de créer un fichier index.html qui permet de lister les rapports que vous souhaitez mettre à disposition. Bien sûr, pour ce faire, on crée le fichier .Rmd que l'on compile ensuite. Pour faire des liens en Rmd, il existe une syntaxe particulière : ![](https://i.imgur.com/S1TLSw9.png) Désormais, l'adresse <a href="https://cati-boom.pages.mia.inra.fr/gitlab-pages/rmd-reports/">https://cati-boom.pages.mia.inra.fr/gitlab-pages/rmd-reports/</a> vous permet d'accéder à tous les rapports que vous souhaitez mettre à disposition. # Distill ![](https://i.imgur.com/0r1HQbL.png) Je vous propose maintenant maintenant d'utiliser un package R : ==distill== [^distill] pour gérer vos rapports d'analyse. Distill est un package R qui permet de gérer une collection de rapports sous la forme d'un blog. La documentation est accessible ici : <a href="https://rstudio.github.io/distill/">https://rstudio.github.io/distill/</a>. Il est très pratique et facile d'utilisation. ## Installation L'installation est on ne peut plus simple. Il suffit d'installer le package distill dans la console de Rstudio. La version minimale de Rstudio pour pouvoir installer distill est RStudio v1.2.718. Pour installer une version plus récente de Rstudio, suivez ce lien : <a href="https://www.rstudio.com/products/rstudio/download/">https://www.rstudio.com/products/rstudio/download/</a>. Voici deux exemples de réalisation de blogs avec ce package : ![](https://i.imgur.com/xj0e4D5.png) <br> Pour installer le package distill, il suffit de taper cette instruction dans la console de Rstudio : ```r install.packages("distill") ``` Comme vu précédemment, j'ai créé un nouveau projet nommé `distill` ici : https://forgemia.inra.fr/CATI-Boom/gitlab-pages/distill. La page web associée est <a href="https://cati-boom.pages.mia.inra.fr/gitlab-pages/distill/">https://cati-boom.pages.mia.inra.fr/gitlab-pages/distill/</a>. ## Créer la structure du blog Voici comment créer le blog : * Je rapatrie ensuite le dépôt en local : ```bash git clone git@forgemia.inra.fr:CATI-Boom/gitlab-pages/distill.git Clonage dans 'distill'... warning: Vous semblez avoir cloné un dépôt vide. ``` Le warning est tout à fait normal. * Je tape ensuite dans la console Rstudio : ```r distill::create_blog(dir = "~/GIT/distill", title="My blog") ``` * J'ouvre le fichier `distill.Rproj` Une arborsecence de fichiers a été créée dans le répertoire distill. C'est le squelette de notre blog distill. ![](https://i.imgur.com/Cb1CmuT.png) * Pour visualiser le blog, il faut cliquer sur le bouton `Build website`. Le blog ne contient qu'un article. Il est stocké dans le répertoire `~/GIT/distill/_posts/welcome`. Il est écrit en R markdown et le fichier html se trouve à côté. ## Ajouter des images pour décrire les posts Il faut faire référence à une image que l'on place dans le répertoire du post auquel on veut ajouter une image descriptive. Par défaut, distill utilise la première image générée par un chunk (bloc de code) R. S'il n'y en a pas, ou si on veut changer celle par défaut, il faut ajouter une instruction `preview` dans les metadata du post et pointer vers l'image. ```yaml= title: "My first post with distill" description: | Glad to build my first blog. author: - name: Olivier Rué preview: preview.png date: 05-11-2020 output: distill::distill_article: self_contained: false ``` ## Paramétrer le contenu hors posts Les instructions suivantes permettent d'ajouter un onglet sur la page d'accueil du site. Ici, j'ajoute un onglet Contributors qui liste les collaborateurs du projet. La page d'accueil est construite à partir du fichier `_site.yml`. Les onglets doivent être listés dans la section `navbar`. Les informations à renseigner sont le texte du lien, et le fichier vers lequel il pointe. Le fichier `contributors.html` est construite à partir d'un fichier `contributors.Rmd`. Dans ce fichier, il est inutile de préciser le type de sortie, le package lui applique le formatage nécessaire pour être intégré au blog. ```yaml= name: "distill" title: "My blog" description: | My blog output_dir: "." navbar: right: - text: "Home" href: index.html - text: "About" href: about.html - text: "Contributors" href: contributors.html output: distill::distill_article ``` Les lignes 12 et 13 permettent de rajouter un lien vers le fichier `contributors.html`. ## Ajouter de la bibliographie à un post Pour ajouter une référence à un article (ou à un outil) qui possède une référence au format bibtex, il faut ajouter le tag `bibliography` dans les metadata du post et faire référence au fichier dans lequel la référence bibtex a été rajoutée. ```yaml= title: "My second report" description: | A short description of the post. author: - name: Olivier Rué url: https://example.com/norajones date: 05-12-2020 bibliography: biblio.bib output: distill::distill_article: self_contained: false ``` La ligne 8 permettent de faire référence dans le post aux entrées présentes dans le fichier `biblio.bib`. Pour y faire référence, il faut ajouter le titre de l'entrée bibtex précédé d'un `@`. Par exemple : ```yaml The work of Poirier et al @poirier2018deciphering, ... ``` ## Et encore plus... Retrouvez toutes les fonctionnalités sur <a href="https://rstudio.github.io/distill/">la documentation de distill</a>. # Conclusions :tada: Vous voilà armés pour : - publier sur le web vos rapports d'analyse - les organiser dans un dépôt centralisé - utiliser Distill pour créer un blog recensant tous vos rapports [^distill]: Allaire, et al. (2018, Sept. 10). Distill for R Markdown. Retrieved from https://rstudio.github.io/distill. [^rmarkdown]: Allaire, J., Cheng, J., Xie, Y., McPherson, J., Chang, W., Allen, J., ... & Arslan, R. (2018). Rmarkdown: Dynamic Documents for R. R package version, 1(11): https://rmarkdown.rstudio.com/. [^rstudio]: Allaire, J. (2012). RStudio: integrated development environment for R. Boston, MA, 537, 538.