TP4 - Document automatique

Chemin(s) de recherche des librairies

La commande .libPaths() permet de lister les différents répertoires dans lesquels R va pouvoir chercher les librairies. Si nous voulons en installer de nouvelles, et pouvoir les réutiliser plus tard, il faut donc spécifier un répertoire dans lequel nous avons les droits d’écriture.

Premièrement, il vous faut créer un répertoire dans votre "Z:/" qui contiendra les librairies R, par exemple nommé "Rlib", directement à la racine de votre "Z:/". Une fois celui-ci créé, vous pouvez indiquez à R qu’il doit aussi prendre en compte ce répertoire pour la recherche de librairies. Pour cela, vous devez exécuter la commande .libPaths("z:/Rlib"). Afin de vérfier que le répertoire a bien été ajouté, vous pouvez de nouveau lister les dossiers connus de R avec .libPaths(). Normalement, votre répertoire (ici "Z:/Rlib") doit être affiché en premier.

Voici donc les commandes à exécutées ici.

.libPaths()
.libPaths("z:/Rlib")
.libPaths()

Attention. Cet ajout du répertoire "Z:/Rlib" aux chemins connus de R, via la commande .libPaths(), devra être effectué à chaque nouvelle session (i.e. à chaque fois que vous relancez RStudio donc).

Installation d’une librairie

Une fois le répertoire ajouté, nous pouvons installer les librairies directement dans R avec la commande install.packages(), en y listant les librairies voulues. Nous allons utilsier ici la librairie rmarkdown. Vous devez donc executer la commande suivante.

install.packages("rmarkdown")

Quand vous l’exécuterez, vous verrez qu’il doit aussi installer d’autres librairies, appelées ici dépendances. Tout ceci est géré automatiquement par R sans que nous ayons à connaître la liste de ces dépendances.

Attention. L’installation d’une librairie n’est à faire qu’une seule fois.

Chargement d’une librairie

Une fois les librairies installées, il sera donc possible de les utiliser. Mais pour ceci, il faut tout d’abord les charger, à chaque session grâce à la fonction library(). Pour charger une librairie, il faudra donc exécuter un code de type :

library(rmarkdown)

Attention. Le chargement d’une librairie via library() devra être effectuée à chaque nouvelle session, pour les librairies dont vous avez besoin.

Titres

Il y a deux façons d’écrire des titres. La première avec des "#" en début de ligne, pour produire des titres de niveau 1 (<h1>) à 6 (<h6>).

# Titre de niveau 1

## Titre de niveau 2

...

###### Titre de niveau 6

L’autre ne concerne que les titres de niveau 1 et 2.

Titre de niveau 1
=================

Titre de niveau 2
-----------------

Paragraphes et divers

Les paragraphes s’écrivent simplement, sans notation particulière. Un passage à la ligne seule ne sera pas suffisant pour un changement de paragraphe, il est nécessaire de laisser (au moins) une ligne entre deux paragraphes.

Il est possible de mettre en avant des mots de deux façons :

• **mot(s) important(s)** : un ou plusieurs mots encadrés par des ** (ou des __) seront transformés en balise strong (souvent mis en gras)
• *mot(s) moins importants* : idem que précédement mais avec * (ou _), transformés en balise em (souvent mis en italique)

Pour faire un lien vers une page ou une URL, il est possible d’utiliser plusieurs syntaxes :

• <url> : lien mis directement (par exemple http://fxjollois.github.io)
• [texte](lien "texte optionnel") : lien mis sur un texte (par exemple ma page web)
• [texte][label] : lien mis sur un texte aussi, avec un pied de page ajouté plus tard avec [label]: url "texte optionnel" (par exemple page perso)

Pour intégrer des images dans un document markdown, on utilise un formalisme similaire aux liens, avec un !avant :

• ![texte](lien "texte optionnel") : le texte sert à contextualiser l’image

  

• ![texte][label] : on définit le label par la suite avec [label]: lien "texte optionnel"

  

  re bla

On peut aussi ajouter des lignes horizontales, pour découper le texte. Pour cela, il est nécessaire d’écrire une ligne avec

• soit au moins 3 caractères identiques ("*" ou "-")
• soit 3 caractères identiques (toujours "*" ou "-") séparés d’un espace.

Voici les quatre façons de faire donc, qui produiront le même résultat :

***
---
* * *
- - -

Et un exemple de séparation

On peut aussi créer des blocs de citations (équivalent à la balise blockquote), en commençant les lignes par ">".

Voici un exemple de bloc de citation, permettant de mettre en avant des éléments importants.

Listes

Il est possible de créer deux types de listes (non-ordonnées et ordonnées). Il faut noter cependant que les listes doivent être séparées des paragraphes par (au moins) une ligne au-dessus et en-dessous. De plus, pour les sous-listes, il faut mettre une tabulation (ou deux si sous-sous-liste, et ainsi de suite).

Il est bien évidemment totalement possible de mélanger les deux types de listes si besoin.

Tableaux

On peut définir un tableau directement, en précisant d’abord le nom des colonnes (séparés par "|"). Il faut ensuite faire une séparation via une ligne avec "---" (au moins) pour chaque colonne et toujours des séparations ("|") entre les colonnes. Ensuite, les valeurs de chaque ligne doivent être toujours séparées par des "|".

Le style de chaque colonne (aligné à gauche - par défaut, aligné à droite ou centré) peut être indiqué dans la ligne de séparation entre les noms de colonnes et les valeurs, avec

• --- (ou :--) : aligné à gauche
• --: : aligné à droite
• :-: : centré

Voici un exemple de tableau, dans lequel nous avons défini le style de chaque colonne

Codes

L’intérêt de ce langage est aussi de pouvoir intégrer des éléments de code (soit des blocs complets, soit des éléments en ligne), permettant de présenter le travail fait.

# premier code quelconque
d = read.table("d")
summary(d)

# deuxième code quelconque
dd = subset(d, var1 == valeur)
summary(dd)

En-tête

Lors de la création d’un nouveau document R markdown, vous devez voir apparaître en début de document une partie d’en-tête, comme ci-dessous, au format YAML.

---
title: "Untitled"
author: "FX Jollois"
date: "17/10/2016"
output: html_document
---

Dans cette en-tête, nous pouvons donc définir le titre, éventuellement un sous-titre (avec subtitle:), le ou les auteurs, la date et des options de sortie. Pour le moment, nous allons garder la sortie au format HTML. Pour passer au format PDF, il faut écrire pdf_document dans output (ainsi qu’avoir \(\LaTeX\) installé sur sa machine - ce qui n’est pas le cas à l’IUT). Pour créer un document de type Word, il faut choisir word_document pour output.

Il y a d’autres possibilités de sortie, ainsi que la possibilité d’ajouter d’autres paramètres de sortie, que nous ne verrons pas ici.

Chunck

Un chunck sera donc un bloc de commande R (ou autre langage possible) qui sera exécuté par R Studio. Pour cela, il faut indiquer sur la première ligne le langage utilisé. Pour R, voici donc un exemple simple

```{r}
# code R
summary(iris)
```

Dans le document sera donc intégré à la fois le code, ainsi que le résultat de son exécution. L’exemple donnera donc

# code R
aggregate(. ~ Species, iris, mean)

##      Species Sepal.Length Sepal.Width Petal.Length Petal.Width
## 1     setosa        5.006       3.428        1.462       0.246
## 2 versicolor        5.936       2.770        4.260       1.326
## 3  virginica        6.588       2.974        5.552       2.026

Il est possible de nommer le chunck en lui donnant un label (sans espace, sans accent) après r dans les {}. Ceci est intéressant surtout dans l’étape de développement, car si une erreur arrive lors de l’exécution, il sera plus facile de retrouver dans quel chunck est l’erreur (indiqué lors de l’affichage de l’erreur).

De plus, il est possible de mettre des options dans le chunck, toujours dans les {}, après une ",". Voici quelques options classiques et utiles (avec leur valeur par défaut indiquée, si elle existe) :

• include = TRUE : si FALSE, le code est exécuté mais il n’est pas inclus dans le document (ni le code, ni son résultat)
• echo = TRUE : si FALSE, le code n’est pas affiché mais bien exécuté
• eval = TRUE : si FALSE, le code est affiché mais n’est pas exécuté
• results = 'markup' : permet de définir comment le résultat est affiché (intéressant pour les tableaux, cf plus loin)
• fig.cap : titre du graphique produit

Il est possible de mettre plusieurs options, toutes séparées par des ",".

Quelques exemples

Dans la suite, voici quelques exemples de chuncks avec options. Regardez le source pour mieux comprendre le fonctionnement.

Tout d’abord, on importe les données heart.txt, mais ce genre de code n’est souvent pas à inclure, dans le sens où l’on ne veut ni l’afficher, ni voir de résultat.

Ensuite, la librairie knitr contient une fonction kable() permettant d’afficher un data.frame au format markdown. Cela permet d’avoir un résultat plus lisible qu’une sortie de console R classique.

knitr::kable(head(heart))

age	sexe	type_douleur	pression	cholester	sucre	electro	taux_max	angine	depression	pic	vaisseau	coeur
70	masculin	D	130	322	A	C	109	non	2.4	2	D	presence
67	feminin	C	115	564	A	C	160	non	1.6	2	A	absence
57	masculin	B	124	261	A	A	141	non	0.3	1	A	presence
64	masculin	D	128	263	A	A	105	oui	0.2	2	B	absence
74	feminin	B	120	269	A	C	121	oui	0.2	1	B	absence
65	masculin	D	120	177	A	A	140	non	0.4	1	A	absence

Enfin, on peut vouloir faire un graphique, ce qui pourrait donner ce qui suit. Pour ce genre de présentation, nous pouvons décider de ne pas afficher le code permettant de les obtenir.

Répartition du sexe des individus selon le problème cardiaque

Inline chunck

On peut faire des chuncks en ligne en encadrant le code avec des ` et en commencant le code par un r. Par exemple, on peut dire que dans le jeu de données heart sont présentés 270 individus et 13 variables.

Paramètres globaux des chuncks

Il est possible de déterminer des paramètres globaux pour tous les blocs chuncks du document (sauf paramètres locaux précisés). Ceci doit se faire comme suit, avec la fonction set() de l’objet opts_chunck de la librairie knitr. Il est par exemple possible de définir echo=FALSE pour n’avoir aucun code apparaissant dans le document.

knitr::opts_chunk$set(...)