# Annexe de reproductibilité

##### François Févotte

##### avril 2020

Ce document a été réalisé à l'occasion du MOOC "Recherche Reproductible". Il accompagne l'analyse de la concentration de CO2 dans l'atmosphère depuis 1958 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 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`. 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 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 :

    $ 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

- tgz

## 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

   - macOS, 64-bit

   - Linux, x86-64

   - liste de toutes les variantes

2. suivre les instructions spécifiques selon votre système d'exploitation.

3. à l'issue de cette étape, vous devriez être en mesure d'ouvrir un terminal Julia :

## 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` et plus détaillée dans le fichier `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`. 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`, 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`, 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, qui fournit un service similaire à knitr pour le langage R ou 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 afin de trouver de la documentation générale sur le langage.

Le format utilisé pour le document computationnel est celui de `Weave.jl`, dont la documentation est disponible en ligne.