3.2 Exercices

Dans cette section nous poursuivons l’introduction à R Markdown entamée dans la section Exercices du module 2.

Rappelons les objectifs de cette introduction.

  • Décrire en quoi consiste R Markdown;
  • Décrire les liens entre R, Markdown et Pandoc;
  • Utiliser la syntaxe Pandoc Markdown de base;
  • Créer des documents dynamiques avec la bibliothèque rmarkdown.



Cette introduction à RMarkdown a été rédigée par Kevin Cazelles, collobateur clé à réalisation de ce cours. Kevin est un chercheur en écologie computationnelle et fervent utilisateur des outils pour la science ouverte. Allez voir ses travaux sur son site https://kevcaz.insileco.io/ et son profil GitHub https://github.com/KevCaz.


3.2.1 Le variante Pandoc de Markdown

Dans cette partie, nous détaillons les éléments de formatage du texte proposés par la syntaxe Pandoc de Markdown26


Informations de départ

De façon générale, nous écrivons du texte dans un fichier R Markdown de la même façon que nous le ferions dans un document Word. Nous pouvons, par exemple, écrire des accents français sans problème.

Les paragraphes

Pour créer des paragraphes, il faut ajouter une ligne (ou plus) vide entre les paragraphes. Ainsi, avec les lignes suivantes :

Un datum est un système de référence qui détermine la position 
d’un ellipsoïde sur la Terre : c’est-à-dire son origine par rapport 
au centre du globe, ainsi que son orientation. 

Les datums géocentriques sont associés à des ellipsoïdes 
globaux. Ce sont des systèmes de référence terrestres globaux 
dont l’origine correspond au centre de masse de la Terre.


nous obtenons :

Un datum est un système de référence qui détermine la position d’un ellipsoïde sur la Terre : c’est-à-dire son origine par rapport au centre du globe, ainsi que son orientation.

Les datums géocentriques sont associés à des ellipsoïdes globaux. Ce sont des systèmes de référence terrestres globaux dont l’origine correspond au centre de masse de la Terre.

Notez qu’avec un simple retour à la ligne, aucun saut de ligne n’est inséré. Les paragraphes sont alors affichés bout à bout. Par exemple, ce texte:

Un datum est un système de référence qui détermine la position 
d’un ellipsoïde sur la Terre : c’est-à-dire son origine par rapport 
au centre du globe, ainsi que son orientation. 
Les datums géocentriques sont associés à des ellipsoïdes 
globaux. Ce sont des systèmes de référence terrestres globaux 
dont l’origine correspond au centre de masse de la Terre.


s’affiche comme ceci:

Un datum est un système de référence qui détermine la position d’un ellipsoïde sur la Terre : c’est-à-dire son origine par rapport au centre du globe, ainsi que son orientation. Les datums géocentriques sont associés à des ellipsoïdes globaux. Ce sont des systèmes de référence terrestres globaux dont l’origine correspond au centre de masse de la Terre.

Il est cependant possible d’ajouter un retour à la ligne en utilisant un retour à la ligne et tabulation à la fin du premier paragraphe. Par exemple, ce texte:

Un datum est un système de référence qui détermine la position 
d’un ellipsoïde sur la Terre : c’est-à-dire son origine par rapport 
au centre du globe, ainsi que son orientation.          
Les datums géocentriques sont associés à des ellipsoïdes 
globaux. Ce sont des systèmes de référence terrestres globaux 
dont l’origine correspond au centre de masse de la Terre.


s’affiche comme ceci:

Un datum est un système de référence qui détermine la position d’un ellipsoïde sur la Terre : c’est-à-dire son origine par rapport au centre du globe, ainsi que son orientation.
Les datums géocentriques sont associés à des ellipsoïdes globaux. Ce sont des systèmes de référence terrestres globaux dont l’origine correspond au centre de masse de la Terre.

La seule différence entre cet exemple et l’exemple précédent est l’ajout d’une tabulation après “orientation.”.


Les symboles réservés

Certains symboles sont réservés au formatage du texte. Lorsque leur affichage est requis, c’est-à-dire lorsque nous désirons les utiliser dans notre texte, nous devons les faire précéder du caractère d’échappement qui est, pour Markdown, l’antislash : “\”.

Par exemple, nous devons entrer  :

\\ \& \# \$ \[


Pour obtenir :

\ & # $ [

Les commentaires

Pour rédiger des commentaires dans le texte qui ne seront pas affichés dans le document final, nous utilisons <!-- devant le commentaire et --> après celui-ci.


Décoration du texte

  • Pour écrire du texte en italique, vous avez deux possibilités :

      *le texte à mettre en italique*
  _le texte à mettre en italique_

  • Pour écrire du texte en gras, vous avez aussi deux possibilités :

      **le texte à mettre en gras**
  __le texte à mettre en gras__

  • Pour écrire du texte en gras et italique, utilisez :

      **le _texte en italique et en gras_**

  • Pour obtenir un texte rayé, entrez :

      ~~texte rayé~~

  • Pour écrire un élément en exposant, utilisez :

      ^texte en exposant^

  • Pour écrire un élément en indice, tapez :

      ~texte en indice~


Notez qu’il n’y a pas de balises pour le soulignement du texte. De manière générale, quand un élément de mise en page manque dans la syntaxe, il est toujours possible d’utiliser des commandes d’un langage. Par exemple, pour souligner dans un document qui sera produit en HTML, je peux utiliser <u>texte souligné</u> mais cela ne me permettra pas d’avoir un texte souligné en Word ou en PDF. De même que si j’utilise \underline{texte souligné} le texte sera souligné en PDF, mais pas en HTML ni en Word.

Procéder de la sorte n’est pas toujours souhaité car le document R Markdown perd en généralité, en ce sens où il ne pourra pas être correctement généré dans tous les formats. Cela n’est cependant pas nécessairement un problème, par exemple, si vous souhaiteZ obtenir le document en un seul format, ce fonctionnement devient un atout puisque vous pouvez utiliser toute la gamme de mise en forme offert par le langage en question.

Les titres

La façon la plus simple de désigner les titres dans un texte se fait par l’utilisation du symbole # (ATX heading). Un seul # désigne un titre de premier niveau, et nous utilisons un nombre croissant de # pour descendre dans l’arborescence des titres:

# Un titre d'ordre 1
## Un titre d'ordre 2
### Un titre d'ordre 3


Il est aussi possible d’utiliser une série de “=” en dessous des titres de premier niveau et une ligne de “-” en dessous des titres de niveau 2. Cette option a la qualité de permettre de repérer facilement les titres dans le code source.

Un titre d'ordre 1
==================
Un titre d'ordre 2
------------------
### Un titre d'ordre 3


Les listes

Les listes sont très intuitives en Markdown, alors qu’elles requièrent des balises un peu lourdes aussi bien en Latex qu’en HTML. Dans les exemples donnés, il faut toujours séparer le texte principal de la liste par des sauts de ligne.

Listes non numérotées

Pour obtenir une liste non numérotée, nous pouvons utiliser le symbole *  :

* objet 1,
* objet 2,
* objet 3.


ou bien le symbole +  :

+ objet 1,
+ objet 2,
+ objet 3.


ou encore le symbole -  :

- objet 1,
- objet 2,
- objet 3.


et même  :

+ objet 1,
* objet 2,
- objet 3.


Dans tous les cas, la liste produite s’affiche ainsi :

  • objet 1,
  • objet 2,
  • objet 3.


Listes espacées

Pour produire une liste plus aérée, nous pouvons ajouter un espace entre les éléments de la liste. Lorsque le document produit est en HTML, ce formatage produit une balise paragraphe (c’est-à-dire que <p> </p> est ajouté).

* objet 1,

* objet 2,

* objet 3.


devient:

  • objet 1,

  • objet 2,

  • objet 3.


Listes hiérarchisées

Pour créer des listes hiérarchisées, il s’agit d’utiliser une indentation de quatre espaces (ou une tabulation) entre chaque niveau. Par exemple, ceci:

- objet 1,
    + machin 1
        - chose 1
        - chose 2
    + machin 2
- objet 2,
- objet 3.


produit cette liste:

  • objet 1,
    • machin 1
      • chose 1
      • chose 2
    • machin 2
  • objet 2,
  • objet 3.


Listes avec du texte ou du code

Pour alterner des éléments d’une liste avec du texte ou du code, il faut utiliser des sauts de lignes avec l’indentation adéquate. Ainsi, avec les lignes suivantes :

- élément 1&nbsp;:

    Un petit texte qui pourrait expliciter ce qu'est l'élément 1.

- machin 2:

          for (i in 1:2) print(i)


nous obtenons :

  • élément 1 :

    Un petit texte qui pourrait expliciter ce qu’est l’élément 1.

  • machin 2:

    for (i in 1:2) print(i)


Listes numérotées

Pour créer une liste numérotée, il suffit de numéroter chaque élément de la liste. Par exemple:

1. machin 1,
2. machin 2,
3. machin 3.


produit ceci:

  1. machin 1,
  2. machin 2,
  3. machin 3.


Si les nombres ne sont pas écrits manière ordonnée, cela ne changera pas le résultat. Néanmoins, le premier nombre détermine le numéro de départ de la liste. En écrivant :

3. machin 1,
3. machin 2,
3. machin 3,
5. machin 4.


nous obtenons:

  1. machin 1,
  2. machin 2,
  3. machin 3,
  4. machin 4.


Pour ne pas se soucier des numéros, il existe un style par défaut :

#. machin 1,
#. machin 2,
#. machin 3.


Nous retrouvons bien la première liste numérotée :

  1. machin 1,
  2. machin 2,
  3. machin 3.


Plusieurs styles de numérotation sont disponibles. Par exemple, en écrivant :

 #) élément 1
 #) élément 2
 #) élément 3
 (1) truc 1
 (2) truc 2
 (5) truc 3
       i. machin 1
       i. machin 2
       i. machin 3


nous obtenons :

  1. élément 1
  2. élément 2
  3. élément 3
  1. truc 1
  2. truc 2
  3. truc 3
    1. machin 1
    2. machin 2
    3. machin 3


Nous avons aussi la possibilité de mélanger les niveaux numérotés et les niveaux non-numérotés. Par exemple, cette liste

1. machin 1,
    1. machin 1.1,
    2. machin 1.2,
2. machin 2,
    - machin 2.1,
    - machin 2.2,
    - machin 3,
3. machin 4,
4. machin 5.


donne ceci  :

  1. machin 1,
    1. machin 1.1,
    2. machin 1.2,
  2. machin 2,
    • machin 2.1,
    • machin 2.2,
  • machin 3,
  1. machin 4,
  2. machin 5.


Enfin, il possible de mettre manuellement fin à une liste en introduisant un commentaire entre les listes à séparer :

    (1) truc 1
    (2) truc 2
    (3) truc 2b

    <!-- end -->

    (1) truc 3
    (2) truc 4

ces lignes sont rendues ainsi :

  1. truc 1
  2. truc 2
  3. truc 2b
  1. truc 3
  2. truc 4


Blocs de citation

Pour utiliser un bloc de citation (la balise “blockquote” en HTML), il suffit d’utiliser “>” avant la citation. Ainsi les lignes suivantes :

> la citation est ajoutée comme ceci, elle nous donne une indentation adéquate
pour une mise en page agréable dont le style peut être facilement travailler
en HTML grâce au CSS.


deviennent :

La citation est ajoutée comme ceci, elle nous donne une indentation adéquate pour une mise en page agréable dont le style peut être facilement travailler en HTML grâce au CSS.

Pour créer une hiérarchie dans les citations, nous ajoutons des “>”  :

> La citation de départ
>
>> une hiérarchie dans la citation


ce qui donne :

La citation de départ

une hiérarchie dans la citation


3.2.2 Intégration de R dans le document

L’intérêt du package rmarkdown est d’étendre la syntaxe Pandoc Markdown avec les fonctionnalités du package knitr pour insérer non seulement du code R mais aussi les sorties associées (sorties console et figures). Nous obtenons ainsi un document dynamique en ce sens que si les données associées et/ou le code R changent, le document évolue aussi. Cela permet, entre autres, de créer des rapports automatisés.

Il y existe deux manières d’insérer des sorties R dans le document:

  1. directement dans le texte (“inline”);
  2. en utilisant un bloc de code dédié.

Pour inclure une sortie texte directement dans un paragraphe, nous utilisons  : `r expression`.

Par exemple, il est possible d’insérer l’heure et la date en utilisant la fonction R Sys.time(). Ainsi, l’utilisation de `r Sys.time()`  dans le texte affichera la sortie de cette fonction R, soit 2022-06-10 10:06:45.

Le reste de cette section se concentre sur les blocs de code R (appelés code chunks en anglais). Typiquement, l’utilisation d’un tel bloc de code ressemble à ceci :

```{r, idbloc, param1 = val1, param2 = val2}
ligne de code 1
ligne de code 2
...
ligne de code n
```


idbloc est le nom de l’identifiant que vous pouvez donner au bloc de code. Ceci permet de citer les blocs ou leurs sorties à l’intérieur du document. L’identifiant n’est pas obligatoire. En revanche, un identifiant donné ne peut être utilisé qu’une seule fois.

param1 = val1 correspond à un paramètre permettant de préciser comment le code source sera affiché dans le document, ou comment la sortie du code sera affichée. Il existe un grand nombre de paramètres possibles. Ils permettent de mettre de l’avant certaines parties du code, et aussi de choisir finement les sorties R (figures, tables, etc.) à ajouter aux documents. L’ensemble des paramètres sont disponibles à l’URL suivante https://yihui.org/knitr/options/).

Les commentaires

Les commentaires sont introduits, comme dans R, sous la forme de lignes de codes commençant par un #. Débutons avec un exemple simple qui inclut un commentaire et une addition :

```{r, addition}
# une addition avec R.
2+3
```


Notez que le terme “addition” qui suit “r” dans l’accolade est l’identifiant du morceau de code (la virgule entre les deux premiers éléments est facultative).

Ce morceau de code s’affiche ainsi:

# une addition avec R.
2+3
[1] 5


Nous obtenons donc code R dans un environnement adéquate (voir la coloration du code) avec la sortie console associée, en l’occurrence, le résultat de l’addition.

Modifier l’affichage du code source avec le paramètre echo

Prenons le bloc de code suivant.

``{r}
# une addition de variables avec R
a <- 2
b <- 3
a + b
<br>


```r
# une addition de variables avec R
a <- 2
b <- 3
a + b
[1] 5


Afin de ne pas afficher le code source dans un document (parce que nous souhaitement uniquement afficher la sortie produite par le code), il suffit d’utiliser le paramètre echo = FALSE, (echo = TRUE par défaut). Ainsi, le bloc de code sanscode

``{r sanscode, echo = FALSE}
# une addition de variables avec R
a <- 2
b <- 3
a + b
```


nous donne:

[1] 5


Le paramètre echo peut aussi être utilisé pour choisir les lignes à montrer. Pour cela, nous utilisons un vecteur indiquant les positions des lignes à montrer. Par exemple, pour montrer uniquement les lignes 1 et 4, nous utilisons:

``{r code14, echo = c(1, 4)}
# une addition de variables avec R
a <- 2
b <- 3
a + b
```


ce qui donne:

# une addition de variables avec R
a + b
[1] 5


3.2.3 À vous de jouer !

À venir

  1. Vous pouvez également consulter le site de référence de Pandoc et le résumé à la première page du guide de référence R Markdown. Pour une source en français, le guide “Élaboration et conversion de documents avec Markdown et Pandoc” (http://enacit1.epfl.ch/markdown-pandoc/) écrit par Jean-Daniel Bonjour fournit un excellent tour d’horizon.↩︎