diff --git a/module1/ressources/introduction_to_markdown.md b/module1/ressources/introduction_to_markdown.md index 7ace1969d0e79eac51b84056dff560699d72d0f3..27fd21a0e63ce1f584a1c09a062d5f006a579ab9 100644 --- a/module1/ressources/introduction_to_markdown.md +++ b/module1/ressources/introduction_to_markdown.md @@ -1,14 +1,14 @@ --- -TITLE: FIXME Introduction à Markdown -Date: Tue Feb 19 19:19:03 2019 +TITLE: Introduction to Markdown +Date: Wed Mar 20 13:57:10 2019 --- -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/). +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/). -Table des matières -=============================================================== +Table of Contents +============================================================== -- [Syntaxe](#syntaxe) +- [Syntax](#syntax) - [Headers](#headers) - [Emphasis](#emphasis) - [Lists](#lists) @@ -16,17 +16,17 @@ Table des matières - [Links](#links) - [Blockquotes](#blockquotes) - [Inline code](#inline-code) -- [Écrire des Maths](#écrire-des-maths) - - [Lettres grecques](#lettres-grecques) - - [Fonctions et opérateurs](#fonctions-et-opérateurs) - - [Exposants et indices](#exposants-et-indices) - - [Fractions, coefficients binomiaux, racines, ...](#fractions-coefficients-binomiaux-racines-) - - [Sommes et intégrales](#sommes-et-intégrales) - - [Déguisements](#déguisements) -- [Autour de `markdown`](#autour-de-markdown) - -Syntaxe -======= +- [Writing Math](#writing-math) + - [Greek Letters](#greek-letters) + - [Usual functions and operators](#usual-functions-and-operators) + - [Exponents and indices](#exponents-and-indices) + - [Fractions, binomial coefficients, square roots, ...](#fractions-binomial-coefficients-square-roots-) + - [Summations and integrals](#summations-and-integrals) + - [Outfits ☺](#outfits-smiley) +- [About `markdown`](#about-markdown) + +Syntax +====== Headers ------- @@ -108,77 +108,77 @@ print("Hello world!") ``` ```` -Écrire des Maths -================ +Writing Math +============ -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. +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. -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. +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. -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: +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 -Cette expression $\sum_{i=1}^n X_i$ est inlinée. +This expression $\sum_{i=1}^n X_i$ is inlined. ``` -Cette expression $\\sum\_{i=1}^n X\_i$ est inlinée. +This expression $\\sum\_{i=1}^n X\_i$ is inlined. ``` example -Cette expression est mise en valeur: +This expression is emphasized: $$\sum_{i=1}^n X_i$$ ``` -Cette expression est mise en valeur: +This expression is emphasized: $$\\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). - -Lettres grecques ----------------- - -| Symbole | Commande | -|---------|------------| -| *α* | `$\alpha$` | -| *β* | `$\beta$` | -| *γ* | `$\gamma$` | -| *Γ* | `$\Gamma$` | -| *π* | `$\pi$` | - -Fonctions et opérateurs ------------------------ - -| Symbole | Commande | -|---------|-------------| -| cos  | `$\cos$` | -| sin  | `$\sin$` | -| lim  | `$\lim$` | -| exp  | `$\exp$` | -| → | `$\to$` | -| ∈ | `$\in$` | -| ∀ | `$\forall$` | -| ∃ | `$\exists$` | -| ≡ | `$\equiv$` | -| ∼ | `$\sim$` | -| ≈ | `$\approx$` | -| × | `$\times$` | -| ≤ | `$\le$` | -| ≥ | `$\ge$` | - -Exposants et indices --------------------- - -| Symbole | Commande | +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). + +Greek Letters +------------- + +| Symbol | Command | +|--------|------------| +| *α* | `$\alpha$` | +| *β* | `$\beta$` | +| *γ* | `$\gamma$` | +| *Γ* | `$\Gamma$` | +| *π* | `$\pi$` | + +Usual functions and operators +----------------------------- + +| Symbol | Command | +|--------|-------------| +| cos  | `$\cos$` | +| sin  | `$\sin$` | +| lim  | `$\lim$` | +| exp  | `$\exp$` | +| → | `$\to$` | +| ∈ | `$\in$` | +| ∀ | `$\forall$` | +| ∃ | `$\exists$` | +| ≡ | `$\equiv$` | +| ∼ | `$\sim$` | +| ≈ | `$\approx$` | +| × | `$\times$` | +| ≤ | `$\le$` | +| ≥ | `$\ge$` | + +Exponents and indices +--------------------- + +| Symbol | Command | |-------------------------------|-------------| | *k**n* + 1 | `$k_{n+1}$` | | *n*2 | `$n^2$` | | *k**n*2 | `$k_n^2$` | -Fractions, coefficients binomiaux, racines, ... ------------------------------------------------ +Fractions, binomial coefficients, square roots, ... +--------------------------------------------------- -| Symbole | Commande | +| Symbol | Command | |-------------------------------|-------------------------------| | $\\frac{4z^3}{16}$ | `$\frac{4z^3}{16}$` | | $\\frac{n!}{k!(n-k)!}$ | `$\frac{n!}{k!(n-k)!}$` | @@ -188,18 +188,18 @@ Fractions, coefficients binomiaux, racines, ... | $\\sqrt{k}$ | `$\sqrt{k}$` | | $\\sqrt\[n\]{k}$ | `$\sqrt[n]{k}$` | -Sommes et intégrales --------------------- +Summations and integrals +------------------------ -| Symbole | Commande | +| Symbol | Command | |----------------------------------------------------|------------------------------------------------| | $\\sum\_{i=1}^{10} t\_i$ | `$\sum_{i=1}^{10} t_i$` | | ∫0∞*e*−*x* *d**x* | `$\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x$` | -Déguisements ------------- +Outfits ☺ +--------- -| Symbole | Commande | +| Symbol | Command | |------------------------|-------------------------| | *â* | `$\hat{a}$` | | *ā* | `$\bar{a}$` | @@ -207,27 +207,27 @@ Déguisements | $\\ddot{a}$ | `$\ddot{a}$` | | $\\overrightarrow{AB}$ | `$\overrightarrow{AB}$` | -Autour de `markdown` -==================== +About `markdown` +================ -Tout d'abord, pour aller plus loin avec `markdown` et ses extensions / ramifications : +First of all, to know more about `markdown` and its extensions, you may want to read: -- 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 ! -- L'article [Markdown](https://en.wikipedia.org/wiki/Markdown#Example) de wikipedia en anglais contient un bon pense-bête sur la syntaxe `markdown`. -- Github propose un court et efficace didacticiel (en anglais) : [Mastering Markdown](https://guides.github.com/features/mastering-markdown/). +- 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... +- The wikipedia article on [Markdown](https://en.wikipedia.org/wiki/Markdown#Example) provides a good overview of the `markdown` syntax. +- Github proposes a short and efficient introduction: [Mastering Markdown](https://guides.github.com/features/mastering-markdown/). -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. +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. -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 : +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: -- Des sites comme et 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` (). -- 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`). +- Some websites like or allow you to convert online `markdown` files into `pdf` files without having to install anything on your computer. +- The [CommonMark](http://commonmark.org/) project proposes a rigorous specification of the `markdown` syntax and converters `markdown` → `html` / `LaTeX` written in `C` and `JavaScript` (). +- 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`. +- [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) is another `markdown` extension that provides its own `markdown` → `html` converter written in `C`. +- [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`). -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. +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. -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). +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. -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`). +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). diff --git a/module2/ressources/emacs_orgmode.md b/module2/ressources/emacs_orgmode.md index 9293c9e4a46dc0d251f596289fb5b25679c89ead..8ea14256428d5d2c741bcc5ccf80f513845b7f46 100644 --- a/module2/ressources/emacs_orgmode.md +++ b/module2/ressources/emacs_orgmode.md @@ -1,6 +1,6 @@ --- TITLE: Emacs/org-mode -Date: Tue Feb 19 19:19:03 2019 +Date: Wed Mar 13 15:12:03 2019 --- **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). @@ -29,15 +29,26 @@ Table of Contents - [Additional useful emacs packages](#additional-useful-emacs-packages) - [Other resources](#other-resources) -Installing emacs, org-mode, ess, and auctex. -============================================ +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 + +1. Emacs 26 (the latest version) +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. + +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). 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.n redhat, fedora). -Today, the stable versions of the most common distributions provide recent enough versions of emacs and org-mode: +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) - 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) @@ -48,10 +59,10 @@ If your distribution is older than this, well, it may be a good time for upgradi Simply run (as root): ``` bash -apt-get update ; apt-get install emacs25 org-mode ess r-base auctex +apt-get update ; apt-get install emacs25 org-mode ``` -Then make sure you have a sufficiently recent version of emacs. +Then verify that you have a sufficiently recent version of Emacs. ``` bash emacs --version 2>&1 | head -n 1 @@ -61,7 +72,7 @@ emacs --version 2>&1 | head -n 1 GNU Emacs 25.2.2 ``` -Likewise, you'll want to check you have a recent version of org-mode: +Likewise, you'll want to check you have a recent version of Org-Mode: ``` bash emacs -batch --funcall "org-version" 2>&1 | grep version @@ -78,42 +89,16 @@ 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. -- **Option 1**: Install the `.dmg` file from [Vincent Goulet](http://vgoulet.act.ulaval.ca/): [](https://vigou3.gitlab.io/emacs-modified-macos/). It ships with recent versions: - - Emacs 26.1 - - Org-mode 9.1.13 - - ESS 17.11 - - 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` +The Web site 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. -- **Option 2**: If you use [Homebrew](https://docs.brew.sh/), do the following: - - ``` bash - brew update - brew install emacs --with-cocoa - brew linkapps emacs - brew install wget - brew tap dunn/emacs - brew install auctex - brew tap brewsci/science - brew install ess - ``` - - 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 - - ``` bash - brew linkapps emacs - ``` - - in order to make Emacs accessible directly from `/Applications`. +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. Windows ------- -Install the `.exe` file from [Vincent Goulet](http://vgoulet.act.ulaval.ca/): [](https://vigou3.gitlab.io/emacs-modified-windows/). It ships with recent versions: +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`. -- Emacs 26.1 -- Org-mode 9.1.13 -- ESS 17.11 +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. ### Directory naming conventions @@ -167,7 +152,7 @@ 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). -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: +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: ``` example rr_org/init.el @@ -176,6 +161,8 @@ rr_org/journal.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`. + Step 1: Prepare your journal ---------------------------- diff --git a/module2/ressources/jupyter.md b/module2/ressources/jupyter.md index 48affe03caaaede67d462314330f0abeb2fa99c2..2d86d4d45c761ce696783614d9ffa8e2b2a2af74 100644 --- a/module2/ressources/jupyter.md +++ b/module2/ressources/jupyter.md @@ -1,7 +1,7 @@ --- TITLE: Jupyter : tips and tricks, Installing and configuring AUTHOR: Arnaud Legrand, Benoit Rospars, Konrad Hinsen -Date: Tue Feb 19 15:42:13 2019 +Date: Wed Mar 20 12:15:02 2019 --- Table of Contents @@ -40,7 +40,7 @@ Simply follow the following steps: 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 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. -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). +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. Open the Jupyter file manager from the menu `File -> Open` and navigate to the directory where you want to upload your notebook. 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. @@ -75,7 +75,7 @@ Note that this `%%R` notation indicates that R should be used for the whole cell 1.3 Other languages ------------------- -Jupyter is not limited to Pytyhon and R. Many other languages are available: [](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. +Jupyter is not limited to Python and R. Many other languages are available: [](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. diff --git a/module2/ressources/jupyter_fr.md b/module2/ressources/jupyter_fr.md index ab3aec145f30e494ac1be3281bbf6f6e43d29c78..62d30bd5c6491b45413437c7be8cc840adbcd0d6 100644 --- a/module2/ressources/jupyter_fr.md +++ b/module2/ressources/jupyter_fr.md @@ -1,105 +1,105 @@ --- -TITLE: FIXME Jupyter : tips and tricks, Installing and configuring +TITLE: Jupyter : Trucs et astuces, installation et configuration AUTHOR: Arnaud Legrand, Benoit Rospars, Konrad Hinsen -Date: Tue Feb 19 17:43:42 2019 +Date: Wed Mar 20 12:15:23 2019 --- -Table of Contents -============================================================== +Table des matières +=============================================================== -- [1 Jupyter tips and tricks](#1-jupyter-tips-and-tricks) - - [1.1 Creating or importing a notebook](#11-creating-or-importing-a-notebook) - - [1.2 Running R and Python in the same notebook](#12-running-r-and-python-in-the-same-notebook) - - [1.3 Other languages](#13-other-languages) -- [2 Installing and configuring Jupyter on your computer](#2-installing-and-configuring-jupyter-on-your-computer) - - [2.1 Installing Jupyter](#21-installing-jupyter) - - [2.2 Making sure Jupyter allows you to use R](#22-making-sure-jupyter-allows-you-to-use-r) - - [2.3 Additional tips](#23-additional-tips) +- [1 Jupyter: Trucs et astuces](#1-jupyter-trucs-et-astuces) + - [1.1 Création ou import d'un notebook](#11-création-ou-import-dun-notebook) + - [1.2 Exécuter du code R et du code Python dans le même notebook](#12-exécuter-du-code-r-et-du-code-python-dans-le-même-notebook) + - [1.3 Autres langages que Python et R](#13-autres-langages-que-python-et-r) +- [2 Installation et configuration de Jupyter sur votre ordinateur](#2-installation-et-configuration-de-jupyter-sur-votre-ordinateur) + - [2.1 Installation de Jupyter](#21-installation-de-jupyter) + - [2.2 S'assurer que Jupyter vous permet d'utiliser R](#22-sassurer-que-jupyter-vous-permet-dutiliser-r) + - [2.3 Conseils additionnels](#23-conseils-additionnels) -1 Jupyter tips and tricks -========================= +1 Jupyter: Trucs et astuces +=========================== -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). +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). -1.1 Creating or importing a notebook +1.1 Création ou import d'un notebook ------------------------------------ -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. +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. -Adding a brand new notebook in a given directory -Simply follow the following steps: +Créer un notebook tout neuf dans un répertoire donné +1. À partir du menu: `File -> Open`. Ceci vous permet d'accéder au gestionnaire de fichiers de Jupyter. +2. Naviguez jusque dans le répertoire dans lequel vous souhaitez créer votre notebook. +3. Utilisez le bouton en haut à droite: `New -> Notebook: Python 3`. +4. Donnez un nom à votre notebook à partir du menu: `File -> Rename`. -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. -3. Then from the top right button: `New -> Notebook: Python 3`. -4. Give your notebook a name from the 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`). - 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`). +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, 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: -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 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. +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). +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. +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. 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. Open the Jupyter file manager from the menu `File -> Open` and navigate to the directory where you want to upload your notebook. -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. +1.2 Exécuter du code R et du code Python dans le même notebook +-------------------------------------------------------------- -1.2 Running R and Python in the same 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. -`rpy2` package allows to use both languages in the same notebook by: - -1. Loading `rpy2`: +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 %load_ext rpy2.ipython ``` -2. Using the `%R` Ipython magic: +2. Utilisez la (nouvellement activée) commande magique `%R`: ``` python %%R summary(cars) ``` - Python objects can then even be passed to R as follows (assuming `df` is a pandas dataframe): + Les objets Python peuvent même être passé à R de la façon suivante (ici, on suppose que `df` est une dataframe pandas): ``` python %%R -i df plot(df) ``` -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. +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. -1.3 Other languages -------------------- +1.3 Autres langages que Python et R +----------------------------------- -Jupyter is not limited to Pytyhon and R. Many other languages are available: [](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. +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), et en particulier des langages non libres comme SAS, Mathematica, Matlab... Notez que la maturité de ces noyaux est très variables. -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. +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. -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)). +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)). -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. +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. -2 Installing and configuring Jupyter on your computer -===================================================== +2 Installation et configuration de Jupyter sur votre ordinateur +=============================================================== -In this section, we explain how to set up a Jupyter environment on your own computer similar to the one deployed for this MOOC. +Dans cette section, nous expliquons comment installer, sur votre ordinateur, un environnement Jupyter similaire à celui que nous avons déployé pour ce MOOC. -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. +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. -2.1 Installing Jupyter ----------------------- +2.1 Installation de Jupyter +--------------------------- -Follow these instructions if you wish to have a Jupyter environment on your own computer similar to the one we set up for this MOOC. +Ces instructions permettent d'obtenir sur votre ordinateur un environnement Jupyter similaire à celui que nous avons déployé dans le cadre du MOOC. -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. +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 is a light version of Anaconda, which includes Python, the Jupyter Notebook, and other commonly used packages for scientific computing and data science. +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. -Then download the [moocrr environment file](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57) and create the environment using conda: +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: ``` shell conda env create -f environment.yml @@ -114,44 +114,44 @@ source activate mooc_rr jupyter notebook ``` -2.2 Making sure Jupyter allows you to use R -------------------------------------------- +2.2 S'assurer que Jupyter vous permet d'utiliser R +-------------------------------------------------- -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. +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 -### • Installing [IRKernel](https://github.com/IRkernel/IRkernel) (R package) +### • Installation de [IRKernel](https://github.com/IRkernel/IRkernel) (R package) -Do the following in R console: +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: -Install the `devtools` package: +- Installer la bibliothèque `devtools`: -``` r -install.packages('devtools',dep=TRUE) -``` + ``` r + install.packages('devtools',dep=TRUE) + ``` -Define a proxy if needed: +- Définissez un proxy si nécessaire (c'est important si votre ordinateur est connecté à une entreprise qui limite l'accès à Internet): -``` r -library(httr) -set_config(use_proxy(url="proxy", port=80, username="username", password="password")) -``` + ``` r + library(httr) + set_config(use_proxy(url="proxy", port=80, username="username", password="password")) + ``` -Install the `IRkernel` package: +- Installez la bibliothèque `IRkernel`: -``` r -devtools::install_github('IRkernel/IRkernel') -IRkernel::installspec() # to register the kernel in the current R installation -``` + ``` r + devtools::install_github('IRkernel/IRkernel') + IRkernel::installspec() # to register the kernel in the current R installation + ``` -### • Installing rpy2 (Python package) +### • Installation de rpy2 (Python package) -On Linux, the rpy2 package is available in standard distributions +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 sudo apt-get install python3-rpy2 python3-tzlocal ``` -An alternative (not really recommended if the first one is available) consists in going through the python package manager with +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 pip3 install rpy2 @@ -159,57 +159,58 @@ pip3 install rpy2 **Windows** -Download the `rpy2` [binary file](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) by choosing the right operating system. +Téléchargez le [fichier binaire](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) `rpy2` en choisissant le bon système d'exploitation. -Open a DOS console and type the following command: +Ouvrez une console DOS et tapez les commandes suivantes: ``` shell python -m pip install rpy2‑2.9.4‑cp37‑cp37m‑win_amd64.whl # adapt filename ``` -Install also `tzlocal`: +Installez également `tzlocal`: ``` shell python -m pip install tzlocal ``` -2.3 Additional tips -------------------- +2.3 Conseils additionnels +------------------------- -### • Exporting a notebook +### • Exporter un notebook -Here is what we had to install on a recent Debian computer to make sure the notebook export via LaTeX works: +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 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: +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: ``` bash 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/). +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/). -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. +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** -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. +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. -### • Improving notebook readability +### • Améliorer la lisibilité d'un notebook -Here are a few extensions that can ease your life: +Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire. Voici quelques extensions qui peuvent vous faciliter un peu la vie: -- [Code folding](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook) to improve readability when browsing the notebook. +- Il est possible [plier/déplier votre code](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook): ``` shell pip3 install jupyter_contrib_nbextensions # jupyter contrib nbextension install --user # not done yet ``` -- [Hiding code](https://github.com/kirbs-/hide_code) to improve readability when exporting. +- 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 sudo pip3 install hide_code @@ -218,10 +219,10 @@ Here are a few extensions that can ease your life: jupyter-serverextension enable --py hide_code ``` -### • Interacting with GitLab and GitHub +### • Interaction avec GitLab et 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. +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. -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). +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. -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. +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. diff --git a/module2/ressources/maintaining_a_journal.md b/module2/ressources/maintaining_a_journal.md index 049ad1b728e4d6fb12d9f434bfe1cd988aba5d9c..039c55e19144bea2876d0de0fe9732d182e64309 100644 --- a/module2/ressources/maintaining_a_journal.md +++ b/module2/ressources/maintaining_a_journal.md @@ -1,19 +1,19 @@ --- TITLE: Maintaining a journal -Date: Tue Feb 19 19:19:03 2019 +Date: Wed Mar 20 12:15:41 2019 --- Table of Contents ============================================================== -- [Some examples of LabBooks provided for inspiration](#some-examples-of-labbooks-provided-for-inspiration) -- [How to report efficiently (by Martin Quinson)](#how-to-report-efficiently-by-martin-quinson) +- [1. Some examples of LabBooks provided for inspiration](#1-some-examples-of-labbooks-provided-for-inspiration) +- [2. How to report efficiently (by Martin Quinson)](#2-how-to-report-efficiently-by-martin-quinson) - [Reporting](#reporting) - [Reporting Logistics](#reporting-logistics) - [Reporting Document Organization](#reporting-document-organization) -Some examples of LabBooks provided for inspiration -================================================== +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: @@ -28,8 +28,8 @@ Since a few years, we systematically require any or our students to have a labor 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. -How to report efficiently (by Martin Quinson) -============================================= +2. How to report efficiently (by Martin Quinson) +================================================ My friend Martin has gathered \[\[\]\[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/): diff --git a/module2/ressources/maintaining_a_journal_fr.md b/module2/ressources/maintaining_a_journal_fr.md index 2128ebcb600b0ce8b77049282b9518679917a6f0..ab3115d766418adcaec64e8348de35e6b14bef19 100644 --- a/module2/ressources/maintaining_a_journal_fr.md +++ b/module2/ressources/maintaining_a_journal_fr.md @@ -1,104 +1,104 @@ --- -TITLE: FIXME Maintaining a journal -Date: Tue Feb 19 19:19:03 2019 +TITLE: Tenir un journal à jour +Date: Wed Mar 20 12:16:07 2019 --- -Table of Contents -============================================================== +Table des matières +=============================================================== -- [Some examples of LabBooks provided for inspiration](#some-examples-of-labbooks-provided-for-inspiration) -- [How to report efficiently (by Martin Quinson)](#how-to-report-efficiently-by-martin-quinson) - - [Reporting](#reporting) - - [Reporting Logistics](#reporting-logistics) - - [Reporting Document Organization](#reporting-document-organization) +- [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) +- [2. Comment rendre compte de son activité efficacement](#2-comment-rendre-compte-de-son-activité-efficacement) + - [Le Reporting](#le-reporting) + - [Logistique](#logistique) + - [Organisation d'un compte rendu d'activité](#organisation-dun-compte-rendu-dactivité) -Some examples of LabBooks provided for inspiration -================================================== +1. Quelques exemples de cahiers de notes ou de laboratoires pouvant servir de source d'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: +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: -- 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. -- 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). -- [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). -- [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 (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. +- 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). +- 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). +- Ceux qui travaillent sous la supervision de [Martin Quinson](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/) suivent des conventions similaires: + - 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. - Betsegaw Lemma, M2R 2017. [LabBook](https://github.com/betsegawlemma/internship/blob/master/intern_report.org) - - 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/). - - Matthieu Nicolas, engineer on PLM, 2014-2016, [Journal](https://github.com/MatthieuNICOLAS/PLM-reporting/blob/master/activity-report.org). + - 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). -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. +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. -How to report efficiently (by Martin Quinson) -============================================= +2. Comment rendre compte de son activité efficacement +===================================================== -My friend Martin has gathered \[\[\]\[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/): +Mon ami Martin a réalisé \[\[\]\[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/)). -Reporting ---------- +Le Reporting +------------ -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: +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: -- 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. +- Ç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. +- Ç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. +- Ç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. -I want you to write your reporting in an org file (yep, you don't have a choice here). \[..\] +Je veux que vous écriviez votre compte rendu d'activité dans un fichier org-mode (et oui, vous n'avez pas le choix! ). \[..\] -Reporting Logistics -------------------- +Logistique +---------- -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. +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é. -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. +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. -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. +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. -Reporting Document Organization -------------------------------- +Organisation d'un compte rendu d'activité +----------------------------------------- -Your reporting document should have four main parts: +Selon moi, une bonne pratique consiste à structurer votre compte rendu d'activité de la façon suivante: -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). +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). -Development -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. +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 -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. +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 -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. +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. -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. +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. -Each of section describing a period should contain three subsubsections: +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: -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). +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. -Blocking points and questions -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). +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). -Planned work -A few items about what you plan to work on during the next period. +Travaux prévus +Une petite liste détaillant les points auxquels vous comptez vous attaquer dans la période à venir. -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. +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. -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. +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. -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. +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. :) -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). +À 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). -**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: +**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 - *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. +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. ``` example * Introduction diff --git a/module2/ressources/orgmode_examples/README.md b/module2/ressources/orgmode_examples/README.md index 152babbe3bb3239d037cd43f1c0ed9f7015c21e0..ba6b4d42f85105e09b0c1f5a948113d78b464cc5 100644 --- a/module2/ressources/orgmode_examples/README.md +++ b/module2/ressources/orgmode_examples/README.md @@ -1,7 +1,7 @@ --- -TITLE: FIXME Document Examples +TITLE: Document Examples AUTHOR: Arnaud Legrand -Date: Tue Feb 19 17:43:42 2019 +Date: Wed Mar 20 13:03:17 2019 --- Table of Contents diff --git a/module2/ressources/orgmode_examples/README_fr.md b/module2/ressources/orgmode_examples/README_fr.md index 463f6e957fee00f4591ace2c8915aeccf8a84df1..bd374808d4383cfd234ba4ef852cbfa73f1603cd 100644 --- a/module2/ressources/orgmode_examples/README_fr.md +++ b/module2/ressources/orgmode_examples/README_fr.md @@ -1,33 +1,33 @@ --- -TITLE: TODO Org Document Examples +TITLE: Quelques exemples de documents en Org-Mode AUTHOR: Arnaud Legrand -Date: Tue Feb 19 17:43:42 2019 +Date: Wed Mar 20 13:01:44 2019 --- Table of Contents ============================================================== -- [Examples from the Video](#examples-from-the-video) -- [Other examples](#other-examples) +- [Les documents montrés en exemple dans les vidéos du MOOC](#les-documents-montrés-en-exemple-dans-les-vidéos-du-mooc) +- [Autres exemples](#autres-exemples) -Examples from the Video -======================= +Les documents montrés en exemple dans les vidéos du MOOC +======================================================== -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: +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): 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. -2. [labbooksingle.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. [labbookseveral.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. [technicalreport.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. +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`. +2. [labbooksingle.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. [labbookseveral.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. [technicalreport.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. -Other examples -============== +Autres exemples +=============== -Here are a few links to other kind of examples: +Voici à toute fin utile quelques liens vers d'autres types d'exemples: -- Slides: all my slides for a series of lectures is available here: . 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) -- Lucas Schnorr, a colleague, maintains: - - 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: -- 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). +- 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). +- 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: . 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). +- Lucas Schnorr, un collègue et ami, maintient: + - 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) + - son cours de programmation (en portugais) pour les élèves de licence: diff --git a/module2/slides/ressources.md b/module2/slides/ressources.md index 6c8912c7e48a9fcabfaeddaef5307fefe727cb33..6c50410f717c46bfb8a5af0a85c6b45e4867c2e6 100644 --- a/module2/slides/ressources.md +++ b/module2/slides/ressources.md @@ -1,8 +1,10 @@ --- -TITLE: FIXME Computational Documents -Date: Tue Feb 19 19:19:03 2019 +TITLE: Computational Documents +Date: Wed Mar 20 13:19:19 2019 --- +This document gathers most references mentioned in the videos. This is a rather crude list. + Table of Contents ============================================================== @@ -15,13 +17,11 @@ Table of Contents - [M2-S2: Why is This so Difficult?](#m2-s2-why-is-this-so-difficult) - [Mistakes](#mistakes) - [Going Public?](#going-public) - - [Tools to Avoid and Possible Alternatives](#tools-to-avoid-and-possible-alternatives) - [M2-S3: Computational Documents: Principles](#m2-s3-computational-documents-principles) - [M2-S5: Collaborating](#m2-s5-collaborating) - [Preparing a Document for a Journal or a Conference](#preparing-a-document-for-a-journal-or-a-conference) - [M2-S6: Comparative Study](#m2-s6-comparative-study) - - [See org-mode documents.](#see-org-mode-documents) - - [Bonus: expériences vécues](#bonus-expériences-vécues) + - [Exemples of Org-Mode documents](#exemples-of-org-mode-documents) M2-S0: Computational Documents ============================== @@ -46,7 +46,7 @@ Functional MRI Incorrect Protein Structures ---------------------------- -[a "buggy software"](https://people.ligo-wa.caltech.edu/~michael.landry/calibration/S5/getsignright.pdf) +[A "buggy software"](https://people.ligo-wa.caltech.edu/~michael.landry/calibration/S5/getsignright.pdf). Other domains ------------- @@ -68,9 +68,6 @@ Going Public? - Someone may [benefit from my hard work](http://www.nature.com/news/the-top-100-papers-1.16224) -Tools to Avoid and Possible Alternatives ----------------------------------------- - M2-S3: Computational Documents: Principles ========================================== @@ -93,31 +90,5 @@ Requirements for producing a **pdf**: M2-S6: Comparative Study ======================== -See org-mode documents. ------------------------ - -Bonus: expériences vécues -------------------------- - -Éléments clés lors du choix: - -- Simplicité de prise en main vs. vrai éditeur -- Où sont fait les calculs -- Multi-langage - - -- Gestion des langages compilés -- Notions de caches et d'état - -Les principaux outils actuels: - -- jupyter -- rstudio -- org-mode - -Limitations: - -- Longs calculs -- Grands documents -- Solutions wysiwyg pour jupyter - -Historique/diff un peu compliqué pour jupyter +[Exemples of Org-Mode documents](../ressources/orgmode_examples/README.org) +--------------------------------------------------------------------------- diff --git a/module2/slides/ressources_fr.md b/module2/slides/ressources_fr.md index 02ffcc0d1c12ed59137e841ade1145593fb12f6e..9f969f94529028967aeba922777c9647018e9bd2 100644 --- a/module2/slides/ressources_fr.md +++ b/module2/slides/ressources_fr.md @@ -1,7 +1,96 @@ --- -TITLE: FIXME Computational Documents -Date: Tue Feb 19 18:18:56 2019 +TITLE: Le document computationnel +Date: Wed Mar 20 13:19:19 2019 --- +Ce document rassemble la plupart des références mentionnées dans les vidéos. C'est une liste relativement grossière qui mériterait d'être améliorée. + Table des matières =============================================================== + +- [M2-S0: Le document computationnel](#m2-s0-le-document-computationnel) +- [M2-S1: Exemples récents d'études assez discutées](#m2-s1-exemples-récents-détudes-assez-discutées) + - [Économie: Politiques d'austérité](#économie-politiques-daustérité) + - [Les IRM fonctionnelles](#les-irm-fonctionnelles) + - [Les fausses structures de protéines](#les-fausses-structures-de-protéines) + - [Autres domaines](#autres-domaines) +- [M2-S2: Pourquoi est-ce difficile?](#m2-s2-pourquoi-est-ce-difficile) + - [Les erreurs classiques](#les-erreurs-classiques) + - [Tout rendre publique ?](#tout-rendre-publique) +- [M2-S3: Le document computationnel : principe](#m2-s3-le-document-computationnel-principe) +- [M2-S5: Travailler avec les autres](#m2-s5-travailler-avec-les-autres) + - [Préparation d'un document pour un journal ou pour une conférence](#préparation-dun-document-pour-un-journal-ou-pour-une-conférence) +- [M2-S6: Analyse comparée des différents outils](#m2-s6-analyse-comparée-des-différents-outils) + - [Exemples de document Org-Mode](#exemples-de-document-org-mode) + +M2-S0: Le document computationnel +================================= + +M2-S1: Exemples récents d'études assez discutées +================================================ + +Économie: Politiques d'austérité +-------------------------------- + +- [Reinhart et Rogoff](https://en.wikipedia.org/wiki/Growth_in_a_Time_of_Debt): *Growth in a Time of Debt* +- Herndon, Ash et Pollin +- Wray: combining data across centuries, exchange rate regimes, + +Les IRM fonctionnelles +---------------------- + +- 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) ☺ +- 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*. + +Les fausses structures de protéines +----------------------------------- + +[A "buggy software"](https://people.ligo-wa.caltech.edu/~michael.landry/calibration/S5/getsignright.pdf). + +Autres domaines +--------------- + +- [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*" + +M2-S2: Pourquoi est-ce difficile? +================================= + +Les erreurs classiques +---------------------- + +- [Enquoi les ordinateurs ont "cassé" la science](http://theconversation.com/how-computers-broke-science-and-what-we-can-do-to-fix-it-49938) +- [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/) + +Tout rendre publique ? +---------------------- + +- Quelqu'un pourrait [tirer parti de mon dur labeur](http://www.nature.com/news/the-top-100-papers-1.16224) + +M2-S3: Le document computationnel : principe +============================================ + +M2-S5: Travailler avec les autres +================================= + +Préparation d'un document pour un journal ou pour une conférence +---------------------------------------------------------------- + +De quoi aurez-vous besoin pour produire un document **pdf**: + +- En interne: *pandoc*, *knitr* ou *emacs/org-mode*. +- *LaTeX* devra aussi être installé + +Voici quelques billets intéressants sur le sujet: + +- + - is a must-have +- +- + +M2-S6: Analyse comparée des différents outils +============================================= + +[Exemples de document Org-Mode](../ressources/orgmode_examples/README_fr.org) +-----------------------------------------------------------------------------