Document computationnel avec R
Pour le partage et la reproductibilité de ses analyses
Séance ElementR - Octobre 2023
Quelques lignes de code…
library(ggplot2)
ggplot(data = iris,
aes(x = cut(Sepal.Length, breaks = c(min(Sepal.Length), 5, 6, 7, max(Sepal.Length)),
include.lowest = TRUE, labels = c("Bas","Bas+","Haut","Haut+")))) +
geom_bar() + xlab("") + ylab("") + ggtitle("Répartition par classe") +
theme(plot.title = element_text(size=27), axis.text=element_text(size=19))
…En programmation lettrée
#-----------------------------------------------------------------
# Représentation graphique
# de la répartition d'individus
# discrétisés en quatre classes
#
# H. Pecout
# 3 Octobre 2023
#-----------------------------------------------------------------
# Discrétisation la variable Sepal.Length (données iris)
## Statistiques sur la série statistique 'Sepal.Length'
summary(iris$Sepal.Length)
## Histogramme de la distribution
hist(iris$Sepal.Length)
## Choix des bornes de classes (amplitude égale)
bornes_des_classes <- c(min(iris$Sepal.Length), 5, 6, 7,
max(iris$Sepal.Length))
## Choix des noms de classes
nom_des_classes <- c("Trés petites","petites","grandes","Très grandes")
## Discrétisation de la variable 'Sepal.length'
iris$classe <- cut(iris$Sepal.Length,
breaks = bornes_des_classes,
labels = nom_des_classes,
include.lowest = TRUE)
#---------------------------------------------------------------------
# Représentation de la distribution selon la discrétisation
## Bibliothèque pour la représentation graphique
library(ggplot2)
## Représentation graphique de la distribution
ggplot(data = iris, aes(x = classe)) + # Choix des données et de la variable à représenter
geom_bar() + # Choix du type de représentation
xlab("") + # Suppression du nom de l'axe x
ylab("") + # Suppression du nom de l'axe y
ggtitle("Répartition par classe") + # Titre du graphique
theme(plot.title = element_text(size=27), # Taille de la police titre
axis.text=element_text(size=19)) # Taille des labels d'axeIl est possible de faire de la programmation lettrée dans n’importe quel type de document…
Mais le document computionnel est l’environnement parfait pour mettre en oeuvre ce paradigme.
Un document computationnel permet de combiner du langage naturel et du langage de programmation :
La programmation lettrée et les documents computionnels sont apparus à la même période, celle de l’émergence du concept de recherche reproductible !
Les premiers notebooks
Émergence de la recherche reproductible
Jon Claerbout est l’un des premiers chercheur à exprimer le fait que les méthodes de calcul menacent la reproductibilité de la recherche si l’on ne donne pas un accès libre aux données et aux logiciels qui sous-tendent.
En 1976, il publie un ouvrage référence en traitement de signal :
« Fundamentals of Geophysical Data Processing »
Cette 1ère version - non-reproductible - sera le début d’un long travail de recherche sur la reproductibilité… Via des notebooks !
Émergence du Literate Programming
Le concept de programmation lettrée est pensé et conçu par Donald Knuth (1977-78). Le notebook se présente comme un outil idéal pour mettre en œuvre ce paradigme.
La mise en forme du texte se fait à l’aide d’un langage de balisage (Markdown, html…)
!
Un fichier texte (.rmd, .qmd, .ipynb…)
Résultat en sortie :
File > New File > R Markdown...
Pandoc est généralement pré-installé sur les systèmes d’exploitation MACOS et Windows.
Si vous n’avez pas \(\LaTeX\) d’installé, utilisez le package tinytex pour la compilation en pdf.
chunk, positionnez le curseur dans le document puis cliquez sur :
rmdformats.
readthedown.File > New File > R Markdown > From Template...
→
?Quarto est un nouveau système open-source de publication d’articles scientifiques et techniques basé sur Pandoc. C’est un outil orienté LP, plus moderne que le Rmarkdown et facilement adaptable à différents cadres d’utilisations.
Il permet d’exploiter différents langages de programmation tels que R, Python, Julia ou JavaScript.
Quarto unifie et étend les fonctionnalités offertes par les différents notebooks existant, plus particulièrement les extensions Rmarkdown.
Quarto est développé par Posit™️ (Rstudio). Cependant, le périmètre d’utilisation de ce système s’étend au delà de la communauté R.
Quarto peut être installé et utilisé de différentes manières :
En tant que logiciel et utilisable en ligne de commande depuis le terminal.
Avec RStudio (directement intégré)
Dans Visual studio code (extension)
Au délà de proposer un système performant et complet pour la production de documentations scientifiques et techniques, Quarto tente également de rendre la pratique des documents computationnels plus accessible.
Rmarkdown restera à moyen terme supporté par Posit™ (Rstudio), mais les efforts de développement seront concentrées sur Quarto. Cela risque de se répercuter sur la communauté des utilisateurs : le développement et la maintenance d’extensions Rmardkown devraient ralentir.
Pas de panique : la conversion ou la migration vers quarto est simple !
Quarto propose directement 4 types de publications possibles :
À ce jour, peu de modèles de mise en page et d’extensions ont été développés. Néanmoins,le système Quarto propose directement toutes les fonctionnalités suffisantes pour créer un document scientifique de qualité (ex: équations, citations, références croisées, table des matière, des figures, note de bas de page, mise en page avancée, et même de l’interactivité pour les diaporama).
id name region pop gdp gdppc year
1 AFG Afghanistan Asia 38928341 19807067268 508.81 2020
2 AGO Angola Africa 32866268 62306913444 1895.77 2020
3 ALB Albania Europe 2837743 14799615097 5215.28 2020
4 AND Andorra Europe 77146 3155065488 40897.33 2019
5 ARE United Arab Emirates Asia 9770526 421142267937 43103.34 2019
6 ARG Argentina America 45376763 383066977654 8441.92 2020Syntaxe markdown pour la création de tabset :
::: panel-tabset
## Julia
{width=30%}
## Python
{width=30%}
## R
{width=30%}
## observable
:::
Rendu graphique :
menu: TRUE - whiteboard: TRUE - chalkboard: TRUE
Pointer
Quarto est directement integré dans les dernière version de Rstudio.
Pour installer la dernière version de Rstudio : https://posit.co/download/rstudio-desktop/
Exemple 1 : Créer un Quarto Document ou une Quarto présentation : File > New File > Quarto...
Avertissement
Un Quarto document ou présentation = Un seul fichier .qmd
Exemple 2 : Créer un Quarto wesite ou Quarto Book : File > New Project > New Directory > ...
Avertissement
Un Quarto book ou website = Plusieurs fichiers .qmd. Un fichier par chapitre ou page du site.
= 
Il est possible d’utiliser jupyter pour la compilation.
A. Créez un nouveau projet Quarto book. File > New Project > New Directory > Quarto Book...
Compilez-le en HTML : Render Book
C. Ajoutez un nouveau chapitre
Votre document compilé en HTML devrait ressembler à cela :
D. Ajouter du contenu (https://quarto.org/docs/authoring/markdown-basics.html)
Quelques exemples :
Titre & liste
# Ma partie 1
## Introduction
Cette partie de ma thèse est sans doute la meilleure car :
- **Ma directrice le pense**
- Elle n'est **pas encore rédigée**Cette partie de ma thèse est sans doute la meilleure car :
Citation & note de bas de page
## Citation
> *L'histoire n'est que la géographie dans le temps, comme la géographie n'est que l'histoire dans l'espace.*
>
> Elisée Reclus
## Note de bas de page
L'ontologie[^1] est une branche de la philosophie et plus spécifiquement de la métaphysique qui, dans son sens le plus général, s'interroge sur la signification du mot « être ».
[^1]: Perso, je n'ai jamais comprisL’Histoire n’est que la Géographie dans le temps, comme la géographie n’est que l’histoire dans l’espace.
Elisée Reclus
L’ontologie1 est une branche de la philosophie et plus spécifiquement de la métaphysique qui, dans son sens le plus général, s’interroge sur la signification du mot « être ».
Tableau en markdown
## Tableau en markdown
| Variable | Avignon | Lorient | calais |
|:----------:|:----------:|:---------:|:--------:|
| Pop | 90 597 | 57 412 | 67 544 |
| sup | 64,78 | 17,48 | 33,5 || Variable | Avignon | Lorient | calais |
|---|---|---|---|
| Pop | 90 597 | 57 412 | 67 544 |
| sup | 64,78 | 17,48 | 33,5 |
Équation mathématique
## Equation mathématique (LaTeX)
$$x_{1,2} = \frac{- b \pm \sqrt{\Delta}}{2a}$$\[x_{1,2} = \frac{- b \pm \sqrt{\Delta}}{2a}\]
Diagramme
```{mermaid}
flowchart LR
A[État de l art] --> B(Terrains)
B --> C{Analyses}
C --> D[Communications]
C --> E[Rédaction de la thèse]
```flowchart LR
A[État de l art] --> B(Terrains)
B --> C{Analyses}
C --> D[Communications]
C --> E[Rédaction de la thèse]
Image
## Inclure une image
{width="20%"}
Vidéo
## Inclure une vidéo 
Bloc de code & inline code
Pour inclure le contenu d’un objet R directement dans une zone de texte : 
Référence bibliographique
La référence bibliographique doit être renseignée dans un fichier.bib (ex : cf. le fichier reference.bib à la racine du répertoire). Plus de détail sur cette page.
Il est très simple de faire référence à de la bibliographie en markdown. Ex : [@bertin1967]Il est très simple de faire référence à de la bibliographie en markdown. Ex : (Bertin 1967)
Note, warning…
:::{.callout-warning}
## Précautions d'usages
Bla bla bla bla
:::
:::{.callout-note}
## Ceci est une note
Bla bla bla bla
:::
:::{.callout-important}
## Ceci est important
Bla bla bla bla
:::Précautions d’usages
Bla bla bla bla
Ceci est une note
Bla bla bla bla
Ceci est important
Bla bla bla bla
Markdown avancé (div)
::: {.panel-tabset}
## Doctorant·es
## Maître·sse de conférence
## Professeur·e
:::
Votre document prend forme :
Télécharger un exemple complet de chapitre (.qmd) mis en forme : ici
Git, GitLab & GitHub…
Git est un système de gestion de version distribué pour :
Notebook Quarto - Revealjs presentations
Code source sur GitLab Huma-Num : https://gitlab.huma-num.fr/elementr/session_notebook/programmation_lettree
Page GitLab déployée : https://elementr.gitpages.huma-num.fr/session_notebook/programmation_lettree/#/title-slide
Informations session
R version 4.3.1 (2023-06-16 ucrt)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 11 x64 (build 22621)
Matrix products: default
locale:
[1] LC_COLLATE=French_France.utf8 LC_CTYPE=French_France.utf8
[3] LC_MONETARY=French_France.utf8 LC_NUMERIC=C
[5] LC_TIME=French_France.utf8
time zone: Europe/Paris
tzcode source: internal
attached base packages:
[1] stats graphics grDevices utils datasets methods base
other attached packages:
[1] leaflet_2.1.2 geojsonsf_2.0.3 sf_1.0-13 ggplot2_3.4.2
loaded via a namespace (and not attached):
[1] gtable_0.3.3 jsonlite_1.8.7 dplyr_1.1.2
[4] compiler_4.3.1 tidyselect_1.2.0 Rcpp_1.0.11
[7] scales_1.2.1 yaml_2.3.7 fastmap_1.1.1
[10] R6_2.5.1 labeling_0.4.2 generics_0.1.3
[13] classInt_0.4-9 knitr_1.43 htmlwidgets_1.6.2
[16] tibble_3.2.1 leaflet.providers_1.9.0 units_0.8-2
[19] munsell_0.5.0 DBI_1.1.3 pillar_1.9.0
[22] rlang_1.1.1 utf8_1.2.3 xfun_0.39
[25] cli_3.6.1 withr_2.5.0 magrittr_2.0.3
[28] crosstalk_1.2.0 class_7.3-22 digest_0.6.32
[31] grid_4.3.1 rstudioapi_0.14 lifecycle_1.0.3
[34] vctrs_0.6.3 KernSmooth_2.23-21 proxy_0.4-27
[37] evaluate_0.21 glue_1.6.2 farver_2.1.1
[40] fansi_1.0.4 e1071_1.7-13 colorspace_2.1-0
[43] rmarkdown_2.23 ellipsis_0.3.2 tools_4.3.1
[46] pkgconfig_2.0.3 htmltools_0.5.5 Licence Etalab
