Depuis le démarrage de notre voyage dans R pour le PMSI, je n’ai montré que des morceaux de codes à mettre dans un fichier source ou à taper directement dans la console. Mais il faut bien avouer que ça n’est pas très « joli », convivial ou adapté à la production à destination d’interlocuteurs (non le DIM n’est pas une bête étrange qui vit dans une grotte sans contact avec le monde extérieur).
Maintenant que nous avons vu les bases, la programmation, le requêtage relationnel et les graphiques, il nous est possible de synthétiser le tout pour faire de la présentation de résultats.
Pour cela R se base en priorité sur la génération de rapports sous forme de fichiers PDF, HTML statique ou Word, mais il est aussi possible de produire directement des présentations ou des sites dynamiques.
Nous allons commencer par les fichiers statiques qui sont produits en utilisant un autre langage servant à la description simple et conviviale de documents : (R)Markdown
(R)Markdown, qu’est-ce que c’est ?
Markdown est ce qu’on appelle un langage de balisage (léger). C’est à dire qu’en ajoutant des éléments signifiants spécifiques dans un document, il est possible de changer la signification sémantique d’un contenu qui sera ensuite interprété graphiquement dans le rendu final du document. RMarkdown n’est que l’adaptation à R de Markdown (et vice-versa).
Pour ceux qui ont déjà écrit du HTML ou du LaTeX, cela doit vous rappeler quelque chose car ce sont des langages de balisage sémantique (mais pas léger). Dans les faits, les documents RMarkdown que nous allons produire vont d’ailleurs être la plupart du temps transcrits dans un de ces deux langages intermédiaires afin de pouvoir être lu de façon agréable.
Par exemple, le bout de code Markdown :
# Début
Contenu
# Finsera interprété en HTML en :
<body>
<h1 id="début">Début</h1>
<p>Contenu</p>
<h1 id="fin">Fin</h1>
</body>Et en LaTeX :
\begin{document}
\section{Début}\label{duxe9but}
Contenu
\section{Fin}\label{fin}
\end{document}On voit donc bien que le Markdown est moins verbeux, plus convivial et plus simple à écrire directement par un humain. La magie de conversion dans un format présentable passe par un logiciel tiers totalement masqué par RStudio : Pandoc, nous ne nous y attarderons donc pas.
La structure d’un document (R)Markdown
Un document Markdown est obligatoirement composé d’un entête (au format YAML pour les techniciens) suivi du corps du document, lui-même composé d’éléments markdown entrelacés de portions de code exécutable.
L’entête
Le format YAML est lui-aussi un format assez simple, il est utilisé pour charger des données dans le moteur de traitement.
Il doit :
- commencer le fichier.
- Commencer et se terminer par 3 tirets (du 6 : « —« ) seuls sur une ligne
- Contenir en son sein des variables qui serviront tant au « compilateur » Markdown qu’aux morceaux de code en R, à raison d’une par ligne sous la forme de paires <identifiant>:<valeur>, une structuration hiérarchique est possible (comme dans
output:ci-dessous)
Par exemple :
---
title: "VIDHOSP"
author: "F. Senis"
date: "`r Sys.Date()`"
output:
html_document:
toc: true
toc_depth: 5
params:
basedir: "~/EXPORTS/2024/M03"
mode: "fichier"
format_attendu: 122
annee: 2023
mois: "1"
canal: "DEF"
cpostaux: "~/REFERENTIELS/2022/CodesPostaux.csv"
cpays: "~/REFERENTIELS/2022/CodesPays.csv"
---définit les variables title:, author:, date: (cette dernière étant le résultat d’un morceau de code R) qui vont servir dans la feuille de style qui servira à préparer la sortie, output: va servir à configurer le moteur de rendu et params: sera passé à R (et exclusivement ces valeurs !), permettant de limiter les paramètres variables du document à l’entête et évitant de devoir modifier des données dans le corps du RMarkdown.
Attention, params: peut être hiérarchique mais au prix d’acrobaties. Il faudra alors écrire ainsi :
params:
niveau1: "N1"
niveau2:
value:
niveau1 : "N21"
niveau2 : "N22"Se qui vous donnera une liste ainsi :
$niveau1
[1] "N1"
$niveau2
$niveau2$niveau1
[1] "N21"
$niveau2$niveau2
[1] "N22"
print(params$niveau1)
[1] "N1"
print(params$niveau2$niveau1)
[1] "N21"Une fois (bien) écrit, un RMarkdown ne devrait jamais avoir besoin d’être modifié en dehors de l’entête.
RStudio nous aide car lorsqu’on veut créer un fichier RMarkdown, un agent de préconfiguration s’ouvre :
Cela préconfigurera l’entête YAML minimal mais souvent suffisant pour commencer et rajoutera un corps d’exemple par défaut (sauf bien sûr si on clique sur « Create Empty Document » en bas à gauche) :
Le corps du fichier Markdown
Tout ce qui suit les « — » qui clôturent l’entête constitue le corps du fichier. Ce dernier sera lu dans l’ordre où il est écrit. Il se compose de parties « en clair », c’est à dire n’étant pas du code R, et de parties à exécuter.
Toute partie à exécuter doit être encadrée par un marqueur spécifique composé de 3 backticks ou accents graves (« ` (ALT Gr+7 sur un clavier PC)) en début de ligne :
---
<L'entête YAML>
---
Du langage Markdown pur ici
```{langage paramètres du bloc}
<le code ici>
```
A nouveau du Markdown iciRStudio représente par un fond coloré l’alternance des parties : par défaut, gris = code exécutable, blanc = code Markdown. Nous verrons la signification du contenu des accolades {} en début de bloc un autre jour.
Il est aussi possible de taper du code au sein même du markdown en l’encadrant par `r <le code>` (c’est à dire <backtick> r <code> <backtick>) dans ce cas, il n’y aura pas de saut de ligne.
Générer le fichier de sortie
Pour compiler du Markdown il faut impérativement sauvegarder le fichier et cliquer sur « Knit ». Après quelques instants le résultat apparait dans le panneau inférieur droit, dans l’onglet Viewer (qui est un mini navigateur HTML dédié) :
Cet exemple est la compilation du code se trouvant dans le chapitre en dessous.
L’appui sur le 3ème bouton du bandeau (
) permet d’ouvrir le document généré dans votre navigateur Web habituel.
En fait quand vous cliquez sur « Knit », votre fichier est compilé en plusieurs passes vers le format destination spécifié dans l’entête output:. Voici l’illustration pour les 2 principaux, mais les autres suivent le même modèle en se basant sur la puissance de Pandoc :
La production d’un autre format
Dans le paragraphe précédent, nous avons produit un fichier HTML. Mais dans l’introduction, je vous disais que l’on pouvait produire d’autre formats.
Pour produire du PDF, il suffit de de sélectionner dans le menu « Knit to PDF » :
Ce qui, après compilation, ouvre votre lecteur PDF par défaut avec le contenu généré :
Les utilisateurs de LaTeX ne seront pas étonnés de l’aspect. C’est typiquement un résultat d’une composition LaTeX, avec pas mal de réglages par défaut !
Idem pour Word avec « Knit to Word » :
ATTENTION, d’avoir cliqué sur « Knit to… » a modifié l’entête en rajoutant une entrée dans output:. Pensez à faire le ménage.
Saisie/édition manuelle des paramètres R
Notez « Knit with parameters… » dans le menu « Knit » qui permet d’éditer les valeurs de params: au moment de la compilation. Comme vous pouvez le voir cependant, les formats hiérarchiques ne sont pas éditables limitant la fonction. Pour ma part, je n’utilise jamais de params: hiérarchiques quitte a créer la structure hiérarchique en début du premier bloc à partir de données à plat de params:.
Le flux d’éléments du corps d’un fichier Markdown
Pour terminer ce premier article, nous allons écrire un markdown sans code R afin d’illustrer les bases et nous verrons les éléments dans les prochains articles
Un bloc se défini en sautant une ligne avant et une ligne après le contenu
Voici le code ayant généré la copie d’écran plus haut dans l’article
---
title: "Essai"
output: html_document
---
Ceci est un bloc de texte
# Ceci est un titre de niveau 1
Ceci est un autre bloc de texte
## Ceci est un sous-titre de niveau 2
Ceci est un bloc de texte
mais écrit sur 3 lignes qui
seront fusionnées lors de la compositionOn voit bien que les 3 dernières lignes de texte ont été fusionnées en un seul bloc.
Un saut de ligne sans changer de paragraphe se crée en terminant la ligne par au moins 2 espaces non significatifs.
Pas besoin de délayer outre mesure, tout est dans le titre.
Ainsi
Je suis un essai
sans espace
Je suis un essai
avec 2 espaces après le mot essai
Je suis un essai<br>
avec la balise explicite <br>
donne
Pour la balise <br>, ajoutée sur l’exemple 3 et qui semble fonctionner, attention ! Cela ne fonctionne que parce que la sortie est du HTML. Si vous générez vers du PDF ou du Word via LaTeX, elle sera simplement ignorée, de plus la deuxième occurrence est elle-aussi remplacée.
Conclusion
Voilà, vous venez de produire votre premier morceau de code Markdown totalement inutile, mais on va essayer de changer ça la prochaine fois en abordant les éléments de structuration de document, puis les éléments de contenu et enfin le code R proprement dit !