---
title : Annexe de reproductibilité
author : François Févotte
date: avril 2020
options:
  css: skeleton_css.css
  template: julia_html.tpl
---

Ce document a été réalisé à l'occasion du [MOOC "Recherche
Reproductible"](https://www.fun-mooc.fr/courses/course-v1:inria+41016+self-paced/info). Il
accompagne l'[analyse de la concentration de CO2 dans l'atmosphère depuis
1958](exercice.html) et détaille les étapes nécessaires pour rejouer l'étude.

Un lecteur peut se contenter de lire le document généré par l'analyse, et
devrait y trouver les détails suffisants pour comprendre ce qui a été fait. Pour
les plus courageux, il est aussi possible d'aller plus loin en rejouant tous les
calculs de l'analyse ; ce document détaille comment.

Tous les fichiers nécessaires à l'analyse sont disponibles dans un dépôt git,
qu'il s'agira en premier lieu de récupérer localement. Les calculs ont été
développés en langage [Julia](http://julialang.org/) et s'appuie sur un
"environnement", c'est à dire un ensemble de paquets de l'écosystème Julia
implémentant diverses fonctionnalités d'analyse de données. La deuxième étape
consistera donc à installer ces divers composants logiciels. Dans la troisième
partie de ce document, nous verrons comment re-jouer l'analyse. Le lecteur
intéressé pourra alors re-jouer tous les calculs sur sa propre machine, voire
tester l'effet de ses propres modifications dans le document computationnel
[`exercice.jmd`](exercice.jmd). Ce processus peut être long et frustrant ; aussi
proposons nous dans une dernière partie une étape de compilation optionnelle que
le lecteur intéressé pourrait suivre afin d'améliorer les performances du rendu
de l'analyse, et ainsi rendre plus efficaces les cycles de modification / test
du document computationnel. Nous y donnons aussi quelques pointeurs vers la
documentation utile.


# Récupération des fichiers

## Via git

Tous les fichiers nécessaires pour la reproduction de l'[analyse de la concentration de CO2 dans l'atmosphère depuis
1958](exercice.html) sont stockés dans un dépôt git disponible à l'url suivante
:

[https://app-learninglab.inria.fr/moocrr/gitlab/3e6bf7b47a05a05ae3d6af86121dcb5d/mooc-rr.git]()

et qu'on pourra cloner à l'aide de la commande :

```sh
$ git clone https://app-learninglab.inria.fr/moocrr/gitlab/3e6bf7b47a05a05ae3d6af86121dcb5d/mooc-rr.git
```

Ceci permettra par la suite d'apporter des modifications à l'étude, et de les
reverser à travers une "Pull Request".


## Par téléchargement direct

S'il n'est pas envisagé de reverser d'éventuelles modifications apportées à
cette étude, il est aussi possible de télécharger directement les fichiers
depuis gitlab sous forme d'une archive au format zip ou tgz :

- [zip](https://app-learninglab.inria.fr/moocrr/gitlab/3e6bf7b47a05a05ae3d6af86121dcb5d/mooc-rr/-/archive/master/mooc-rr-master.zip)
- [tgz](https://app-learninglab.inria.fr/moocrr/gitlab/3e6bf7b47a05a05ae3d6af86121dcb5d/mooc-rr/-/archive/master/mooc-rr-master.tar.gz)


## Répertoire de l'étude

Au sein du dépôt git, les fichiers concernant l'analyse sont contenus dans le
répertoire `module3/exo3/`. Il est suggéré à partir de maintenant de consulter
le présent document (`module3/exo3/repro.html`) directement depuis votre
répertoire de travail local.


# Installation préalable

Les étapes listées dans cette partie n'ont vocation à être réalisées qu'une
seule fois, pour installer les logiciels requis sur votre machine.

## Julia

1. télécharger le langage Julia (version 1.4.0), dans sa variante appropriée en
   fonction de votre architecture matérielle et de votre système
   d'exploitation. Nous listons ci-dessous les liens directs vers le
   téléchargement pour les 3 OS majoritaires en architecture x86 à 64 bits, ce qui
   devrait couvrir la grande majorité des cas. Le dernier lien mène à la liste
   complète des variantes disponibles :
   - [Windows, 64-bit](https://julialang-s3.julialang.org/bin/winnt/x64/1.4/julia-1.4.0-win64.exe)
   - [macOS, 64-bit](https://julialang-s3.julialang.org/bin/mac/x64/1.4/julia-1.4.0-mac64.dmg)
   - [Linux, x86-64](https://julialang-s3.julialang.org/bin/linux/x64/1.4/julia-1.4.0-linux-x86_64.tar.gz)
   - [liste de toutes les variantes](https://julialang.org/downloads/)
   
2. suivre les [instructions
   spécifiques](https://julialang.org/downloads/platform/) selon votre système
   d'exploitation.
   
3. à l'issue de cette étape, vous devriez être en mesure d'ouvrir un terminal
   Julia :
   ![capture écran d'un terminal Julia](https://software.opensuse.org/images/thumbnails/julia.png)


## Environnement

L'ensemble des briques logicielles sur lesquelles s'appuie notre analyse
constitue un "environnement", décrit de manière succincte dans le fichier
[`Project.toml`](Project.toml) et plus détaillée dans le fichier
[`Manifest.toml`](Manifest.toml). Les paquets logiciels compris dans cet
environnement peuvent être installés en tapant les deux commandes suivantes dans
la console Julia :

```
julia> include(raw"C:\Users\francois\Desktop\mooc-rr\module3\exo3\Tools.jl")

julia> Tools.setup()
 Activating environment at `.../Project.toml`
[ Info: Installing required packages
    Cloning default registries into `~/.julia`
    Cloning registry from "https://github.com/JuliaRegistries/General.git"
      Added registry `General` to `~/.julia/registries/General`
  Installed Missings ───────────────────── v0.4.3
  Installed DataAPI ────────────────────── v1.1.0
...
[ Info: Precompiling dependencies (this might take a while)
Precompiling project...
363.818213 seconds (65 allocations: 2.656 KiB)
```

**Notes :**
- Dans la commande `include(raw("...Tools.jl"))`, n'oubliez pas d'adapter le
  chemin du fichier [`Tools.jl`](Tools.jl). Si vous êtes en train de visualiser
  ce document avec un navigateur web, vous pouvez par exemple récupérer ce
  chemin dans le lien ci-dessus à l'aide d'un simple "clic-droit > copier
  l'adresse du lien" (n'oubliez pas d'enlever le préfixe "`file://`" si vous
  faites cela !).

- Cette étape nécessite une connexion Internet afin de télécharger les paquets
  requis. Elle peut durer quelques minutes (et semble particulièrement longue
  sur les systèmes Windows où nous l'avons testée).

- Vous pouvez garder votre console Julia ouverte pour la ré-utiliser pour les
  prochaines étapes.


# Génération du document computationnel

Le document computationnel de l'étude est constitué par le fichier
[`exercice.jmd`](exercice.jmd), qui entremêle commentaires (en langage Markdown)
et code (en langage Julia).

Ce document computationnel peut être rendu au format HTML, pour générer la
sortie [`exercice.html`](exercice.html), dans laquelle le code julia a été
exécuté et les résultats produits sont visualisés. Tout ceci est pris en charge
par le paquet Julia [Weave](https://github.com/JunoLab/Weave.jl), qui fournit un
service similaire à [knitr](https://yihui.org/knitr/) pour le langage R ou
[Pweave](http://mpastell.com/pweave) pour Python.

Pour (re-)générer ce document HTML, les commandes suivantes doivent être entrées
dans la console Julia :

```
julia> include(raw"C:\Users\francois\Desktop\mooc-rr\module3\exo3\Tools.jl")

julia> Tools.weave()
 Activating environment at `.../Project.toml`
[ Info: Writing to file exercice.jl
[ Info: Weaving chunk 1 from line 39
[ Info: Weaving chunk 2 from line 67
[ Info: * Instantiating project
[ Info: Weaving chunk 3 from line 73
...
[ Info: Report weaved to exercice.html
 96.114542 seconds (65 allocations: 2.656 KiB)
```

**Notes :**
- Il est inutile de ré-exécuter la ligne `include(...)` si vous utilisez la même
  console que dans les étapes précédentes.
  
- Cette étape peut durer une minute ou deux ; nous verrons dans la prochaine
  partie comment accélérer ce processus si vous prévoyez de réaliser et tester
  des modifications dans le document computationnel.
  
- Vous pouvez garder votre console ouverte pour la ré-utiliser ultérieurement si
  nécessaire.
  
  
# Modification de l'étude

Vous pouvez tester dès maintenant vos idées en apportant des modifications au
fichier `exercice.jmd` et en re-générant son rendu HTML selon les instructions
de la partie précédente.

## (Optionnellement) compilation des paquets de l'environnement

La (re)-génération du rendu HTML prend pour l'instant quelques minutes, ce qui
rend les cycles modification/test assez longs et pénibles. Nous voyons dans
cette partie comment améliorer la productivité de ce genre de tests en compilant
les paquets Julia utilisés dans l'étude pour rendre leur utilisation plus
performante.

```
julia> include(raw"C:\Users\francois\Desktop\mooc-rr\module3\exo3\Tools.jl")

julia> Tools.compile()
 Activating environment at `~/mooc/mooc-rr/module3/exo3/Project.toml`
 Activating environment at `~/mooc/mooc-rr/module3/exo3/Project.toml`
[ Info: Writing to file exercice.jl
...
[ Info: PackageCompiler: creating system image object file, this might take a while...
410.437941 seconds (65 allocations: 2.641 KiB)
```

Prévoyez d'aller boire un café : cette étape peut durer une bonne dizaine de
minutes. A la fin, cette phase de compilation devrait avoir généré un nouveau
fichier `Exercice.so` dans le répertoire de l'étude. A partir de maintenant, le
processus de génération du rendu HTML devrait être accéléré de manière
substantielle, pour ne prendre que quelques secondes :

```
julia> Tools.weave()
[ Info: Using custom system image: Exercice.so
 Activating environment at `.../Project.toml`
[ Info: Writing to file exercice.jl
[ Info: Weaving chunk 1 from line 39
[ Info: Weaving chunk 2 from line 67
[ Info: * Instantiating project
[ Info: Weaving chunk 3 from line 73
...
[ Info: Report weaved to exercice.html
  7.262408 seconds (65 allocations: 2.656 KiB)
```

## Quelques pointeurs vers la documentation des outils utilisés

Tous les calculs présentés dans l'étude sont réalisés en langage Julia. On
pourra se référer au [manuel du langage Julia](https://docs.julialang.org/) afin
de trouver de la documentation générale sur le langage.

Le format utilisé pour le [document computationnel](exercice.jmd) est celui de
`Weave.jl`, dont la [documentation](http://weavejl.mpastell.com/stable/) est
disponible en ligne.
