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

:27-04-2020:
# Module 3 : La main à la pâte : une analyse réplicable
## 1. Une analyse réplicable, c'est quoi ?
Dans le cadre d'une *analyse traditionnelle* on se concentre sur les résultats et on montre un résumé méthodologique
des calculs et discussion des conclusions. 

Concernant, l'*analyse réplicable* = 4 blocs = résultats + discussion mais aussi code + explication (des calculs menés)  
Pourquoi? facilité la reproduction de cette analyse, facile à modifier, facile à inspecter et vérifier!

## 2. Etude de cas : l'incidence de syndromes grippaux 
Jeu de données [Réseau Sentinelles](http://www.sentiweb.fr) Inserm, UPMC  
Présentation du jeu de données : 
 - 2ème ligne présente les étiquettes des colonnes de données
 - 1ère colonne = année et semaine en format iso (= l'année commence par la semaine qui contient le 4 janvier)
 - 3ème colonne = données d'intérêt = *incidence des syndromes grippaux*
 - anomalie dans le jeu de données ? ex: absence de données pour la semaine 19 de l'année 1989 (198919)
      - dans notre cas, peu d'importance car ce n'est qu'une semaine sur une suite de longues années --> point à supprimer
      - ATTENTION pour la suppression de ce point : ne pas le supprimer directement sur les raw data du jeu de données car PAS REPLICABLE

### A RETENIR
 - Aucune modification des données ne doit être faîtes "à la main" car sinon aucune trace visible de l'intervention
 - Tout doit se faire dans du code

### NB 
Le site Web du Réseau Sentinelles que nous utilisons dans ce module a subi des modifications importantes après le tournage des vidéos.
L'accès aux données ne se passe plus comme montré. Il faut passer par les menus "Surveillance continue" - "Base de données" - "Accès aux données" et cliquer sur l'onglet "Télécharger", 
puis choisir les données au format *CSV* pour la France Métropolitaine. 
Le format des données téléchargées a aussi légèrement changé, il faut adapter le traitement des données manquantes. Le code que nous montrons dans les vidéos ne fonctionne plus avec 
les données d'aujourd'hui. Une version mise à jour est disponible [ici](https://www.fun-mooc.fr/courses/course-v1:inria+41016+self-paced/courseware/5b932aa591d245d48d8943385cb3120a/bd37d027f9e54180b7657296967d3ef9/1?activate_block_id=block-v1%3Ainria%2B41016%2Bself-paced%2Btype%40vertical%2Bblock%4002a68b059f844a61ac3998729b78678d).

## 3. Crééer un document computationnel et importer les données (parcours 3B.)
### 3.1. Choix initiaux
 - Environnement RStudio
 - Langage R
 - Bibliothèque *parsedate* pour la gestion des dates en format *iso*

### 3.2. Créer un document computationnel
 - Créer un nouveau document du type *RMarkdown* nommé "Analyse de l'incidence du syndrome grippal"

### 3.3. Importer des données
 - Télécharger les données (il faut connaître l'url du téléchargement) via le code `data_url = ""` accessible dans les téléchargements
 - ici url est : https://www.sentiweb.fr/datasets/incidence-PAY-3.csv
 - lire les données `data = read.csv (data_url, skip=1)`
 - afficher le début des données `head(data)` : ordre chronologique inverse (1ère ligne = dernier point du jeu de données)
 - afficher la fin du jeu de données `tail(data)`

### 3.4. Données manquantes et comment les gérer
 - Dans quelles lignes il y a des données manquantes (analyse R ligne par ligne, on regarde pour une ligne i dans chaque colonne s'il y a une na) ?
 - `lignes_na = apply(data, 1, function(x)any(is.na(x)))` puis *afficher le contenu des lignes*  `data[lignes_na,]`
 - un dernier test à effectuer pour s'assurer que tous s'est bien passé : *inspecter les types de données* `class(data$week)` et `class(data$inc)`, incidence (inc) est de type factor car du aux données manquantes
 - pour corriger le type factor, `data = read.csv(data_url, skip=1, na.strings = '-')` considérer le "-" comme une donnée manquante; puis `class(data$inc)` --> integer

## 4. Vérification et inspection (parcours 3B.)
--> préparer les données pour l'analyse  
Bibliothèque supplémentaire utilisée pour lire la date format iso = *parsedate*  `library(parsedate)`  
### Comment réaliser la conversation de la date sous format iso? 
1. convertir l'entier (yyyyww) sous forme d'une chaîne de caractère
 - `date = 199501`
 - `ws = paste(date)`
 - `iso = paste0(substring(ws, 1, 4), "-W", substring(ws, 5,6))`
 - `iso`  

Nous pouvons aussi faire appel à la fonction *`parse_iso_8601()`* pour obtenir une date
--> on obtient une date yyyy-mm-dd où le jour donné est le lundi du mois.

2. *Il faut appliquer cette procédure à chaque ligne du jeu de données* en écrivant une fonction  
 `convert_week=function(date) {
    ws=paste(date)
    iso = paste0(substring(ws, 1, 4), "-W", substring(ws, 5, 6))
    as.character(parse_iso_8601(iso))
}`  

mettre les résultats dans une nouvelle colonne `data$date = as.Date(sapply(data$week, convert_week))` puis `class(date$date)`
$-->$ voir les notes du document module3_ressources_analyse-syndrome-grippal-rstudio.Rmd

3. Trier les données pour qu'elles soient dans l'ordre chronologique

## 5. Questions et réponses (parcours 3B.)
voir les notes du document analyse-syndrome-grippal-rstudio.Rmd

** Travail pratique évalué par les pairs **

# Module 4 : Vers une étude reproductible : la réalité du terrain