This document presents a brief overview of the Markdown syntax and builds on a [presentation from the Github team](https://guides.github.com/features/mastering-markdown/) and [blog post from Archer Reilly](http://csrgxtu.github.io/2015/03/20/Writing-Mathematic-Fomulars-in-Markdown/).
This document presents a brief overview of the Markdown syntax and
builds on a [presentation from the Github
Table of Contents<span class="tag" data-tag-name="TOC"></span>
team](https://guides.github.com/features/mastering-markdown/) and [blog
-[Summations and integrals](#summations-and-integrals)
======
-[Outfits ☺](#outfits-smiley)
-[About `markdown`](#about-markdown)
Headers
-------
# Syntax
## Headers
``` example
``` example
# This is an <h1> tag
# This is an <h1> tag
...
@@ -37,8 +39,7 @@ Headers
...
@@ -37,8 +39,7 @@ Headers
###### This is an <h6> tag
###### This is an <h6> tag
```
```
Emphasis
## Emphasis
--------
``` example
``` example
*This text will be italic*
*This text will be italic*
...
@@ -50,8 +51,7 @@ __This will also be bold__
...
@@ -50,8 +51,7 @@ __This will also be bold__
_You **can** combine them_
_You **can** combine them_
```
```
Lists
## Lists
-----
### Unordered
### Unordered
...
@@ -72,24 +72,21 @@ Lists
...
@@ -72,24 +72,21 @@ Lists
2. Item 3b
2. Item 3b
```
```
Images
## Images
------
``` example
``` example
Format: 
Format: 
```
```
Links
## Links
-----
``` example
``` example
http://github.com - automatic!
http://github.com - automatic!
[GitHub](http://github.com)
[GitHub](http://github.com)
```
```
Blockquotes
## Blockquotes
-----------
``` example
``` example
As Kanye West said:
As Kanye West said:
...
@@ -98,8 +95,7 @@ As Kanye West said:
...
@@ -98,8 +95,7 @@ As Kanye West said:
> the present is our past.
> the present is our past.
```
```
Inline code
## Inline code
-----------
```` example
```` example
To print some text with python, you should use the `print()` function.
To print some text with python, you should use the `print()` function.
...
@@ -108,20 +104,28 @@ print("Hello world!")
...
@@ -108,20 +104,28 @@ print("Hello world!")
```
```
````
````
Writing Math
# Writing Math
============
Math formulas are easy to write using Markdown, either using the **inline** mode or the **displayed formulas** mode. With the inline mode, formulas are inlined in the current paragraph whereas with the displayed mode, they appear as centered and emphasized.
Math formulas are easy to write using Markdown, either using the
**inline** mode or the **displayed formulas** mode. With the inline
mode, formulas are inlined in the current paragraph whereas with the
displayed mode, they appear as centered and emphasized.
The formatting generally slightly differs in both cases since, to display nicely on a single line, it is generally required to pack them a bit more than when they are emphasized.
The formatting generally slightly differs in both cases since, to
display nicely on a single line, it is generally required to pack them a
bit more than when they are emphasized.
To write formulas using the **inline** mode, they should be surrounded by a single `$` (as a consequence, whenever you need to use the original dollar symbol, you should prefix it with a backslash: `\$`). To write formulas using the **displayed** mode, they should be surrounded by a `$$`. Here are a few examples:
To write formulas using the **inline** mode, they should be surrounded
by a single `$` (as a consequence, whenever you need to use the original
dollar symbol, you should prefix it with a backslash: `\$`). To write
formulas using the **displayed** mode, they should be surrounded by a
`$$`. Here are a few examples:
``` example
``` example
This expression $\sum_{i=1}^n X_i$ is inlined.
This expression $\sum_{i=1}^n X_i$ is inlined.
```
```
This expression $\\sum\_{i=1}^n X\_i$ is inlined.
This expression \(\sum_{i=1}^n X_i\) is inlined.
``` example
``` example
This expression is emphasized:
This expression is emphasized:
...
@@ -131,103 +135,152 @@ $$\sum_{i=1}^n X_i$$
...
@@ -131,103 +135,152 @@ $$\sum_{i=1}^n X_i$$
This expression is emphasized:
This expression is emphasized:
$$\\sum\_{i=1}^n X\_i$$
\[\sum_{i=1}^n X_i\]
In the rest of this section we present a brief selection of common symbols and commands. Actually, almost any classical LaTeX command can used as such in Markdown, provided it is surrounded by a `$`. For more complete examples, please have a look at these ces [examples by James H. Steiger](http://www.statpower.net/Content/310/R%2520Stuff/SampleMarkdown.html).
In the rest of this section we present a brief selection of common
symbols and commands. Actually, almost any classical LaTeX command can
Greek Letters
used as such in Markdown, provided it is surrounded by a `$`. For more
-------------
complete examples, please have a look at these ces [examples by James H.
First of all, to know more about `markdown` and its extensions, you may
================
want to read:
First of all, to know more about `markdown` and its extensions, you may want to read:
- The « [Élaboration et conversion de documents avec Markdown et
Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » tutorial by
- The « [Élaboration et conversion de documents avec Markdown et Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » tutorial by Jean-Daniel Bonjour (EPFL). A must-read in French...
Jean-Daniel Bonjour (EPFL). A must-read in French…
- The wikipedia article on [Markdown](https://en.wikipedia.org/wiki/Markdown#Example) provides a good overview of the `markdown` syntax.
- The wikipedia article on
- Github proposes a short and efficient introduction: [Mastering Markdown](https://guides.github.com/features/mastering-markdown/).
As we explain in the video, `github` and `gitlab` allow you to easily edit `mardown` documents and to render them in `html`. This is quite convenient but may be a bit cumbersome for a daily use. You may prefer to edit these documents with a real editor and later to export them in whichever format you may like (`html`, `pdf`, `docx`, `epub`, etc). There are a few editors specifically designed for `markdown` (see for example the [Editors](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#editors) page of the `pandoc` website) but we rather advise you to use a general-purpose editor that is capable of handling the `markdown` syntax. A few ones were mentioned in the beginning of the video and additional information are available in the ["Quelques éditeurs adaptés à l'édition Markdown"](https://enacit1.epfl.ch/markdown-pandoc/#editeurs_markdown) section of Jean-Daniel Bonjour's tutorial.
- Github proposes a short and efficient introduction: [Mastering
To convert `markdown` in an "arbitrary" other format, the best solution today is [Pandoc](http://pandoc.org/), a software developed by John MacFarlane, a philosopher from de Berkeley, and whose [main page is on github](https://github.com/jgm/pandoc). J.-D. Bonjour's tutorial provides many explanations on how to install and use `pandoc` in the [Utilisation du convertisseur Pandoc](https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc) section. `pandoc` is written in Haskell and may be a bit cumbersome to install. Therefore, we provide here a few alternative solutions:
As we explain in the video, `github` and `gitlab` allow you to easily
- Some websites like <http://www.markdowntopdf.com/> or <http://markdown2pdf.com/> allow you to convert online `markdown` files into `pdf` files without having to install anything on your computer.
edit `mardown` documents and to render them in `html`. This is quite
- The [CommonMark](http://commonmark.org/) project proposes a rigorous specification of the `markdown` syntax and converters `markdown` → `html` / `LaTeX` written in `C` and `JavaScript` (<https://github.com/CommonMark/CommonMark>).
convenient but may be a bit cumbersome for a daily use. You may prefer
- You will find on the website of [John Gruber](https://daringfireball.net/projects/markdown/), the creator of `markdown`, a `markdown` → `html` converter written in `perl`.
to edit these documents with a real editor and later to export them in
-[MultiMarkdown](http://fletcherpenney.net/multimarkdown/) is another `markdown` extension that provides its own `markdown` → `html` converter written in `C`.
whichever format you may like (`html`, `pdf`, `docx`, `epub`, etc).
-[grip](https://github.com/joeyespo/grip) is a `python`-based server that allows you to convert on the fly `markdown` documents and to preview them with your favorite browser (this is quite useful to avoid useless commits just for the sake of previewing when using `github` ou `gitlab`).
There are a few editors specifically designed for `markdown` (see for
example the
The `pdf` conversion always relies on [LaTeX](https://fr.wikipedia.org/wiki/LaTeX), which requires a full-fledged and running LaTeX installation on your computer.
of the `pandoc` website) but we rather advise you to use a
In the demo, we show how to generate a `docx` from a `markdown` document with `Pandoc` and we explain that it is then possible to use a word processor like `LibreOffice` to edit the resulting file. Obviously the modifications will not be back-propagated to the original `markdown` document. You may however want to use `Pandoc` again to convert your new `docx` document to a new `markdown` document.
general-purpose editor that is capable of handling the `markdown`
syntax. A few ones were mentioned in the beginning of the video and
Another common strategy consists in doing most of the editing of an article/report in `Markdown` and to export it into a `docx` (or `LaTeX`) only in the end so as to prepare it for a camera-ready version with a standard word processing environment (or a `LaTeX` editor).
additional information are available in the ["Quelques éditeurs adaptés
Voici un aperçu rapide de la syntaxe Markdown repris d'une [présentation de Github](https://guides.github.com/features/mastering-markdown/) ainsi que de celles d'[Archer Reilly](http://csrgxtu.github.io/2015/03/20/Writing-Mathematic-Fomulars-in-Markdown/).
Voici un aperçu rapide de la syntaxe Markdown repris d'une [présentation
de Github](https://guides.github.com/features/mastering-markdown/) ainsi
Table des matières<span class="tag" data-tag-name="TOC"></span>
-[Fonctions et opérateurs](#fonctions-et-opérateurs)
-[Sommes et intégrales](#sommes-et-intégrales)
-[Exposants et indices](#exposants-et-indices)
-[Déguisements](#déguisements)
-[Fractions, coefficients binomiaux, racines,
-[Autour de `markdown`](#autour-de-markdown)
…](#fractions-coefficients-binomiaux-racines-)
-[Sommes et intégrales](#sommes-et-intégrales)
Syntaxe
-[Déguisements](#déguisements)
=======
-[Autour de `markdown`](#autour-de-markdown)
Headers
# Syntaxe
-------
## Headers
``` example
``` example
# This is an <h1> tag
# This is an <h1> tag
...
@@ -37,8 +38,7 @@ Headers
...
@@ -37,8 +38,7 @@ Headers
###### This is an <h6> tag
###### This is an <h6> tag
```
```
Emphasis
## Emphasis
--------
``` example
``` example
*This text will be italic*
*This text will be italic*
...
@@ -50,8 +50,7 @@ __This will also be bold__
...
@@ -50,8 +50,7 @@ __This will also be bold__
_You **can** combine them_
_You **can** combine them_
```
```
Lists
## Lists
-----
### Unordered
### Unordered
...
@@ -72,24 +71,21 @@ Lists
...
@@ -72,24 +71,21 @@ Lists
2. Item 3b
2. Item 3b
```
```
Images
## Images
------
``` example
``` example
Format: 
Format: 
```
```
Links
## Links
-----
``` example
``` example
http://github.com - automatic!
http://github.com - automatic!
[GitHub](http://github.com)
[GitHub](http://github.com)
```
```
Blockquotes
## Blockquotes
-----------
``` example
``` example
As Kanye West said:
As Kanye West said:
...
@@ -98,8 +94,7 @@ As Kanye West said:
...
@@ -98,8 +94,7 @@ As Kanye West said:
> the present is our past.
> the present is our past.
```
```
Inline code
## Inline code
-----------
```` example
```` example
To print some text with python, you should use the `print()` function.
To print some text with python, you should use the `print()` function.
...
@@ -108,20 +103,29 @@ print("Hello world!")
...
@@ -108,20 +103,29 @@ print("Hello world!")
```
```
````
````
Écrire des Maths
# Écrire des Maths
================
Il est possible d'écrire des formules en Markdown, soit en mode **inline** soit en mode **displayed formulas**. Dans le premier cas, les formules sont inclues directement à l'intérieur du paragraphe courant alors que dans le second, elles apparaissent centrées et mises en exergue.
Il est possible d'écrire des formules en Markdown, soit en mode
**inline** soit en mode **displayed formulas**. Dans le premier cas, les
formules sont inclues directement à l'intérieur du paragraphe courant
alors que dans le second, elles apparaissent centrées et mises en
exergue.
Le formatage de la formule est légèrement différent dans les deux cas car pour qu'une formule s'affiche joliment sur une seule ligne, il faut la "tasser" un peu plus que lorsqu'elle est mise en valeur.
Le formatage de la formule est légèrement différent dans les deux cas
car pour qu'une formule s'affiche joliment sur une seule ligne, il faut
la "tasser" un peu plus que lorsqu'elle est mise en valeur.
Pour écrire une formule en mode **inline**, il faut la délimiter par un `$` (du coup, pour écrire le symbole dollar, il faut le préfixer par un backslash, comme ceci: `\$`) alors que pour écrire en mode **displayed**, il faut la délimiter par un `$$`. Un petit exemple valant mieux qu'un long discours, voici concrètement comment cela fonctionne:
Pour écrire une formule en mode **inline**, il faut la délimiter par un
`$` (du coup, pour écrire le symbole dollar, il faut le préfixer par un
backslash, comme ceci: `\$`) alors que pour écrire en mode
**displayed**, il faut la délimiter par un `$$`. Un petit exemple valant
mieux qu'un long discours, voici concrètement comment cela fonctionne:
``` example
``` example
Cette expression $\sum_{i=1}^n X_i$ est inlinée.
Cette expression $\sum_{i=1}^n X_i$ est inlinée.
```
```
Cette expression $\\sum\_{i=1}^n X\_i$ est inlinée.
Cette expression \(\sum_{i=1}^n X_i\) est inlinée.
``` example
``` example
Cette expression est mise en valeur:
Cette expression est mise en valeur:
...
@@ -131,103 +135,162 @@ $$\sum_{i=1}^n X_i$$
...
@@ -131,103 +135,162 @@ $$\sum_{i=1}^n X_i$$
Cette expression est mise en valeur:
Cette expression est mise en valeur:
$$\\sum\_{i=1}^n X\_i$$
\[\sum_{i=1}^n X_i\]
Nous vous présentons par la suite une sélection de symboles et de commandes courantes. En fait, à peu près tout ce qui est classique dans le langage LaTeX peut être utilisé pourvu que vous délimitiez bien avec un `$`. Pour d'autres exemples plus complets jetez un coup d'œil à ces [exemples de James H. Steiger](http://www.statpower.net/Content/310/R%2520Stuff/SampleMarkdown.html).
Nous vous présentons par la suite une sélection de symboles et de
commandes courantes. En fait, à peu près tout ce qui est classique dans
Lettres grecques
le langage LaTeX peut être utilisé pourvu que vous délimitiez bien avec
----------------
un `$`. Pour d'autres exemples plus complets jetez un coup d'œil à ces
Tout d'abord, pour aller plus loin avec `markdown` et ses extensions /
====================
ramifications :
Tout d'abord, pour aller plus loin avec `markdown` et ses extensions / ramifications :
- Le didacticiel « [Élaboration et conversion de documents avec
Markdown et Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » de
- Le didacticiel « [Élaboration et conversion de documents avec Markdown et Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » de Jean-Daniel Bonjour (EPFL), précis, complet, concis, en français ; un vrai bonheur !
Jean-Daniel Bonjour (EPFL), précis, complet, concis, en français ;
- L'article [Markdown](https://en.wikipedia.org/wiki/Markdown#Example) de wikipedia en anglais contient un bon pense-bête sur la syntaxe `markdown`.
un vrai bonheur \!
- Github propose un court et efficace didacticiel (en anglais) : [Mastering Markdown](https://guides.github.com/features/mastering-markdown/).
de wikipedia en anglais contient un bon pense-bête sur la syntaxe
Comme nous l'illustrons dans la « film d'écran » (*screencast*), l'éditeur de texte des dépôts `github` et `gitlab` permet d'interpréter / transformer à la demande un fichier `mardown` en un fichier `html`. C'est à la fois agréable et pratique, mais ce n'est pas une solution pour une utilisation quotidienne de `markdown`, pour cela, il est plus efficace d'éditer son texte, avec un éditeur de texte, sur son ordinateur, avant de « l'exporter » dans un format comme `html`, `pdf`, `docx`, `epub`, etc. Il existe des éditeurs plus ou moins spécialisés pour `markdown`, certains sont indiqués sur la page [Editors](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#editors) du site de `pandoc`, mais nous préconisons clairement l'emploi d'un éditeur de texte « généraliste » capable de reconnaître la syntaxe `markdown`. Nous en avons indiqué en début de séquence et on pourra trouver des informations complémentaires dans la section [Quelques éditeurs adaptés à l'édition Markdown](https://enacit1.epfl.ch/markdown-pandoc/#editeurs_markdown) du didacticiel de Jean-Daniel Bonjour.
`markdown`.
- Github propose un court et efficace didacticiel (en anglais) :
Pour convertir un fichier `markdown` en un format « arbitraire », la solution à ce jour la plus complète est [Pandoc](http://pandoc.org/), logiciel développé par John MacFarlane, un philosophe de Berkeley (le site [github](https://github.com/jgm/pandoc)). En plus du site de `Pandoc`, le didacticiel de J.-D. Bonjour donne de nombreuses explications sur comment installer et utiliser `pandoc` dans la section [Utilisation du convertisseur Pandoc](https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc). Comme `pandoc` -- écrit en Haskell -- peut être parfois un peu difficile à installer, nous indiquons maintenant quelques solutions alternatives :
- Des sites comme <http://www.markdowntopdf.com/> et <http://markdown2pdf.com/> permettent de convertir en ligne un fichier `markdown` en un fichier `pdf`.
- Le projet [CommonMark](http://commonmark.org/) propose, en plus d'une spécifications plus rigoureuse de la syntaxe `markdown`, des convertisseurs `markdown` → `html` / `LaTeX` (et plus) écris en `C` et en `JavaScript` (<https://github.com/CommonMark/CommonMark>).
Comme nous l'illustrons dans la « film d'écran » (*screencast*),
- Le site de [John Gruber](https://daringfireball.net/projects/markdown/), le créateur de `markdown`, fournit un convertisseur `markdown` → `html` écrit en `perl`.
l'éditeur de texte des dépôts `github` et `gitlab` permet d'interpréter
-[MultiMarkdown](http://fletcherpenney.net/multimarkdown/) est une autre extension de `markdown` qui vient avec son convertisseur `markdown` → `html` écrit en `C`.
/ transformer à la demande un fichier `mardown` en un fichier `html`.
-[grip](https://github.com/joeyespo/grip) est un serveur écrit en `python` qui permet de convertir et visualiser à la volée des fichiers `markdown` avec son navigateur (très utile pour éviter d'avoir à faire des « commits » en grande quantité lorsqu'on écrit de tels fichiers pour un dépôt `github` ou `gitlab`).
C'est à la fois agréable et pratique, mais ce n'est pas une solution
pour une utilisation quotidienne de `markdown`, pour cela, il est plus
La conversion en `pdf` passe toujours par [LaTeX](https://fr.wikipedia.org/wiki/LaTeX) ce qui nécessite d'avoir une version complète et à jour de ce logiciel sur sa machine.
efficace d'éditer son texte, avec un éditeur de texte, sur son
ordinateur, avant de « l'exporter » dans un format comme `html`, `pdf`,
Dans la petite démonstration, nous montrons comment générer un fichier `docx` à partir d'un fichier `md` avec `Pandoc` et nous soulignons qu'il est alors possible d'utiliser un traitement de texte comme `LibreOffice` pour modifier le fichier obtenu. Il est clair que si des modifications sont apportées au `docx` elle en seront pas (automatiquement) propagées au `md`. Il faudra utiliser `Pandoc` pour cela et effectuer une conversion de `docx` vers `md` (et seules les éléments du format `docx` qui existent en `md` seront conservés).
`docx`, `epub`, etc. Il existe des éditeurs plus ou moins spécialisés
pour `markdown`, certains sont indiqués sur la page
Une stratégie qui est souvent employée et qui fonctionne bien en pratique consiste à faire le gros du travail de rédaction d'un article ou d'un mémoire en `Markdown`. La rédaction terminée, le fichier est exporté au format `docx` (ou `LaTeX`) et des ajustements de mise en page sont alors effectués avec un logiciel de traitement de texte (ou un éditeur `LaTeX`).
[Editors](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#editors) du
site de `pandoc`, mais nous préconisons clairement l'emploi d'un éditeur
de texte « généraliste » capable de reconnaître la syntaxe `markdown`.
Nous en avons indiqué en début de séquence et on pourra trouver des
informations complémentaires dans la section [Quelques éditeurs adaptés
à l'édition
Markdown](https://enacit1.epfl.ch/markdown-pandoc/#editeurs_markdown) du
didacticiel de Jean-Daniel Bonjour.
Pour convertir un fichier `markdown` en un format « arbitraire », la
solution à ce jour la plus complète est [Pandoc](http://pandoc.org/),
logiciel développé par John MacFarlane, un philosophe de Berkeley (le
site [github](https://github.com/jgm/pandoc)). En plus du site de
`Pandoc`, le didacticiel de J.-D. Bonjour donne de nombreuses
explications sur comment installer et utiliser `pandoc` dans la section
[Utilisation du convertisseur
Pandoc](https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc). Comme
`pandoc` – écrit en Haskell – peut être parfois un peu difficile à
installer, nous indiquons maintenant quelques solutions alternatives :
- Des sites comme <http://www.markdowntopdf.com/> et
<http://markdown2pdf.com/> permettent de convertir en ligne un
fichier `markdown` en un fichier `pdf`.
- Le projet [CommonMark](http://commonmark.org/) propose, en plus
d'une spécifications plus rigoureuse de la syntaxe `markdown`, des
convertisseurs `markdown` → `html` / `LaTeX` (et plus) écris en `C`
et en `JavaScript` (<https://github.com/CommonMark/CommonMark>).
- Le site de [John
Gruber](https://daringfireball.net/projects/markdown/), le créateur
de `markdown`, fournit un convertisseur `markdown` → `html` écrit en
`perl`.
-[MultiMarkdown](http://fletcherpenney.net/multimarkdown/) est une
autre extension de `markdown` qui vient avec son convertisseur
`markdown` → `html` écrit en `C`.
-[grip](https://github.com/joeyespo/grip) est un serveur écrit en
`python` qui permet de convertir et visualiser à la volée des
fichiers `markdown` avec son navigateur (très utile pour éviter
d'avoir à faire des « commits » en grande quantité lorsqu'on écrit
de tels fichiers pour un dépôt `github` ou `gitlab`).
La conversion en `pdf` passe toujours par
[LaTeX](https://fr.wikipedia.org/wiki/LaTeX) ce qui nécessite d'avoir
une version complète et à jour de ce logiciel sur sa machine.
Dans la petite démonstration, nous montrons comment générer un fichier
`docx` à partir d'un fichier `md` avec `Pandoc` et nous soulignons qu'il
est alors possible d'utiliser un traitement de texte comme `LibreOffice`
pour modifier le fichier obtenu. Il est clair que si des modifications
sont apportées au `docx` elle en seront pas (automatiquement) propagées
au `md`. Il faudra utiliser `Pandoc` pour cela et effectuer une
conversion de `docx` vers `md` (et seules les éléments du format `docx`
qui existent en `md` seront conservés).
Une stratégie qui est souvent employée et qui fonctionne bien en
pratique consiste à faire le gros du travail de rédaction d'un article
ou d'un mémoire en `Markdown`. La rédaction terminée, le fichier est
exporté au format `docx` (ou `LaTeX`) et des ajustements de mise en page
sont alors effectués avec un logiciel de traitement de texte (ou un
**Disclaimer:** The two sections *A simple "reproducible research" emacs configuration* and *A stub of replicable article* explain how to set up emacs/org-mode for this MOOC. These are very important sections in the context of this MOOC. **These sections are illustrated in two out of the [three video tutorials of this sequence](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4), and****which you really should follow carefully**. **Otherwise, you may have trouble doing the exercises later on**. Likewise, I strongly encourage you to watch the ["emacs and git" video tutorial available at the same place](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4).
**Disclaimer:** The two sections *A simple "reproducible research" emacs
configuration* and *A stub of replicable article* explain how to set up
The next section provides information on how to install emacs.
emacs/org-mode for this MOOC. These are very important sections in the
context of this MOOC. **These sections are illustrated in two out of the
Table of Contents<span class="tag" data-tag-name="TOC"></span>
-[Step 1: Prepare your journal](#step-1-prepare-your-journal)
In the following we describe for each platform the installation method that we consider most convenient. There are other options that may be preferable in particular situations, so you may want to look at the [Emacs Web site](https://www.gnu.org/software/emacs/download.html) for details, but we strongly suggest you first try the method we recommend.
-[A stub of a replicable article](#a-stub-of-a-replicable-article)
-[Emacs tips and tricks](#emacs-tips-and-tricks)
-[Cheat-sheets](#cheat-sheets)
-[Video tutorials](#video-tutorials)
-[Additional useful emacs
packages](#additional-useful-emacs-packages)
-[Other resources](#other-resources)
# Installing Emacs
In the following we describe for each platform the installation method
that we consider most convenient. There are other options that may be
preferable in particular situations, so you may want to look at the
[Emacs Web site](https://www.gnu.org/software/emacs/download.html) for
details, but we strongly suggest you first try the method we recommend.
At the end of the installation procedure, you should have one of
At the end of the installation procedure, you should have one of
1. Emacs 26 (the latest version)
1. Emacs 26 (the latest version)
2. Emacs 25 plus Org-Mode 9
2. Emacs 25 plus Org-Mode 9
Emacs 25 comes with Org-Mode 8, which is not compatible with our examples. So if you use Emacs 25, you must separately install Org-Mode 9. Emacs 26 already includes Org-Mode 9.
Emacs 25 comes with Org-Mode 8, which is not compatible with our
examples. So if you use Emacs 25, you must separately install Org-Mode
9. Emacs 26 already includes Org-Mode 9.
Our MOOC also requires a few extra Emacs packages: [ESS](https://ess.r-project.org/)(for working with the R language) and [AUCTeX](https://www.gnu.org/software/auctex/)(for editing LaTeX). They will be installed automatically the first time you start Emacs if you use the configuration described under [A simple "reproducible research" emacs configuration](#a-simple-reproducible-research-emacs-configuration).
Our MOOC also requires a few extra Emacs packages:
[ESS](https://ess.r-project.org/)(for working with the R language) and
[AUCTeX](https://www.gnu.org/software/auctex/)(for editing LaTeX). They
will be installed automatically the first time you start Emacs if you
use the configuration described under [A simple "reproducible research"
We provide here only instructions for Debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g.n redhat, fedora).
We provide here only instructions for Debian-based distributions. Feel
free to contribute to this document to provide up-to-date information
for other distributions (e.g.n redhat, fedora).
These are the versions of Emacs that various distributions provide:
These are the versions of Emacs that various distributions provide:
- Debian (stretch) ships with [emacs 25.1](https://packages.debian.org/stretch/emacs25) and [org-mode 9.0.3](https://packages.debian.org/stretch/org-mode)
- Debian (stretch) ships with
- Ubuntu (bionic 18.04) ships with [emacs 25.2](https://packages.ubuntu.com/bionic/emacs25) and [org-mode 9.1.6](https://packages.ubuntu.com/bionic/org-mode)
[emacs 25.1](https://packages.debian.org/stretch/emacs25) and
- Ubuntu (artful 17.04) ships with [emacs 25.2](https://packages.ubuntu.com/artful/emacs25) and [org-mode 9.0.9](https://packages.ubuntu.com/artful/org-mode)
Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/)
Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/)
```
```
The version numbers you get will depend on the distribution you are running. **You really want to make sure you do not rely on org-mode 8**, which is now deprecated.
The version numbers you get will depend on the distribution you are
running. <spanclass="underline">You really want to make sure you do not
rely on org-mode 8</span>, which is now deprecated.
macOS
## macOS
-----
**Note:** macOS comes with a prehistoric command-line-only version of Emacs located at `/usr/bin/emacs`. It's best to forget about it.
**Note:** macOS comes with a prehistoric command-line-only version of
Emacs located at `/usr/bin/emacs`. It's best to forget about it.
The Web site <https://emacsformacosx.com/> proposes precompiled Emacs versions for macOS. Download the latest version (the one that figures prominently on the page) and install it like you would install any other macOS application, by copying `Emacs.app` from the downloaded disk image to a convenient location on your computer.
The Web site <https://emacsformacosx.com/> proposes precompiled Emacs
versions for macOS. Download the latest version (the one that figures
prominently on the page) and install it like you would install any other
macOS application, by copying `Emacs.app` from the downloaded disk image
to a convenient location on your computer.
In case you need to run Emacs from the command line (note: this is not required in the MOOC), you have to enter the full path to the executable. Assuming that you have copied `Emacs.app` to `/path/to/emacs`, this is `/path/to/emacs/Emacs.app/Contents/MacOS/Emacs`. Note that if you just type `emacs`, you will use the prehistoric command-line-only version at `/usr/bin/emacs` provided by Apple.
In case you need to run Emacs from the command line (note: this is not
required for the MOOC), you have to enter the full path to the
executable. Assuming that you have copied `Emacs.app` to
`/path/to/emacs`, this is
`/path/to/emacs/Emacs.app/Contents/MacOS/Emacs`. If you just type
`emacs`, you will use the prehistoric command-line-only version at
`/usr/bin/emacs` provided by Apple.
Windows
## Windows
-------
Download the [precompiled Emacs 26.1](https://ftp.gnu.org/gnu/emacs/windows/emacs-26/emacs-26.1-i686.zip) and unzip the zip file preserving the directory structure, and run `bin\runemacs.exe`.
and unzip the zip file preserving the directory structure, and run
`bin\runemacs.exe`.
Alternatively, create a desktop shortcut to `bin\runemacs.exe`, and start Emacs by double-clicking on that shortcut's icon. See [here](https://www.gnu.org/software/emacs/manual/html_node/emacs/Windows-Startup.html) for an explanation of this and other methods for launching Emacs under Windows.
Alternatively, create a desktop shortcut to `bin\runemacs.exe`, and
start Emacs by double-clicking on that shortcut's icon. See
for an explanation of this and other methods for launching Emacs under
Windows.
### Directory naming conventions
### Directory naming conventions
In the following instructions, we refer to your home directory through the (UNIX) `~/` notation. On Windows, your home directory should be something like `C:\Users\yourname`. Therefore, whenever we mention the `~/org/` (resp. the `~/.emacs.d/`) directory this means we are referring to `C:\Users\yourname\org` (resp. `C:\Users\yourname\.emacs.d\`).
In the following instructions, we refer to your home directory through
the (UNIX) `~/` notation. On Windows, your home directory should be
something like `C:\Users\yourname`. Therefore, whenever we mention the
`~/org/` (resp. the `~/.emacs.d/`) directory this means we are referring
to `C:\Users\yourname\org` (resp. `C:\Users\yourname\.emacs.d\`).
### Making R and Python available to the console
### Making R and Python available to the console
When running a command, Windows will look for the command in the directories indicated in the `PATH` environment variable. If none of these directories contains the command, Windows will stop and indicate the command does not exist. To make sure R (which may be in something like `C:/Program Files/R/R-3.5.1/bin/x64/`) and Python (which may be in something like `C:/Program Files/Python/Python37/`) can easily be run from Emacs, you should thus configure the `PATH` variable accordingly.
When running a command, Windows will look for the command in the
directories indicated in the `PATH` environment variable. If none of
these directories contains the command, Windows will stop and indicate
the command does not exist. To make sure R (which may be in something
like `C:/Program Files/R/R-3.5.1/bin/x64/`) and Python (which may be in
something like `C:/Program Files/Python/Python37/`) can easily be run
from Emacs, you should thus configure the `PATH` variable accordingly.
This requires to go through the "Environment Variable" editor as explained [here](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/).
This requires to go through the "Environment Variable" editor as
Then you will want to deactivate interactive plots in matplotlib. To this end, you first need to know where the matplotlib configuration is located. Open a python console the type the following code:
Then you will want to deactivate interactive plots in matplotlib. To
this end, you first need to know where the matplotlib configuration is
located. Open a python console the type the following code:
Open the `matplotlibrc` file and modify the line starting with `backend` to make it `backend : Agg`.
Open the `matplotlibrc` file and modify the line starting with `backend`
to make it `backend : Agg`.
All platforms: pretty code in HTML export
# A simple "reproducible research" emacs configuration
-----------------------------------------
To have code pretty printing when exporting to HTML, you should install the `htmlize` package, which is done by opening emacs and typing the following command:
This section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) (/"Mise en place Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help.
1. `~/.emacs`
2. `~/.emacs.el`
3. `~/.emacs.elc`
Emacs comes with very basic default configuration and it appears like everyone has its own taste. You will for example find [here](https://www.emacswiki.org/emacs/StarterKits) several default Emacs configurations that reflect the preferences of their creators. Likewise the configuration of Org-Mode is incredibly flexible (see for example [the org-mode website](https://orgmode.org/worg/org-configs/index.html) for more references). In the context of this MOOC, we propose you a relatively minimalist one that is rather "*reproducible research*" oriented by adding a few org-mode specific configurations.
There is also a directory that you should backup and then remove (if it
exists), with everything it might contain:
Step 0: Backup and download our configuration
1. `~/.emacs.d`
---------------------------------------------
The procedure we propose will wipe your already existing custom Emacs configuration if you have one. **You should thus beforehand make a backup** of `~/.emacs` and of `~/.emacs.d/init.el` (if these files exist).
In the above filenames, `~/` stands for your home directory. Windows
users should replace it by `C:\Users\MyName`, replacing MyName by their
user name.
Then download [this archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org_archive.tgz) and uncompress it. It contains the following files and we will refer to them in the following:
and uncompress it. It contains the following files and we will refer to
them in the following:
``` example
``` example
rr_org/init.el
rr_org/init.el
rr_org/journal.org
rr_org/journal.org
```
```
Alternatively, [the files you are looking for are available here](rr_org/).
Alternatively, [the files you are looking for are available
here](rr_org/).
If you use Windows, and if you use a desktop shortcut to start Emacs, you must include the path to the file `init.el` in the command for the shortcut. For example, if you installed Emacs as `C:\Users\MyName/emacs`, your desktop shortcut should execute the command `C:\Users\MyName\emacs\bin\runemacs.exe -l .emacs.d/init.el`.
If you use Windows, and if you use a desktop shortcut to start Emacs,
you must include the path to the file `init.el` in the command for the
shortcut. For example, if you installed Emacs as
`C:\Users\MyName/emacs`, your desktop shortcut should execute the
Create an `org/` directory in the top of your home:
Create an `org/` directory in the top of your home:
...
@@ -172,33 +276,42 @@ Create an `org/` directory in the top of your home:
...
@@ -172,33 +276,42 @@ Create an `org/` directory in the top of your home:
mkdir -p ~/org/
mkdir -p ~/org/
```
```
Then copy `rr_org/journal.org` file in your `~/org/` directory. This file will be your laboratory notebook and all the notes you will capture with `C-c c` will go automatically go in this file. The first entry of this notebook is populated with [many Emacs shortcuts](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) that you should give a try.
Then copy `rr_org/journal.org` file in your `~/org/` directory. This
file will be your laboratory notebook and all the notes you will capture
Step 2: Set up Emacs configuration
with `C-c c` will go automatically go in this file. The first entry of
Copy `rr_org/init.el` in your `~/.emacs.d/` directory.
## Step 3: Put the Emacs configuration file in the right place
Alternatively, if you do not want to mess with your already existing emacs configuration, you may launch emacs with this specific configuration with the following command: `emacs -q -l rr_org/init.el`.
Create the directory `~/.emacs.d/` and copy `rr_org/init.el` into it.
Step 3: Adapt the configuration to your specific needs if required
## Step 4: Adapt the configuration to your specific needs if required
take a bit of time because Emacs will download a few add-on packages.
For that reason, please make sure that you have a working internet
connection for this step.
Open a new instance of Emacs and open a `foo.org` file. Copy the following lines in this file:
Then open a file `foo.org`. Copy the following lines into this file:
``` example
``` example
#+begin_src shell :session foo :results output :exports both
#+begin_src shell :session foo :results output :exports both
...
@@ -206,25 +319,50 @@ ls -la # or dir under windows
...
@@ -206,25 +319,50 @@ ls -la # or dir under windows
#+end_src
#+end_src
```
```
Put your cursor inside this code block and execute it with the following command: `C-c C-c` (If you are not familiar with Emacs commands, this one means '`Ctrl + C`' twice)
Put your cursor inside this code block and execute it with the following
command: `C-c C-c` (If you are not familiar with Emacs commands, this
A `#+RESULTS:` block with the result of the command should appear if it worked.
one means '`Ctrl + C`' twice)
In the video, we already have demonstrated the main features and shortcuts of emacs/org-mode that will help you maintain a document and benefit from literate programming. The list of features and shortcuts is demonstrated in the [first entry of your labbook](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org).
A `#+RESULTS:` block with the result of the command should appear if it
worked.
Step 5: Open and play with your journal:
----------------------------------------
In the video, we already have demonstrated the main features and
shortcuts of emacs/org-mode that will help you maintain a document and
In step 1, you were told to create an journal in `~org/journal.org`. First you probably want to make sure this file is stored in a version control system like git. We leave it up to you to set this up but if you have any trouble, feel free to ask on the FUN forums.
benefit from literate programming. The list of features and shortcuts is
This section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) (/"Écrire un article réplicable avec Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help.
In step 2, you were told to create a journal in `~org/journal.org`. You
Remember, you need a working LaTeX and R environment. If you can't open a terminal and run the commands `R`, `pdflatex`, and `python`, you will not be able to generate this document. When being compiled, the article downloads the corresponding LaTeX packages so you also need to have a working `wget` command (alternatively, it uses `curl`). Once downloaded, you may still read the source (<https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org>) and understand how it works though.
probably want to make sure this file is stored in a version control
system like git. We leave it up to you to set this up but if you have
Download the following [archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz), uncompress it and simply `make` to generate the article. You should then be able to open the [resulting article](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf). This is summarized in the following command:
@@ -233,63 +371,99 @@ tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf
...
@@ -233,63 +371,99 @@ tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf
**Possible issues**:
**Possible issues**:
- If the `make` command fails (especially on Mac), it may be because Emacs or something else is not correctly installed. In that case, open the article directly with the following command:
- If the `make` command fails (especially on Mac), it may be because
Emacs or something else is not correctly installed. In that case,
and export it to pdf with the following shortcut: `C-c C-e l o`
and export it to pdf with the following shortcut: `C-c C-e l o`
- If it still doesn't work and emacs complains about not finding ESS, it may be because you installed ESS in your home instead of system-wide. In that case, try to remove the `-q` in the previous command line to load your personal emacs configuration.
Finally, when you'll be tired of always re-executing all the source code when exporting, just look for the following line in [article.org](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org):
- If it still doesn't work and emacs complains about not finding ESS,
it may be because you installed ESS in your home instead of
system-wide. In that case, try to remove the `-q` in the previous
command line to load your personal emacs configuration.
Finally, when you'll be tired of always re-executing all the source code
when exporting, just look for the following line in
If you remove the `# ` in the beginning of the line, it will not be a comment anymore and will indicate org-mode to stop evaluating every chunk of code when exporting.
If you remove the `# ` in the beginning of the line, it will not be a
comment anymore and will indicate org-mode to stop evaluating every
chunk of code when exporting.
Emacs tips and tricks
# Emacs tips and tricks
=====================
Cheat-sheets
## Cheat-sheets
------------
Learning Emacs and Org-Mode can be difficult as there is an inordinate amount of shortcuts. Many people have thus come up with cheat-sheats. Here is a selection in case it helps:
Learning Emacs and Org-Mode can be difficult as there is an inordinate
amount of shortcuts. Many people have thus come up with cheat-sheats.
Here is a selection in case it helps:
### Emacs
### Emacs
- [Common and step-by-step Emacs shortcuts for our *reproducible research* configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
- [Common and step-by-step Emacs shortcuts for our *reproducible
- [The official GNU emacs refcard](https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf)
research*
- Two graphical cheat-sheats by Sacha Chua on  and on .
- [Common and step-by-step org-mode shortcuts for our *reproducible research* configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
- [Common and step-by-step org-mode shortcuts for our *reproducible
- [The official org-mode refcard](https://orgmode.org/worg/orgcard.html)
research*
- [The official description of the org-mode syntax](https://orgmode.org/worg/dev/org-syntax.html) and a [relatively concise description of the org-mode syntax](https://gist.github.com/hoeltgman/3825415).
For those of you who prefer video explanations, here is a [Youtube channel with many step by step emacs tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg).
For those of you who prefer video explanations, here is a [Youtube
[Company-mode](http://company-mode.github.io/) is a text completion framework for Emacs. It allows to have smart completion in emacs for the most common languages. If you feel this is needed, you should follow the instructions from the official Web page: [<http://company-mode.github.io/>](http://company-mode.github.io/)
[Company-mode](http://company-mode.github.io/) is a text completion
framework for Emacs. It allows to have smart completion in emacs for the
most common languages. If you feel this is needed, you should follow the
instructions from the official Web page:
<http://company-mode.github.io/>
### Magit
### Magit
[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is briefly illustrated in the context of this MOOC in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) ("*Utilisation Emacs/git*" in French).
[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is
briefly illustrated in the context of this MOOC in a [video
It is very powerful and we use it on a daily basis but you should definitely understand what git does behind the scenes beforehand. If you feel this would be useful for you, you should follow [this visual walk-through](https://magit.vc/screenshots/) or [this really short "crash course"](https://www.emacswiki.org/emacs/Magit). If you installed the previous "*reproducible research*" emacs configuration, you can easily invoke magit by using `C-x g`.
It is very powerful and we use it on a daily basis but you should
definitely understand what git does behind the scenes beforehand. If you
feel this would be useful for you, you should follow [this visual
walk-through](https://magit.vc/screenshots/) or [this really short
"crash course"](https://www.emacswiki.org/emacs/Magit). If you installed
the previous "*reproducible research*" emacs configuration, you can
**Disclaimer:** The two sections *A simple "reproducible research" emacs configuration* and *A stub of replicable article* explain how to set up emacs/org-mode for this MOOC. These are very important sections in the context of this MOOC. **These sections are illustrated in two out of the [three video tutorials of this sequence](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4), and****which you really should follow carefully**. **Otherwise, you may have trouble doing the exercises later on**. Likewise, I strongly encourage you to watch the ["emacs and git" video tutorial available at the same place](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4).
**Disclaimer:** The two sections *A simple "reproducible research" emacs
configuration* and *A stub of replicable article* explain how to set up
The next section provides information on how to install emacs.
emacs/org-mode for this MOOC. These are very important sections in the
context of this MOOC. **These sections are illustrated in two out of the
Table of Contents<span class="tag" data-tag-name="TOC"></span>
-[Step 3: Adapt the configuration to your specific needs if
We provide here only instructions for Debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g.n redhat, fedora).
- Debian (stretch) ships with [emacs 25.1](https://packages.debian.org/stretch/emacs25) and [org-mode 9.0.3](https://packages.debian.org/stretch/org-mode)
Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/)
Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/)
```
```
The version numbers you get will depend on the distribution you are running. **You really want to make sure you do not rely on org-mode 8**, which is now deprecated.
The version numbers you get will depend on the distribution you are
running. <spanclass="underline">You really want to make sure you do not
macOS
rely on org-mode 8</span>, which is now deprecated.
-----
## macOS
**Note:** macOS comes with a prehistoric command-line-only version of Emacs located at `/usr/bin/emacs`. It's best to forget about it.
**Note:** macOS comes with a prehistoric command-line-only version of
-**Option 1**: Install the `.dmg` file from [Vincent Goulet](http://vgoulet.act.ulaval.ca/): [<https://vigou3.gitlab.io/emacs-modified-macos/>](https://vigou3.gitlab.io/emacs-modified-macos/). It ships with recent versions:
Emacs located at `/usr/bin/emacs`. It's best to forget about it.
- Emacs 26.1
- Org-mode 9.1.13
The Web site <https://emacsformacosx.com/> proposes precompiled Emacs
- ESS 17.11
versions for macOS. Download the latest version (the one that figures
prominently on the page) and install it like you would install any other
If you install this version of Emacs, or in fact any other version of Emacs distributed as a clickable application in a `.dmg` file, you must type the full path to the executable if you want to run Emacs from a terminal. For example, if your clickable application is at `/Applications/Emacs.app`, then the executable is at `/Applications/Emacs.app/Contents/MacOS/Emacs`
macOS application, by copying `Emacs.app` from the downloaded disk image
to a convenient location on your computer.
-**Option 2**: If you use [Homebrew](https://docs.brew.sh/), do the following:
This Emacs version contains everything used in the MOOC except the
``` bash
packages [ESS](https://ess.r-project.org/)(for working with the R
brew update
language) and [AUCTeX](https://www.gnu.org/software/auctex/)(for
brew install emacs --with-cocoa
editing LaTeX). If you use the configuration described under [A simple
these packages will be installed automatically the first time you start
brew install auctex
Emacs.
brew tap brewsci/science
brew install ess
In case you need to run Emacs from the command line (note: this is not
```
required in the MOOC), you have to enter the full path to the
executable. Assuming that you have copied `Emacs.app` to
This provides an `emacs` command for use from the command line, plus a clickable application at `Cellar/emacs/26.1_1/Emacs.app` inside your Homebrew directory. If you installed Homebrew at the default location `/usr/local`, then this is `/usr/local/Cellar/emacs/26.1_1/Emacs.app`. If you installed Homebrew on an account with administrator privileges, you can add
`/path/to/emacs`, this is
`/path/to/emacs/Emacs.app/Contents/MacOS/Emacs`. Note that if you just
``` bash
type `emacs`, you will use the prehistoric command-line-only version at
brew linkapps emacs
`/usr/bin/emacs` provided by Apple.
```
## Windows
in order to make Emacs accessible directly from `/Applications`.
Install the `.exe` file from [Vincent
Windows
Goulet](http://vgoulet.act.ulaval.ca/):
-------
<https://vigou3.gitlab.io/emacs-modified-windows/>. It ships with recent
versions:
Install the `.exe` file from [Vincent Goulet](http://vgoulet.act.ulaval.ca/): [<https://vigou3.gitlab.io/emacs-modified-windows/>](https://vigou3.gitlab.io/emacs-modified-windows/). It ships with recent versions:
- Emacs 26.1
- Emacs 26.1
- Org-mode 9.1.13
- Org-mode 9.1.13
- ESS 17.11
- ESS 17.11
### Directory naming conventions
### Directory naming conventions
In the following instructions, we refer to your home directory through the (UNIX) `~/` notation. On Windows, your home directory should be something like `C:\Users\yourname`. Therefore, whenever we mention the `~/org/` (resp. the `~/.emacs.d/`) directory this means we are referring to `C:\Users\yourname\org` (resp. `C:\Users\yourname\.emacs.d\`).
In the following instructions, we refer to your home directory through
the (UNIX) `~/` notation. On Windows, your home directory should be
something like `C:\Users\yourname`. Therefore, whenever we mention the
`~/org/` (resp. the `~/.emacs.d/`) directory this means we are referring
to `C:\Users\yourname\org` (resp. `C:\Users\yourname\.emacs.d\`).
### Making R and Python available to the console
### Making R and Python available to the console
When running a command, Windows will look for the command in the directories indicated in the `PATH` environment variable. If none of these directories contains the command, Windows will stop and indicate the command does not exist. To make sure R (which may be in something like `C:/Program Files/R/R-3.5.1/bin/x64/`) and Python (which may be in something like `C:/Program Files/Python/Python37/`) can easily be run from Emacs, you should thus configure the `PATH` variable accordingly.
When running a command, Windows will look for the command in the
directories indicated in the `PATH` environment variable. If none of
these directories contains the command, Windows will stop and indicate
the command does not exist. To make sure R (which may be in something
like `C:/Program Files/R/R-3.5.1/bin/x64/`) and Python (which may be in
something like `C:/Program Files/Python/Python37/`) can easily be run
from Emacs, you should thus configure the `PATH` variable accordingly.
This requires to go through the "Environment Variable" editor as explained [here](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/).
This requires to go through the "Environment Variable" editor as
Then you will want to deactivate interactive plots in matplotlib. To this end, you first need to know where the matplotlib configuration is located. Open a python console the type the following code:
Then you will want to deactivate interactive plots in matplotlib. To
this end, you first need to know where the matplotlib configuration is
located. Open a python console the type the following code:
Open the `matplotlibrc` file and modify the line starting with `backend` to make it `backend : Agg`.
Open the `matplotlibrc` file and modify the line starting with `backend`
to make it `backend : Agg`.
All platforms: pretty code in HTML export
## All platforms: pretty code in HTML export
-----------------------------------------
To have code pretty printing when exporting to HTML, you should install the `htmlize` package, which is done by opening emacs and typing the following command:
To have code pretty printing when exporting to HTML, you should install
the `htmlize` package, which is done by opening emacs and typing the
following
command:
``` example
``` example
M-x package-install RET htmlize RET # where M-x means pressing the "Esc" key then the "x" key
M-x package-install RET htmlize RET # where M-x means pressing the "Esc" key then the "x" key
```
```
A simple "reproducible research" emacs configuration
# A simple "reproducible research" emacs configuration
This section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) (/"Mise en place Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help.
(*"Mise en place Emacs/Orgmode"* in French). Watching it before
following the instructions given in this section may help.
Emacs comes with very basic default configuration and it appears like everyone has its own taste. You will for example find [here](https://www.emacswiki.org/emacs/StarterKits) several default Emacs configurations that reflect the preferences of their creators. Likewise the configuration of Org-Mode is incredibly flexible (see for example [the org-mode website](https://orgmode.org/worg/org-configs/index.html) for more references). In the context of this MOOC, we propose you a relatively minimalist one that is rather "*reproducible research*" oriented by adding a few org-mode specific configurations.
Emacs comes with very basic default configuration and it appears like
everyone has its own taste. You will for example find
[here](https://www.emacswiki.org/emacs/StarterKits) several default
Emacs configurations that reflect the preferences of their creators.
Likewise the configuration of Org-Mode is incredibly flexible (see for
example [the org-mode
website](https://orgmode.org/worg/org-configs/index.html) for more
references). In the context of this MOOC, we propose you a relatively
minimalist one that is rather "*reproducible research*" oriented by
adding a few org-mode specific configurations.
Step 0: Backup and download our configuration
## Step 0: Backup and download our configuration
---------------------------------------------
The procedure we propose will wipe your already existing custom Emacs configuration if you have one. **You should thus beforehand make a backup** of `~/.emacs` and of `~/.emacs.d/init.el` (if these files exist).
The procedure we propose will wipe your already existing custom Emacs
configuration if you have one. **You should thus beforehand make a
backup** of `~/.emacs` and of `~/.emacs.d/init.el` (if these files
exist).
Then download [this archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/rr_org_archive.tgz) and uncompress it. It contains the following files and we will refer to them in the following:
and uncompress it. It contains the following files and we will refer to
them in the following:
``` example
``` example
rr_org/init.el
rr_org/init.el
rr_org/journal.org
rr_org/journal.org
```
```
Alternatively, [the files you are looking for are available here](rr_org/).
Alternatively, [the files you are looking for are available
here](rr_org/).
Step 1: Prepare your journal
## Step 1: Prepare your journal
----------------------------
Create an `org/` directory in the top of your home:
Create an `org/` directory in the top of your home:
...
@@ -185,33 +244,42 @@ Create an `org/` directory in the top of your home:
...
@@ -185,33 +244,42 @@ Create an `org/` directory in the top of your home:
mkdir -p ~/org/
mkdir -p ~/org/
```
```
Then copy `rr_org/journal.org` file in your `~/org/` directory. This file will be your laboratory notebook and all the notes you will capture with `C-c c` will go automatically go in this file. The first entry of this notebook is populated with [many Emacs shortcuts](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) that you should give a try.
Then copy `rr_org/journal.org` file in your `~/org/` directory. This
file will be your laboratory notebook and all the notes you will capture
with `C-c c` will go automatically go in this file. The first entry of
Copy `rr_org/init.el` in your `~/.emacs.d/` directory.
Copy `rr_org/init.el` in your `~/.emacs.d/` directory.
Alternatively, if you do not want to mess with your already existing emacs configuration, you may launch emacs with this specific configuration with the following command: `emacs -q -l rr_org/init.el`.
Alternatively, if you do not want to mess with your already existing
emacs configuration, you may launch emacs with this specific
Step 3: Adapt the configuration to your specific needs if required
configuration with the following command: `emacs -q -l rr_org/init.el`.
Open a new instance of Emacs and open a `foo.org` file. Copy the following lines in this file:
Open a new instance of Emacs and open a `foo.org` file. Copy the
following lines in this file:
``` example
``` example
#+begin_src shell :session foo :results output :exports both
#+begin_src shell :session foo :results output :exports both
...
@@ -219,25 +287,50 @@ ls -la # or dir under windows
...
@@ -219,25 +287,50 @@ ls -la # or dir under windows
#+end_src
#+end_src
```
```
Put your cursor inside this code block and execute it with the following command: `C-c C-c` (If you are not familiar with Emacs commands, this one means '`Ctrl + C`' twice)
Put your cursor inside this code block and execute it with the following
command: `C-c C-c` (If you are not familiar with Emacs commands, this
A `#+RESULTS:` block with the result of the command should appear if it worked.
one means '`Ctrl + C`' twice)
In the video, we already have demonstrated the main features and shortcuts of emacs/org-mode that will help you maintain a document and benefit from literate programming. The list of features and shortcuts is demonstrated in the [first entry of your labbook](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org).
A `#+RESULTS:` block with the result of the command should appear if it
worked.
Step 5: Open and play with your journal:
----------------------------------------
In the video, we already have demonstrated the main features and
shortcuts of emacs/org-mode that will help you maintain a document and
In step 1, you were told to create an journal in `~org/journal.org`. First you probably want to make sure this file is stored in a version control system like git. We leave it up to you to set this up but if you have any trouble, feel free to ask on the FUN forums.
benefit from literate programming. The list of features and shortcuts is
This section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) (/"Écrire un article réplicable avec Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help.
In step 1, you were told to create an journal in `~org/journal.org`.
Remember, you need a working LaTeX and R environment. If you can't open a terminal and run the commands `R`, `pdflatex`, and `python`, you will not be able to generate this document. When being compiled, the article downloads the corresponding LaTeX packages so you also need to have a working `wget` command (alternatively, it uses `curl`). Once downloaded, you may still read the source (<https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org>) and understand how it works though.
First you probably want to make sure this file is stored in a version
control system like git. We leave it up to you to set this up but if you
Download the following [archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz), uncompress it and simply `make` to generate the article. You should then be able to open the [resulting article](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf). This is summarized in the following command:
have any trouble, feel free to ask on the FUN forums.
@@ -246,63 +339,99 @@ tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf
...
@@ -246,63 +339,99 @@ tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf
**Possible issues**:
**Possible issues**:
- If the `make` command fails (especially on Mac), it may be because Emacs or something else is not correctly installed. In that case, open the article directly with the following command:
- If the `make` command fails (especially on Mac), it may be because
Emacs or something else is not correctly installed. In that case,
and export it to pdf with the following shortcut: `C-c C-e l o`
and export it to pdf with the following shortcut: `C-c C-e l o`
- If it still doesn't work and emacs complains about not finding ESS, it may be because you installed ESS in your home instead of system-wide. In that case, try to remove the `-q` in the previous command line to load your personal emacs configuration.
Finally, when you'll be tired of always re-executing all the source code when exporting, just look for the following line in [article.org](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org):
- If it still doesn't work and emacs complains about not finding ESS,
it may be because you installed ESS in your home instead of
system-wide. In that case, try to remove the `-q` in the previous
command line to load your personal emacs configuration.
Finally, when you'll be tired of always re-executing all the source code
when exporting, just look for the following line in
If you remove the `# ` in the beginning of the line, it will not be a comment anymore and will indicate org-mode to stop evaluating every chunk of code when exporting.
If you remove the `# ` in the beginning of the line, it will not be a
comment anymore and will indicate org-mode to stop evaluating every
chunk of code when exporting.
Emacs tips and tricks
# Emacs tips and tricks
=====================
Cheat-sheets
## Cheat-sheets
------------
Learning Emacs and Org-Mode can be difficult as there is an inordinate amount of shortcuts. Many people have thus come up with cheat-sheats. Here is a selection in case it helps:
Learning Emacs and Org-Mode can be difficult as there is an inordinate
amount of shortcuts. Many people have thus come up with cheat-sheats.
Here is a selection in case it helps:
### Emacs
### Emacs
- [Common and step-by-step Emacs shortcuts for our *reproducible research* configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
- [Common and step-by-step Emacs shortcuts for our *reproducible
- [The official GNU emacs refcard](https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf)
research*
- Two graphical cheat-sheats by Sacha Chua on  and on .
- [Common and step-by-step org-mode shortcuts for our *reproducible research* configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
- [Common and step-by-step org-mode shortcuts for our *reproducible
- [The official org-mode refcard](https://orgmode.org/worg/orgcard.html)
research*
- [The official description of the org-mode syntax](https://orgmode.org/worg/dev/org-syntax.html) and a [relatively concise description of the org-mode syntax](https://gist.github.com/hoeltgman/3825415).
For those of you who prefer video explanations, here is a [Youtube channel with many step by step emacs tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg).
For those of you who prefer video explanations, here is a [Youtube
[Company-mode](http://company-mode.github.io/) is a text completion framework for Emacs. It allows to have smart completion in emacs for the most common languages. If you feel this is needed, you should follow the instructions from the official Web page: [<http://company-mode.github.io/>](http://company-mode.github.io/)
[Company-mode](http://company-mode.github.io/) is a text completion
framework for Emacs. It allows to have smart completion in emacs for the
most common languages. If you feel this is needed, you should follow the
instructions from the official Web page:
<http://company-mode.github.io/>
### Magit
### Magit
[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is briefly illustrated in the context of this MOOC in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) ("*Utilisation Emacs/git*" in French).
[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is
briefly illustrated in the context of this MOOC in a [video
It is very powerful and we use it on a daily basis but you should definitely understand what git does behind the scenes beforehand. If you feel this would be useful for you, you should follow [this visual walk-through](https://magit.vc/screenshots/) or [this really short "crash course"](https://www.emacswiki.org/emacs/Magit). If you installed the previous "*reproducible research*" emacs configuration, you can easily invoke magit by using `C-x g`.
It is very powerful and we use it on a daily basis but you should
definitely understand what git does behind the scenes beforehand. If you
feel this would be useful for you, you should follow [this visual
walk-through](https://magit.vc/screenshots/) or [this really short
"crash course"](https://www.emacswiki.org/emacs/Magit). If you installed
the previous "*reproducible research*" emacs configuration, you can
**This document is particularly important if you follow the RStudio or the Org-Mode path.****If you follow the Jupyter path, it can be ignored at first****as we have closely integrated Jupyter and GitLab in the context of this MOOC.**
**This document is particularly important if you follow the RStudio or
the Org-Mode path.** **If you follow the Jupyter path, it can be ignored
So far, you only used git via the web interface from the GitLab we deployed for the MOOC: <https://app-learninglab.inria.fr/gitlab/>
at first** **as we have closely integrated Jupyter and GitLab in the
context of this MOOC.**
If you access this link from the FUN platform, you do not have to authenticate and you can readily read and modify all your files. This is very convenient but in most cases, you will want to have your own local copy of the repository and you will have to synchronize your local copy with the remote GitLab one. To propagate your modifications, you will obviously have to authenticate yourself on GitLab.
So far, you only used git via the web interface from the GitLab we
This document describes the software you need to have installed on your machine and how to handle authentication. The "Configuring Git" section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)(in French).
deployed for the MOOC: <https://app-learninglab.inria.fr/gitlab/>
Please read all these instructions carefully, in particular the one on "Configuring your password on GitLab".
If you access this link from the FUN platform, you do not have to
authenticate and you can readily read and modify all your files. This is
Table of Contents<span class="tag" data-tag-name="TOC"></span>
very convenient but in most cases, you will want to have your own local
-[Getting your default password on GitLab (and possibly changing it)](#getting-your-default-password-on-gitlab-and-possibly-changing-it)
(in French).
-[Remembering your password locally](#remembering-your-password-locally)
-[Optional: authenticating through SSH](#optional-authenticating-through-ssh)
Please read all these instructions carefully, in particular the one on
-[Using Git through the command line to synchronize your local files with Gitlab](#using-git-through-the-command-line-to-synchronize-your-local-files-with-gitlab)
"Configuring your password on
GitLab".
Installing Git
==============
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
Linux (Debian, Ubuntu)
-[Installing Git](#installing-git)
----------------------
-[Linux (Debian, Ubuntu)](#linux-debian-ubuntu)
-[Mac OSX and Windows](#mac-osx-and-windows)
We provide here only instructions for Debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g., RedHat, Fedora).
-[Configuring Git](#configuring-git)
-[Telling Git who you are: Name and
Email](#telling-git-who-you-are-name-and-email)
-[Dealing with proxies](#dealing-with-proxies)
-[Getting your default password on GitLab (and possibly changing
3. Confirm that you have set the Git username correctly:
3. Confirm that you have set the Git username correctly:
``` shell
``` shell
git config --global user.name
git config --global user.name
git config --global user.email
git config --global user.email
```
```
``` example
``` example
Mona Lisa
Mona Lisa
email@example.com
email@example.com
```
```
Dealing with proxies
## Dealing with proxies
--------------------
You may be behind a proxy, in which case you may have trouble cloning or fetching from a remote repository or you may get an error like `unable to access ... Couldn't resolve host ...`
You may be behind a proxy, in which case you may have trouble cloning or
fetching from a remote repository or you may get an error like `unable
The `proxyPassword` will be stored in plain text (unencrypted) in your `.gitconfig` file, which you may not want. In that case, remove it from the URL and you will be prompted for it every time it is needed.
The `proxyPassword` will be stored in plain text (unencrypted) in your
`.gitconfig` file, which you may not want. In that case, remove it from
Getting your default password on GitLab (and possibly changing it)
the URL and you will be prompted for it every time it is needed.
**Warning (Jupyter users) :** changing your default Gitlab password will prevent you from committing in Jupyter. You will have to do the extra step of changing your `~/.git-credentials` in the Jupyter environment (possibly several times).
## Getting your default password on GitLab (and possibly changing it)
1. Get your default password using the [Gitlab credentials retrieval tool](https://app-learninglab.inria.fr/jupyterhub/services/password) as described on the [corresponding resource](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85).
**Warning (Jupyter users) :** changing your default Gitlab password will
prevent you from committing in Jupyter. You will have to do the extra
step of changing your `~/.git-credentials` in the Jupyter environment
(possibly several times).
1. Get your default password using the [Gitlab credentials retrieval
The first long and ugly character sequence is your GitLab login/id. It is easy to find once you are logged on gitlab. The second one however is your password and this webpage is the only place where you can find it. We used the FUN authentification mechanism to propagate your credentials so only you can have access to it. You'll need to use this password when trying to propagate some modifications from your computer to GitLab.
</div>
*Note: You have to access this webpage from the FUN platform otherwise you may get a 405 error* *when trying to direcly open <https://app-learninglab.inria.fr/jupyterhub/services/password>.*
The first long and ugly character sequence is your GitLab login/id.
It is easy to find once you are logged on gitlab. The second one
however is your password and this webpage is the only place where
you can find it. We used the FUN authentification mechanism to
propagate your credentials so only you can have access to it. You'll
need to use this password when trying to propagate some
modifications from your computer to GitLab.
*Note: You have to access this webpage from the FUN platform
otherwise you may get a 405 error* *when trying to direcly open
2. Access [GitLab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/5571950188c946e790f06d4bc90fb5f6) from the FUN plateform (click on "Accédez à Gitlab / Access to Gitlab" Button).
</div>
*Note: Again, you have to access Gitlab from the FUN platform otherwise you may get a 405 error* /when trying to direcly open <https://app-learninglab.inria.fr/gitlab/users/sign_in/>.
2. Access
3. Click on the first `Sign in` button (alternatively, you can the login/password you just retrieved and use the second `Sign in` button).
3. Click on the first `Sign in` button (alternatively, you can the
login/password you just retrieved and use the second `Sign in`
button).
<div class="CENTER">
4. If you wish to modify your password, you should go to `Account > Settings > Password` and define your password using the default password you just retrieved. Again, if you use the Jupyter notebooks we have deployed for the MOOC, remember that changing your default Gitlab password will prevent you from committing in Jupyter. You will have to do the extra step of changing your Jupyter `~/.git-credentials` through a Jupyter console (see next section).
</div>
4. If you wish to modify your password, you should go to `Account >
Settings > Password` and define your password using the default
password you just retrieved. Again, if you use the Jupyter notebooks
we have deployed for the MOOC, remember that changing your default
Gitlab password will prevent you from committing in Jupyter. You
will have to do the extra step of changing your Jupyter
`~/.git-credentials` through a Jupyter console (see next section).
<div class="CENTER">
</div>
Remembering your password locally
## Remembering your password locally
---------------------------------
If you clone your repository by simply pasting the GitLab URL, you will be prompted for your login and your password every time you want to propagate your local modifications, which is tedious. This is why you should ask git to remember your login and password as follows
If you clone your repository by simply pasting the GitLab URL, you will
be prompted for your login and your password every time you want to
propagate your local modifications, which is tedious. This is why you
should ask git to remember your login and password as
follows
``` shell
``` shell
git config --global credential.helper cache # remember my password
git config --global credential.helper cache # remember my password
git config --global credential.helper "cache --timeout=3600" # for one hour at most
git config --global credential.helper "cache --timeout=3600" # for one hour at most
```
```
With this setup, you will be prompted for your password but it will be cached in memory and they will not be asked again before an hour. You may want to read [these instructions](https://stackoverflow.com/questions/5343068/is-there-a-way-to-skip-password-typing-when-using-https-on-github) to better understand how all this works.
With this setup, you will be prompted for your password but it will be
cached in memory and they will not be asked again before an hour. You
If you want your password to be permanently remembered, you should use this command
If you want your password to be permanently remembered, you should use
this command
``` shell
``` shell
git config credential.helper store
git config credential.helper store
```
```
Your password will be then stored in a `.git-credentials` file in plain text. On a perfectly secured machine, it may be fine... or not... ;) Use it at your own risk.
Your password will be then stored in a `.git-credentials` file in plain
text. On a perfectly secured machine, it may be fine… or not… ;) Use it
at your own risk.
Optional: authenticating through SSH
## Optional: authenticating through SSH
------------------------------------
There are two ways of authenticating and synchronizing your local repository with GitLab: through HTTPS or through SSH. The first one is what was just described and does not require any particular software installation on your machine so this is what I recommend for this MOOC. Yet, I like the second one better (although is may seem a bit more technical), which is why I describe it here. It consists in installing SSH, creating a pair or private/public keys, and uploading your SSH public key on GitLab. This section provides with information on how to do this.
There are two ways of authenticating and synchronizing your local
repository with GitLab: through HTTPS or through SSH. The first one is
what was just described and does not require any particular software
installation on your machine so this is what I recommend for this MOOC.
Yet, I like the second one better (although is may seem a bit more
technical), which is why I describe it here. It consists in installing
SSH, creating a pair or private/public keys, and uploading your SSH
public key on GitLab. This section provides with information on how to
do this.
### Installing SSH
### Installing SSH
1. Linux (Debian, Ubuntu)
1. Linux (Debian, Ubuntu)
We provide here only instructions for debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g., RedHat, Fedora).
We provide here only instructions for debian-based distributions.
Feel free to contribute to this document to provide up-to-date
information for other distributions (e.g., RedHat, Fedora).
Run (as root):
Run (as root):
``` bash
``` bash
apt-get update ; apt-get install openssh-client
apt-get update ; apt-get install openssh-client
```
```
2. macOS
2. macOS
You do not have anything to do as it is installed by default.
You do not have anything to do as it is installed by default.
3. Windows
3. Windows
You should install the [Putty](https://www.ssh.com/ssh/putty/windows/) client. Once it is installed, look for the section on [generating an SSH key](https://www.ssh.com/ssh/putty/windows/puttygen).
You should install the
[Putty](https://www.ssh.com/ssh/putty/windows/) client. Once it is
installed, look for the section on [generating an SSH
Here are [all the official explanations on how to set up your SSH key on GitLab](https://docs.gitlab.com/ee/ssh/). Alternatively, you may also want to have a look at this video:
Here are [all the official explanations on how to set up your SSH key on
GitLab](https://docs.gitlab.com/ee/ssh/). Alternatively, you may also
This section describes a generic (through the command line) way to synchronize your local files with Gitlab. You will not need this if you follow the Jupyter path. If you follow the RStudio path, all these operations can be done through RStudio and you may want to read [the corresponding instructions](file:///jump_to_id/1a4f58a1efed437c93a9f5c5f15df428). If you follow the Org-Mode path, all these operations can be done through Magit and you may want to read [the corresponding instructions](file:///jump_to_id/508299f7373449a3939faa5b11462bc4).
This section describes a generic (through the command line) way to
synchronize your local files with Gitlab. You will not need this if you
follow the Jupyter path. If you follow the RStudio path, all these
operations can be done through RStudio and you may want to read [the
corresponding
instructions](file:///jump_to_id/1a4f58a1efed437c93a9f5c5f15df428). If
you follow the Org-Mode path, all these operations can be done through
Here are other ways to learn Git through the command line:
Here are other ways to learn Git through the command line:
- The [Software Carpentry git tutorial](http://swcarpentry.github.io/git-novice/)
- The [Software Carpentry git
- The (freely available) Pro Git book ([in English](https://git-scm.com/book/en/v2) or [in French](https://git-scm.com/book/fr/v2)). Reading the first two chapters is enough to get a good start.
Now a directory `mooc-rr` has been created on your computer.
Now a directory `mooc-rr` has been created on your computer.
3. Inspect the repository
3. Inspect the repository
``` shell
``` shell
cd mooc-rr
cd mooc-rr
ls # (Unix)
ls # (Unix)
...
@@ -207,52 +320,82 @@ Now, let's start!
...
@@ -207,52 +320,82 @@ Now, let's start!
```
```
4. Synchronizing to GitLab
4. Synchronizing to GitLab
You should indicate which files to track (`git add`) and commit them locally (`git commit`) before they can be transfered (`git push`) to GitLab. The `git status` will indicate you whether files are tracked/modified/committed/...
You should indicate which files to track (`git add`) and commit them
locally (`git commit`) before they can be transfered (`git push`) to
Let's assume you just created a `fichier.txt` file on the top of the `mooc-rr` directory.
GitLab. The `git status` will indicate you whether files are
tracked/modified/committed/…
Let's assume you just created a `fichier.txt` file on the top of the
`mooc-rr` directory.
``` shell
``` shell
git status
git status
```
```
<div class="CENTER">
</div>
``` shell
``` shell
git add fichier.txt
git add fichier.txt
git status
git status
```
```
<div class="CENTER">
</div>
``` shell
``` shell
git commit -m "message commit"
git commit -m "message commit"
```
```
<div class="CENTER">
</div>
``` shell
``` shell
git status
git status
```
```
<div class="CENTER">
</div>
The file can then be transfered to GitLab:
The file can then be transfered to GitLab:
``` shell
``` shell
git push
git push
```
```
At this point, git will ask you about your login/password unless you followed the previous *Remembering your password locally* instructions.
At this point, git will ask you about your login/password unless you
followed the previous *Remembering your password locally*
N.B.: you will not be allowed to propagate your modifications to GitLab if other modifications (e.g., from someone else) have been propagated in between
instructions.
N.B.: you will not be allowed to propagate your modifications to
GitLab if other modifications (e.g., from someone else) have been
propagated in between
<div class="CENTER">
</div>
5. Synchronizing from Gitlab: to avoid the previous problem, you need to fetch the remote GitLab modifications first and apply them locally.
5. Synchronizing from Gitlab: to avoid the previous problem, you need
to fetch the remote GitLab modifications first and apply them
The following [webpage](https://www.dataquest.io/blog/jupyter-notebook-tips-tricks-shortcuts/) lists several Jupyter tricks (in particular, it illustrates many `IPython magic` commands) that should improve your efficiency (note that this blog post is about two years old so some of the tricks may have been integrated in the default behavior of Jupyter now).
lists several Jupyter tricks (in particular, it illustrates many
Using the Jupyter environment we deployed for this MOOC will allow to easily access any file from your default GitLab project. There are situations however where you may want to play with other notebooks.
`IPython magic` commands) that should improve your efficiency (note that
this blog post is about two years old so some of the tricks may have
Adding a brand new notebook in a given directory
been integrated in the default behavior of Jupyter now).
Simply follow the following steps:
## 1.1 Creating or importing a notebook
1. From the menu: `File -> Open`. You're now in the Jupyter file manager.
2. Navigate to the directory where you want your notebook to be created.
Using the Jupyter environment we deployed for this MOOC will allow to
3. Then from the top right button: `New -> Notebook: Python 3`.
easily access any file from your default GitLab project. There are
4. Give your notebook a name from the menu: `File -> Rename`.
situations however where you may want to play with other notebooks.
N.B.: If you create a file by doing `File -> New Notebook ->
- Adding a brand new notebook in a given directory
Python 3`, the new notebook will be created in the current directory. Moving it afterward is possible but a bit cumbersome (you'll have to go through the Jupyter file manager by following the menu `File -> Open`, then select it, `Shut` it `down`, and `Move` and/or `Rename`).
Simply follow the following steps:
Importing an already existing notebook
1. From the menu: `File -> Open`. You're now in the Jupyter file
If your notebook is already in your GitLab project, then simply synchronize by using the `Git pull` button and use the `File -> Open` menu. Otherwise, imagine, you want to import the [following notebook](https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb) from someone else's repository to re-execute it.
manager.
1. Download the file on your computer. E.g., for this [GitLab hosted notebook](https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb), click on `Open raw` (a small `</>` within a document icon) and save (`Ctrl-S` on most browsers) the content (a long JSON text file).
2. Navigate to the directory where you want your notebook to be
2. Open the Jupyter file manager from the menu `File -> Open` and navigate to the directory where you want to upload your notebook.
created.
3. Then from the top right button, `Upload` the previously downloaded notebook and confirm the upload.
4. Open the freshly uploaded notebook through the Jupyter file manager.
3. Then from the top right button: `New -> Notebook: Python 3`.
1.2 Running R and Python in the same notebook
4. Give your notebook a name from the menu: `File -> Rename`.
---------------------------------------------
N.B.: If you create a file by doing `File -> New Notebook ->
Python 3`, the new notebook will be created in the current
directory. Moving it afterward is possible but a bit cumbersome
(you'll have to go through the Jupyter file manager by following
the menu `File -> Open`, then select it, `Shut` it `down`, and
`Move` and/or `Rename`).
- Importing an already existing notebook
If your notebook is already in your GitLab project, then simply
synchronize by using the `Git pull` button and use the `File ->
Open` menu. Otherwise, imagine, you want to import the [following
Note that this `%%R` notation indicates that R should be used for the whole cell but an other possibility is to use `%R` to have a single line of R within a python cell.
Jupyter is not limited to Python and R. Many other languages are available: [<https://github.com/jupyter/jupyter/wiki/Jupyter-kernels>](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels), including non-free languages like SAS, Mathematica, Matlab... Note that the maturity of these kernels differs widely.
None of these other languages have been deployed in the context of our MOOC but you may want to read the next sections to learn how to set up your own Jupyter on your computer and benefit from these extensions.
Since the question was asked several times, if you really need to stay with SAS, you should know that SAS can be used within Jupyter using either the [Python SASKernel](https://sassoftware.github.io/sas_kernel/) or the [Python SASPy](https://sassoftware.github.io/saspy/) package (step by step explanations about this are given [here](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md)).
Since proprietary software such as SAS cannot easily be inspected, we discourage its use as it hinders reproducibility by essence. But perfection does not exist anyway and using Jupyter literate programming approach allied with systematic control version and environment control will certainly help anyway.
Note that Jupyter notebooks are only a small part of the picture and that Jupyter is now part of a bigger project: [JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906), which allows you to mix various components (including notebooks) in your browser. In the context of this MOOC, our time frame was too short to benefit from JupyterLab which was still under active development. You may, however, prefer JupyterLab when doing an installation on your own computer.
First, download and install the [latest version of Miniconda](https://conda.io/miniconda.html). We use Miniconda version `4.5.4` and Python version `3.6` on our server.
Miniconda is a light version of Anaconda, which includes Python, the Jupyter Notebook, and other commonly used packages for scientific computing and data science.
Then download the [mooc<sub>rr</sub> environment file](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57) and create the environment using conda:
The environment described in the last section should include R, but if you proceeded otherwise and only have Python available in Jupyter, you may want to read the following section.
The environment described in the last section should include R, but if
you proceeded otherwise and only have Python available in Jupyter, you
Here is what we had to install on a recent Debian computer to make sure the notebook export via LaTeX works:
Here is what we had to install on a recent Debian computer to make sure
the notebook export via LaTeX works:
``` shell
``` shell
sudo apt-get install texlive-xetex wkhtmltopdf
sudo apt-get install texlive-xetex wkhtmltopdf
```
```
Obviously, you can convert to html or pdf using the using the `File > Download as > HTML` (or `PDF`) menu option. This can also be done from the command line with the following command:
Obviously, you can convert to html or pdf using the using the `File >
Download as > HTML` (or `PDF`) menu option. This can also be done from
the command line with the following command:
``` bash
``` bash
ipython3 nbconvert --to pdf Untitled.ipynb
ipython3 nbconvert --to pdf Untitled.ipynb
```
```
If you want to use a specific style, then the `nbconvert` exporter should be customized. This is discussed and demoed [here](http://markus-beuckelmann.de/blog/customizing-nbconvert-pdf.html). We encourage you to simply read the [doc of nbconvert](https://nbconvert.readthedocs.io/en/latest/).
If you want to use a specific style, then the `nbconvert` exporter
should be customized. This is discussed and demoed
Instead of going directly through LaTeX and playing too much with the `nbconvert` exporter, an other option consists in exporting to Markdown and playing with [pandoc](https://pandoc.org/). Both approaches work, it's rather a matter of taste.
Instead of going directly through LaTeX and playing too much with the
`nbconvert` exporter, an other option consists in exporting to Markdown
and playing with [pandoc](https://pandoc.org/). Both approaches work,
it's rather a matter of taste.
**Windows**
**Windows**
Download and install MiKTeX from the [MiKTeX webpage](https://miktex.org/download) by choosing the right operating system. You will be prompted to install some specific packages when exporting to pdf.
Download and install MiKTeX from the [MiKTeX
webpage](https://miktex.org/download) by choosing the right operating
system. You will be prompted to install some specific packages when
exporting to pdf.
### • Improving notebook readability
### • Improving notebook readability
Here are a few extensions that can ease your life:
Here are a few extensions that can ease your life:
-[Code folding](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook) to improve readability when browsing the notebook.
to improve readability when browsing the notebook.
``` shell
``` shell
pip3 install jupyter_contrib_nbextensions
pip3 install jupyter_contrib_nbextensions
# jupyter contrib nbextension install --user # not done yet
# jupyter contrib nbextension install --user # not done yet
```
```
-[Hiding code](https://github.com/kirbs-/hide_code) to improve readability when exporting.
- [Hiding code](https://github.com/kirbs-/hide_code) to improve
readability when exporting.
``` bash
``` bash
sudo pip3 install hide_code
sudo pip3 install hide_code
sudo jupyter-nbextension install --py hide_code
sudo jupyter-nbextension install --py hide_code
...
@@ -220,8 +299,28 @@ Here are a few extensions that can ease your life:
...
@@ -220,8 +299,28 @@ Here are a few extensions that can ease your life:
### • Interacting with GitLab and GitHub
### • Interacting with GitLab and GitHub
To ease your experience, we added pull/push buttons that allow you to commit and sync with GitLab. This development was specific to the MOOC but inspired from a previous [proof of concept](https://github.com/Lab41/sunny-side-up). We have recently discovered that someone else developed about at the same time a [rather generic version of this Jupyter plugin](https://github.com/sat28/githubcommit). Otherwise, remember that it is very easy to insert a shell cell in Jupyter in which you can easily issue git commands. This is how we work most of the time.
To ease your experience, we added pull/push buttons that allow you to
commit and sync with GitLab. This development was specific to the MOOC
This being said, you may have noticed that Jupyter keeps a perfect track of the sequence in which cells have been run by updating the "output index". This is a very good property from the reproducibility point of view but depending on your usage, you may find it a bit painful when committing. Some people have thus developed [specific git hooks](https://gist.github.com/pbugnion/ea2797393033b54674af) to ignore these numbers when committing Jupyter notebooks. There is a long an interesting discussion about various options on [StackOverflow](https://stackoverflow.com/questions/18734739/using-ipython-notebooks-under-version-control).
but inspired from a previous [proof of
concept](https://github.com/Lab41/sunny-side-up). We have recently
For those who use [JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906) rather than the plain Jupyter, a specific [JupyterLab git plugin](https://github.com/jupyterlab/jupyterlab-git) has been developed to offer a nice version control experience.
discovered that someone else developed about at the same time a [rather
generic version of this Jupyter
plugin](https://github.com/sat28/githubcommit). Otherwise, remember that
it is very easy to insert a shell cell in Jupyter in which you can
easily issue git commands. This is how we work most of the time.
This being said, you may have noticed that Jupyter keeps a perfect track
of the sequence in which cells have been run by updating the "output
index". This is a very good property from the reproducibility point of
view but depending on your usage, you may find it a bit painful when
committing. Some people have thus developed [specific git
hooks](https://gist.github.com/pbugnion/ea2797393033b54674af) to ignore
these numbers when committing Jupyter notebooks. There is a long an
Cette [page web](https://www.dataquest.io/blog/jupyter-notebook-tips-tricks-shortcuts/)(en anglais) recense un certain nombre d'astuces relatives à l'utilisation de Jupyter (et en particulier des illustrations des nombreuses commandes magiques `IPython magic`) et susceptibles d'améliorer votre efficacité (notez bien que ce billet a plus de deux ans que Jupyter évoluant très rapidement, certaines de ces astuces ou de ces modules complémentaires font maintenant partie du comportement par défaut des versions les plus récentes de Jupyter).
L'environnement Jupyter que nous avons déployé dans le cadre de ce MOOC vous permettra d'accéder très simplement à tout fichier (et en particulier les notebooks des différents exercices que nous avons créés pour vous) de votre projet gitlab par défaut. Il y a néanmoins des situations où vous pouvez vouloir utiliser d'autres notebooks que ceux du MOOC.
(en anglais) recense un certain nombre d'astuces relatives à
l'utilisation de Jupyter (et en particulier des illustrations des
Créer un notebook tout neuf dans un répertoire donné
nombreuses commandes magiques `IPython magic`) et susceptibles
1. À partir du menu: `File -> Open`. Ceci vous permet d'accéder au gestionnaire de fichiers de Jupyter.
d'améliorer votre efficacité (notez bien que ce billet a plus de deux
2. Naviguez jusque dans le répertoire dans lequel vous souhaitez créer votre notebook.
ans que Jupyter évoluant très rapidement, certaines de ces astuces ou de
3. Utilisez le bouton en haut à droite: `New -> Notebook: Python 3`.
ces modules complémentaires font maintenant partie du comportement par
4. Donnez un nom à votre notebook à partir du menu: `File -> Rename`.
défaut des versions les plus récentes de Jupyter).
N.B.: Si vous créez un notebook à partir du menu `File -> New
## 1.1 Création ou import d'un notebook
Notebook -> Python 3`, il sera créé dans le répertoire courant. Le déplacer après coup et un peu pénible. Il vous faudra aller dans le gestionnaire de fichiers de Jupyter (menu `File -> Open`), sélectionner le notebook, l'arrêter (`Shut =down`), puis le déplacer (`Move`) et/ou le renommer (`Rename`).
L'environnement Jupyter que nous avons déployé dans le cadre de ce MOOC
Importer un notebook déja existant
vous permettra d'accéder très simplement à tout fichier (et en
Si le notebook qui vous intéresse est déjà dans votre projet GitLab, il vous suffit de synchroniser la copie de votre Jupyter à l'aide du bouton `Git
particulier les notebooks des différents exercices que nous avons créés
pull` et d'utiliser le menu `File -> Open`. Dans le cas contraire, par exemple si souhaitez importer cet [autre notebook](https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb) rédigé par quelqu'un d'autre, procédez de la façon suivante:
pour vous) de votre projet gitlab par défaut. Il y a néanmoins des
situations où vous pouvez vouloir utiliser d'autres notebooks que ceux
1. Télé-chargez le fichier sur votre répertoire. Pour ce [Notebook hébergé sur un gitLab](https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb), cliquez sur `Open raw` (l'icone avec un petit `</>` ) et sauvegardez (`Ctrl-S` sur la plupart des navigateurs) son contenu (un long fichier texte au format JSON).
du MOOC.
2. Ouvrez le gestionnaire de fichiers de Jupyter via le menu `File ->
Open` et naviguez jusqu'au répertoire où vous souhaitez déposer votre notebook.
- Créer un notebook tout neuf dans un répertoire donné
3. Utilisez le bouton en haut à droite `Upload` pour transférer le document de votre ordinateur vers le serveur Jupyter et confirmez l'upload.
4. Vous pouvez maintenant ouvrir le notebook fraîchement récupéré à l'aide du navigateur de fichiers de Jupyter et réexécuter le code correspondant.
1. À partir du menu: `File -> Open`. Ceci vous permet d'accéder au
gestionnaire de fichiers de Jupyter.
1.2 Exécuter du code R et du code Python dans le même notebook
2. Naviguez jusque dans le répertoire dans lequel vous souhaitez
créer votre notebook.
C'était impossible avec les premières versions de Jupyter mais c'est désormais très facile grâce à la bibliothèque python `rpy2`. Il vous faut tout d'abord ouvrir un notebook python.
3. Utilisez le bouton en haut à droite: `New -> Notebook:
1. Chargez la bibliothèque `rpy2`. Le `%load_ext` est une commande magique jupyter qui charge cette bibliothèque et vous donne accès à de nouvelles commandes magiques.
Python 3`.
4. Donnez un nom à votre notebook à partir du menu: `File ->
Rename`.
N.B.: Si vous créez un notebook à partir du menu `File -> New
Notebook -> Python 3`, il sera créé dans le répertoire courant.
Le déplacer après coup et un peu pénible. Il vous faudra aller
dans le gestionnaire de fichiers de Jupyter (menu `File ->
Open`), sélectionner le notebook, l'arrêter (`Shut =down`), puis
le déplacer (`Move`) et/ou le renommer (`Rename`).
- Importer un notebook déja existant
Si le notebook qui vous intéresse est déjà dans votre projet GitLab,
il vous suffit de synchroniser la copie de votre Jupyter à l'aide du
bouton `Git
pull` et d'utiliser le menu `File -> Open`. Dans le cas contraire,
Cette notation `%%R` indique à Python et à Jupyter et que le langage R doit être utilisé pour évaluer l'ensemble de la cellule. En interne, python (`rpy2`) maintient une session R, lui passe le code de la cellule et récupère le résultat. Jupyter fait alors le nécessaire pour l'afficher correctement. Il est également possible d'utiliser `%R` pour avoir une seule ligne de R au sein d'une cellule python.
doitêtreutilisépourévaluerl'ensemble de la cellule. En interne,
1.3 Autres langages que Python et R
python (`rpy2`) maintient une session R, lui passe le code de la cellule
-----------------------------------
et récupère le résultat. Jupyter fait alors le nécessaire pour
l'affichercorrectement.Ilestégalementpossibled'utiliser `%R` pour
Jupyter tire son nom des langages Julia, Python, et R. Il ne se limite donc pas aux langages Python et R. De nombreux autres langages de programmation sont disponibles: [<https://github.com/jupyter/jupyter/wiki/Jupyter-kernels>](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels), et en particulier des langages non libres comme SAS, Mathematica, Matlab... Notez que la maturité de ces noyaux est très variables.
avoir une seule ligne de R au sein d'unecellulepython.
Nous n'avons déployé aucun de ces autres langages dans le cadre du MOOC mais nous vous invitons à lire les sections suivantes pour apprendre à déployer votre propre instance de jupyter et activer certaines de ses extensions.
## 1.3 Autres langages que Python et R
Puisque la question est posée de façon récurrente, si vous avez besoin d'utiliser le langage SAS plutôt que le langage R, il y a deux façons d'utiliser SAS avec Jupyter: soit avec le noyau [Python SASKernel](https://sassoftware.github.io/sas_kernel/), soit avec la bibliothèque [Python SASPy](https://sassoftware.github.io/saspy/)(des explications détaillés sont données [ici](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md)).
Malgré la qualité et la stabilité de ce langage, SAS n'en reste pas moins un langage propriétaire, ce qui rend l'inspection de ses procédures très difficile et limite la réutilisation des procédures produites par d'autres chercheurs. Nous le déconseillons donc dans un objectif de recherche reproductible mais il faut aussi savoir ne pas être dogmatique. La perfection n'existe pas ;) et, même en utilisant SAS, l'utilisation de la programmation lettrée de Jupyter et d'un contrôle de version (avec gitlab) et d'environnement (avec docker par exemple) se révélera très certainement précieux.
Dans cette section, nous expliquons comment installer, sur votre ordinateur, un environnement Jupyter similaire à celui que nous avons déployé pour ce MOOC.
Nousn'avons déployé aucun de ces autres langages dans le cadre du MOOC
mais nous vous invitons à lire les sections suivantes pour apprendre à
Notez que les notebooks Jupyter ne constituent qu'une petite partie de l'écosystème et que Jupyter fait maintenant partie d'un projet plus large, [JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906), qui permet d'assembler différents composants (dont les notebooks) dans votre navigateur. Dans le cadre de ce MOOC, nous avons manqué de temps pour bénéficier de tout JupyterLab qui était toujours en développement actif. À l'heure actuelle, vous pouvez cependant avoir intérêt à installer tout JupyterLab sur votre ordinateur.
déployer votre propre instance de jupyter et activer certaines de ses
extensions.
2.1 Installation de Jupyter
---------------------------
Puisque la question est posée de façon récurrente, si vous avez besoin
Ces instructions permettent d'obtenir sur votre ordinateur un environnement Jupyter similaire à celui que nous avons déployé dans le cadre du MOOC.
d'utiliser SAS avec Jupyter: soit avec le noyau [Python
SASKernel](https://sassoftware.github.io/sas_kernel/), soit avec la
Téléchargez et installez la [dernière version de Miniconda](https://conda.io/miniconda.html). Sur notre serveur, nous utilisons la version `4.5.4` de Miniconda et la version `3.6` de Python.
Miniconda est une version légère d'Anaconda, une suite logicielle incluant Python, Jupyter, R ainsi que les bibliothèques les plus couramment utilisées en calcul scientifique et en science des données.
Téléchargez ensuite le [fichier d'environnement `mooc_rr` ](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57) et déployez votre environnement à l'aide de conda:
Malgré la qualité et la stabilité de ce langage, SAS n'enrestepas
moinsunlangagepropriétaire,cequirendl'inspection de ses
procédures très difficile et limite la réutilisation des procédures
produites par d'autreschercheurs.Nousledéconseillonsdoncdansun
Si vous avez installé l'environnement de la façon décrite dans la section précédente, vous devriez déjà avoir R à votre disposition et vous n'avez donc rien à faire. Mais si vous avez procédé différemment et n'avez que Python et Jupyter à votre disposition, il vous faudra certainement suivre les étapes suivantes
Si vous avez installé l'environnement de la façon décrite dans la
section précédente, vous devriez déjà avoir R à votre disposition et
vous n'avez donc rien à faire. Mais si vous avez procédé différemment et
n'avez que Python et Jupyter à votre disposition, il vous faudra
certainement suivre les étapes
suivantes
### • Installation de [IRKernel](https://github.com/IRkernel/IRkernel) (R package)
### • Installation de [IRKernel](https://github.com/IRkernel/IRkernel) (R package)
IRKernel vous permettra de faire des notebooks utilisant le langage R plutôt que le langage Python. Nous supposons ici que R est déjà installé et fonctionnel sur votre ordinateur. Dans une console R:
IRKernel vous permettra de faire des notebooks utilisant le langage R
plutôt que le langage Python. Nous supposons ici que R est déjà installé
- Installer la bibliothèque `devtools`:
et fonctionnel sur votre ordinateur. Dans une console R:
- Installer la bibliothèque `devtools`:
``` r
``` r
install.packages('devtools',dep=TRUE)
install.packages('devtools',dep=TRUE)
```
```
- Définissez un proxy si nécessaire (c'est important si votre ordinateur est connecté à une entreprise qui limite l'accès à Internet):
- Définissez un proxy si nécessaire (c'est important si votre
ordinateur est connecté à une entreprise qui limite l'accès à
IRkernel::installspec() # to register the kernel in the current R installation
IRkernel::installspec() # to register the kernel in the current R installation
...
@@ -145,13 +242,18 @@ IRKernel vous permettra de faire des notebooks utilisant le langage R plutôt qu
...
@@ -145,13 +242,18 @@ IRKernel vous permettra de faire des notebooks utilisant le langage R plutôt qu
### • Installation de rpy2 (Python package)
### • Installation de rpy2 (Python package)
La bibliothèque `rpy2` permet à Python d'appeler R et donc de mélanger les deux langages dans le même notebook. Cette bibliothèque est en général disponible sur les distributions récentes. Par exemple sous debian ou ubuntu:
La bibliothèque `rpy2` permet à Python d'appeler R et donc de mélanger
les deux langages dans le même notebook. Cette bibliothèque est en
général disponible sur les distributions récentes. Par exemple sous
debian ou ubuntu:
``` shell
``` shell
sudo apt-get install python3-rpy2 python3-tzlocal
sudo apt-get install python3-rpy2 python3-tzlocal
```
```
Si vous ne disposez pas d'une distribution linux récente, il est possible (mais non recommandé) d'utiliser le gestionnaire de paquets de python:
Si vous ne disposez pas d'une distribution linux récente, il est
possible (mais non recommandé) d'utiliser le gestionnaire de paquets de
python:
``` python
``` python
pip3 install rpy2
pip3 install rpy2
...
@@ -159,9 +261,12 @@ pip3 install rpy2
...
@@ -159,9 +261,12 @@ pip3 install rpy2
**Windows**
**Windows**
Téléchargez le [fichier binaire](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2)`rpy2` en choisissant le bon système d'exploitation.
Téléchargez le [fichier
binaire](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) `rpy2` en
choisissant le bon système d'exploitation.
Ouvrez une console DOS et tapez les commandes suivantes:
@@ -173,45 +278,62 @@ Installez également `tzlocal`:
...
@@ -173,45 +278,62 @@ Installez également `tzlocal`:
python -m pip install tzlocal
python -m pip install tzlocal
```
```
2.3 Conseils additionnels
## 2.3 Conseils additionnels
-------------------------
### • Exporter un notebook
### • Exporter un notebook
Jupyter évolue rapidement et ces informations peuvent vite devenir obsolète mais voici ce qu'il peut être utile d'installer sur une debian récente pour que l'export des notebooks via LaTeX soit fonctionnel:
Jupyter évolue rapidement et ces informations peuvent vite devenir
obsolète mais voici ce qu'il peut être utile d'installer sur une debian
récente pour que l'export des notebooks via LaTeX soit fonctionnel:
``` shell
``` shell
sudo apt-get install texlive-xetex wkhtmltopdf
sudo apt-get install texlive-xetex wkhtmltopdf
```
```
L'export vers HTML ou PDF peut se faire dans Jupyter via le menu `File
L'export vers HTML ou PDF peut se faire dans Jupyter via le menu `File
> Download as > HTML` (ou `PDF`). Il peut également être fait en ligne de commande de la façon suivante:
> Download as > HTML` (ou `PDF`). Il peut également être fait en ligne
de commande de la façon suivante:
``` bash
``` bash
ipython3 nbconvert --to pdf Untitled.ipynb
ipython3 nbconvert --to pdf Untitled.ipynb
```
```
Pour utiliser un style spécifique, il suffit de personnaliser l'exporter `nbconvert`. Cette personnalisation est présentée [ici](http://markus-beuckelmann.de/blog/customizing-nbconvert-pdf.html) mais nous vous encourageons à simplement lire la [documentation de nbconvert](https://nbconvert.readthedocs.io/en/latest/).
Pour utiliser un style spécifique, il suffit de personnaliser l'exporter
Plutôt que de bidouiller trop `nbconvert`, il est aussi possible d'exporter en Markdown et d'utiliser [pandoc](https://pandoc.org/) qui est très flexible. Les deux approches sont possibles, c'est une question de goût.
Plutôt que de bidouiller trop `nbconvert`, il est aussi possible
d'exporter en Markdown et d'utiliser [pandoc](https://pandoc.org/) qui
est très flexible. Les deux approches sont possibles, c'est une question
de goût.
**Windows**
**Windows**
Nous vous conseillons de télécharger et d'installer la distribution MiKTeX à partir du [site web de MiKTeX](https://miktex.org/download) en choisissant le bon système d'exploitation. Lors de votre premier export vers pdf, il vous sera certainement demandé d'installer des packages LaTeX spécifiques.
Nous vous conseillons de télécharger et d'installer la distribution
MiKTeX à partir du [site web de MiKTeX](https://miktex.org/download) en
choisissant le bon système d'exploitation. Lors de votre premier export
vers pdf, il vous sera certainement demandé d'installer des packages
LaTeX spécifiques.
### • Améliorer la lisibilité d'un notebook
### • Améliorer la lisibilité d'un notebook
Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire. Voici quelques extensions qui peuvent vous faciliter un peu la vie:
Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire.
Voici quelques extensions qui peuvent vous faciliter un peu la vie:
- Il est possible [plier/déplier votre code](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook):
# jupyter contrib nbextension install --user # not done yet
# jupyter contrib nbextension install --user # not done yet
```
```
- Il est aussi possible de [contrôler la visibilité des cellules](https://github.com/kirbs-/hide_code), ce qui peut être très utile si on exporte le notebook:
- Il est aussi possible de [contrôler la visibilité des
cellules](https://github.com/kirbs-/hide_code), ce qui peut être
très utile si on exporte le notebook:
``` bash
``` bash
sudo pip3 install hide_code
sudo pip3 install hide_code
sudo jupyter-nbextension install --py hide_code
sudo jupyter-nbextension install --py hide_code
...
@@ -221,8 +343,36 @@ Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire. Voici
...
@@ -221,8 +343,36 @@ Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire. Voici
### • Interaction avec GitLab et GitHub
### • Interaction avec GitLab et GitHub
Pour rendre vous simplifier la vie, nous avons rajouté des boutons `pull/push` dans Jupyter qui vous permettent de synchroniser vos modifications avec GitLab. Ce développement spécifique pour ce MOOC s'est inspiré d'une [preuve de concept](https://github.com/Lab41/sunny-side-up) précédente mais est vraiment *ad hoc*. Indépendemment et à peu près au même moment, une autre personne a développé un [Plugin Jupyter assez générique permettant de se synchroniser avec Gitlab ou Github](https://github.com/sat28/githubcommit). Si cette fonctionnalité vous intéresse, c'est donc une piste intéressante à explorer. Sinon, souvenez vous qu'il est très simple d'insérer une cellule shell dans Jupyter et dans laquelle vous pouvez facilement insérer des commandes git. C'est la façon dont nous travaillons en pratique la majorité du temps.
Pour rendre vous simplifier la vie, nous avons rajouté des boutons
`pull/push` dans Jupyter qui vous permettent de synchroniser vos
Ceci étant dit, vous avez certainement remarqué que Jupyter conserve une trace parfaite de l'ordre dans lequel les cellules ont été exécutées en incrémentant leur "indice". C'est une très bonne propriété d'un point de vue reproductibilité mais il se peut, selon votre usage, que cela s'avère peu pratique du point de vue du suivi de version. Certaines personnes ont donc développé des [git hooks spécifiques](https://gist.github.com/pbugnion/ea2797393033b54674af) permettant d'ignorer ces numéros lorsque l'on committe des notebooks Jupyter. Il y au une longue discussion à ce sujet sur [StackOverflow](https://stackoverflow.com/questions/18734739/using-ipython-notebooks-under-version-control) qui détaille différentes options.
modifications avec GitLab. Ce développement spécifique pour ce MOOC
s'est inspiré d'une [preuve de
Enfin, pour ceux qui utilisent [JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906) plutôt que le Jupyter de base, un [plugin git pour JupyterLab](https://github.com/jupyterlab/jupyterlab-git) a été développé et offre des fonctionnalités de suivi de version dignes d'un IDE classique.
concept](https://github.com/Lab41/sunny-side-up) précédente mais est
vraiment *ad hoc*. Indépendemment et à peu près au même moment, une
autre personne a développé un [Plugin Jupyter assez générique permettant
de se synchroniser avec Gitlab ou
Github](https://github.com/sat28/githubcommit). Si cette fonctionnalité
vous intéresse, c'est donc une piste intéressante à explorer. Sinon,
souvenez vous qu'il est très simple d'insérer une cellule shell dans
Jupyter et dans laquelle vous pouvez facilement insérer des commandes
git. C'est la façon dont nous travaillons en pratique la majorité du
temps.
Ceci étant dit, vous avez certainement remarqué que Jupyter conserve une
trace parfaite de l'ordre dans lequel les cellules ont été exécutées en
incrémentant leur "indice". C'est une très bonne propriété d'un point de
vue reproductibilité mais il se peut, selon votre usage, que cela
s'avère peu pratique du point de vue du suivi de version. Certaines
# 1\. Some examples of LabBooks provided for inspiration
Since a few years, we systematically require any or our students to have a laboratory notebook in org-mode. Most of the time, they start in private repositories but often end up being fully opened. Here are a few ones:
Since a few years, we systematically require any or our students to have
- Luka Stanisic (a former PhD student advised by Arnaud Legrand) starting using this methodology during his Msc and developed further throughout his PhD. Part of his [PhD thesis](http://mescal.imag.fr/membres/luka.stanisic/thesis/thesis.pdf) was actually about designing a methodology for reproducible experiments in large scale distributed systems. You may want to have a look at [his postdoc LabBook](http://starpu-simgrid.gforge.inria.fr/) and to the [report of Léo Villeveygoux](https://framagit.org/lvgx/pfe/blob/master/doc/labbook.org) whom he advised.
a laboratory notebook in org-mode. Most of the time, they start in
- Tom Cornebize is currently a PhD student advised by Arnaud Legrand and during his MSc, he also heavily [loged his activity on Github](https://github.com/Ezibenroc/simulating_mpi_applications_at_scale).
private repositories but often end up being fully opened. Here are a few
-[Lucas Schnorr](https://github.com/schnorr)'s students usually also maintain their journal in a very nice way: [Tais Bellini's BSc.](https://github.com/taisbellini/aiyra/blob/master/LabBook.org), [Arthur Krause's LabBook](https://github.com/mittmann/hpc/blob/master/LabBook.org), [Luca Nesi's LabBook](http://www.inf.ufrgs.br/~llnesi/memory_report/MemoryReport.html).
ones:
-[Martin Quinson](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/)'s students also follow such conventions:
- Ezequiel Torti Lopez, M2R 2014. [Report](https://github.com/mquinson/simgrid-simpar/blob/master/report.org), with both the data provenance and the data analysis included in the appendix.
- Luka Stanisic (a former PhD student advised by Arnaud Legrand)
starting using this methodology during his Msc and developed further
- Gabriel Corona, engineer on SimGrid, 2015-2016. [Journal](https://github.com/randomstuff/simgrid-journal/blob/master/journal.org), [Blog (findings)](http://www.gabriel.urdhr.fr/tags/simgrid/).
throughout his PhD. Part of his [PhD
- Matthieu Nicolas, engineer on PLM, 2014-2016, [Journal](https://github.com/MatthieuNICOLAS/PLM-reporting/blob/master/activity-report.org).
was actually about designing a methodology for reproducible
Org-mode is obviously not the only option and many of our students use am mixture of org-mode, rstudio and jupyter depending on what is more convenient.
experiments in large scale distributed systems. You may want to have
a look at [his postdoc
2. How to report efficiently (by Martin Quinson)
LabBook](http://starpu-simgrid.gforge.inria.fr/) and to the [report
My friend Martin has gathered \[\[<https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/>\]\[an excellent compendium of information and references on his webpage to explain his students what he expects from them\]\]. **I'll therefore simply paraphrase him here** with the most important aspects related to reporting but feel free to read [the original version](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/):
whom he advised.
- Tom Cornebize is currently a PhD student advised by Arnaud Legrand
Reporting
and during his MSc, he also heavily [loged his activity on
-[Lucas Schnorr](https://github.com/schnorr)'s students usually also
I ask you to write a little reporting regularly. Depending on the situation, it may be every day, every week or every month. In any case, your reporting is very important for the following reasons:
maintain their journal in a very nice way: [Tais Bellini's
- It forces you to think about what you are doing, which may help you to unblock your problem by your own. Writing down the problems in a clear way is often sufficient to see the solution appearing.
[Arthur Krause's
- It helps me following your progress even between the meetings. I cannot unblock you if I don't detect that you are on a wrong lead or otherwise blocked.
- It keeps a track of the steps in your work. That's good for the day where you want to write your final report (even if a final report should never be presented in the chronological order). That's good for the next after you who will be supposed to continue you effort, or to build upon it.
[Luca Nesi's
- That person may be yourself (if you go for a PhD program), another intern, myself or even someone else on the Internet: that's what we call Open Science, an effort where everyone can build upon the scientific work of everyone.
with both the data provenance and the data analysis included in
Once you're setup with all software installed and somehow configured, you need to create a reporting file in a place where I can see it and where it won't get lost if your disk crashes or something. Open a dedicated git repository (on github, gitorious, gitlab, ...) for that. After your internship, your report should be archived directly in the source tree of the software that you are working on, if any. But having your reporting located in the source tree may complicate things during your work.
the appendix.
- Betsegaw Lemma, M2R 2017.
Yes, it means that your file will be public at some point, but that's why we call it "Open Science", after all. Also, you should write it in English if possible. The part of your reporting that is called "Journal" (see below) may be written in French if you are more efficient this way but the rest must be in English. Don't make your tone too formal because the file is public. Make it efficient. Nobody will ever blame you for the work you did during an internship a long time ago. If you really want, we can even make this file anonymous. Just speak to me.
You want to write your reporting before leaving work. Weekly reporting should be written on Friday, one or two hours before leaving. That's the best solution to have a nice week end without thinking about work, and still lose no information that you would need on Monday morning.
I ask you to write a little reporting regularly. Depending on the
situation, it may be every day, every week or every month. In any case,
your reporting is very important for the following reasons:
- It forces you to think about what you are doing, which may help you
to unblock your problem by your own. Writing down the problems in a
clear way is often sufficient to see the solution appearing.
- It helps me following your progress even between the meetings. I
cannot unblock you if I don't detect that you are on a wrong lead or
otherwise blocked.
- It keeps a track of the steps in your work. That's good for the day
where you want to write your final report (even if a final report
should never be presented in the chronological order). That's good
for the next after you who will be supposed to continue you effort,
or to build upon it.
- That person may be yourself (if you go for a PhD program), another
intern, myself or even someone else on the Internet: that's what we
call Open Science, an effort where everyone can build upon the
scientific work of everyone.
I want you to write your reporting in an org file (yep, you don't have a
choice here). \[..\]
## Reporting Logistics
Once you're setup with all software installed and somehow configured,
you need to create a reporting file in a place where I can see it and
where it won't get lost if your disk crashes or something. Open a
dedicated git repository (on github, gitorious, gitlab, …) for that.
After your internship, your report should be archived directly in the
source tree of the software that you are working on, if any. But having
your reporting located in the source tree may complicate things during
your work.
Yes, it means that your file will be public at some point, but that's
why we call it "Open Science", after all. Also, you should write it in
English if possible. The part of your reporting that is called "Journal"
(see below) may be written in French if you are more efficient this way
but the rest must be in English. Don't make your tone too formal because
the file is public. Make it efficient. Nobody will ever blame you for
the work you did during an internship a long time ago. If you really
want, we can even make this file anonymous. Just speak to me.
You want to write your reporting before leaving work. Weekly reporting
should be written on Friday, one or two hours before leaving. That's the
best solution to have a nice week end without thinking about work, and
still lose no information that you would need on Monday morning.
## Reporting Document Organization
Your reporting document should have four main parts:
Your reporting document should have four main parts:
Findings
- Findings
This section summarizes the general information that you gathered during your work. It is empty at the beginning of your internship, and gets fleshed with the important things that you find on your way. That's where bibliographical information go, for example. But that's definitely not where TODO notes go (see below).
This section summarizes the general information that you gathered
during your work. It is empty at the beginning of your internship,
Development
and gets fleshed with the important things that you find on your
This section presents the technical sides of your work. Don't write anything in there yet. Put it all in the Journal part for now.
way. That's where bibliographical information go, for example. But
that's definitely not where TODO notes go (see below).
Journal
- Development
Describe the day-to-day work done for each period (day, week or month) of your internship. That's the most important part of your reporting, and we come back to it below.
This section presents the technical sides of your work. Don't write
anything in there yet. Put it all in the Journal part for now.
Conclusion
- Journal
That's what you write in the next week of your internship. You can see it as a letter to the next guy, explaining the current state of your work, a few words about its technical organization, and what should be done next on that topic. Keep this part highly technical, the overall organization of your internship will be seen in your final report.
Describe the day-to-day work done for each period (day, week or
month) of your internship. That's the most important part of your
The Journal part is the only part that you may write in French on need. You want to add one subsection per period to your journal. Don't make it too long, or you would waste time writing long texts that very few will ever read. Don't make it too short or it will be impossible to understand it on Monday morning (or three months after). Finding the good balance is sometimes difficult, but I will provide feedback on your first entries, so don't worry.
reporting, and we come back to it below.
- Conclusion
That's what you write in the next week of your internship. You can
see it as a letter to the next guy, explaining the current state of
your work, a few words about its technical organization, and what
should be done next on that topic. Keep this part highly technical,
the overall organization of your internship will be seen in your
final report.
The Journal part is the only part that you may write in French on need.
You want to add one subsection per period to your journal. Don't make it
too long, or you would waste time writing long texts that very few will
ever read. Don't make it too short or it will be impossible to
understand it on Monday morning (or three months after). Finding the
good balance is sometimes difficult, but I will provide feedback on your
first entries, so don't worry.
Each of section describing a period should contain three subsubsections:
Each of section describing a period should contain three subsubsections:
Things done
- Things done
a few words about what you've done. Something like 2 or 4 items with a few words describing what you've done. You can omit the title of that section and put the items directly in the upper section (see the example below).
a few words about what you've done. Something like 2 or 4 items with
a few words describing what you've done. You can omit the title of
Blocking points and questions
that section and put the items directly in the upper section (see
try to explain clearly the things that block you or slow you down. If you found the solution already, then it should be part of the previous subsection (but you should say a few words nevertheless). Also ask every question that you may have for me in that section. If the question are personal (e.g., about the logistics of your internship such as salary or so), please prefer emails that are not publicly visible. If this section is empty for a given period, skip it all together (no empty subsubsections).
the example below).
- Blocking points and questions
Planned work
try to explain clearly the things that block you or slow you down.
A few items about what you plan to work on during the next period.
If you found the solution already, then it should be part of the
previous subsection (but you should say a few words nevertheless).
A template of reporting file is given at the end of this section. This is just a strong advice: If you really feel better with another file organization, then give it a try for one period, and ask for my feedback. I can adapt, and I do not pretend that my advice is the definitive answer. It's just the result of my experience so far.
Also ask every question that you may have for me in that section. If
the question are personal (e.g., about the logistics of your
Notice how TODO items are written: they are given as items in the Planned work sections of the journal. As explained in the [documentation](http://orgmode.org/manual/Checkboxes.html), you simply have to write "\[\]" in front of items that you plan to do in the future.
internship such as salary or so), please prefer emails that are not
publicly visible. If this section is empty for a given period, skip
You should add a \[1/\] on the "Planned work" line, so that emacs keeps track of what is done and what is still to do. Once they are done, you type C-c C-C on their lines to change the blank box \[\] into a checked box \[X\]. Also, the \[1/\] will be changed to denote the amount of work that is still to be done.
it all together (no empty subsubsections).
- Planned work
At any point, you can see all ongoing TODO items with the following keystrokes: "C-c / t". More information on TODOs in orgmode's [documentation](http://orgmode.org/manual/TODO-basics.html). The important thing here is that most TODO items must only be written in the *Journal* part (so that we know when they occurred).
A few items about what you plan to work on during the next period.
**Do not edit past entries of your journal**, unless you have very good reasons. If you must, make sure that you don't lose information about the path that you took (remember the Open Science thingy). You should always **add** information to past entries, such as:
A template of reporting file is given at the end of this section. This
is just a strong advice: If you really feel better with another file
organization, then give it a try for one period, and ask for my
feedback. I can adapt, and I do not pretend that my advice is the
definitive answer. It's just the result of my experience so far.
Notice how TODO items are written: they are given as items in the
Planned work sections of the journal. As explained in the
[documentation](http://orgmode.org/manual/Checkboxes.html), you simply
have to write "\[\]" in front of items that you plan to do in the
future.
You should add a \[1/\] on the "Planned work" line, so that emacs keeps
track of what is done and what is still to do. Once they are done, you
type C-c C-C on their lines to change the blank box \[\] into a checked
box \[X\]. Also, the \[1/\] will be changed to denote the amount of work
that is still to be done.
At any point, you can see all ongoing TODO items with the following
keystrokes: "C-c / t". More information on TODOs in orgmode's
[documentation](http://orgmode.org/manual/TODO-basics.html). The
important thing here is that most TODO items must only be written in the
*Journal* part (so that we know when they occurred).
**Do not edit past entries of your journal**, unless you have very good
reasons. If you must, make sure that you don't lose information about
the path that you took (remember the Open Science thingy). You should
always **add** information to past entries, such
as:
``` shell
``` shell
- *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information.
- *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information.
```
```
The only exception are TODO entries, that should clearly be rewritten to DONE entries. If you need to adapt your TODO entry (because the initial goal was poorly stated or otherwise), change the initial entry from TODO to CANCELED (or check the box after stating in a subitem that it was not done but canceled, and why), and create a new TODO entry in the current period section.
The only exception are TODO entries, that should clearly be rewritten to
DONE entries. If you need to adapt your TODO entry (because the initial
goal was poorly stated or otherwise), change the initial entry from TODO
to CANCELED (or check the box after stating in a subitem that it was not
done but canceled, and why), and create a new TODO entry in the current
-[1. Quelques exemples de cahiers de notes ou de laboratoires pouvant
-[1. Quelques exemples de cahiers de notes ou de laboratoires pouvant servir de source d'inspiration](#1-quelques-exemples-de-cahiers-de-notes-ou-de-laboratoires-pouvant-servir-de-source-dinspiration)
servir de source
-[2. Comment rendre compte de son activité efficacement](#2-comment-rendre-compte-de-son-activité-efficacement)
Depuis plusieurs années, nous demandons systématiquement à tout étudiant travaillant avec nous tenir à jour un cahier de laboratoire, généralement en org-mode. La plupart du temps, ces documents commencent à être rédigés dans des dépôts privés mais assez souvent ils finissent par être complètement ouverts et mis à disposition du plus grand nombre. En voici quelques-uns:
# 1\. Quelques exemples de cahiers de notes ou de laboratoires pouvant servir de source d'inspiration
- Luka Stanisic (un ancien doctorant d'Arnaud Legrand) a commencé à utiliser cette méthodologie pendant son stage de M2 et a continué à l'améliorer pendant son doctorat. Une partie de sa [thèse](http://mescal.imag.fr/membres/luka.stanisic/thesis/thesis.pdf) a en fait porté sur la conception d'une méthodologie adaptée à la traçabilité et à la reproductibilité des expériences sur les plates-formes de calcul à hautes performances. Vous pourriez donc vouloir jeter un oeil au [cahier de laboratoire tenu pendant son postdoc](http://starpu-simgrid.gforge.inria.fr/) ainsi qu'au [rapport de Léo Villeveygoux](https://framagit.org/lvgx/pfe/blob/master/doc/labbook.org) qu'il a encadré pendant cette même période.
Depuis plusieurs années, nous demandons systématiquement à tout étudiant
- Tom Cornebize est actuellement en thèse sous la supervision d'Arnaud Legrand et comme les autres, pendant son stage de master, il a également intensément [pris des notes sur son activité quotidienne et les a mis à disposition sur Github](https://github.com/Ezibenroc/simulating_mpi_applications_at_scale).
travaillant avec nous tenir à jour un cahier de laboratoire,
- Les étudiants de [Lucas Schnorr](https://github.com/schnorr) sont aussi généralement bien formés à cet exercice de prise de note dans un journal: [Tais Bellini's BSc.](https://github.com/taisbellini/aiyra/blob/master/LabBook.org), [Arthur Krause's LabBook](https://github.com/mittmann/hpc/blob/master/LabBook.org), [Luca Nesi's LabBook](http://www.inf.ufrgs.br/~llnesi/memory_report/MemoryReport.html).
généralement en org-mode. La plupart du temps, ces documents
- Ceux qui travaillent sous la supervision de [Martin Quinson](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/) suivent des conventions similaires:
commencent à être rédigés dans des dépôts privés mais assez souvent ils
- Ezequiel Torti Lopez, pendant son M2 en 2014, a produit un [rapport](https://github.com/mquinson/simgrid-simpar/blob/master/report.org) où les données, leur provenance et leur analyse étaient fournies dans l'annexe.
finissent par être complètement ouverts et mis à disposition du plus
- Gabriel Corona (ingénieur de recherche sur le projet SimGrid, 2015-2016) maintient également un [journal](https://github.com/randomstuff/simgrid-journal/blob/master/journal.org) et un [blog (findings)](http://www.gabriel.urdhr.fr/tags/simgrid/).
- Matthieu Nicolas (ingénieur sur PLM, 2014-2016): [Journal](https://github.com/MatthieuNICOLAS/PLM-reporting/blob/master/activity-report.org).
- Luka Stanisic (un ancien doctorant d'Arnaud Legrand) a commencé à
utiliser cette méthodologie pendant son stage de M2 et a continué à
Org-mode n'est évidemment pas la seule option et il est courant que nos étudiants et collègues utilisent un mélange d'org-mode, rstudio et de jupyter selon ce qui est le plus adapté à leurs besoins du moment.
l'améliorer pendant son doctorat. Une partie de sa
traçabilité et à la reproductibilité des expériences sur les
plates-formes de calcul à hautes performances. Vous pourriez donc
Mon ami Martin a réalisé \[\[<https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/>\]\[une excellente collection d'informations et de références sur sa page web pour expliquer à ses étudiants ce qu'il attends d'eux\]\]. **Je vais donc tout simplement le paraphraser dans cette section** en rappelant les éléments qui me semblent essentiels (mais je vous invite à lire [l'original](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/)).
vouloir jeter un oeil au [cahier de laboratoire tenu pendant son
postdoc](http://starpu-simgrid.gforge.inria.fr/) ainsi qu'au
Je vous demande de rendre compte de votre activité par écrit, régulièrement. Selon la situation, cela peut être chaque jour, chaque semaine ou chaque mois, mais dans tous les cas, votre compte rendu est essentiel pour les raisons suivantes:
- Tom Cornebize est actuellement en thèse sous la supervision d'Arnaud
Legrand et comme les autres, pendant son stage de master, il a
- Ça vous force à réfléchir à ce que vous êtes en train de faire, à prendre du recul, ce qui peut vous permettre de résoudre vos problèmes par vous même. Énoncer clairement votre problème permet souvent de faire apparaître des solutions.
également intensément [pris des notes sur son activité quotidienne
- Ça m'aide à suivre votre progression et à réfléchir à votre problème, même entre deux réunions. Je ne pourrai pas vous aider si je ne sais pas que vous êtes partis dans une mauvaise direction ou même que vous êtes bloqués avec tel ou tel point technique.
et les a mis à disposition sur
- Ça vous permet de garder une trace de votre travail. C'est très précieux le jour où vous aurez à écrire votre rapport final (même si un rapport n'est jamais présenté dans un ordre chronologique).
- C'est aussi précieux pour celui qui viendra après vous et souhaitera repartir de vos travaux, les poursuivre ou les améliorer. Cette personne peut d'ailleurs être vous même dans quelques mois (si vous vous engagez dans une thèse), un autre stagiaire, moi-même ou même un inconnu à l'autre bout du monde et qui a trouvé vos travaux via Internet: c'est ce qu'on appelle la science ouverte, un effort collectif ou chacun peut efficacement s'appuyer sur le travail scientifique de toute autre personne.
- Les étudiants de [Lucas Schnorr](https://github.com/schnorr) sont
aussi généralement bien formés à cet exercice de prise de note dans
Je veux que vous écriviez votre compte rendu d'activité dans un fichier org-mode (et oui, vous n'avez pas le choix! ). \[..\]
Une fois que vous aurez mis en place et plus ou moins configuré tous les logiciels dont vous aurez besoin, il vous faudra créer un fichier dans un endroit auquel je puisse accéder et qui ne sera pas perdu si jamais votre disque dur est endommagé, que vous vous faites voler votre ordinateur, ou autre. Pour cela, commencez par créer un dépôt git (sur github, gitorious, ou gitlab, ...). À la fin de votre stage, votre rapport devra être archivé directement dans l'arborescence du logiciel auquel vous avez contribué. Travailler directement dans cette arborescence pendant votre stage peut cependant être un peu compliqué.
- Ceux qui travaillent sous la supervision de [Martin
Mais, oui, cela veut dire que votre journal sera publique à un moment ou à un autre (après tout, c'est pour ça qu'on parle de science ouverte). Vous avez donc intérêt à écrire votre rapport en Anglais si c'est possible. La partie compte-rendu d'activité (votre "journal") peut être écrite en Français si vous êtes plus efficace ainsi mais le reste doit être rédigé en Anglais. Pas la peine de prendre un ton trop formel sous prétexte que le document a vocation à être publique. Soyez efficace. Personne ne vous tiendra rigueur de ce que vous avez pu écrire à l'occasion de votre stage il y a de nombreuses années. Si vous insistez, il est possible d'anonymiser ou de pseudonymiser ce document, venez m'en parler.
Enfin, il est important d'écrire votre compte rendu avant de quitter votre bureau, tant que les choses sont fraîches dans votre esprit. En plus, cela vous libérera de la charge mentale induite par ce travail de mémorisation. Si vous décidez de faire un reporting hebdomadaire, faites le le vendredi, une ou deux heures avant de partir. C'est la meilleur façon de passer un bon week-end sans avoir à penser à votre travail et de ne perdre aucune information dont vous pourriez avoir besoin lundi matin. Même principe si vous faites un reporting quotidien.
- Ezequiel Torti Lopez, pendant son M2 en 2014, a produit un
- Gabriel Corona (ingénieur de recherche sur le projet SimGrid,
Résultats
2015-2016) maintient également un
Cette section résume les informations que vous avez obtenu à l'occasion de votre recherche. Elle est généralement vide au début de votre stage et prendra du volume au fur et à mesure que vous trouvez des choses. C'est aussi souvent ici qu'atterrissent les références bibliographiques par exemple mais ce n'est clairement pas l'endroit où vous stockez votre liste des choses à faire (TODO).
Cette section présente les aspects techniques de votre travail. N'écrivez rien ici pour l'instant. Mettez tout ce que vous collectez dans la partie Journal.
- Matthieu Nicolas (ingénieur sur PLM, 2014-2016):
C'est ici que vous décrivez votre travail au jour le jour, de façon chronologique (jour, semaine, mois, ...). C'est la partie la plus importante de votre reporting et nous y revenons un peu plus bas.
Org-mode n'est évidemment pas la seule option et il est courant que nos
étudiants et collègues utilisent un mélange d'org-mode, rstudio et de
Conclusion
jupyter selon ce qui est le plus adapté à leurs besoins du moment.
C'est la section que vous écrivez la dernière semaine (ou celle d'après) de votre stage. Vous pouvez la voir comme une lettre à la prochaine personne expliquant l'état actuel de votre travail, avec quelques informations que son organisation technique et ce qui, selon vous, sont les prochaines choses à faire et pourquoi. Cette partie peut-être hautement technique, les tenants et les aboutissants plus globaux de votre stage étant des considérations qui apparaîtront plutôt dans votre rapport final de stage.
# 2\. Comment rendre compte de son activité efficacement
La partie Journal est la seul que vous avez le droit d'écrire en Français si vous êtes plus à l'aise ainsi. Pas la peine de vous "répandre", vous perdriez votre temps à écrire un long texte que très peu de personnes seront susceptibles de lire. Ne la bâclez pour autant car si elle est trop courte elle sera incompréhensible la semaine d'après (ou trois mois plus tard). Trouver le bon équilibre n'est pas toujours simple mais je vous ferai un retour sur vos premières entrées donc ne vous inquiétez pas.
Mon ami Martin a réalisé
Une bonne habitude consiste à ce que chacune des entrées section décrivant une période de travail soit structurée de la façon suivante:
excellente collection d'informations et de références sur sa page web
Travail effectué
pour expliquer à ses étudiants ce qu'il attends d'eux\]\]. **Je vais
quelques mots sur ce que vous avez fait et son contexte. Cela peut prendre la forme d'une petite liste de 2 à 4 entrées sur ce que vous avez fait et pourquoi vous l'avez fait.
donc tout simplement le paraphraser dans cette section** en rappelant
les éléments qui me semblent essentiels (mais je vous invite à lire
essayez d'expliquer clairement les points de blocage que vous rencontrez ou bien les points qui vous gênent et vous ralentissent. Si vous avez finalement déjà trouvé la réponse à ces problèmes, indiquez leu dans la sous-section précédente. C'est aussi ici que vous écrirez toute question que vous aimeriez me poser. Si ce sont des interrogations personnelles (par exemple sur la logistique de votre stage, le logement, votre salaire), utilisez plutôt le mail qui restera privé entre nous (souvenez vous que ce journal a vocation a devenir un document publique). Si cette section est vide pour une période donnée, sautez la tout simplement (ne gardez pas de sous-sections vides).
## Le Reporting
Travaux prévus
Une petite liste détaillant les points auxquels vous comptez vous attaquer dans la période à venir.
Je vous demande de rendre compte de votre activité par écrit,
régulièrement. Selon la situation, cela peut être chaque jour, chaque
Vous trouverez à la fin un modèle de compte rendu d'activité. Un conseil: si vraiment vous vous sentez mieux avec une autre structuration de document, essayez pour une période donnée et on fera le point. Je sais m'adapter et je ne prétends pas avoir la science infuse ni que mes conseils soient la solution ultime et universelle. C'est juste le résultat de mon expérience jusqu'ici.
semaine ou chaque mois, mais dans tous les cas, votre compte rendu est
essentiel pour les raisons suivantes:
Remarquez comment les entrées commençant par le mot-clé TODO apparaissent. On le retrouvera typiquement dans les sections "Travaux prévus" du journal. Comme expliqué dans la [documentation d'org-mode](http://orgmode.org/manual/Checkboxes.html), vous pouvez aussi tout simplement écrire `[ ]` au début de chaque élément d'une liste de choses que vous avez l'intention de faire.
- Ça vous force à réfléchir à ce que vous êtes en train de faire, à
Dans ce cas, en rajoutant un \[1/\] à la fin de la sous-sous-section "Travaux prévus", Emacs tiendra à jour le compte des choses faites et qui restent à faire. Une fois que ce qui est décrit dans l'un des éléments d'une liste est faite, il vous suffit de faire `C-c C-C` sur cette entrée pour transformer le `[ ]` en une version cochée `[X]`. Le \[1/\] sera alors mis à jour pour refléter la quantité de travail restant. Lorsque tout aura été effectué, le mot-clé TODO passera à DONE, ce qui procure un incroyable sentiment de satisfaction. :)
prendre du recul, ce qui peut vous permettre de résoudre vos
problèmes par vous même. Énoncer clairement votre problème permet
À tout moment, vous pouvez avoir accès à l'ensemble des choses à faire (TODO) à l'aide du raccourci clavier suivant: `C-c / t`. Vous trouverez plus d'informations sur les TODOs dans la [documentation d'orgmode](http://orgmode.org/manual/TODO-basics.html). Le point important à retenir ici est que la plupart des TODO doivent apparaître dans la partie journal (afin de savoir quand ils se sont posés).
souvent de faire apparaître des solutions.
- Ça m'aide à suivre votre progression et à réfléchir à votre
**N'éditez jamais les entrées de votre journal a posteriori**, sauf si vous avez vraiment une très bonne raison. Si cela devait arriver, assurez vous que vous ne perdez pas d'informations sur ce que vous avez fait et les choix que vous avez effectués (souvenez vous, science ouverte, tout ça tout ça). Il faut toujours **ajouter** des nouvelles informations aux anciennes, par exemple comme ceci:
problème, même entre deux réunions. Je ne pourrai pas vous aider si
je ne sais pas que vous êtes partis dans une mauvaise direction ou
même que vous êtes bloqués avec tel ou tel point technique.
- Ça vous permet de garder une trace de votre travail. C'est très
précieux le jour où vous aurez à écrire votre rapport final (même
si un rapport n'est jamais présenté dans un ordre chronologique).
- C'est aussi précieux pour celui qui viendra après vous et souhaitera
repartir de vos travaux, les poursuivre ou les améliorer. Cette
personne peut d'ailleurs être vous même dans quelques mois (si vous
vous engagez dans une thèse), un autre stagiaire, moi-même ou même
un inconnu à l'autre bout du monde et qui a trouvé vos travaux via
Internet: c'est ce qu'on appelle la science ouverte, un effort
collectif ou chacun peut efficacement s'appuyer sur le travail
scientifique de toute autre personne.
Je veux que vous écriviez votre compte rendu d'activité dans un fichier
org-mode (et oui, vous n'avez pas le choix\! ). \[..\]
## Logistique
Une fois que vous aurez mis en place et plus ou moins configuré tous les
logiciels dont vous aurez besoin, il vous faudra créer un fichier dans
un endroit auquel je puisse accéder et qui ne sera pas perdu si jamais
votre disque dur est endommagé, que vous vous faites voler votre
ordinateur, ou autre. Pour cela, commencez par créer un dépôt git (sur
github, gitorious, ou gitlab, …). À la fin de votre stage, votre rapport
devra être archivé directement dans l'arborescence du logiciel auquel
vous avez contribué. Travailler directement dans cette arborescence
pendant votre stage peut cependant être un peu compliqué.
Mais, oui, cela veut dire que votre journal sera publique à un moment ou
à un autre (après tout, c'est pour ça qu'on parle de science ouverte).
Vous avez donc intérêt à écrire votre rapport en Anglais si c'est
possible. La partie compte-rendu d'activité (votre "journal") peut être
écrite en Français si vous êtes plus efficace ainsi mais le reste doit
être rédigé en Anglais. Pas la peine de prendre un ton trop formel sous
prétexte que le document a vocation à être publique. Soyez efficace.
Personne ne vous tiendra rigueur de ce que vous avez pu écrire à
l'occasion de votre stage il y a de nombreuses années. Si vous insistez,
il est possible d'anonymiser ou de pseudonymiser ce document, venez m'en
parler.
Enfin, il est important d'écrire votre compte rendu avant de quitter
votre bureau, tant que les choses sont fraîches dans votre esprit. En
plus, cela vous libérera de la charge mentale induite par ce travail de
mémorisation. Si vous décidez de faire un reporting hebdomadaire, faites
le le vendredi, une ou deux heures avant de partir. C'est la meilleur
façon de passer un bon week-end sans avoir à penser à votre travail et
de ne perdre aucune information dont vous pourriez avoir besoin lundi
matin. Même principe si vous faites un reporting quotidien.
## Organisation d'un compte rendu d'activité
Selon moi, une bonne pratique consiste à structurer votre compte rendu
d'activité de la façon suivante:
- Résultats
Cette section résume les informations que vous avez obtenu à
l'occasion de votre recherche. Elle est généralement vide au début
de votre stage et prendra du volume au fur et à mesure que vous
trouvez des choses. C'est aussi souvent ici qu'atterrissent les
références bibliographiques par exemple mais ce n'est clairement
pas l'endroit où vous stockez votre liste des choses à faire (TODO).
- Développement
Cette section présente les aspects techniques de votre travail.
N'écrivez rien ici pour l'instant. Mettez tout ce que vous
collectez dans la partie Journal.
- Journal
C'est ici que vous décrivez votre travail au jour le jour, de façon
chronologique (jour, semaine, mois, …). C'est la partie la plus
importante de votre reporting et nous y revenons un peu plus bas.
- Conclusion
C'est la section que vous écrivez la dernière semaine (ou celle
d'après) de votre stage. Vous pouvez la voir comme une lettre à la
prochaine personne expliquant l'état actuel de votre travail, avec
quelques informations que son organisation technique et ce qui,
selon vous, sont les prochaines choses à faire et pourquoi. Cette
partie peut-être hautement technique, les tenants et les
aboutissants plus globaux de votre stage étant des considérations
qui apparaîtront plutôt dans votre rapport final de stage.
La partie Journal est la seul que vous avez le droit d'écrire en
Français si vous êtes plus à l'aise ainsi. Pas la peine de vous
"répandre", vous perdriez votre temps à écrire un long texte que très
peu de personnes seront susceptibles de lire. Ne la bâclez pour autant
car si elle est trop courte elle sera incompréhensible la semaine
d'après (ou trois mois plus tard). Trouver le bon équilibre n'est pas
toujours simple mais je vous ferai un retour sur vos premières entrées
donc ne vous inquiétez pas.
Une bonne habitude consiste à ce que chacune des entrées section
décrivant une période de travail soit structurée de la façon suivante:
- Travail effectué
quelques mots sur ce que vous avez fait et son contexte. Cela peut
prendre la forme d'une petite liste de 2 à 4 entrées sur ce que vous
avez fait et pourquoi vous l'avez fait.
- Ponts bloquants et questions
essayez d'expliquer clairement les points de blocage que vous
rencontrez ou bien les points qui vous gênent et vous ralentissent.
Si vous avez finalement déjà trouvé la réponse à ces problèmes,
indiquez leu dans la sous-section précédente. C'est aussi ici que
vous écrirez toute question que vous aimeriez me poser. Si ce sont
des interrogations personnelles (par exemple sur la logistique de
votre stage, le logement, votre salaire), utilisez plutôt le mail
qui restera privé entre nous (souvenez vous que ce journal a
vocation a devenir un document publique). Si cette section est vide
pour une période donnée, sautez la tout simplement (ne gardez pas de
sous-sections vides).
- Travaux prévus
Une petite liste détaillant les points auxquels vous comptez vous
attaquer dans la période à venir.
Vous trouverez à la fin un modèle de compte rendu d'activité. Un
conseil: si vraiment vous vous sentez mieux avec une autre structuration
de document, essayez pour une période donnée et on fera le point. Je
sais m'adapter et je ne prétends pas avoir la science infuse ni que mes
conseils soient la solution ultime et universelle. C'est juste le
résultat de mon expérience jusqu'ici.
Remarquez comment les entrées commençant par le mot-clé TODO
apparaissent. On le retrouvera typiquement dans les sections "Travaux
prévus" du journal. Comme expliqué dans la [documentation
aussi tout simplement écrire `[ ]` au début de chaque élément d'une
liste de choses que vous avez l'intention de faire.
Dans ce cas, en rajoutant un \[1/\] à la fin de la sous-sous-section
"Travaux prévus", Emacs tiendra à jour le compte des choses faites et
qui restent à faire. Une fois que ce qui est décrit dans l'un des
éléments d'une liste est faite, il vous suffit de faire `C-c C-C` sur
cette entrée pour transformer le `[ ]` en une version cochée `[X]`. Le
\[1/\] sera alors mis à jour pour refléter la quantité de travail
restant. Lorsque tout aura été effectué, le mot-clé TODO passera à DONE,
ce qui procure un incroyable sentiment de satisfaction. :)
À tout moment, vous pouvez avoir accès à l'ensemble des choses à faire
(TODO) à l'aide du raccourci clavier suivant: `C-c / t`. Vous trouverez
plus d'informations sur les TODOs dans la [documentation
d'orgmode](http://orgmode.org/manual/TODO-basics.html). Le point
important à retenir ici est que la plupart des TODO doivent apparaître
dans la partie journal (afin de savoir quand ils se sont posés).
**N'éditez jamais les entrées de votre journal a posteriori**, sauf si
vous avez vraiment une très bonne raison. Si cela devait arriver,
assurez vous que vous ne perdez pas d'informations sur ce que vous avez
fait et les choix que vous avez effectués (souvenez vous, science
ouverte, tout ça tout ça). Il faut toujours **ajouter** des nouvelles
informations aux anciennes, par exemple comme
ceci:
``` shell
``` shell
- *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information.
- *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information.
```
```
La seule exception à cet édition des entrées passées, ce sont les entrées de type TODO, qui sont dynamiques et ont vocation à être transformées en entrées de type DONE. Si vous réalisez qu'il est utile d'adapter une entrée TODO (parce que l'objectif initial a été mal formulé, est inadapté, que sais je?), faites passer l'entrée d'origine de TODO à CANCELED (et/ou cochez le `[ ]` en indiquant dans une sous-entrée que cette tâche n'a pas été faite mais annulée et pourquoi) et créez une nouvelle entrée TODO dans la section du jour.
La seule exception à cet édition des entrées passées, ce sont les
entrées de type TODO, qui sont dynamiques et ont vocation à être
transformées en entrées de type DONE. Si vous réalisez qu'il est utile
d'adapter une entrée TODO (parce que l'objectif initial a été mal
formulé, est inadapté, que sais je?), faites passer l'entrée d'origine
de TODO à CANCELED (et/ou cochez le `[ ]` en indiquant dans une
sous-entrée que cette tâche n'a pas été faite mais annulée et pourquoi)
et créez une nouvelle entrée TODO dans la section du jour.
-[Examples from the Video](#examples-from-the-video)
-[Examples from the Video](#examples-from-the-video)
-[Other examples](#other-examples)
-[Other examples](#other-examples)
Examples from the Video
# Examples from the Video
=======================
In the MOOC video, I quickly demo how org-mode can be used in various contexts. Here are the (sometimes trimmed) corresponding org-files. These documents depend on many other external data files and are not meant to lead to reproducible documents but it will give you an idea of how it can be organized:
In the MOOC video, I quickly demo how org-mode can be used in various
contexts. Here are the (sometimes trimmed) corresponding org-files.
These documents depend on many other external data files and are not
meant to lead to reproducible documents but it will give you an idea of
how it can be organized:
1.[journal.org](journal.org): an excerpt (I've only left a few code samples and links to some resources on R, Stats, ...) from my own journal. This is a personal document where everything (meeting notes, hacking, random thoughts, ...) goes by default. Entries are created with the `C-c c` shortcut.
1.[journal.org](journal.org): an excerpt (I've only left a few code
2.[labbook<sub>single</sub>.org](labbook_single.org): this is an excerpt from the laboratory notebook [Tom Cornebize](https://cornebize.net/) wrote during his Master thesis internship under my supervision. This a personal labbook. I consider this notebook to be excellent and was the ideal level of details for us to communicate without any ambiguity and for him to move forward with confidence.
samples and links to some resources on R, Stats, …) from my own
3.[paper.org](paper.org): this is an ongoing paper based on the previous labbook of Tom Cornebize. As such it is not reproducible as there are hardcoded paths and uncleaned dependencies but writing it from the labbook was super easy as we just had to cut and paste the parts we needed. What may be interesting is the organization and the org tricks to export to the right LaTeX style. As you may notice, in the end of the document, there is a commented section with emacs commands that are automatically executed when opening the file. It is an effective way to depend less on the `.emacs/init.el` which is generally customized by everyone.
journal. This is a personal document where everything (meeting
4.[labbook<sub>several</sub>.org](labbook_several.org): this is a labbook for a specific project shared by several persons. As a consequence it starts with information about installation, common scripts, has section with notes about all our meetings, a section with information about experiments and an other one about analysis. Entries could have been labeled by who wrote them but there were only a few of us and this information was available in git so we did not bother. In such labbook, it is common to find annotations indicating that such experiment was `:FLAWED:` as it had some issues.
notes, hacking, random thoughts, …) goes by default. Entries are
5.[technical<sub>report</sub>.org](technical_report.org): this is a short technical document I wrote after a colleague sent me a PDF describing an experiment he was conducting and asked me about how reproducible I felt it was. It turned out I had to cut and paste the C code from the PDF, then remove all the line numbers and fix syntax, etc. Obviously I got quite different performance results but writing everything in org-mode made it very easy to generate both HTML and PDF and to explicitly explain how the measurements were done.
created with the `C-c c` shortcut.
2.[labbook<sub>single</sub>.org](labbook_single.org): this is an
excerpt from the laboratory notebook [Tom
Cornebize](https://cornebize.net/) wrote during his Master thesis
internship under my supervision. This a personal labbook. I consider
this notebook to be excellent and was the ideal level of details for
us to communicate without any ambiguity and for him to move forward
with confidence.
3.[paper.org](paper.org): this is an ongoing paper based on the
previous labbook of Tom Cornebize. As such it is not reproducible as
there are hardcoded paths and uncleaned dependencies but writing it
from the labbook was super easy as we just had to cut and paste the
parts we needed. What may be interesting is the organization and the
org tricks to export to the right LaTeX style. As you may notice, in
the end of the document, there is a commented section with emacs
commands that are automatically executed when opening the file. It
is an effective way to depend less on the `.emacs/init.el` which is
generally customized by everyone.
4.[labbook<sub>several</sub>.org](labbook_several.org): this is a
labbook for a specific project shared by several persons. As a
consequence it starts with information about installation, common
scripts, has section with notes about all our meetings, a section
with information about experiments and an other one about analysis.
Entries could have been labeled by who wrote them but there were
only a few of us and this information was available in git so we did
not bother. In such labbook, it is common to find annotations
indicating that such experiment was `:FLAWED:` as it had some
issues.
5.[technical<sub>report</sub>.org](technical_report.org): this is a
short technical document I wrote after a colleague sent me a PDF
describing an experiment he was conducting and asked me about how
reproducible I felt it was. It turned out I had to cut and paste the
C code from the PDF, then remove all the line numbers and fix
syntax, etc. Obviously I got quite different performance results but
writing everything in org-mode made it very easy to generate both
HTML and PDF and to explicitly explain how the measurements were
done.
Other examples
# Other examples
==============
Here are a few links to other kind of examples:
Here are a few links to other kind of examples:
- Slides: all my slides for a series of lectures is available here: <https://github.com/alegrand/SMPE>. Here is a [typical source](https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.org) and the [resulting PDF](https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.pdf)
- Slides: all my slides for a series of lectures is available here:
- Lucas Schnorr, a colleague, maintains:
<https://github.com/alegrand/SMPE>. Here is a [typical
- a set of templates for various computer science journals/conferences: [IEEE](https://github.com/schnorr/ieeeorg), [Wiley](https://github.com/schnorr/wileyorg), [ACM](https://github.com/schnorr/acmorg), [LNCS](https://github.com/schnorr/llncsorg)
- his lecture on programming languages for undergrads: <https://github.com/schnorr/mlp/tree/master/conteudo>
and the [resulting
- John Kitchin is an expert org-mode user and he maintains a very interesting [blog with many interesting tips](http://kitchingroup.cheme.cmu.edu/blog/). You may want to check this [seminar he gave at SciPy](https://www.youtube.com/watch?v=IsSMs-4GlT8&list=FLQp2VLAOlvq142YN3JO3y8w&app=desktop).
Dans les vidéos, je montre rapidement comment org-mode peut être utilisé dans différents contextes (feuille de TD, journal, cahier de laboratoire, article). Voici les fichiers org-mode (quelques fois un peu épurés) correspondant. Ces documents dépendent souvent d'autres fichiers externes et ne sont pas prévu pour permettre de produire directement des documents reproductibles mais ils peuvent vous donner une idée de la façon dont ils peuvent être organisés:
Dans les vidéos, je montre rapidement comment org-mode peut être utilisé
dans différents contextes (feuille de TD, journal, cahier de
laboratoire, article). Voici les fichiers org-mode (quelques fois un peu
épurés) correspondant. Ces documents dépendent souvent d'autres fichiers
externes et ne sont pas prévu pour permettre de produire directement des
documents reproductibles mais ils peuvent vous donner une idée de la
façon dont ils peuvent être organisés:
1.[journal.org](journal.org): ceci est un extrait (je n'ai laissé que quelques exemples de programmes et de liens vers des ressources sur R, les statistiques, etc.) de mon propre journal. C'est un document personnel dans lequel tout ce que je peux faire (notes prises pendant une réunion, petit code vite fait, idées diverses et variées, notes bibliographiques, ...) atterrit par défaut. Les entrées avec la date sont créées automatiquement à l'aide du raccourci `C-c c`.
1.[journal.org](journal.org): ceci est un extrait (je n'ai laissé que
2.[labbook<sub>single</sub>.org](labbook_single.org): ceci est un extrait du cahier de laboratoire tenu par [Tom Cornebize](https://cornebize.net/) pendant son stage de Master sous ma direction. C'est un cahier de laboratoire personnel et que je considère comme excellent car il a le niveau de détail idéal pour nous permettre à la fois de communiquer sans aucune ambiguïté, pour moi, de bien suivre ses avancées, et pour lui, d'avancer dans ses travaux avec confiance.
quelques exemples de programmes et de liens vers des ressources sur
3.[paper.org](paper.org): ceci est un article en cours basé sur le cahier de laboratoire précédent. En l'état, il n'est pas reproductible car il y a plusieurs chemins absolus en dur et des dépendances logicielles non explicitées mais sa rédaction à partir du cahier de laboratoire a vraiment été très facile puisqu'il nous suffisait de copier/coller et d'assembler toutes les parties dont nous avions besoin de rendre compte. Ce qui peut être intéressant, c'est l'organisation de ce document (avec des sections cachées qui récupèrent les données, les traitent et génèrent les figures) ainsi que la configuration org-mode permettant d'exporter avec le bon style LaTeX. Comme vous le remarquerez, il y a à la toute fin du document une section avec des commandes emacs lisp commentées mais qui sont exécutées par emacs à l'ouverture du fichier. C'est une façon simple mais efficace de dépendre le moins possible du `.emacs/init.el` que chacun personnalise à sa convenance.
R, les statistiques, etc.) de mon propre journal. C'est un document
4.[labbook<sub>several</sub>.org](labbook_several.org): ceci est un petit exemple de cahier de laboratoire partagé par plusieurs personnes. Il commence donc par des informations sur les dépendances logicielles à installer, les scripts les plus utiles. On y trouve ensuite une section avec des notes sur nos réunions puis une section avec des informations sur nos expériences et enfin une section sur les analyses de données. Idéalement, chaque entrée devrait être étiquetée par le nom de celui qui l'a écrite mais comme nous étions peu nombreux et que cette information est de toutes façons disponible dans le git, nous ne nous sommes pas embêtés. C'est néanmoins une bonne habitude à prendre car si quelqu'un reformate le document (par exemple en ré-indentant et en changeant les espaces) il devient en général le dernier "propriétaire" de l'ensemble des lignes dans git. Dans ce cahier de laboratoire, vous trouverez également des annotations indiquant que telle ou telle expérience est `:FLAWED:`. Ces annotations ont été réalisées a posteriori, lorsque l'on a réalisé qu'il y avait eu un problème et une petite explication (avec une nouvelle date) est en général alors ajoutée. L'annotation `:FLAWED:` nous permet de conserver l'ensemble des expériences tout en sachant d'un coup d'oeil lesquelles ne doivent pas être prises en compte.
personnel dans lequel tout ce que je peux faire (notes prises
5.[technical<sub>report</sub>.org](technical_report.org): ceci est un petit document technique que j'ai écrit après qu'un collègue m'ai envoyé un document PDF décrivant une expérience qu'il avait réalisé et souhaitait mon avis sur si c'était suffisant d'un point de vue reproductibilité. Il s'est avéré que ré-exécuter le code présenté, j'ai pu copier coller le code C à partir du PDF mais qu'il a fallu que j'enlève tous les numéros de lignes, que je corrige des problèmes de syntaxes introduit par la colorisation syntaxique et le formatage PDF, etc. Évidemment, les résultats de performance que j'ai obtenus étaient assez différents mais en écrivant tout en org-mode, j'ai très facilement et très rapidement pu produire un document à la fois en HTML et en PDF tout en explicitant très précisément comment les mesures étaient effectuées.
pendant une réunion, petit code vite fait, idées diverses et
variées, notes bibliographiques, …) atterrit par défaut. Les
entrées avec la date sont créées automatiquement à l'aide du
raccourci `C-c c`.
2.[labbook<sub>single</sub>.org](labbook_single.org): ceci est un
extrait du cahier de laboratoire tenu par [Tom
Cornebize](https://cornebize.net/) pendant son stage de Master sous
ma direction. C'est un cahier de laboratoire personnel et que je
considère comme excellent car il a le niveau de détail idéal pour
nous permettre à la fois de communiquer sans aucune ambiguïté, pour
moi, de bien suivre ses avancées, et pour lui, d'avancer dans ses
travaux avec confiance.
3.[paper.org](paper.org): ceci est un article en cours basé sur le
cahier de laboratoire précédent. En l'état, il n'est pas
reproductible car il y a plusieurs chemins absolus en dur et des
dépendances logicielles non explicitées mais sa rédaction à partir
du cahier de laboratoire a vraiment été très facile puisqu'il nous
suffisait de copier/coller et d'assembler toutes les parties dont
nous avions besoin de rendre compte. Ce qui peut être intéressant,
c'est l'organisation de ce document (avec des sections cachées qui
récupèrent les données, les traitent et génèrent les figures) ainsi
que la configuration org-mode permettant d'exporter avec le bon
style LaTeX. Comme vous le remarquerez, il y a à la toute fin du
document une section avec des commandes emacs lisp commentées mais
qui sont exécutées par emacs à l'ouverture du fichier. C'est une
façon simple mais efficace de dépendre le moins possible du
`.emacs/init.el` que chacun personnalise à sa convenance.
4.[labbook<sub>several</sub>.org](labbook_several.org): ceci est un
petit exemple de cahier de laboratoire partagé par plusieurs
personnes. Il commence donc par des informations sur les dépendances
logicielles à installer, les scripts les plus utiles. On y trouve
ensuite une section avec des notes sur nos réunions puis une section
avec des informations sur nos expériences et enfin une section sur
les analyses de données. Idéalement, chaque entrée devrait être
étiquetée par le nom de celui qui l'a écrite mais comme nous étions
peu nombreux et que cette information est de toutes façons
disponible dans le git, nous ne nous sommes pas embêtés. C'est
néanmoins une bonne habitude à prendre car si quelqu'un reformate
le document (par exemple en ré-indentant et en changeant les
espaces) il devient en général le dernier "propriétaire" de
l'ensemble des lignes dans git. Dans ce cahier de laboratoire, vous
trouverez également des annotations indiquant que telle ou telle
expérience est `:FLAWED:`. Ces annotations ont été réalisées a
posteriori, lorsque l'on a réalisé qu'il y avait eu un problème et
une petite explication (avec une nouvelle date) est en général alors
ajoutée. L'annotation `:FLAWED:` nous permet de conserver l'ensemble
des expériences tout en sachant d'un coup d'oeil lesquelles ne
doivent pas être prises en compte.
5.[technical<sub>report</sub>.org](technical_report.org): ceci est un
petit document technique que j'ai écrit après qu'un collègue m'ai
envoyé un document PDF décrivant une expérience qu'il avait réalisé
et souhaitait mon avis sur si c'était suffisant d'un point de vue
reproductibilité. Il s'est avéré que ré-exécuter le code présenté,
j'ai pu copier coller le code C à partir du PDF mais qu'il a fallu
que j'enlève tous les numéros de lignes, que je corrige des
problèmes de syntaxes introduit par la colorisation syntaxique et
le formatage PDF, etc. Évidemment, les résultats de performance que
j'ai obtenus étaient assez différents mais en écrivant tout en
org-mode, j'ai très facilement et très rapidement pu produire un
document à la fois en HTML et en PDF tout en explicitant très
précisément comment les mesures étaient effectuées.
Autres exemples
# Autres exemples
===============
Voici à toute fin utile quelques liens vers d'autres types d'exemples:
Voici à toute fin utile quelques liens vers d'autres types d'exemples:
- John Kitchin est un expert org-modiste impliqué dans les questions de recherche reproductible et qui tient à jour un [blog avec une foule d'astuces intéressantes](http://kitchingroup.cheme.cmu.edu/blog/). Vous pourriez vouloir jeter un œil au [séminaire qu'il a donné à SciPy](https://www.youtube.com/watch?v=IsSMs-4GlT8&list=FLQp2VLAOlvq142YN3JO3y8w&app=desktop).
- John Kitchin est un expert org-modiste impliqué dans les questions
- Présentations: l'ensemble des slides que j'utilise pour une série de cours ainsi que pour des présentations sur la recherche reproductible sont disponibles ici: <https://github.com/alegrand/SMPE>. Je n'ai pas fait d'effort particulier pour m'assurer que ça compile sur toutes les machines de la terre mais voici à quoi ressemblent typiquement les [sources](https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.org) avec le [PDF résultant](https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.pdf).
de recherche reproductible et qui tient à jour un [blog avec une
- Lucas Schnorr, un collègue et ami, maintient:
foule d'astuces
- un ensemble de modèles en org-mode pour certaines conférences et journaux en informatique: [IEEE](https://github.com/schnorr/ieeeorg), [Wiley](https://github.com/schnorr/wileyorg), [ACM](https://github.com/schnorr/acmorg), [LNCS](https://github.com/schnorr/llncsorg)
-[Using Git from RStudio](#using-git-from-rstudio)
-[Using Git from RStudio](#using-git-from-rstudio)
-[Cloning a repository](#cloning-a-repository)
-[Cloning a repository](#cloning-a-repository)
-[Modifying a file](#modifying-a-file)
-[Modifying a file](#modifying-a-file)
Installing RStudio
# Installing RStudio
==================
Linux (debian, ubuntu)
## Linux (debian, ubuntu)
----------------------
We provide here only instructions for Debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g., RedHat, Fedora).
We provide here only instructions for Debian-based distributions. Feel
free to contribute to this document to provide up-to-date information
for other distributions (e.g., RedHat, Fedora).
Today, the stable versions of the most common distributions provide recent enough versions of R:
Today, the stable versions of the most common distributions provide
recent enough versions of R:
- Debian (stretch) ships with [R 3.3.3-1](https://packages.debian.org/stretch/r-base), [knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr), and [ggplot 2.2.1](https://packages.debian.org/stretch/r-cran-ggplot2)
- Debian (stretch) ships with
- Ubuntu (bionic 18.04) ships with [R 3.4.4](https://packages.ubuntu.com/bionic/r-base), and [knitr 1.17](https://packages.ubuntu.com/bionic/r-cran-knitr), and [ggplot 2.2.1](https://packages.ubuntu.com/bionic/r-cran-ggplot2)
- Ubuntu (artful 17.04) ships with [R 3.4.2](https://packages.ubuntu.com/artful/r-base), and [knitr 1.15](https://packages.ubuntu.com/artful/r-cran-knitr), and [ggplot 2.2.1](https://packages.ubuntu.com/artful/r-cran-ggplot2)
Alternatively, if the installation of `r-cran-gplot2` or `r-cran-knitr` fails, you may want to install them locally (through the R packaging system) and manually by running the following commands in R (or RStudio):
Alternatively, if the installation of `r-cran-gplot2` or `r-cran-knitr`
fails, you may want to install them locally (through the R packaging
system) and manually by running the following commands in R (or
RStudio):
``` r
``` r
install.packages("knitr")
install.packages("knitr")
install.packages("ggplot2")
install.packages("ggplot2")
```
```
If you plan to export pdf documents with LaTeX, you probably also want to run (as root):
If you plan to export pdf documents with LaTeX, you probably also want
RStudio is unfortunately not packaged within Debian so the easiest is to download the corresponding Debian package on the [RStudio webpage](https://www.rstudio.com/products/rstudio/download/#download) and then to install it manually (you may have to adjust the version number in the following example). Here is how to install it:
RStudio is unfortunately not packaged within Debian so the easiest is to
download the corresponding Debian package on the [RStudio
> Some instructions on installing R and knitr must be missing. This should be tested and improved.
> Some instructions on installing R and knitr must be missing. This
> should be tested and improved.
- Download and install R from the [CRAN webpage](https://cran.r-project.org/) by choosing the right operating system.
- Download and install R from the [CRAN
- Download and install RStudio from the [RStudio webpage](https://www.rstudio.com/products/rstudio/download/#download) by choosing the right operating system.
webpage](https://cran.r-project.org/) by choosing the right
- Download and install MiKTeX from the [MiKTeX webpage](https://miktex.org/download) by choosing the right operating system. You will be prompted to install some specific packages when exporting to pdf.
operating system.
- Open RStudio and type the following commands in the console to install `knitr` and `ggplot2`:
webpage](https://miktex.org/download) by choosing the right
operating system. You will be prompted to install some specific
packages when exporting to pdf.
- Open RStudio and type the following commands in the console to
install `knitr` and `ggplot2`:
<!-- end list -->
``` r
``` r
install.packages("knitr",dep=TRUE)
install.packages("knitr",dep=TRUE)
install.packages("ggplot2",dep=TRUE)
install.packages("ggplot2",dep=TRUE)
```
```
RStudio documentation
# RStudio documentation
=====================
The RStudio team has created a lot of very good material and tutorials.
The RStudio team has created a lot of very good material and tutorials. You should definitively look at the [Cheat sheets webpage](https://www.rstudio.com/resources/cheatsheets/). In particular you may want to have look at the following ones:
You should definitively look at the [Cheat sheets
webpage](https://www.rstudio.com/resources/cheatsheets/). In particular
-[R Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf)(here is also a [nice step-by-step presentation of Rmarkdown](https://rmarkdown.rstudio.com/)),
- The [R Markdown Reference guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf),
-[The RStudio
-[Data visualization with ggplot2](https://github.com/rstudio/cheatsheets/raw/master/data-visualization-2.1.pdf),
In case it helps, here are some (sometimes outdated) French versions of
If you have never used git with RStudio, **we strongly advise that you follow [our tutorial on using git from RStudio](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/d132a854b0464ad29085cedaded23136)** (/"RStudio et Gitlab"/ in French). Before proceeding, make sure you also have followed the **["git/GitLab configuration" tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)** (in French).
these documents:
Alternatively, you may want to watch [this video](https://www.youtube.com/embed/uHYcDQDbMY8)(in English). If you do not like videos, you should have a look at the [step-by-step explanations from Software Carpentry](https://swcarpentry.github.io/git-novice/14-supplemental-rstudio/index.html). It comes with many screenshots and is quite progressive.
It comes with many screenshots and is quite progressive.
## Cloning a repository
Open RStudio and do the following steps:
Open RStudio and do the following steps:
- Create a new version controled project: `File / New Project / Version Control`
- Create a new version controled project: `File / New Project /
Version Control`
<divclass="CENTER">
</div>
- Get the URL from your GitLab repository:
- Get the URL from your GitLab repository:
<divclass="CENTER">
- Indicate this URL in the "Repository URL" field (*you may want to prefix this URL with `xxx@` where `xxx` is**your Gitlab id to avoid repeatedly giving it later on*).
</div>
- Indicate this URL in the "Repository URL" field (*you may want to
prefix this URL with `xxx@` where `xxx` is* *your Gitlab id to avoid
repeatedly giving it later on*).
<divclass="CENTER">
</div>
- If you're behind a proxy, git should be configured accordingly.
- If you're behind a proxy, git should be configured accordingly. Check the ["Dealing with proxies" section](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85).
- Git will then connect to Gitlab and fetch a whole copy of the
- Git will then connect to Gitlab and fetch a whole copy of the repository.
repository.
- RStudio should restart in a mode related to Git:
- RStudio should restart in a mode related to Git:
<divclass="CENTER">
</div>
- The file manager on the right, allows you to browse the version controled repository.
- The file manager on the right, allows you to browse the version
controled repository.
Modifying a file
## Modifying a file
----------------
- Open `Module2/exo1/toy_document.Rmd` and perform a simple modification.
- Open `Module2/exo1/toy_document.Rmd` and perform a simple
- Save
modification.
- Go to the Git menu to commit
- Save
- Go to the Git menu to commit
<divclass="CENTER">
</div>
- Select the lines to commit and then click on `commit`
- Select the lines to commit and then click on `commit`
<divclass="CENTER">
Your modifications have now been commited on your local machine. They haven't been propagated to GitLab yet.
</div>
- Click on `push` to propagate them on GitLab
Your modifications have now been commited on your local machine.
They haven't been propagated to GitLab yet.
- Click on `push` to propagate them on GitLab
<divclass="CENTER">
**NB**: You won't be able to propagate your modifications on GitLab if some modifications have been done on GitLab in the meantime. 
</div>
- You should first merge these remote modifications locally. Click on `pull` to get these modifications on your machine.
**NB**: You won't be able to propagate your modifications on GitLab
if some modifications have been done on GitLab in the meantime.
- You should first merge these remote modifications locally. Click on
`pull` to get these modifications on your machine.
-[Utiliser Git avec RStudio](#utiliser-git-avec-rstudio)
-[Utiliser Git avec RStudio](#utiliser-git-avec-rstudio)
-[Cloner un dépôt](#cloner-un-dépôt)
-[Cloner un dépôt](#cloner-un-dépôt)
-[Modifier un fichier](#modifier-un-fichier)
-[Modifier un fichier](#modifier-un-fichier)
Installer RStudio
# Installer RStudio
=================
Linux (debian, ubuntu)
## Linux (debian, ubuntu)
----------------------
Nous ne fournissons ici que des instructions pour les distributions basées sur Debian. N’hésitez pas à contribuer à ce document en fournissant des informations à jour sur les autres distributions (RedHat, Fedora, par exemple).
Nous ne fournissons ici que des instructions pour les distributions
basées sur Debian. N’hésitez pas à contribuer à ce document en
fournissant des informations à jour sur les autres distributions
(RedHat, Fedora, par exemple).
Aujourd'hui, les versions stables des distributions les plus courantes fournissent des versions assez récentes de R :
Aujourd'hui, les versions stables des distributions les plus courantes
fournissent des versions assez récentes de R :
- Debian (stretch) est livré avec [R 3.3.3-1](https://packages.debian.org/stretch/r-base), [knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr), et [ggplot 2.2.1](https://packages.debian.org/stretch/r-cran-ggplot2)
- Debian (stretch) est livré avec
- Ubuntu (bionic 18.04) est livré avec [R 3.4.4](https://packages.ubuntu.com/bionic/r-base), [knitr 1.17](https://packages.ubuntu.com/bionic/r-cran-knitr), et [ggplot 2.2.1](https://packages.ubuntu.com/bionic/r-cran-ggplot2)
- Ubuntu (artful 17.04) est livré avec [R 3.4.2](https://packages.ubuntu.com/artful/r-base), [knitr 1.15](https://packages.ubuntu.com/artful/r-cran-knitr), et [ggplot 2.2.1](https://packages.ubuntu.com/artful/r-cran-ggplot2)
[knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr), et
Si l'installation de `r-cran-knitr` ou `r-cran-gplot2` échoue, vous pouvez également installer ces packages manuellement en exécutant les commandes suivantes sous R (ou RStudio) :
Si l'installation de `r-cran-knitr` ou `r-cran-gplot2` échoue, vous
pouvez également installer ces packages manuellement en exécutant les
commandes suivantes sous R (ou RStudio) :
``` r
``` r
install.packages("knitr")
install.packages("knitr")
install.packages("ggplot2")
install.packages("ggplot2")
```
```
Si vous envisagez d'exporter des documents pdf avec LaTeX, il faudra probablement aussi exécuter (à la racine) :
Si vous envisagez d'exporter des documents pdf avec LaTeX, il faudra
RStudio n’est malheureusement pas intégré à Debian. Le plus simple est de télécharger le paquet Debian correspondant sur le [site RStudio](https://www.rstudio.com/products/rstudio/download/#download), puis de l’installer manuellement (vous devrez peut-être adapter le numéro de version) :
RStudio n’est malheureusement pas intégré à Debian. Le plus simple est
de télécharger le paquet Debian correspondant sur le [site
- Télécharger et installer R depuis le [site CRAN](https://cran.r-project.org/) en choisissant le bon système d'exploitation.
- Télécharger et installer R depuis le [site
- Télécharger et installer RStudio depuis le [site RStudio](https://www.rstudio.com/products/rstudio/download/#download) en choisissant le bon système d'exploitation.
CRAN](https://cran.r-project.org/) en choisissant le bon système
- Télécharger et installer MiKTeX depuis le [site MiKTeX](https://miktex.org/download) en choisissant le bon système d'exploitation. Vous serez amené à installer différents packages lors du premier export pdf.
d'exploitation.
- Ouvrir RStudio et exécuter les commandes suivantes dans la console pour installer `knitr` et `ggplot2`
- Télécharger et installer RStudio depuis le [site
MiKTeX](https://miktex.org/download) en choisissant le bon système
d'exploitation. Vous serez amené à installer différents packages
lors du premier export pdf.
- Ouvrir RStudio et exécuter les commandes suivantes dans la console
pour installer `knitr` et `ggplot2`
<!-- end list -->
``` r
``` r
install.packages("knitr",dep=TRUE)
install.packages("knitr",dep=TRUE)
install.packages("ggplot2",dep=TRUE)
install.packages("ggplot2",dep=TRUE)
```
```
Documentation RStudio
# Documentation RStudio
=====================
L’équipe de RStudio a créé différents matériels et tutoriels très bien
L’équipe de RStudio a créé différents matériels et tutoriels très bien faits. Nous vous recommandons de consulter les [fiches mémo](https://www.rstudio.com/resources/cheatsheets/). En particulier, vous pourriez être intéressés par celles-ci :
faits. Nous vous recommandons de consulter les [fiches
mémo](https://www.rstudio.com/resources/cheatsheets/). En particulier,
-[R Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf)(here is also a [nice step-by-step presentation of Rmarkdown](https://rmarkdown.rstudio.com/)),
- The [R Markdown Reference guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf),
-[RStudio
-[Data visualization with ggplot2](https://github.com/rstudio/cheatsheets/raw/master/data-visualization-2.1.pdf),
Voici aussi les versions françaises de certains documents mais elles ne
La première chose à faire est de configurer Git sur votre ordinateur. Pour ce faire, vous pouvez suivre la vidéo [configurer Git pour Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)(en français) et le document [Git et Gitlab](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/gitlab_fr.org) correspondant (en français).
sont pas toujours à jour :
Vous pourrez alors utiliser Git avec RStudio. Pour ce faire, vous pouvez suivre la vidéo [RStudio - Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/d132a854b0464ad29085cedaded23136)(en français) dont les étapes sont reprises ci-dessous.
*(Nous vous signalons aussi cette*[vidéo](https://www.youtube.com/embed/uHYcDQDbMY8)*(en anglais) ainsi que le*[tuto pas à pas](https://swcarpentry.github.io/git-novice/14-supplemental-rstudio/index.html)*(en anglais) de Software Carpentry.)*
- Créer un nouveau projet sous contrôle de version : `File / New
- Créer un nouveau projet sous contrôle de version : `File / New
Project / Version Control`
Project / Version Control`
<divclass="CENTER">
</div>
- Récupérer l'URL du dépôt Gitlab
- Récupérer l'URL du dépôt Gitlab
<divclass="CENTER">
- Indiquez cette URL dans le champ "Repository URL" *(vous voudrez**peut-être préfixer cette URL avec `xxx@` où `xxx` est votre identifiant**Gitlab pour éviter d'avoir à le ressaisir ultérieurement)*.
</div>
- Indiquez cette URL dans le champ "Repository URL" *(vous voudrez*
*peut-être préfixer cette URL avec `xxx@` où `xxx` est votre
identifiant* *Gitlab pour éviter d'avoir à le ressaisir
ultérieurement)*.
<divclass="CENTER">
</div>
- Si vous êtes derrière un proxy, il faut le définir dans Git (voir le
paragraphe "Gérer les proxy" de la page sur [Git et
- Si vous êtes derrière un proxy, il faut le définir dans Git (voir le paragraphe "Gérer les proxy" de la page sur [Git et Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)).
- Git se connecte à Gitlab et récupère une copie complète du dépôt.
- Git se connecte à Gitlab et récupère une copie complète du dépôt.
- RStudio redémarre dans un mode lié à Git :
- RStudio redémarre dans un mode lié à Git :
<divclass="CENTER">
</div>
- Le gestionnaire de fichiers à droite vous permet de parcourir le dépôt sous contrôle de version.
- Le gestionnaire de fichiers à droite vous permet de parcourir le
dépôt sous contrôle de version.
Modifier un fichier
## Modifier un fichier
-------------------
- Ouvrir le fichier `Module2/exo1/toy_document.Rmd` et le modifier.
- Ouvrir le fichier `Module2/exo1/toy_document.Rmd` et le modifier.
- Enregistrer.
- Aller dans le menu Git pour effectuer le commit.
- Enregistrer.
- Aller dans le menu Git pour effectuer le commit.
<divclass="CENTER">
</div>
- Sélectionner les lignes à commiter puis cliquer sur `commit`.
- Sélectionner les lignes à commiter puis cliquer sur `commit`.
<divclass="CENTER">
Les modifications ont été commitées uniquement sur la machine. Elles n'ont pas été propagées sur Gitlab.
</div>
- Cliquer sur `push` pour les propager sur Gitlab.
Les modifications ont été commitées uniquement sur la machine. Elles
n'ont pas été propagées sur Gitlab.
- Cliquer sur `push` pour les propager sur Gitlab.
<divclass="CENTER">
**NB :** Vous ne pouvez pas propager vos modifications sur GitLab si des modifications ont été faites sur GitLab entre-temps.
</div>
**NB :** Vous ne pouvez pas propager vos modifications sur GitLab si
des modifications ont été faites sur GitLab entre-temps.
<divclass="CENTER">
</div>
- Il faut d’abord récupérer ces modifications distantes sur votre machine locale. Pour ce faire cliquer sur `pull`.
- Il faut d’abord récupérer ces modifications distantes sur votre
- Wray: combining data across centuries, exchange rate regimes,
*Growth in a Time of Debt*
- Herndon, Ash et Pollin
- Wray: combining data across centuries, exchange rate regimes,
Functional MRI
## Functional MRI
--------------
- 2010: [Bennett et al. and the dead salmon](https://www.researchgate.net/publication/255651552_Neural_correlates_of_interspecies_perspective_taking_in_the_post-mortem_Atlantic_Salmon_an_argument_for_multiple_comparisons_correction) ☺
- 2010: [Bennett et al. and the dead
- 2016: [Eklund, Nichols, and Knutsson](http://www.pnas.org/content/113/28/7900.abstract). [A bug in fmri software could invalidate 15 years of brain research](http://www.sciencealert.com/a-bug-in-fmri-software-could-invalidate-decades-of-brain-research-scientists-discover)(*40 000 articles*)
-[Oncology](http://www.nature.com/nrd/journal/v10/n9/full/nrd3439-c1.html?foxtrotcallback=true): "*half of published studies, even in prestigious journals, can't be reproduced in industrial labs*"
-[Psychology](http://theconversation.com/we-found-only-one-third-of-published-psychology-research-is-reliable-now-what-46596): "*attempting to reproduce 100 previously published findings*, *only one-third of published psychology research was found to be reliable*"
"*half of published studies, even in prestigious journals, can't be
-[Programming and data manipulation mistakes in Genomics](https://qz.com/768334/years-of-genomics-research-is-riddled-with-errors-thanks-to-a-bunch-of-botched-excel-spreadsheets/)
- 2010: [Bennett et al.: le saumon mort](https://www.researchgate.net/publication/255651552_Neural_correlates_of_interspecies_perspective_taking_in_the_post-mortem_Atlantic_Salmon_an_argument_for_multiple_comparisons_correction) ☺
-[Reinhart et
- 2016: [Eklund, Nichols, and Knutsson](http://www.pnas.org/content/113/28/7900.abstract). [Un bug dans les logiciels d'IRM pourrait invalider 15 années de recherche sur le cerveau](http://www.sciencealert.com/a-bug-in-fmri-software-could-invalidate-decades-of-brain-research-scientists-discover)(*40 000 articles*)
- 2016: C'est [plus subtil que ça](https://www.cogneurosociety.org/debunking-the-myth-that-fmri-studies-are-invalid/). [D'après Nichols, un des auteurs de l'article d'origine](http://blogs.warwick.ac.uk/nichols/entry/bibliometrics_of_cluster/), c'est plutôt de l'ordre de *3 600 études qui seraient potentiellement impactées*.
*Growth in a Time of Debt*
- Herndon, Ash et Pollin
Les fausses structures de protéines
- Wray: combining data across centuries, exchange rate regimes,
-[Oncologie](http://www.nature.com/nrd/journal/v10/n9/full/nrd3439-c1.html?foxtrotcallback=true): "*half of published studies, even in prestigious journals, can't be reproduced in industrial labs*"
-[Psychologie](http://theconversation.com/we-found-only-one-third-of-published-psychology-research-is-reliable-now-what-46596): "*attempting to reproduce 100 previously published findings*, *only one-third of published psychology research was found to be reliable*"
dans les logiciels d'IRM pourrait invalider 15 années de recherche
-[Enquoi les ordinateurs ont "cassé" la science](http://theconversation.com/how-computers-broke-science-and-what-we-can-do-to-fix-it-49938)
c'est plutôt de l'ordre de *3 600 études qui seraient
-[Erreurs de programmation et de manipulation de données en génomique](https://qz.com/768334/years-of-genomics-research-is-riddled-with-errors-thanks-to-a-bunch-of-botched-excel-spreadsheets/)
potentiellement impactées*.
Tout rendre publique ?
## Les fausses structures de protéines
----------------------
[A "buggy
- Quelqu'un pourrait [tirer parti de mon dur labeur](http://www.nature.com/news/the-top-100-papers-1.16224)
When taking notes, it may be difficult to remember which version of the code or of a file was used. This is what version control is useful for. Here are a few useful commands that we typically insert at the top of our notebooks in shell cells
When taking notes, it may be difficult to remember which version of the
code or of a file was used. This is what version control is useful for.
Here are a few useful commands that we typically insert at the top of
our notebooks in shell cells
``` shell
``` shell
git log -1
git log -1
...
@@ -65,9 +76,12 @@ Untracked files:
...
@@ -65,9 +76,12 @@ Untracked files:
no changes added to commit (use "git add" and/or "git commit -a")
no changes added to commit (use "git add" and/or "git commit -a")
```
```
*Note: the -u indicates that git should also display the contents of new directories it did not previously know about.*
*Note: the -u indicates that git should also display the contents of new
directories it did not previously know about.*
Then, we often include commands at the end of our notebook indicating how to commit the results (adding the new files, committing with a clear message and pushing). E.g.,
Then, we often include commands at the end of our notebook indicating
how to commit the results (adding the new files, committing with a clear
message and pushing). E.g.,
``` shell
``` shell
git add resources.org;
git add resources.org;
...
@@ -87,15 +101,17 @@ To gitlab.inria.fr:learninglab/mooc-rr/mooc-rr-ressources.git
...
@@ -87,15 +101,17 @@ To gitlab.inria.fr:learninglab/mooc-rr/mooc-rr-ressources.git
6359f8c..1f8a567 master -> master
6359f8c..1f8a567 master -> master
```
```
Obviously, in this case you need to save the notebook before running this cell, hence the output of this final command (with the new git hash) will not be stored in the cell. This is not really a problem and is the price to pay for running git from within the notebook itself.
Obviously, in this case you need to save the notebook before running
this cell, hence the output of this final command (with the new git
hash) will not be stored in the cell. This is not really a problem and
is the price to pay for running git from within the notebook itself.
Getting information about Python(3) libraries
# Getting information about Python(3) libraries
=============================================
Getting information about your system
## Getting information about your system
-------------------------------------
This topic is discussed on [StackOverflow](https://stackoverflow.com/questions/3103178/how-to-get-the-system-info-with-python).
This topic is discussed on [StackOverflow](https://stackoverflow.com/questions/20180543/how-to-check-version-of-python-modules). When using `pip` (the Python package installer) within a shell command, it is easy to query the version of all installed packages (note that on your system, you may have to use either `pip` or `pip3` depending on how it is named and which versions of Python are available on your machine
When using `pip` (the Python package installer) within a shell command,
it is easy to query the version of all installed packages (note that on
your system, you may have to use either `pip` or `pip3` depending on how
it is named and which versions of Python are available on your machine
Here is for example how I get this information on my machine:
Here is for example how I get this information on my machine:
...
@@ -137,7 +157,10 @@ wcwidth==0.1.7
...
@@ -137,7 +157,10 @@ wcwidth==0.1.7
webencodings==0.5
webencodings==0.5
```
```
In a Jupyter notebook, this can easily be done by using the `%%sh` magic. Here is for example what you could do and get on the Jupyter notebooks we deployed for the MOOC (note that here, you should simply use the `pip` command):
In a Jupyter notebook, this can easily be done by using the `%%sh`
magic. Here is for example what you could do and get on the Jupyter
notebooks we deployed for the MOOC (note that here, you should simply
use the `pip` command):
``` python
``` python
%%sh
%%sh
...
@@ -162,9 +185,13 @@ xlrd==1.1.0
...
@@ -162,9 +185,13 @@ xlrd==1.1.0
zope.interface==4.5.0
zope.interface==4.5.0
```
```
In the rest of this document, I will assume the correct command is `pip` and I will not systematically insert the `%%sh` magic.
In the rest of this document, I will assume the correct command is `pip`
and I will not systematically insert the `%%sh` magic.
Once you know which packages are installed, you can easily get additional information about a given package and in particular check whether it was installed "locally" through pip or whether it is installed system-wide. Again, in a shell command:
Once you know which packages are installed, you can easily get
additional information about a given package and in particular check
whether it was installed "locally" through pip or whether it is
Without resorting to pip (that will list all available packages), you may want to know which modules are loaded in a Python session as well as their version. Inspired by [StackOverflow](https://stackoverflow.com/questions/4858100/how-to-list-imported-modules), here is a simple function that lists loaded package (that have a `__version__` attribute, which is unfortunately not completely standard).
Without resorting to pip (that will list all available packages), you
may want to know which modules are loaded in a Python session as well as
here is a simple function that lists loaded package (that have a
`__version__` attribute, which is unfortunately not completely
standard).
``` python
``` python
defprint_imported_modules():
defprint_imported_modules():
...
@@ -249,24 +281,30 @@ urllib.request 3.6
...
@@ -249,24 +281,30 @@ urllib.request 3.6
zlib 1.0
zlib 1.0
```
```
Saving and restoring an environment with pip
## Saving and restoring an environment with pip
--------------------------------------------
The easiest way to go is as follows:
The easiest way to go is as
follows:
``` shell
``` shell
pip3 freeze > requirements.txt # to obtain the list of packages with their version
pip3 freeze > requirements.txt # to obtain the list of packages with their version
pip3 install-r requirements.txt # to install the previous list of packages, possibly on an other machine
pip3 install-r requirements.txt # to install the previous list of packages, possibly on an other machine
```
```
If you want to have several installed Python environments, you may want to use [Pipenv](https://docs.pipenv.org/). I doubt it allows to track correctly FORTRAN or C dynamic libraries that are wrapped by Python though.
If you want to have several installed Python environments, you may want
to use [Pipenv](https://docs.pipenv.org/). I doubt it allows to track
correctly FORTRAN or C dynamic libraries that are wrapped by Python
though.
Installing a new package or a specific version
## Installing a new package or a specific version
----------------------------------------------
The Jupyter environment we deployed on our servers for the MOOC is based on the version 4.5.4 of Miniconda and Python 3.6. In this environment you should simply use the `pip` command (remember on your machine, you may have to use `pip3`).
The Jupyter environment we deployed on our servers for the MOOC is based
on the version 4.5.4 of Miniconda and Python 3.6. In this environment
you should simply use the `pip` command (remember on your machine, you
may have to use `pip3`).
If I query the current version of `statsmodels` in a shell command, here is what I will get.
If I query the current version of `statsmodels` in a shell command, here
The best way seems to be to rely on the `devtools` package (if this package is not installed, you should install it first by running in `R` the command `install.packages("devtools")`).
The best way seems to be to rely on the `devtools` package (if this
package is not installed, you should install it first by running in `R`
Some actually advocate that [writing a reproducible research compendium is best done by writing an R package](https://github.com/ropensci/rrrpkg). Those of you willing to have a clean R dependency management should thus have a look at [Packrat](https://rstudio.github.io/packrat/).
Some actually advocate that [writing a reproducible research compendium
is best done by writing an R
package](https://github.com/ropensci/rrrpkg). Those of you willing to
have a clean R dependency management should thus have a look at
[Packrat](https://rstudio.github.io/packrat/).
Getting the list of installed packages and their version
## Getting the list of installed packages and their version
Finally, it is good to know that there is a built-in R command (`installed.packages`) allowing to retrieve and list the details of all packages installed.
Finally, it is good to know that there is a built-in R command
(`installed.packages`) allowing to retrieve and list the details of all
This section is mostly a cut and paste from the [recent post by Ian Pylvainen](https://support.rstudio.com/hc/en-us/articles/219949047-Installing-older-versions-of-packages) on this topic. It comprises a very clear explanation of how to proceed.
This section is mostly a cut and paste from the [recent post by Ian
on this topic. It comprises a very clear explanation of how to proceed.
### Installing a pre-compiled version
### Installing a pre-compiled version
If you're on a Debian or a Ubuntu system, it may be difficult to access a specific version without breaking your system. So unless you are moving to the latest version available in your Linux distribution, **we strongly recommend you to build from source**. In this case, you'll need to make sure you have the necessary toolchain to build packages from source (e.g., gcc, FORTRAN, etc.). On Windows, this may require you to install [Rtools](https://cran.r-project.org/bin/windows/Rtools/).
If you're on a Debian or a Ubuntu system, it may be difficult to access
a specific version without breaking your system. So unless you are
moving to the latest version available in your Linux distribution, **we
strongly recommend you to build from source**. In this case, you'll need
to make sure you have the necessary toolchain to build packages from
source (e.g., gcc, FORTRAN, etc.). On Windows, this may require you to
If you're on Windows or OS X and looking for a package for an **older version of R** (R 2.1 or below), you can check the [CRAN binary archive](https://cran-archive.r-project.org/bin/). Once you have the URL, you can install it using a command similar to the example below:
If you're on Windows or OS X and looking for a package for an **older
version of R** (R 2.1 or below), you can check the [CRAN binary
archive](https://cran-archive.r-project.org/bin/). Once you have the
URL, you can install it using a command similar to the example
The simplest method to install the version you need is to use the `install_version()` function of the `devtools` package (obviously, you need to install `devtools` first, which can be done by running in `R` the command `install.packages("devtools")`). For instance:
The simplest method to install the version you need is to use the
`install_version()` function of the `devtools` package (obviously, you
need to install `devtools` first, which can be done by running in `R`
the command `install.packages("devtools")`). For instance:
Alternatively, you may want to install an older package from source If devtools fails or if you do not want to depend on it, you can install it from source via `install.packages()` directed using the right URL. This URL can be obtained by browsing the [CRAN Package Archive](https://cran.r-project.org/src/contrib/Archive).
Alternatively, you may want to install an older package from source If
devtools fails or if you do not want to depend on it, you can install it
from source via `install.packages()` directed using the right URL. This
@@ -443,7 +509,12 @@ R CMD INSTALL ggplot2_0.9.1.tar.gz
...
@@ -443,7 +509,12 @@ R CMD INSTALL ggplot2_0.9.1.tar.gz
### Potential issues
### Potential issues
There are a few potential issues that may arise with installing older versions of packages:
There are a few potential issues that may arise with installing older
versions of packages:
- You may be losing functionality or bug fixes that are only present in the newer versions of the packages.
- You may be losing functionality or bug fixes that are only present
- The older package version needed may not be compatible with the version of R you have installed. In this case, you will either need to downgrade R to a compatible version or update your R code to work with a newer version of the package.
in the newer versions of the packages.
- The older package version needed may not be compatible with the
version of R you have installed. In this case, you will either need
to downgrade R to a compatible version or update your R code to work
-[Lister les packages installés et leur version](#lister-les-packages-installés-et-leur-version)
-[Obtenir des informations sur votre
-[Lister les packages importés (chargés dans une session Python) et leur version](#lister-les-packages-importés-chargés-dans-une-session-python-et-leur-version)
Lorsqu'on prend des notes, il peut être difficile de se rappeler quelle version de code ou de fichier a été utilisée. C'est l'intérêt du contrôle de versions. Voici quelques commandes utiles que nous insérons généralement au début de nos notebooks dans des cellules shell :
Lorsqu'on prend des notes, il peut être difficile de se rappeler quelle
version de code ou de fichier a été utilisée. C'est l'intérêt du
contrôle de versions. Voici quelques commandes utiles que nous insérons
généralement au début de nos notebooks dans des cellules shell :
``` shell
``` shell
git log -1
git log -1
...
@@ -65,9 +79,12 @@ Untracked files:
...
@@ -65,9 +79,12 @@ Untracked files:
no changes added to commit (use "git add" and/or "git commit -a")
no changes added to commit (use "git add" and/or "git commit -a")
```
```
*Note : L'option -u indique que Git doit aussi afficher le contenu des répertoires nouvellement créés.*
*Note : L'option -u indique que Git doit aussi afficher le contenu des
répertoires nouvellement créés.*
Nous ajoutons aussi souvent des commandes à la fin des notebooks pour indiquer comment commiter les résultats (ajout des nouveaux fichiers, commit avec un message clair et commande push). Par exemple :
Nous ajoutons aussi souvent des commandes à la fin des notebooks pour
indiquer comment commiter les résultats (ajout des nouveaux fichiers,
commit avec un message clair et commande push). Par exemple :
``` shell
``` shell
git add resources.org;
git add resources.org;
...
@@ -87,15 +104,18 @@ To gitlab.inria.fr:learninglab/mooc-rr/mooc-rr-ressources.git
...
@@ -87,15 +104,18 @@ To gitlab.inria.fr:learninglab/mooc-rr/mooc-rr-ressources.git
6359f8c..1f8a567 master -> master
6359f8c..1f8a567 master -> master
```
```
Évidemment, dans ce cas il faut enregistrer le notebook avant d'exécuter cette cellule, donc le résultat de cette dernière commande (avec le nouveau Git hash) ne sera pas stocké dans la cellule. Ce n'est pas vraiment un problème et c'est le prix à payer pour exécuter Git à partir du notebook lui-même.
Évidemment, dans ce cas il faut enregistrer le notebook avant d'exécuter
cette cellule, donc le résultat de cette dernière commande (avec le
nouveau Git hash) ne sera pas stocké dans la cellule. Ce n'est pas
vraiment un problème et c'est le prix à payer pour exécuter Git à partir
du notebook lui-même.
Obtenir des informations sur les librairies Python 3
# Obtenir des informations sur les librairies Python 3
Cette question est discutée sur [StackOverflow](https://stackoverflow.com/questions/20180543/how-to-check-version-of-python-modules). Il est facile d'obtenir la version de tous les packages installés en exécutant `pip` (l'installateur de packages Python) dans une commande shell (la commande peut être `pip` or `pip3` selon la configuration de votre ordinateur).
Il est facile d'obtenir la version de tous les packages installés en
exécutant `pip` (l'installateur de packages Python) dans une commande
shell (la commande peut être `pip` or `pip3` selon la configuration de
votre ordinateur).
Voici par exemple comment j'obtiens ces informations sur ma machine :
Voici par exemple comment j'obtiens ces informations sur ma machine :
...
@@ -137,7 +161,10 @@ wcwidth==0.1.7
...
@@ -137,7 +161,10 @@ wcwidth==0.1.7
webencodings==0.5
webencodings==0.5
```
```
Dans un notebook Jupyter, cela peut facilement être fait en utilisant la commande magique `%%sh`. Voici par exemple ce que vous pouvez faire et obtenir avec les notebooks Jupyter que nous avons déployés pour le MOOC (notez qu’ici vous devez simplement utiliser la commande `pip`) :
Dans un notebook Jupyter, cela peut facilement être fait en utilisant la
commande magique `%%sh`. Voici par exemple ce que vous pouvez faire et
obtenir avec les notebooks Jupyter que nous avons déployés pour le MOOC
(notez qu’ici vous devez simplement utiliser la commande `pip`) :
``` python
``` python
%%sh
%%sh
...
@@ -162,9 +189,14 @@ xlrd==1.1.0
...
@@ -162,9 +189,14 @@ xlrd==1.1.0
zope.interface==4.5.0
zope.interface==4.5.0
```
```
Dans la suite de ce document, je supposerai que la commande correcte est `pip` et je ne vais pas systématiquement insérer la commande magique `%%sh`.
Dans la suite de ce document, je supposerai que la commande correcte est
`pip` et je ne vais pas systématiquement insérer la commande magique
`%%sh`.
Une fois que vous savez quels packages sont installés, vous pouvez facilement obtenir des informations supplémentaires sur un package donné et notamment vérifier s'il a été installé "localement" via pip ou s'il est installé à l'échelle du système. À nouveau dans une commande shell :
Une fois que vous savez quels packages sont installés, vous pouvez
facilement obtenir des informations supplémentaires sur un package donné
et notamment vérifier s'il a été installé "localement" via pip ou s'il
est installé à l'échelle du système. À nouveau dans une commande shell :
Vous pouvez vouloir savoir quels packages sont chargés dans une session Python ainsi que leur version sans recourir à pip (qui listera tous les packages disponibles). Inspiré par [StackOverflow](https://stackoverflow.com/questions/4858100/how-to-list-imported-modules), voici une fonction simple qui liste les packages chargés (ayant un attribut `__version__`, qui n’est malheureusement pas tout à fait standard).
Vous pouvez vouloir savoir quels packages sont chargés dans une session
Python ainsi que leur version sans recourir à pip (qui listera tous les
La façon la plus simple de faire est la suivante :
La façon la plus simple de faire est la
suivante :
``` shell
``` shell
pip3 freeze > requirements.txt # to obtain the list of packages with their version
pip3 freeze > requirements.txt # to obtain the list of packages with their version
pip3 install-r requirements.txt # to install the previous list of packages, possibly on an other machine
pip3 install-r requirements.txt # to install the previous list of packages, possibly on an other machine
```
```
Si vous voulez avoir plusieurs environnements Python sur votre ordinateur, vous pouvez vouloir utiliser [Pipenv](https://docs.pipenv.org/)(mais je doute que cela permette de tracer correctement les bibliothèques dynamiques FORTRAN ou C encapsulées dans Python).
Si vous voulez avoir plusieurs environnements Python sur votre
ordinateur, vous pouvez vouloir utiliser
[Pipenv](https://docs.pipenv.org/)(mais je doute que cela permette de
tracer correctement les bibliothèques dynamiques FORTRAN ou C
encapsulées dans Python).
Installer un nouveau package ou une version spécifique
## Installer un nouveau package ou une version spécifique
L’environnement Jupyter que nous avons déployé sur nos serveurs pour le MOOC est basé sur Miniconda 4.5.4 et Python 3.6. Dans cet environnement, vous devez simplement utiliser la commande `pip` (vous devrez peut-être utiliser `pip3` sur votre ordinateur).
L’environnement Jupyter que nous avons déployé sur nos serveurs pour le
MOOC est basé sur Miniconda 4.5.4 et Python 3.6. Dans cet environnement,
vous devez simplement utiliser la commande `pip` (vous devrez peut-être
utiliser `pip3` sur votre ordinateur).
Voici ce que j'obtiens si j'interroge la version actuelle de `statsmodels` dans une commande shell.
Voici ce que j'obtiens si j'interroge la version actuelle de
Le meilleur moyen semble être d'utiliser le package `devtools`. Si le package n'est pas installé, vous devez d'abord l'installer en exécutant la commande `install.packages("devtools",dep=TRUE)` dans `R`).
Le meilleur moyen semble être d'utiliser le package `devtools`. Si le
package n'est pas installé, vous devez d'abord l'installer en exécutant
la commande `install.packages("devtools",dep=TRUE)` dans `R`).
Ceux d'entre vous qui souhaitent disposer d'une gestion des dépendances "propre" en R peuvent aussi jeter un coup d'œil à [Packrat](https://rstudio.github.io/packrat/).
Ceux d'entre vous qui souhaitent disposer d'une gestion des dépendances
"propre" en R peuvent aussi jeter un coup d'œil à
[Packrat](https://rstudio.github.io/packrat/).
Installer un nouveau package ou une version spécifique
## Installer un nouveau package ou une version spécifique
Cette section est principalement un copier-coller du [récent post de Ian Pylvainen](https://support.rstudio.com/hc/en-us/articles/219949047-Installing-older-versions-of-packages) sur ce sujet. Il comprend une explication très claire de la façon de procéder.
Cette section est principalement un copier-coller du [récent post de Ian
sur ce sujet. Il comprend une explication très claire de la façon de
procéder.
### Installer une version pré-compilée
### Installer une version pré-compilée
Si vous êtes sur un système Debian ou Ubuntu, il peut être difficile d’accéder à une version spécifique sans casser votre système. Donc, sauf si vous passez à la dernière version disponible pour votre distribution Linux, **nous vous recommandons fortement d'installer les packages à l'aide des fichiers source**. Dans ce cas, vous devez vous assurer que vous disposez de l'ensemble des outils nécessaires pour créer des packages à partir des sources (par exemple : gcc, FORTRAN, etc.). Sous Windows, il se peut que vous deviez installer [Rtools](https://cran.r-project.org/bin/windows/Rtools/).
Si vous êtes sur un système Debian ou Ubuntu, il peut être difficile
d’accéder à une version spécifique sans casser votre système. Donc,
Si vous utilisez Windows ou OS X et recherchez un package pour une **ancienne version de R** (version 2.1 ou inférieure), vous pouvez le rechercher sur l'[archive binaire du site CRAN](https://cran-archive.r-project.org/bin/). Une fois que vous avez l'URL, vous pouvez l'installer à l'aide d'une commande similaire à l'exemple ci-dessous :
sauf si vous passez à la dernière version disponible pour votre
distribution Linux, **nous vous recommandons fortement d'installer les
packages à l'aide des fichiers source**. Dans ce cas, vous devez vous
assurer que vous disposez de l'ensemble des outils nécessaires pour
créer des packages à partir des sources (par exemple : gcc, FORTRAN,
etc.). Sous Windows, il se peut que vous deviez installer
La méthode la plus simple pour installer la version dont vous avez besoin consiste à utiliser la fonction `install_version()` du package `devtools` (vous devez évidemment avoir préalablement installé `devtools`, ce qui peut être fait en exécutant `R` la commande `install.packages("devtools",dep=TRUE)`). Par exemple:
La méthode la plus simple pour installer la version dont vous avez
besoin consiste à utiliser la fonction `install_version()` du package
`devtools` (vous devez évidemment avoir préalablement installé
`devtools`, ce qui peut être fait en exécutant `R` la commande
`install.packages("devtools",dep=TRUE)`). Par exemple:
Vous pouvez également installer un ancien package à partir de son code source. Si vous ne réussissez pas avec devtools ou si vous ne voulez pas dépendre de ce package, vous pouvez l’installer à partir du source à l'aide de la commande `install.packages()` en utilisant la bonne URL. Cette URL peut être obtenue en naviguant dans [l'archive de packages du site CRAN](https://cran.r-project.org/src/contrib/Archive).
Vous pouvez également installer un ancien package à partir de son code
source. Si vous ne réussissez pas avec devtools ou si vous ne voulez pas
dépendre de ce package, vous pouvez l’installer à partir du source à
l'aide de la commande `install.packages()` en utilisant la bonne URL.
Cette URL peut être obtenue en naviguant dans [l'archive de packages du
site CRAN](https://cran.r-project.org/src/contrib/Archive).
Une fois que vous avez l'URL, vous pouvez l'installer à l'aide d'une commande similaire à l'exemple ci-dessous :
Une fois que vous avez l'URL, vous pouvez l'installer à l'aide d'une
@@ -445,7 +522,14 @@ R CMD INSTALL ggplot2_0.9.1.tar.gz
...
@@ -445,7 +522,14 @@ R CMD INSTALL ggplot2_0.9.1.tar.gz
### Problèmes potentiels
### Problèmes potentiels
Quelques problèmes sont susceptibles de survenir lors de l'installation d'anciennes versions de packages :
Quelques problèmes sont susceptibles de survenir lors de l'installation
d'anciennes versions de packages :
- Vous pouvez perdre des fonctionnalités ou des corrections de bugs qui ne sont présentes que dans les versions les plus récentes des packages.
- L'ancienne version de package requise peut ne pas être compatible avec la version de R que vous avez installée. Dans ce cas, vous devrez soit rétrograder R vers une version compatible, soit mettre à jour votre code R pour qu'il fonctionne avec une version plus récente du package.
- Vous pouvez perdre des fonctionnalités ou des corrections de bugs
qui ne sont présentes que dans les versions les plus récentes des
packages.
- L'ancienne version de package requise peut ne pas être compatible
avec la version de R que vous avez installée. Dans ce cas, vous
devrez soit rétrograder R vers une version compatible, soit mettre à
jour votre code R pour qu'il fonctionne avec une version plus
-[Numerical and statistical issues](#numerical-and-statistical-issues)
-[Workflows](#workflows)
-[Publication practices](#publication-practices)
-[Numerical and statistical
-[Experimentation](#experimentation)
issues](#numerical-and-statistical-issues)
-[Publication practices](#publication-practices)
"Thoughts" on language/software stability
-[Experimentation](#experimentation)
=========================================
# "Thoughts" on language/software stability
As we explained, the programming language used in an analysis has a clear influence on the reproducibility of your analysis. It is not a characteristic of the language itself but rather a consequence of the development philosophy of the underlying community. For example C is a very stable language with a [very clear specification designed by a committee](https://en.wikipedia.org/wiki/C_(programming_language)#ANSI_C_and_ISO_C) (even though some compilers may not respect this norm).
As we explained, the programming language used in an analysis has a
On the other end of the spectrum, [Python](https://en.wikipedia.org/wiki/Python_(programming_language)) had a much more organic development based on a readability philosophy and valuing continuous improvement over backwards-compatibility. Furthermore, Python is commonly used as a wrapping language (e.g., to easily use C or FORTRAN libraries) and has its own packaging system. All these design choices tend to make reproducibility often a bit painful with Python, even though the community is slowly taking this into account. The transition from Python 2 to the not fully backwards compatible Python 3 has been a particularly painful process, not least because the two languages are so similar that is it not always easy to figure out if a given script or module is written in Python 2 or Python 3. It isn't even rare to see Python scripts that work under both Python 2 and Python 3, but produce different results due to the change in the behavior of integer division.
clear influence on the reproducibility of your analysis. It is not a
characteristic of the language itself but rather a consequence of the
[R](https://en.wikipedia.org/wiki/R_(programming_language)), in comparison is much closer (in terms of developer community) to languages like [SAS](https://en.wikipedia.org/wiki/SAS_(software)), which is heavily used in the pharmaceutical industry where statistical procedures need to be standardized and rock solid/stable. R is obviously not immune to evolutions that break old versions and hinder reproducibility/backward compatibility. Here is a relatively recent [true story about this](http://members.cbio.mines-paristech.fr/~thocking/HOCKING-reproducible-research-with-R.html) and some colleagues who worked on the [statistics introductory course with R on FUN](https://www.fun-mooc.fr/courses/UPSUD/42001S06/session06/about) reported us several issues with a few functions (`plotmeans` from `gplots`, `survfit` from `survival`, or `hclust`) whose default parameters had changed over the years. It is thus probably good practice to give explicit values for all parameters (which can be cumbersome) instead of relying on default values, and to restrict your dependencies as much as possible.
development philosophy of the underlying community. For example C is a
very stable language with a [very clear specification designed by a
This being said, the R development community is generally quite careful about stability. We (the authors of this MOOC) believe that open source (which allows to inspect how computation is done and to identify both mistakes and sources of non-reproducibility) is more important than the rock solid stability of SAS, which is proprietary software.
(even though some compilers may not respect this norm).
Yet, if you really need to stay with SAS, you should know that SAS can be used within Jupyter using the [Python SASPy](https://sassoftware.github.io/saspy/) and the [Python SASKernel](https://sassoftware.github.io/sas_kernel/) packages (step by step explanations about this are given [here](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)). Using such literate programming approach allied with systematic version and environment control will always help. Similar solutions exist for many languages ([list of Jupyter kernels](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels)).
had a much more organic development based on a readability philosophy
and valuing continuous improvement over backwards-compatibility.
As we mentioned in the video sequences, there are several solutions to control your environment:
Furthermore, Python is commonly used as a wrapping language (e.g., to
easily use C or FORTRAN libraries) and has its own packaging system. All
- The easy (preserve the mess) ones: [CDE](http://www.pgbovine.net/cde.html) or [ReproZip](https://vida-nyu.github.io/reprozip/)
these design choices tend to make reproducibility often a bit painful
- The more demanding (encourage cleanliness) where you start with a clean environment and install only what's strictly necessary (and document it):
with Python, even though the community is slowly taking this into
- The very well known [Docker](https://www.docker.io/)
account. The transition from Python 2 to the not fully backwards
-[Singularity](https://singularity.lbl.gov/) or [Spack](https://spack.io/), which are more targeted toward the specific needs of high performance computing users
compatible Python 3 has been a particularly painful process, not least
-[Guix](https://www.gnu.org/software/guix/), [Nix](https://nixos.org/) that are very clean (perfect?) solutions to this dependency hell and which we recommend
because the two languages are so similar that is it not always easy to
figure out if a given script or module is written in Python 2 or Python
It may be hard to understand the difference between these different approaches and decide which one is better in your context.
3. It isn't even rare to see Python scripts that work under both Python
2 and Python 3, but produce different results due to the change in the
Here is a webinar where some of these tools are demoed in a reproducible research context: [Controling your environment (by Michael Mercier and Cristian Ruiz)](https://github.com/alegrand/RR_webinars/blob/master/2_controling_your_environment/index.org)
behavior of integer division.
You may also want to have a look at [the Popper conventions](http://falsifiable.us/)([webinar by Ivo Gimenez through google hangout](https://github.com/alegrand/RR_webinars/blob/master/11_popper/index.org)) or at the [presentation of Konrad Hinsen on Active Papers](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org)(<http://www.activepapers.org/>).
[R](https://en.wikipedia.org/wiki/R_\(programming_language\)), in
comparison is much closer (in terms of developer community) to languages
Preservation/Archiving
like [SAS](https://en.wikipedia.org/wiki/SAS_\(software\)), which is
======================
heavily used in the pharmaceutical industry where statistical procedures
need to be standardized and rock solid/stable. R is obviously not immune
Ensuring software is properly archived, i.e, is safely stored so that it can be accessed in a perennial way, can be quite tricky. If you have never seen [Roberto Di Cosmo presenting the Software Heritage project](https://github.com/alegrand/RR_webinars/blob/master/5_archiving_software_and_data/index.org), this is a must see. [<https://www.softwareheritage.org/>](https://www.softwareheritage.org/)
to evolutions that break old versions and hinder
reproducibility/backward compatibility. Here is a relatively recent
For regular data, we highly recommend using [<https://www.zenodo.org/>](https://www.zenodo.org/) whenever the data is not sensitive.
parameters had changed over the years. It is thus probably good practice
- Light-weight: [dask](http://dask.pydata.org/)(python), [drake](https://ropensci.github.io/drake/)(R), [swift](http://swift-lang.org/)(molecular biology), [snakemake](https://snakemake.readthedocs.io/)(like`make` but more expressive and in `python`)...
to give explicit values for all parameters (which can be cumbersome)
instead of relying on default values, and to restrict your dependencies
as much as possible.
You may want to have a look at this webinar: \[\[<https://github.com/alegrand/RR_webinars/blob/master/6_reproducibility_bioinformatics/index.org>\]\[Reproducible Science in Bio-informatics: Current Status, Solutions and Research Opportunities (by Sarah Cohen Boulakia, Yvan Le Bras and Jérôme Chopard).\]\]
This being said, the R development community is generally quite careful
Numerical and statistical issues
about stability. We (the authors of this MOOC) believe that open source
================================
(which allows to inspect how computation is done and to identify both
mistakes and sources of non-reproducibility) is more important than the
We have mentioned these topics in our MOOC but we could by no way cover them properly. We only suggest here a few interesting talks about this.
rock solid stability of SAS, which is proprietary software.
-\[\[<https://github.com/alegrand/RR_webinars/blob/master/10_statistics_and_replication_in_HCI/index.org>\]\[In this talk, Pierre Dragicevic provides a nice illustration of the consequences of statistical uncertainty and of how some concepts (e.G. p-values) are commonly badly understood.\]\]
Yet, if you really need to stay with SAS, you should know that SAS can
-\[\[<https://github.com/alegrand/RR_webinars/blob/master/3_numerical_reproducibility/index.org>\]\[Nathalie Revol, Philippe Langlois and Stef Graillat present the main challenges encountered when trying to achieve numerical reproducibility and present recent research work on this topic.\]\]
be used within Jupyter using the [Python
SASPy](https://sassoftware.github.io/saspy/) and the [Python
Publication practices
SASKernel](https://sassoftware.github.io/sas_kernel/) packages (step by
Revol, Philippe Langlois and Stef Graillat present the main
challenges encountered when trying to achieve numerical
reproducibility and present recent research work on this topic.\]\]
# Publication practices
You may want to have a look at the following two webinars:
You may want to have a look at the following two webinars:
-[Enabling open and reproducible research at computer systems’ conferences (by Grigori Fursin)](https://github.com/alegrand/RR_webinars/blob/master/8_artifact_evaluation/index.org). In particular, this talk discusses *artifact evaluation* that is becoming more and more popular.
-[Enabling open and reproducible research at computer systems’
-[Publication Modes Favoring Reproducible Research (by Konrad Hinsen and Nicolas Rougier)](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org). In this talk, the motivation for the [ReScience journal](http://rescience.github.io/) initiative are presented.
conferences (by Grigori
-[Simine Vazire - When Should We be Skeptical of Scientific Claims?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), which is discussing publication practices in social sciences and in particular HARKing (Hypothesizing After the Results are Known), p-hacking, etc.
In particular, this talk discusses *artifact evaluation* that is
Experimentation
becoming more and more popular.
===============
-[Publication Modes Favoring Reproducible Research (by Konrad Hinsen
and Nicolas
Experimentation was not covered in this MOOC, although it is an essential part of science. The main reason is that practices and constraints can vary so wildly from one domain to another that it could not be properly covered in a first edition. We would be happy to gather references you consider as interesting in your domain so do not hesitate to provide us with such references by using the forum and we will update this page.
-[A recent talk by Lucas Nussbaum on Experimental Testbeds in Computer Science](https://github.com/alegrand/RR_webinars/blob/master/9_experimental_testbeds/index.org).
journal](http://rescience.github.io/) initiative are presented.
-[Simine Vazire - When Should We be Skeptical of Scientific
Claims?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), which is
discussing publication practices in social sciences and in
particular HARKing (Hypothesizing After the Results are Known),
p-hacking, etc.
# Experimentation
Experimentation was not covered in this MOOC, although it is an
essential part of science. The main reason is that practices and
constraints can vary so wildly from one domain to another that it could
not be properly covered in a first edition. We would be happy to gather
references you consider as interesting in your domain so do not hesitate
to provide us with such references by using the forum and we will update
this page.
-[A recent talk by Lucas Nussbaum on Experimental Testbeds in
# Réflexions sur la stabilité des langages de programmation
Comme nous l'avons expliqué, le langage de programmation utilisé dans une analyse a une influence évidente sur la reproductibilité de l'analyse. Ce n'est pas une caractéristique du langage lui-même mais plutôt une conséquence de la philosophie de développement de la communauté sous-jacente. Par exemple, C est un langage très stable avec une [spécification très claire conçue par un comité](https://en.wikipedia.org/wiki/C_(programming_language)#ANSI_C_and_ISO_C) (même si certains compilateurs ne respectent cette norme).
Comme nous l'avons expliqué, le langage de programmation utilisé dans
À l’autre bout du spectre, [Python](https://en.wikipedia.org/wiki/Python_(programming_language)) a connu un développement beaucoup plus organique basé sur une philosophie de lisibilité et valorisant l'amélioration continue par rapport à la compatibilité ascendante. De plus, Python est couramment utilisé comme langage de wrapping (par exemple pour utiliser facilement les bibliothèques C ou FORTRAN) et dispose de son propre système de packaging. Tous ces choix de conception ont souvent tendance à rendre la reproductibilité un peu pénible avec Python, même si la communauté en tient lentement compte. La transition de Python 2 à Python 3, qui n'est pas totalement compatible avec les versions antérieures, a été un processus particulièrement pénible, notamment parce que les deux langages sont si similaires qu'il n'est pas toujours facile de savoir si un script ou un module donné est écrit en Python 2 ou Python 3. Il n'est même pas rare de voir des scripts Python qui fonctionnent sous Python 2 et Python 3, mais produisent des résultats différents en raison du changement de comportement de la division entière.
une analyse a une influence évidente sur la reproductibilité de
l'analyse. Ce n'est pas une caractéristique du langage lui-même mais
[R](https://en.wikipedia.org/wiki/R_(programming_language)), en comparaison, est beaucoup plus proche (en termes de communauté de développeurs) de langages comme [SAS](https://en.wikipedia.org/wiki/SAS_(logiciel)), très utilisé dans l'industrie pharmaceutique où les procédures statistiques doivent être standardisées et stables/solides. R n’est évidemment pas à l’abri des évolutions qui cassent les anciennes versions et gênent la reproductibilité/compatibilité avec les versions antérieures. Voici une [véritable histoire relativement récente à ce sujet](http://members.cbio.mines-paristech.fr//thocking/HOCKING-reproducible-research-with-R.html) et des collègues qui ont travaillé sur le [MOOC d'initiation à la statistique avec R sur FUN](https://www.fun-mooc.fr/courses/course-v1:UPSUD+42001+session10/about) nous ont signalé plusieurs problèmes concernant quelques fonctions (`gplots::plotmeans`, `survival::survfit` ou `hclust`) dont les paramètres par défaut ont changé au fil des ans. Il est donc probablement utile de donner des valeurs explicites pour tous les paramètres (ce qui peut être fastidieux) au lieu de s’appuyer sur des valeurs par défaut et de restreindre autant que possible vos dépendances.
plutôt une conséquence de la philosophie de développement de la
communauté sous-jacente. Par exemple, C est un langage très stable avec
Ceci étant dit, la communauté de développement R est généralement très prudente en matière de stabilité. Nous (les auteurs de ce MOOC) pensons que l'open source (qui permet de contrôler le calcul et d'identifier les erreurs et les sources de non-reproductibilité) est plus important que la stabilité à toute épreuve de SAS, qui est un logiciel propriétaire.
Cependant, si vous avez vraiment besoin de rester sous SAS, sachez que SAS peut être utilisé dans Jupyter en utilisant les packages Python [SASPy](https://sassoftware.github.io/saspy/) et [SASKernel](https://sassoftware.github.io/sas_kernel/)(tuto pas à pas [ici](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)). L'utilisation d'une telle approche de programmation alphabète alliée à un contrôle systématique de la version et de l'environnement est un plus. Des solutions similaires existent pour de nombreux langages ([liste des kernels Jupyter](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels)).
(même si certains compilateurs ne respectent cette norme).
a connu un développement beaucoup plus organique basé sur une
Comme nous l'avons mentionné dans les séquences vidéo, plusieurs solutions permettent de contrôler votre environnement :
philosophie de lisibilité et valorisant l'amélioration continue par
rapport à la compatibilité ascendante. De plus, Python est couramment
- Les faciles (autorisant le désordre) : [CDE](http://www.pgbovine.net/cde.html) ou [ReproZip](https://vida-nyu.github.io/reprozip/)
utilisé comme langage de wrapping (par exemple pour utiliser facilement
- Les plus exigeants (encourageant la propreté) où vous commencez avec un environnement propre et n’installez que ce qui est strictement nécessaire (et le documentez) :
les bibliothèques C ou FORTRAN) et dispose de son propre système de
- Le très connu [Docker](https://www.docker.io/)
packaging. Tous ces choix de conception ont souvent tendance à rendre la
-[Singularity](https://singularity.lbl.gov/) ou [Spack](https://spack.io/), qui sont plus ciblés sur les besoins spécifiques des utilisateurs d'informatique de haute performance
reproductibilité un peu pénible avec Python, même si la communauté en
-[Guix](https://www.gnu.org/software/guix/), [Nix](https://nixos.org/) qui sont des solutions très propres (parfaites ?) à cet enfer de dépendance et que nous recommandons
tient lentement compte. La transition de Python 2 à Python 3, qui n'est
pas totalement compatible avec les versions antérieures, a été un
Il peut être difficile de comprendre la différence entre ces différentes approches et de décider laquelle est la meilleure dans votre contexte.
processus particulièrement pénible, notamment parce que les deux
langages sont si similaires qu'il n'est pas toujours facile de savoir si
Voici un webinaire où certains de ces outils sont présentés dans un contexte de recherche reproductible : [Controling your environment (by Michael Mercier and Cristian Ruiz)](https://github.com/alegrand/RR_webinars/blob/master/2_controling_your_environment/index.org).
un script ou un module donné est écrit en Python 2 ou Python 3. Il n'est
même pas rare de voir des scripts Python qui fonctionnent sous Python 2
Vous voudrez peut-être aussi jeter un coup d’œil sur la convention [Popper](http://falsifiable.us/)([webinaire par Ivo Gimenez par Google hangout](https://github.com/alegrand/RR_webinars/blob/master/11_popper/index.org)) ou sur la [présentation de Konrad Hinsen](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org) sur [Active Papers](http://www.activepapers.org/).
et Python 3, mais produisent des résultats différents en raison du
changement de comportement de la division entière.
Préservation/Archivage
======================
[R](https://en.wikipedia.org/wiki/R_\(programming_language\)), en
comparaison, est beaucoup plus proche (en termes de communauté de
S'assurer que le logiciel est correctement archivé, c'est-à-dire qu'il est stocké de manière sécurisée afin de pouvoir y accéder de manière pérenne, peut être assez délicat. Si vous n'avez jamais vu la [présentation du projet Software Heritage par Roberto Di Cosmo](https://github.com/alegrand/RR_webinars/blob/master/5_archiving_software_and_data/index.org), c'est à voir absolument. [<https://www.softwareheritage.org/>](https://www.softwareheritage.org/)
développeurs) de langages comme
[SAS](https://en.wikipedia.org/wiki/SAS_\(logiciel\)), très utilisé dans
Pour les données, nous vous recommandons vivement d’utiliser [<https://www.zenodo.org/>](https://www.zenodo.org/) lorsque les données ne sont pas sensibles.
l'industrie pharmaceutique où les procédures statistiques doivent être
standardisées et stables/solides. R n’est évidemment pas à l’abri des
Workflows
évolutions qui cassent les anciennes versions et gênent la
=========
reproductibilité/compatibilité avec les versions antérieures. Voici une
[véritable histoire relativement récente à ce
Dans les séquences vidéo, nous avons mentionné les gestionnaires de flux de travaux (domaine d'application d'origine entre parenthèses) :
et des collègues qui ont travaillé sur le [MOOC d'initiation à la
- workflows assez complexes : [Galaxy](https://galaxyproject.org/)(génomique), [Kepler](https://kepler-project.org/)(écologie), [Taverna](https://taverna.apache.org/)(bioinformatique), [Pegasus](https://pegasus.isi.edu/)(astronomie), [Collective Knowledge](http://cknowledge.org/)(optimisation de la compilation), [VisTrails](https://www.vistrails.org)(traitement d'image)
statistique avec R sur
- workflows plus légers : [dask](http://dask.pydata.org/)(Python), [drake](https://ropensci.github.io/drake/)(R), [swift](http://swift-lang.org/)(biologie moléculaire), [snakemake](https://snakemake.readthedocs.io/)(comme`make` mais plus expressif et en `Python`)...
- hybride à mi-chemin entre le notebook et le workflow : [SOS-notebook](https://vatlab.github.io/sos-docs/)
nous ont signalé plusieurs problèmes concernant quelques fonctions
(`gplots::plotmeans`, `survival::survfit` ou `hclust`) dont les
Vous voudrez peut-être consulter ce webinaire : \[\[<https://github.com/alegrand/RR_webinars/blob/master/6_reproducibility_bioinformatics/index.org>\]\[Science Reproducible en Bioinformatique : état actuel, solutions et opportunités de recherche (par Sarah Cohen Boulakia, Yvan Le Bras and Jérôme Chopard)\]\].
paramètres par défaut ont changé au fil des ans. Il est donc
probablement utile de donner des valeurs explicites pour tous les
Problèmes numériques et statistiques
paramètres (ce qui peut être fastidieux) au lieu de s’appuyer sur des
====================================
valeurs par défaut et de restreindre autant que possible vos
dépendances.
Nous avons mentionné ces sujets dans notre MOOC mais nous ne pourrions en aucun cas les couvrir correctement. Nous ne suggérons ici que quelques présentations intéressantes à ce sujet.
Ceci étant dit, la communauté de développement R est généralement très
-\[\[<https://github.com/alegrand/RR_webinars/blob/master/10_statistics_and_replication_in_HCI/index.org>\]\[Pierre Dragicevic donne une belle illustration des conséquences de l’incertitude statistique et de la manière dont certains concepts (par exemple les p-values) sont généralement mal compris\]\].
prudente en matière de stabilité. Nous (les auteurs de ce MOOC) pensons
-\[\[<https://github.com/alegrand/RR_webinars/blob/master/3_numerical_reproducibility/index.org>\]\[Nathalie Revol, Philippe Langlois et Stef Graillat présentent les principaux problèmes rencontrés en essayant d'obtenir une reproductibilité numérique et présentent les travaux de recherche récents en la matière\]\].
que l'open source (qui permet de contrôler le calcul et d'identifier les
erreurs et les sources de non-reproductibilité) est plus important que
Pratiques de publication
la stabilité à toute épreuve de SAS, qui est un logiciel propriétaire.
========================
Cependant, si vous avez vraiment besoin de rester sous SAS, sachez que
SAS peut être utilisé dans Jupyter en utilisant les packages Python
[SASPy](https://sassoftware.github.io/saspy/) et
[SASKernel](https://sassoftware.github.io/sas_kernel/)(tuto pas à pas
Revol, Philippe Langlois et Stef Graillat présentent les principaux
problèmes rencontrés en essayant d'obtenir une reproductibilité
numérique et présentent les travaux de recherche récents en la
matière\]\].
# Pratiques de publication
Vous souhaiterez peut-être consulter les webinaires suivants :
Vous souhaiterez peut-être consulter les webinaires suivants :
-[Permettre une recherche ouverte et reproductible lors de conférences sur les systèmes informatiques (par Grigori Fursin)](https://github.com/alegrand/RR_webinars/blob/master/8_artifact_evaluation/index.org). En particulier, cette discussion aborde *l'évaluation des artefacts* qui devient de plus en plus populaire.
-[Permettre une recherche ouverte et reproductible lors de
-[Modalités de publication favorisant la recherche reproductible (par Konrad Hinsen et Nicolas Rougier)](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org). Présentation des motivations de l'intiative [ReScience journal](http://rescience.github.io/).
conférences sur les systèmes informatiques (par Grigori
-[Simine Vazire - Quand devrions-nous être sceptiques face aux affirmations scientifiques ?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), qui traite des pratiques de publication dans les sciences sociales et en particulier HARKing (Hypothèses après que les résultats sont connus), p-hacking, etc.
En particulier, cette discussion aborde *l'évaluation des artefacts*
Expérimentation
qui devient de plus en plus populaire.
===============
-[Modalités de publication favorisant la recherche reproductible (par
Konrad Hinsen et Nicolas
L'expérimentation n'est pas couverte dans ce MOOC bien qu'il s'agisse d'un élément essentiel de la science. La raison principale est que les pratiques et les contraintes varient tellement d'un domaine à l'autre que ce thème ne pouvait pas être correctement couvert dans une première édition. Nous serions heureux de rassembler les références que vous jugez intéressantes dans votre domaine. N'hésitez donc pas à nous les fournir à l'aide du forum. Nous les intégrerons dans cette page.
Présentation des motivations de l'intiative [ReScience
-[Une récente conférence de Lucas Nussbaum sur les bancs d’essais expérimentaux en informatique](https://github.com/alegrand/RR_webinars/blob/master/9_experimental_testbeds/index.org).
journal](http://rescience.github.io/).
-[Simine Vazire - Quand devrions-nous être sceptiques face aux
affirmations
scientifiques ?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), qui
traite des pratiques de publication dans les sciences sociales et en
particulier HARKing (Hypothèses après que les résultats sont
connus), p-hacking, etc.
# Expérimentation
L'expérimentation n'est pas couverte dans ce MOOC bien qu'il s'agisse
d'un élément essentiel de la science. La raison principale est que les
pratiques et les contraintes varient tellement d'un domaine à l'autre
que ce thème ne pouvait pas être correctement couvert dans une première
édition. Nous serions heureux de rassembler les références que vous
jugez intéressantes dans votre domaine. N'hésitez donc pas à nous les
fournir à l'aide du forum. Nous les intégrerons dans cette page.
-[Une récente conférence de Lucas Nussbaum sur les bancs d’essais
