4 Rédiger

R et RStudio offrent un environnement pour rédiger des rapports de recherche. Le package Rmarkdown (Allaire et al., 2021) intègre les fonctions pour ce faire. Plus, R et RStudio permettent de faire des articles, des livres (comme celui-ci), des sites, des applications, etc. Pour ce faire, ils intègrent différents langages de programmation. Cette section insiste sur la production de rapports de recherche simple. La philosophie étant, si Rmarkdown ne le fait pas, c’est superflu. Il demeure possible de personnaliser plusieurs éléments de ces textes, mais souvent cela sera inutile pour l’utilisateur débutant.

L’avantage principal de rédiger dans R est certainement le fait de tenir dans un projet, toute la syntaxe, le jeu de données, les graphiques ainsi que le texte rapportant le tout dans un seul fichier.

4.1 Préliminaires

Pour la toute première utilisation, il faut s’assurer est que le package Rmarkdown soit bien installé (voir Les packages). Il est préférable d’utiliser RStudio: l’environnement y est plus agréable et facilite l’expérience de l’utilisateur.

Une seconde étape, si l’utilisateur veut produire des pdf, est d’installer un éditeur $\LaTeX$. Cela peut se faire facilement avec la commande suivante.

tinytex::install_tinytex()

Il suffit de le faire une fois à la première utilisation ou pour d’éventuelles mises à jour. Maintenant, tout est prêt!

4.2 Ouvrir un document

Une fois tout installé, il faut faire File -> New File -> Rmarkdown pour ouvrir un nouveau document. La boîte de dialogue affichée à la Figure 4.1 demande quatre éléments : le titre, le nom de l’auteur, la date et le format du rapport (html, pdf ou word). Les deux premiers sont les plus utilisés. Une fois rempli, il faut cliquer sur OK.

Figure 4.1: Boîte de dialogue de Rmarkdown

Cette procédure ouvre un script d’extension .Rmd. Il s’agit d’un exemple typique qui rappelle des éléments de base pour produire un document. L’exemple est présenté à la Figure 4.2. C’est une bonne source pour se rappeler les lignes de la syntaxe Rmarkdown. Chaque élément est vu en détail dans la prochaines section.

Figure 4.2: Exemple de Rmarkdown

Il est possible de voir immédiatement le résultat final de ce script en cliquant sur Knit (tricoter) au milieu en haut (le symbole de pelote de laine avec une aiguille). À chaque fois que l’utilisateur désire produire le rapport, il faudra le tricoter en cliquant sur cet icône.

4.3 Les éléments importants

4.3.1 L’entête

L’entête est la zone qui conserve les éléments du texte, permet la personnalisation et l’ajout de composante, le cas échéant. Cet espace se nomme YAML pour Yet Another Markdown Language. Pour l’instant, les renseignements initiaux s’y retrouvent (titre, nom, date et format).

Figure 4.3: Entête ou YAML

4.3.2 Les niveaux de titre

Pour les titres de section, les # permette d’indiquer qu’il s’agit effectivement d’un titre et leur nombre permette d’indiquer leur niveau, comme # est de niveau 1, ## est de niveau 2, ### est le niveau 3, etc. Dans l’exemple, il y a deux titres de sections de niveau 2.

4.3.3 Les chunks

Comme le texte est rédiger dans R, il sera utile d’employer du code de ce langage dans le rapport. Ainsi, les rapports servent à jumeler, textes, analyses et graphiques. Pour déterminer le texte du code à lire, la syntaxe à rouler est inscrite dans un chunk (morceau en français). Les chunks sont délimités par trois accents graves (backticks en anglais), puis un accolade indiquant le langage utilisé dans le chunk (r en général), et se termine par trois autre accents grave. La Figure 4.4 montre un chunk.

Figure 4.4: Un chunk

Pour accélérer l’écriture au clavier, il est possible de faire Ctrl + Alt + I (pour Windows) ou Option + Cmd + I (pour Mac) pour ouvrir un chunk complet automatiquement. C’est beaucoup plus efficace que de le taper caractère par caractère.

Le code peut être présenté avec echo = TRUE (par défaut) ou caché echo = FALSE au besoin.

Le code est automatiquement exécuté. S’il y a un chunk, le code est roulé. Cela se modifie avec eval = TRUE (par défaut) pour exécuter le code ou ne pas exécuter le code echo = FALSE. Il va sans dire que s’il y a une erreur de code dans un chunk, R ne produira pas le rapport.

Ces arguments echo et eval doivent être spécifier dans les accolades du chunk. Il est possible de combiner les deux selon les besoins.

4.3.4 Les figures

Pour inclure une figure, il faut la programmer dans un chunk. Dans l’exemple, le graphique du jeu de pressure est présenté avec plot(pressure) dans un chunk, voir la Figure 4.5. Noter dans les accolades la présence de echo=FALSE qui, au moment de produire l’image, n’affichera pas le code source dans le document final (le chunk n’est pas rapporté). Seule la figure est affichée.

Figure 4.5: Ajouter une figure

Une autre option est utile pour les figure est de leur ajouter une légende (caption en anglais). Pour ce faire, il faut ajouter dans les accolades du chunk l’argument fig.cap = 'Légende de la figure'.

Un souci qui arrive à l’occasion est la taille des figures dans le document final. Il est possible de contrôler la taille avec les arguments out.height="50%" et out.width="50%" (en changeant le 50% par le pourcentage désiré) dans les accolades du chunk.

4.3.5 Les images externes

Pour ajouter une image, il est possible de l’ajouter simplement avec la syntaxe suivante dans un chunk. Comme les figures, il possible de leur donner une légende et de gérer leur taille.

knitr::include_graphics("chemin_vers_l_image/image.extension")

4.3.6 Les tableaux

Pour ajouter un tableau, il est possible de passer par la fonction kable() de knitr. Le premier argument est le tableau à présenter. Dans cet exemple, il s’agit des six premières lignes (avec la fonction head()) du jeu de données cars. Les autres options sont pour la présentation. L’argument caption = spécifie le titre, l’argument align = permet de centrer (avec "c") les éléments dans les cellules et booktabs = TRUE retire la majorité du grillage du tableau.

Il importe pour chaque tableau de s’assurer que la variable contient le data.frame ou la matrix disposé tel que l’utilisateur le souhaite (voir Concaténer pour créer ces objets).

knitr::kable(head(cars), 
             caption = "Titre du tableau", 
             align = "c", 
             booktabs = TRUE)

Table 4.1: Titre du tableau
speed	dist
4	2
4	10
7	4
7	22
8	16
9	10

4.3.7 Les équations

Il arrive qu’il soit nécessaire d’ajouter des équations dans un rapport. Pour ce faire, R utilise latex, un très puissant langage de programmation pour la rédaction de texte. Toute équation commence et termine avec le signe de dollars $. Par exemple, l’équation $2+2=4$ s’écrit $2+2=4$ . Il est possible d’ajouter des exposants avec ^ ou des indices avec _. Les lettres grecques s’écrivent avec une barre oblique, par exemple, $\beta$, s’écrit $\beta$ ou la variance $\sigma^2$, s’écrit $\sigma^2$ .

S’il faut utiliser les vrais symboles, par exemple $ et %, alors il faut ajouter un \ devant, comme \$ ou \%. Également, l’utilisation de la barre oblique devant un espace permet de créer un espace insécable.

4.3.8 Référer à des variables dans le texte

Pour référer à des variables de l’environnement du rapport, il est possible d’appeler ces valeurs des accents graves. Voici un exemple.

moyenne <- 10

Pour rapporter la nouvelle variable moyenne dans le texte, il faut écrire `r moyenne`, c’est-à-dire un accent grave, l’appel à r pour indiquer que la suite est du code R, le nom de la variable et un autre accent grave pour indiquer la fin. Ainsi, `r moyenne` retranscrit son contenu, soit 10.

4.3.9 Formater du texte

Plutôt que d’utiliser des onglets et des options pour modifier le texte, il faut utiliser la syntaxe Markdown (un langage de programmation de texte) pour altérer le texte. Ainsi, entourer un ou des mots avec une étoile de chaque côté met le texte en italique, comme ceci : *italique* donne italique; deux étoiles mettent en gras, **gras** donne gras, pour ajouter des éléments de code, il faut entourer le mot d’accent grave, `code` donne code. Pour souligner il faut passer par du latex pour les pdf, avec \underline{souligné}, ou par <u>souligné</u> en html, ce qui donne souligné.

4.3.10 Ajouter un hyperlien

Pour ajouter un hyperlien, il faut l’écrire entre crochet avec le préfixe http://, comme : <http://mqr.teluq.ca>, ce qui donne http://mqr.teluq.ca. Si l’utilisateur préfère cacher le lien sous un mot ou une phrase comme ceci : ce livre, il doit écrire : [ce livre](http://mqr.teluq.ca).

4.3.11 Les commentaires dans le texte

Un commentaire dans le texte permet de délimiter une section de texte qui ne sera par exécuté lorsque le texte sera rendu. Cela permet de retirer du texte ou du code qui n’est pas présentement utile tout en le conservant dans le fichier.

Pour commenter dans un fichier .Rmd, il faut entourer le texte de , comme ceci . Pour être plus efficace, plutôt que d’écrire tout au long, il est possible de sélectionner le texte puis Ctrl + Shift + C, ce qui commentera tout le texte sélectionné.

4.4 Pour aller plus loin

Cette section n’est qu’un survol des possibilités. Pour aller plus loin, il y a de la documentation sur le web pouvant aider à maîtriser la création d’équation, des spécifier sur la gestion des figures, ou les façons de formater les figures. Et comme c’est la communauté de R qui crée le contenu, il y a plus d’une bonne manière de faire la même chose.

3 Calculer

Exercices