20 décembre 2021

Ecrire avec RMarkdown

Principes

Markdown est un format d’écriture très simple et lisible.

Pandoc convertit les documents Markdown en LaTeX (à compiler en PDF), HTML, Word…

RMarkdown étend Markdown pour R et Bookdown étend RMarkdown.

knitR exécute le code R à l’intérieur des documents et appelle RMarkdown.

Document RMarkdown simple

Dans RStudio : File / New File / R Markdown

Syntaxe

Etudier le modèle :

  • En-tête YAML et premier bout de code ;

  • Formatage du texte ;

  • Bouts de code.

Anti-sèche.

Tricotage

  • Tester les 3 formats : HTML, PDF, Word.

PDF nécessite LaTeX.

Le même document peut être utilisé sous différents format sans réécriture.

Modèles

Des packages fournissent des modèles.

Modèles memoiR

Article simple : HTML pour un partage rapide, PDF simple.

Article stylé : PDF pour l’autoarchivage et HTML pour la lecture. Word possible.

Présentation : Beamer et HTML (utiliser ioslides).

Mémoire (Mémoire de master, Thèse, HDR, livre) : PDF et HTML.

Gallerie

Documentation dans les modèles.

Méthode de travail

Un projet R contient tout :

  • Modèle de document ; Fichiers nécessaire à la mise en forme (styles de texte, de bibliographie, …) ;

  • Données ; Code R pour produire les résultats, y compris les figures ;

  • Figures additionnelles.

Ce n’est pas un package :

  • Un package a une organisation formelle inutile pour un article.

Création du projet

Utiliser l’assistant New Project /New Directory / Document Project using memoiR.

Tricoter pour vérifier le fonctionnement.

Possibilité de tricoter en HTML pour gagner du temps.

Données

Placer les données dans le projet, dans un format lisible par R (typiquement, CSV).

Lire les données dans le préambule de l’article.

Calculs et figures

Placer les calculs dans des bouts de code dans la section Matériels et Méthodes.

Utiliser les options des bouts de code :

  • echo : affichage du code dans l’article (FALSE pour la publication) ;

  • cache : pour ne pas répéter les calculs à chaque compilation.

Les figures sont produites directement par le code :

  • insérer les bouts de code contenant les commandes plot dans la section Résultats.

Bibliographie

Utiliser sa bibliographie générale, produite par Zotero et Better Bibtex :

  • Pas de perte de temps pendant la rédaction ;

  • Exportation en temps réel de la bibliographie du projet.

Ou utiliser directement une bibliographie spécifique, dans un fichier bib autonome.

Voir la Documentation.

Séparer l’atelier et le magasin

Modèles sauf memoir :

  • Tricoter aux formats PDF et HTML.
  • Exécuter memoiR::build_githubpages().

Les fichiers produits (PDF, HTML, libs) sont déplacés dans /docs.

Le fichier /README.md est dupliqué dans /docs.

Modèle memoir : Build Book tricote tout dans /docs.

Collaboration

Passer le projet sous Git et le pousser sur GitHub.

Ajouter des collaborateurs.

Présentation

Activer les pages web du dépôt GitHub :

  • Settings, GitHub Pages :

    • Source = Master Branch / docs Folder

    • choisir un thème.

Présentation

Dans README.md, ajouter les liens vers les fichiers produits :

  • HTML pour la lecture en ligne ;

  • PDF pour le téléchargement.

Intégration continue

Objectifs

Sous-traiter à GitHub Actions (service en ligne) la construction des documents

Permet une mise à jour en continu, à chaque push.

Moyens

Entrer les secrets du projet : jeton Github et adresse de messagerie.

Créer le script : memoiR::build_ghworkflow()

Pages GitHub sur la branche gh-pages

Figures pour la publication

Principes

Produire des figures à utiliser hors des documents Markdown.

Continuité entre l’analyse de données et la production de figures.

Eviter les copier-coller : créer directement des fichiers pour contrôler les tailles relatives.

Si les données changent, les figures sont refaites par le script.

Exemple

plot(cars)