# Module 1 : Cahier de notes, cahier de laboratoire
## 0. Introduction
## 1. Nous utilisons tous des cahiers de notes
## 2. Un aperçu historique de la prise de notes
## 3. Du fichier texte au langage de balisage léger

Pense-bête du langage Markdown ([lien Wiki](https://fr.wikipedia.org/wiki/Markdown))

## 4. Pérennité et évolutivité des notes avec la gestion de version (Gitlab)
## 5. Les étiquettes et les logiciels d'indexation pour s'y retrouver


# Module 2 : La vitrine et l'envers du décor :  le document computationnel
## 0. Introduction :
__document computationnel__ = vitrine = la théorie  
__documents sous-jacents__ = envers du décor = la pratique

Un document computationnel est un document qui permet :
 - **d'améliorer la traçabilité d'un calcul**,
 - de **présenter** ses travaux,
 - d'accéder à **l'ensemble des calculs sous-jacents** d'une analyse.

Différents outils disponibles tels que: 
 - Jupyter (langage préférentiel Python)
 - RStudio (langage R)
 - OrgMode (pour les plus avertis)

## 1. Exemples récents d'études assez discutées

Dans une étude, la capacité à pouvoir inspecter les méthodes utilisées pour produire tel ou tel résultat est essentielle!  
Mais attention, 
 - la remise en question fait partie du processus scientifique
 - tout comme la rigueur et la **transparence**.

### Détails
 - Pour certaines études, les raisons pouvant empêcher, pendant plusieurs années, le débat sur la pertinence d’une étude sont :
1. la non-publication des procédures de calculs
2. la non-publication des données utilisées

En effet, c’est dans les procédures de calcul que se glissent des erreurs qui peuvent remettre en cause les conclusions.
C’est aussi dans les procédures de calcul que l’on trouve les détails des statistiques calculées et que l’on accède à plus d’information sur la puissance des tests utilisés.
La publication des données utilisées est également essentielle car c’est ce qui permet de vérifier leur pertinence ainsi que la façon dont elles sont traitées (en particulier l'exclusion).
D’autre part, il est parfois possible de trouver dans ces données des informations importantes à côté desquelles les auteurs seraient passés.

 - Les principales causes d'erreur peuvent être
     - l'acquisition des données (biais, calibrage de la machine, etc), 
     - les erreurs de calculs,
     - le traitement de données ou les statistiques inadaptées.

 - Les conséquences du manque de transparence sont : 
1. Il est difficile de s’appuyer sur le travail des autres.
2. Les articles contiennent moins d'information (pas de détails sur les calculs, protocoles expérimentaux, analyse de données, etc.) et sont donc plus faciles à lire.
3. Il est difficile de vérifier et de reproduire les analyses présentées dans les articles.
4. Deux articles peuvent présenter des résultats en contradiction apparente les uns avec les autres, tout en étant tous deux parfaitement corrects, le manque de détails empêchant de déterminer les conditions exactes d'application.

En effet, d’une part, certains travaux peuvent être faux et d’autres justes sans qu’on ait le moyen de vérifier précisément s’ils sont justes ou faux. 
D’autre part, si certains articles sont imprécis, il peuvent donner l’impression qu’un résultat est vrai dans un cadre plus général que ce qu’il est vraiment. 
Il est alors difficile de vérifier ce qu’il se passe “à l’intersection”.


## 2. Pourquoi est-ce difficile ?
### 2.1. Les raisons

Les raisons rendant un travail de recherche difficilement reproducible sont : 
1. Le manque d'informations: comment ont été obtenues les données ? quelles données ont été écartées ? quel protocole et pourquoi? quelle procédure statistique?
2. Les erreurs induites par l'utilisation des ordinateurs (rapidité, simplicité d'utilisation)
 - erreur point and click : erreur de manipulation
 - tableur : erreurs de programmation et de manipulation de données
 - utilisation de nombreux logiciels complexes
 - bug

**Il est donc important d'identifier la fiabilité de chacunes de ces briques.** Si l'un des composants par sa nature l'interdit, il faut songer à le remplacer pour le bien fondé de l'étude.

Mais *l'informatique est-elle seule responsable?*

### 2.2. Rigueur et organisation

Le manque de rigueur, technique et d'organisation : 
 - pas de backup
 - pas d'historique
 - pas de contrôle qualité

### 2.3. Dimension culturelle et sociale

**Article** = version **simplifiée** et intelligible d'une procédure (de résultats).
Cependant, la *technicité de la recherche* est telle, aujourd'hui, qu'il est impossible de tout décrire dans un article de 6 à 10 pages.
Les données sont souvent résumées en figure finale (multiples transformations et manipulations). Les statistiques pour obtenir ces courbes sont peu décrites.

Il est possible de **tracer** toutes ces informations et de les **rendre disponibles**, ce qui nécessite du temps et les bons outils.

### 2.4. Tout rendre public ? 

Risquée ? Rendre public ses faiblesses qui deviendraient évidentes ? 
Prendre le risque que quelqu'un trouve une erreur ? Retravaille mes données et publi? 

--> Mettre à disposition notre travail est le meilleur moyen pour corriger, améliorer, évoluer et démontrer la **propriété intellectuelle**.
En effet, expliciter augmente les chances de trouver les erreurs et de les éliminer = **TRANSPARENCE**.

Concernant les données sensibles (données cliniques), il existe des outils de *cryptographie*.

### 2.5. Outils à éviter et alternatives

Préferrer les logiciels libres (ancienne version accessible) --> meilleure chance de retrouver les données en cas de perte (backup et historique possibles).  
1. Utiliser des formats **textes simples et ouverts** --> possible de les ouvrir avec différents logiciels : **markdown, orgmode, csv** (pour les données).  
2. Utiliser les logiciels et langage de programmation **libres** : **R, python**.
3. Ne pas stocker les données sur un hébergeurs où les données peuvent être captives et où la confidentialité n'est pas rééllement respectée : **framadrop, gitlab/github**.
4. Eviter les outils "intuitifs" tels que tableurs --> mauvaise traçabilité. Préférrer **R, python**.

## 3. Le document computationnel : principe

L'objectif essentiel de ce document est de permettre la **transparence** la plus complète possible.  
La science moderne = majeur partie de la science derrière un ordinateur pour l'interprétation des données.  
La recherche reproducible consiste à réduire le fossé séparant l'auteur et le lecteur.

### 3.1. Objectifs méthodologiques
Avoir un outil permettant
 - d'inspecter : justifier/comprendre
 - de refaire : vérifier (par le lecteur si le calcul est correct)/corriger/réutiliser (refaire l'analyse le plus simplement possible)

### 3.2. La vitrine ...
= texte, ligne de calcul, figure, courbe, article classique au format html ou pdf = document final

### 3.3. l'envers du décor
document dynamique constitué de différentes parties avec lesquelles on peut interagir = zone de texte (markdown, expliquer les choix), zone de code (fragment code python par ex), zone de résultats des lignes de code = document initial  
Certaines zones peuvent être rendues non-visibles dans le fichier pdf final. Possible grâce à différents outils : Jupyter, RStudio, OrgMode.

**Principe indentique des outils**:
 - 1 seul document : explication, code, résultats
 - session
 - export  
** mais différences de syntaxe, d'inter-opérabilité des langages, le contrôle/configuration pour l'export. 

## 4. Prise en main avec l'outil
Faire le choix entre 3 outils différents :  
4.A Prise en main de l'outil Jupyter  
**4.B Prise en main de l'outil RStudio**  
4.C Prise en main de l'outil OrgMode  
RStudio = environnement de développement spécifique au langage R.  
1. Lancement
2. Exécution des blocs
3. Production et partage du document final

Qu’est-ce qu’un environnement comme Rstudio apporte par rapport à travailler dans la console R ou bien exécuter directement des scripts R ?  
 - Il permet d'avoir un historique bien structuré des analyses effectuées. 
 - Il permet d’inspecter les données, de garder une trace de cette inspection, et d’expliquer au fur et à mesure les transformations que l’on effectue.
 - Il sauvegarde les résultats intermédiaires, qu’ils soient textuels ou graphiques.
 - Il vous permet de générer des documents au format HTML, PDF ou .doc(x)/.odt.
 - Il permet de s’assurer que la figure obtenue est bien le résultat du calcul décrit dans le document.

Dans Rstudio, quelles sont les fonctionnalités fournies pour le langage R mais non disponibles pour le langage Python ?
 - La complétion sur les noms de variables
 - La non-persistance des variables et de leur état pour les codes Python
 - En python, seules les sorties texte sont gérées, pas les sorties graphiques

Qu’est-ce qui permet d’être efficace dans un environnement comme Rstudio ?
 - Les fonctions d’export et de réexécution du code depuis le début
 - La complétion
 - Apprendre les raccourcis claviers
 - Lire la documentation et les pense-bêtes

## 5. Travailler avec les autres
**Rpubs** = outils idéal pour partager de façon rapide mais non-pérenne tout comme Dropbox.  
**Gitlab/Github** = idéal pour partager de façon rapide et PERENNE mais partage de tous l'historique! si utilisation de cet outil, il faut archiver.  
Utilisation de **sites compagnons** comme HAL (article), Figshare/zenodo (figures et données). 

*De quoi aurez-vous besoin pour produire un document pdf:*  
En interne: pandoc, knitr ou emacs/org-mode.  
LaTeX devra aussi être installé  
Voici quelques billets intéressants sur le sujet:  
1. [ipython-notebook](http://blog.juliusschulz.de/blog/ultimate-ipython-notebook)
2. [github/hide_code](https://github.com/kirbs-/hide_code)
3. [markdown_manuscript](http://svmiller.com/blog/2016/02/svm-r-markdown-manuscript/)
4. [KleinbergsGridSimulator](https://github.com/balouf/Kleinberg/blob/master/KleinbergsGridSimulator.ipynb)

## 6. Analyse comparée des différents outils
### 6.1. Jupyter
 - Facile à prendre en main
 - Document dynamique
 - co-auteur (ligne de code modifiable et exécutable par tous)

### 6.2. RStudio
### 6.3. OrgMode
1. Pour un journal
 - Un seul auteur
 - Organisation chronologique
 - Etiquettes (recherche par étiquettes pour filtrer les entrées)
 - Notes, liens, code
2. Pour un cahier de laboratoire
 - Organisation sémantique
 - Conventions d'organisation
 - Plusieurs auteurs
 - Etiquettes pour auteurs, expériences ...
3. Pour un article reproducible
- Plusieurs auteurs
- Régénerer les figures
- Revenir aux sources

### 6.4. L'outil importe peu, ce qui importe c'est :
 - collecter l'information
 - organiser l'information et la rendre exploitable
 - la rendre disponible

**Pour la suite du MOOC, choix de RStudio**