diff --git a/module1/ressources/introduction_to_markdown.md b/module1/ressources/introduction_to_markdown.md index 27fd21a0e63ce1f584a1c09a062d5f006a579ab9..c86eda548f396cd10bfa2487c1072bd2ab8810fd 100644 --- a/module1/ressources/introduction_to_markdown.md +++ b/module1/ressources/introduction_to_markdown.md @@ -1,35 +1,37 @@ --- -TITLE: Introduction to Markdown -Date: Wed Mar 20 13:57:10 2019 +title: Introduction to Markdown +date: Wed Mar 20 13:57:10 2019 --- -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 of Contents -============================================================== - -- [Syntax](#syntax) - - [Headers](#headers) - - [Emphasis](#emphasis) - - [Lists](#lists) - - [Images](#images) - - [Links](#links) - - [Blockquotes](#blockquotes) - - [Inline code](#inline-code) -- [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 -------- +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 of Contents TOC + + - [Syntax](#syntax) + - [Headers](#headers) + - [Emphasis](#emphasis) + - [Lists](#lists) + - [Images](#images) + - [Links](#links) + - [Blockquotes](#blockquotes) + - [Inline code](#inline-code) + - [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 ``` example # This is an

tag @@ -37,8 +39,7 @@ Headers ###### This is an

tag ``` -Emphasis --------- +## Emphasis ``` example *This text will be italic* @@ -50,8 +51,7 @@ __This will also be bold__ _You **can** combine them_ ``` -Lists ------ +## Lists ### Unordered @@ -72,24 +72,21 @@ Lists 2. Item 3b ``` -Images ------- +## Images ``` example ![GitHub Logo](/images/logo.png) Format: ![Alt Text](url) ``` -Links ------ +## Links ``` example http://github.com - automatic! [GitHub](http://github.com) ``` -Blockquotes ------------ +## Blockquotes ``` example As Kanye West said: @@ -98,8 +95,7 @@ As Kanye West said: > the present is our past. ``` -Inline code ------------ +## Inline code ```` example To print some text with python, you should use the `print()` function. @@ -108,20 +104,28 @@ print("Hello world!") ``` ```` -Writing Math -============ +# Writing Math -Math formulas are easy to write using Markdown, either using the **inline** mode or the **displayed formulas** mode. With the inline mode, formulas are inlined in the current paragraph whereas with the displayed mode, they appear as centered and emphasized. +Math formulas are easy to write using Markdown, either using the +**inline** mode or the **displayed formulas** mode. With the inline +mode, formulas are inlined in the current paragraph whereas with the +displayed mode, they appear as centered and emphasized. -The formatting generally slightly differs in both cases since, to display nicely on a single line, it is generally required to pack them a bit more than when they are emphasized. +The formatting generally slightly differs in both cases since, to +display nicely on a single line, it is generally required to pack them a +bit more than when they are emphasized. -To write formulas using the **inline** mode, they should be surrounded by a single `$` (as a consequence, whenever you need to use the original dollar symbol, you should prefix it with a backslash: `\$`). To write formulas using the **displayed** mode, they should be surrounded by a `$$`. Here are a few examples: +To write formulas using the **inline** mode, they should be surrounded +by a single `$` (as a consequence, whenever you need to use the original +dollar symbol, you should prefix it with a backslash: `\$`). To write +formulas using the **displayed** mode, they should be surrounded by a +`$$`. Here are a few examples: ``` example This expression $\sum_{i=1}^n X_i$ is inlined. ``` -This expression $\\sum\_{i=1}^n X\_i$ is inlined. +This expression \(\sum_{i=1}^n X_i\) is inlined. ``` example This expression is emphasized: @@ -131,103 +135,152 @@ $$\sum_{i=1}^n X_i$$ This expression is emphasized: -$$\\sum\_{i=1}^n X\_i$$ - -In the rest of this section we present a brief selection of common symbols and commands. Actually, almost any classical LaTeX command can used as such in Markdown, provided it is surrounded by a `$`. For more complete examples, please have a look at these ces [examples by James H. Steiger](http://www.statpower.net/Content/310/R%2520Stuff/SampleMarkdown.html). - -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, binomial coefficients, square roots, ... ---------------------------------------------------- +\[\sum_{i=1}^n X_i\] + +In the rest of this section we present a brief selection of common +symbols and commands. Actually, almost any classical LaTeX command can +used as such in Markdown, provided it is surrounded by a `$`. For more +complete examples, please have a look at these ces [examples by James H. +Steiger](http://www.statpower.net/Content/310/R%2520Stuff/SampleMarkdown.html). + +## Greek Letters + +| Symbol | Command | +| ---------- | ---------- | +| \(\alpha\) | `$\alpha$` | +| \(\beta\) | `$\beta$` | +| \(\gamma\) | `$\gamma$` | +| \(\Gamma\) | `$\Gamma$` | +| \(\pi\) | `$\pi$` | + +## Usual functions and operators + +| Symbol | Command | +| ----------- | ----------- | +| \(\cos\) | `$\cos$` | +| \(\sin\) | `$\sin$` | +| \(\lim\) | `$\lim$` | +| \(\exp\) | `$\exp$` | +| \(\to\) | `$\to$` | +| \(\in\) | `$\in$` | +| \(\forall\) | `$\forall$` | +| \(\exists\) | `$\exists$` | +| \(\equiv\) | `$\equiv$` | +| \(\sim\) | `$\sim$` | +| \(\approx\) | `$\approx$` | +| \(\times\) | `$\times$` | +| \(\le\) | `$\le$` | +| \(\ge\) | `$\ge$` | + +## Exponents and indices + +| Symbol | Command | +| ----------- | ----------- | +| \(k_{n+1}\) | `$k_{n+1}$` | +| \(n^2\) | `$n^2$` | +| \(k_n^2\) | `$k_n^2$` | + +## Fractions, binomial coefficients, square roots, … | Symbol | Command | -|-------------------------------|-------------------------------| -| $\\frac{4z^3}{16}$ | `$\frac{4z^3}{16}$` | -| $\\frac{n!}{k!(n-k)!}$ | `$\frac{n!}{k!(n-k)!}$` | -| $\\binom{n}{k}$ | `$\binom{n}{k}$` | -| $\\frac{\\frac{x}{1}}{x - y}$ | `$\frac{\frac{x}{1}}{x - y}$` | -| **3/7 | `$^3/_7$` | -| $\\sqrt{k}$ | `$\sqrt{k}$` | -| $\\sqrt\[n\]{k}$ | `$\sqrt[n]{k}$` | - -Summations and integrals ------------------------- - -| 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$` | - -Outfits ☺ ---------- - -| Symbol | Command | -|------------------------|-------------------------| -| *â* | `$\hat{a}$` | -| *ā* | `$\bar{a}$` | -| *ȧ* | `$\dot{a}$` | -| $\\ddot{a}$ | `$\ddot{a}$` | -| $\\overrightarrow{AB}$ | `$\overrightarrow{AB}$` | - -About `markdown` -================ - -First of all, to know more about `markdown` and its extensions, you may want to read: - -- The « [Élaboration et conversion de documents avec Markdown et Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » tutorial by 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/). - -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. - -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: - -- 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`). - -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. - -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. - -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). +| ----------------------------- | ----------------------------- | +| \(\frac{4z^3}{16}\) | `$\frac{4z^3}{16}$` | +| \(\frac{n!}{k!(n-k)!}\) | `$\frac{n!}{k!(n-k)!}$` | +| \(\binom{n}{k}\) | `$\binom{n}{k}$` | +| \(\frac{\frac{x}{1}}{x - y}\) | `$\frac{\frac{x}{1}}{x - y}$` | +| \(^3/_7\) | `$^3/_7$` | +| \(\sqrt{k}\) | `$\sqrt{k}$` | +| \(\sqrt[n]{k}\) | `$\sqrt[n]{k}$` | + +## Summations and integrals + +| Symbol | Command | +| ---------------------------------------------- | ---------------------------------------------- | +| \(\sum_{i=1}^{10} t_i\) | `$\sum_{i=1}^{10} t_i$` | +| \(\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x\) | `$\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x$` | + +## Outfits ☺ + +| Symbol | Command | +| ----------------------- | ----------------------- | +| \(\hat{a}\) | `$\hat{a}$` | +| \(\bar{a}\) | `$\bar{a}$` | +| \(\dot{a}\) | `$\dot{a}$` | +| \(\ddot{a}\) | `$\ddot{a}$` | +| \(\overrightarrow{AB}\) | `$\overrightarrow{AB}$` | + +# About `markdown` + +First of all, to know more about `markdown` and its extensions, you may +want to read: + + - The « [Élaboration et conversion de documents avec Markdown et + Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » tutorial by + 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/). + +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. + +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: + + - 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`). + +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. + +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. + +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/module1/ressources/introduction_to_markdown_fr.md b/module1/ressources/introduction_to_markdown_fr.md index 3e12bbecb7febe392b441b70c08a05eafe703741..096445549a2872cd7d647f2cbf146ad186e72d49 100644 --- a/module1/ressources/introduction_to_markdown_fr.md +++ b/module1/ressources/introduction_to_markdown_fr.md @@ -1,35 +1,36 @@ --- -TITLE: Introduction à Markdown -Date: Tue Feb 19 19:19:03 2019 +title: Introduction à Markdown +date: Tue Feb 19 19:19:03 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/). - -Table des matières -=============================================================== - -- [Syntaxe](#syntaxe) - - [Headers](#headers) - - [Emphasis](#emphasis) - - [Lists](#lists) - - [Images](#images) - - [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 -======= - -Headers -------- +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/). + +# Table des matières TOC + + - [Syntaxe](#syntaxe) + - [Headers](#headers) + - [Emphasis](#emphasis) + - [Lists](#lists) + - [Images](#images) + - [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 + +## Headers ``` example # This is an

tag @@ -37,8 +38,7 @@ Headers ###### This is an

tag ``` -Emphasis --------- +## Emphasis ``` example *This text will be italic* @@ -50,8 +50,7 @@ __This will also be bold__ _You **can** combine them_ ``` -Lists ------ +## Lists ### Unordered @@ -72,24 +71,21 @@ Lists 2. Item 3b ``` -Images ------- +## Images ``` example ![GitHub Logo](/images/logo.png) Format: ![Alt Text](url) ``` -Links ------ +## Links ``` example http://github.com - automatic! [GitHub](http://github.com) ``` -Blockquotes ------------ +## Blockquotes ``` example As Kanye West said: @@ -98,8 +94,7 @@ As Kanye West said: > the present is our past. ``` -Inline code ------------ +## Inline code ```` example To print some text with python, you should use the `print()` function. @@ -108,20 +103,29 @@ print("Hello world!") ``` ```` -Écrire des Maths -================ +# Écrire des Maths -Il est possible d'écrire des formules en Markdown, soit en mode **inline** soit en mode **displayed formulas**. Dans le premier cas, les formules sont inclues directement à l'intérieur du paragraphe courant alors que dans le second, elles apparaissent centrées et mises en exergue. +Il est possible d'écrire des formules en Markdown, soit en mode +**inline** soit en mode **displayed formulas**. Dans le premier cas, les +formules sont inclues directement à l'intérieur du paragraphe courant +alors que dans le second, elles apparaissent centrées et mises en +exergue. -Le formatage de la formule est légèrement différent dans les deux cas car pour qu'une formule s'affiche joliment sur une seule ligne, il faut la "tasser" un peu plus que lorsqu'elle est mise en valeur. +Le formatage de la formule est légèrement différent dans les deux cas +car pour qu'une formule s'affiche joliment sur une seule ligne, il faut +la "tasser" un peu plus que lorsqu'elle est mise en valeur. -Pour écrire une formule en mode **inline**, il faut la délimiter par un `$` (du coup, pour écrire le symbole dollar, il faut le préfixer par un backslash, comme ceci: `\$`) alors que pour écrire en mode **displayed**, il faut la délimiter par un `$$`. Un petit exemple valant mieux qu'un long discours, voici concrètement comment cela fonctionne: +Pour écrire une formule en mode **inline**, il faut la délimiter par un +`$` (du coup, pour écrire le symbole dollar, il faut le préfixer par un +backslash, comme ceci: `\$`) alors que pour écrire en mode +**displayed**, il faut la délimiter par un `$$`. Un petit exemple valant +mieux qu'un long discours, voici concrètement comment cela fonctionne: ``` example Cette expression $\sum_{i=1}^n X_i$ est inlinée. ``` -Cette expression $\\sum\_{i=1}^n X\_i$ est inlinée. +Cette expression \(\sum_{i=1}^n X_i\) est inlinée. ``` example Cette expression est mise en valeur: @@ -131,103 +135,162 @@ $$\sum_{i=1}^n X_i$$ Cette expression est mise en valeur: -$$\\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 | -|-------------------------------|-------------| -| *k**n* + 1 | `$k_{n+1}$` | -| *n*2 | `$n^2$` | -| *k**n*2 | `$k_n^2$` | - -Fractions, coefficients binomiaux, racines, ... ------------------------------------------------ +\[\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\) | `$\alpha$` | +| \(\beta\) | `$\beta$` | +| \(\gamma\) | `$\gamma$` | +| \(\Gamma\) | `$\Gamma$` | +| \(\pi\) | `$\pi$` | + +## Fonctions et opérateurs + +| Symbole | Commande | +| ----------- | ----------- | +| \(\cos\) | `$\cos$` | +| \(\sin\) | `$\sin$` | +| \(\lim\) | `$\lim$` | +| \(\exp\) | `$\exp$` | +| \(\to\) | `$\to$` | +| \(\in\) | `$\in$` | +| \(\forall\) | `$\forall$` | +| \(\exists\) | `$\exists$` | +| \(\equiv\) | `$\equiv$` | +| \(\sim\) | `$\sim$` | +| \(\approx\) | `$\approx$` | +| \(\times\) | `$\times$` | +| \(\le\) | `$\le$` | +| \(\ge\) | `$\ge$` | + +## Exposants et indices + +| Symbole | Commande | +| ----------- | ----------- | +| \(k_{n+1}\) | `$k_{n+1}$` | +| \(n^2\) | `$n^2$` | +| \(k_n^2\) | `$k_n^2$` | + +## Fractions, coefficients binomiaux, racines, … | Symbole | Commande | -|-------------------------------|-------------------------------| -| $\\frac{4z^3}{16}$ | `$\frac{4z^3}{16}$` | -| $\\frac{n!}{k!(n-k)!}$ | `$\frac{n!}{k!(n-k)!}$` | -| $\\binom{n}{k}$ | `$\binom{n}{k}$` | -| $\\frac{\\frac{x}{1}}{x - y}$ | `$\frac{\frac{x}{1}}{x - y}$` | -| **3/7 | `$^3/_7$` | -| $\\sqrt{k}$ | `$\sqrt{k}$` | -| $\\sqrt\[n\]{k}$ | `$\sqrt[n]{k}$` | - -Sommes et intégrales --------------------- - -| Symbole | Commande | -|----------------------------------------------------|------------------------------------------------| -| $\\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 ------------- - -| Symbole | Commande | -|------------------------|-------------------------| -| *â* | `$\hat{a}$` | -| *ā* | `$\bar{a}$` | -| *ȧ* | `$\dot{a}$` | -| $\\ddot{a}$ | `$\ddot{a}$` | -| $\\overrightarrow{AB}$ | `$\overrightarrow{AB}$` | - -Autour de `markdown` -==================== - -Tout d'abord, pour aller plus loin avec `markdown` et ses extensions / ramifications : - -- Le didacticiel « [Élaboration et conversion de documents avec Markdown et Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » de 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/). - -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. - -Pour convertir un fichier `markdown` en un format « arbitraire », la solution à ce jour la plus complète est [Pandoc](http://pandoc.org/), logiciel développé par John MacFarlane, un philosophe de Berkeley (le site [github](https://github.com/jgm/pandoc)). En plus du site de `Pandoc`, le didacticiel de J.-D. Bonjour donne de nombreuses explications sur comment installer et utiliser `pandoc` dans la section [Utilisation du convertisseur Pandoc](https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc). Comme `pandoc` -- écrit en Haskell -- peut être parfois un peu difficile à installer, nous indiquons maintenant quelques solutions alternatives : - -- Des sites comme 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`). - -La conversion en `pdf` passe toujours par [LaTeX](https://fr.wikipedia.org/wiki/LaTeX) ce qui nécessite d'avoir une version complète et à jour de ce logiciel sur sa machine. - -Dans la petite démonstration, nous montrons comment générer un fichier `docx` à partir d'un fichier `md` avec `Pandoc` et nous soulignons qu'il est alors possible d'utiliser un traitement de texte comme `LibreOffice` pour modifier le fichier obtenu. Il est clair que si des modifications sont apportées au `docx` elle en seront pas (automatiquement) propagées au `md`. Il faudra utiliser `Pandoc` pour cela et effectuer une conversion de `docx` vers `md` (et seules les éléments du format `docx` qui existent en `md` seront conservés). - -Une stratégie qui est souvent employée et qui fonctionne bien en pratique consiste à faire le gros du travail de rédaction d'un article ou d'un mémoire en `Markdown`. La rédaction terminée, le fichier est exporté au format `docx` (ou `LaTeX`) et des ajustements de mise en page sont alors effectués avec un logiciel de traitement de texte (ou un éditeur `LaTeX`). +| ----------------------------- | ----------------------------- | +| \(\frac{4z^3}{16}\) | `$\frac{4z^3}{16}$` | +| \(\frac{n!}{k!(n-k)!}\) | `$\frac{n!}{k!(n-k)!}$` | +| \(\binom{n}{k}\) | `$\binom{n}{k}$` | +| \(\frac{\frac{x}{1}}{x - y}\) | `$\frac{\frac{x}{1}}{x - y}$` | +| \(^3/_7\) | `$^3/_7$` | +| \(\sqrt{k}\) | `$\sqrt{k}$` | +| \(\sqrt[n]{k}\) | `$\sqrt[n]{k}$` | + +## Sommes et intégrales + +| Symbole | Commande | +| ---------------------------------------------- | ---------------------------------------------- | +| \(\sum_{i=1}^{10} t_i\) | `$\sum_{i=1}^{10} t_i$` | +| \(\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x\) | `$\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x$` | + +## Déguisements + +| Symbole | Commande | +| ----------------------- | ----------------------- | +| \(\hat{a}\) | `$\hat{a}$` | +| \(\bar{a}\) | `$\bar{a}$` | +| \(\dot{a}\) | `$\dot{a}$` | +| \(\ddot{a}\) | `$\ddot{a}$` | +| \(\overrightarrow{AB}\) | `$\overrightarrow{AB}$` | + +# Autour de `markdown` + +Tout d'abord, pour aller plus loin avec `markdown` et ses extensions / +ramifications : + + - Le didacticiel « [Élaboration et conversion de documents avec + Markdown et Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » de + 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/). + +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. + +Pour convertir un fichier `markdown` en un format « arbitraire », la +solution à ce jour la plus complète est [Pandoc](http://pandoc.org/), +logiciel développé par John MacFarlane, un philosophe de Berkeley (le +site [github](https://github.com/jgm/pandoc)). En plus du site de +`Pandoc`, le didacticiel de J.-D. Bonjour donne de nombreuses +explications sur comment installer et utiliser `pandoc` dans la section +[Utilisation du convertisseur +Pandoc](https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc). Comme +`pandoc` – écrit en Haskell – peut être parfois un peu difficile à +installer, nous indiquons maintenant quelques solutions alternatives : + + - Des sites comme 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`). + +La conversion en `pdf` passe toujours par +[LaTeX](https://fr.wikipedia.org/wiki/LaTeX) ce qui nécessite d'avoir +une version complète et à jour de ce logiciel sur sa machine. + +Dans la petite démonstration, nous montrons comment générer un fichier +`docx` à partir d'un fichier `md` avec `Pandoc` et nous soulignons qu'il +est alors possible d'utiliser un traitement de texte comme `LibreOffice` +pour modifier le fichier obtenu. Il est clair que si des modifications +sont apportées au `docx` elle en seront pas (automatiquement) propagées +au `md`. Il faudra utiliser `Pandoc` pour cela et effectuer une +conversion de `docx` vers `md` (et seules les éléments du format `docx` +qui existent en `md` seront conservés). + +Une stratégie qui est souvent employée et qui fonctionne bien en +pratique consiste à faire le gros du travail de rédaction d'un article +ou d'un mémoire en `Markdown`. La rédaction terminée, le fichier est +exporté au format `docx` (ou `LaTeX`) et des ajustements de mise en page +sont alors effectués avec un logiciel de traitement de texte (ou un +éditeur `LaTeX`). diff --git a/module2/ressources/emacs_orgmode.md b/module2/ressources/emacs_orgmode.md index 8ea14256428d5d2c741bcc5ccf80f513845b7f46..7d7ae0d9f1b498e80a2c428d33d125a433674e5a 100644 --- a/module2/ressources/emacs_orgmode.md +++ b/module2/ressources/emacs_orgmode.md @@ -1,60 +1,98 @@ --- -TITLE: Emacs/org-mode -Date: Wed Mar 13 15:12:03 2019 +title: Emacs/org-mode +date: Wed Mar 20 16:01:41 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). - -The next section provides information on how to install emacs. - -Table of Contents -============================================================== - -- [Installing emacs, org-mode, ess, and auctex.](#installing-emacs-org-mode-ess-and-auctex) - - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) - - [macOS](#macos) - - [Windows](#windows) - - [All platforms: pretty code in HTML export](#all-platforms-pretty-code-in-html-export) -- [A simple "reproducible research" emacs configuration](#a-simple-reproducible-research-emacs-configuration) - - [Step 0: Backup and download our configuration](#step-0-backup-and-download-our-configuration) - - [Step 1: Prepare your journal](#step-1-prepare-your-journal) - - [Step 2: Set up Emacs configuration](#step-2-set-up-emacs-configuration) - - [Step 3: Adapt the configuration to your specific needs if required](#step-3-adapt-the-configuration-to-your-specific-needs-if-required) - - [Step 4: Check whether the installation is working or not](#step-4-check-whether-the-installation-is-working-or-not) - - [Step 5: Open and play with your journal:](#step-5-open-and-play-with-your-journal) -- [A stub of a replicable article](#a-stub-of-a-replicable-article) -- [Emacs tips and tricks](#emacs-tips-and-tricks) - - [Cheat-sheets](#cheat-sheets) - - [Video tutorials](#video-tutorials) - - [Additional useful emacs packages](#additional-useful-emacs-packages) - - [Other resources](#other-resources) - -Installing Emacs -================ - -In the following we describe for each platform the installation method that we consider most convenient. There are other options that may be preferable in particular situations, so you may want to look at the [Emacs Web site](https://www.gnu.org/software/emacs/download.html) for details, but we strongly suggest you first try the method we recommend. +**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). + +The next section provides information on how to install +emacs. + +# Table of Contents TOC + + - [Installing emacs, org-mode, ess, and + auctex.](#installing-emacs-org-mode-ess-and-auctex) + - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) + - [macOS](#macos) + - [Windows](#windows) + - [All platforms: pretty code in HTML + export](#all-platforms-pretty-code-in-html-export) + - [A simple "reproducible research" emacs + configuration](#a-simple-reproducible-research-emacs-configuration) + - [Step 0: Backup and download our + configuration](#step-0-backup-and-download-our-configuration) + - [Step 1: Prepare your journal](#step-1-prepare-your-journal) + - [Step 2: Set up Emacs + configuration](#step-2-set-up-emacs-configuration) + - [Step 3: Adapt the configuration to your specific needs if + required](#step-3-adapt-the-configuration-to-your-specific-needs-if-required) + - [Step 4: Check whether the installation is working or + not](#step-4-check-whether-the-installation-is-working-or-not) + - [Step 5: Open and play with your + journal:](#step-5-open-and-play-with-your-journal) + - [A stub of a replicable article](#a-stub-of-a-replicable-article) + - [Emacs tips and tricks](#emacs-tips-and-tricks) + - [Cheat-sheets](#cheat-sheets) + - [Video tutorials](#video-tutorials) + - [Additional useful emacs + packages](#additional-useful-emacs-packages) + - [Other resources](#other-resources) + +# Installing Emacs + +In the following we describe for each platform the installation method +that we consider most convenient. There are other options that may be +preferable in particular situations, so you may want to look at the +[Emacs Web site](https://www.gnu.org/software/emacs/download.html) for +details, but we strongly suggest you first try the method we recommend. At the end of the installation procedure, you should have one of 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. +Emacs 25 comes with Org-Mode 8, which is not compatible with our +examples. So if you use Emacs 25, you must separately install Org-Mode +9. Emacs 26 already includes Org-Mode 9. -Our MOOC also requires a few extra Emacs packages: [ESS](https://ess.r-project.org/) (for working with the R language) and [AUCTeX](https://www.gnu.org/software/auctex/) (for editing LaTeX). They will be installed automatically the first time you start Emacs if you use the configuration described under [A simple "reproducible research" emacs configuration](#a-simple-reproducible-research-emacs-configuration). +Our MOOC also requires a few extra Emacs packages: +[ESS](https://ess.r-project.org/) (for working with the R language) and +[AUCTeX](https://www.gnu.org/software/auctex/) (for editing LaTeX). They +will be installed automatically the first time you start Emacs if you +use the configuration described under [A simple "reproducible research" +emacs +configuration](#a-simple-reproducible-research-emacs-configuration). -Linux (Debian, Ubuntu) ----------------------- +## Linux (Debian, Ubuntu) -We provide here only instructions for Debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g.n redhat, fedora). +We provide here only instructions for Debian-based distributions. Feel +free to contribute to this document to provide up-to-date information +for other distributions (e.g.n redhat, fedora). These are the versions of Emacs that various distributions provide: -- 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) -- Ubuntu (artful 17.04) ships with [emacs 25.2](https://packages.ubuntu.com/artful/emacs25) and [org-mode 9.0.9](https://packages.ubuntu.com/artful/org-mode) + - 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) + - Ubuntu (artful 17.04) ships with + [emacs 25.2](https://packages.ubuntu.com/artful/emacs25) and + [org-mode 9.0.9](https://packages.ubuntu.com/artful/org-mode) -If your distribution is older than this, well, it may be a good time for upgrading... +If your distribution is older than this, well, it may be a good time for +upgrading… Simply run (as root): @@ -82,33 +120,63 @@ emacs -batch --funcall "org-version" 2>&1 | grep version Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/) ``` -The version numbers you get will depend on the distribution you are running. **You really want to make sure you do not rely on org-mode 8**, which is now deprecated. +The version numbers you get will depend on the distribution you are +running. You really want to make sure you do not +rely on org-mode 8, which is now deprecated. -macOS ------ +## macOS -**Note:** macOS comes with a prehistoric command-line-only version of Emacs located at `/usr/bin/emacs`. It's best to forget about it. +**Note:** macOS comes with a prehistoric command-line-only version of +Emacs located at `/usr/bin/emacs`. It's best to forget about it. -The Web site proposes precompiled Emacs versions for macOS. Download the latest version (the one that figures prominently on the page) and install it like you would install any other macOS application, by copying `Emacs.app` from the downloaded disk image to a convenient location on your computer. +The Web site proposes precompiled Emacs +versions for macOS. Download the latest version (the one that figures +prominently on the page) and install it like you would install any other +macOS application, by copying `Emacs.app` from the downloaded disk image +to a convenient location on your computer. -In case you need to run Emacs from the command line (note: this is not required in the MOOC), you have to enter the full path to the executable. Assuming that you have copied `Emacs.app` to `/path/to/emacs`, this is `/path/to/emacs/Emacs.app/Contents/MacOS/Emacs`. Note that if you just type `emacs`, you will use the prehistoric command-line-only version at `/usr/bin/emacs` provided by Apple. +In case you need to run Emacs from the command line (note: this is not +required for the MOOC), you have to enter the full path to the +executable. Assuming that you have copied `Emacs.app` to +`/path/to/emacs`, this is +`/path/to/emacs/Emacs.app/Contents/MacOS/Emacs`. If you just type +`emacs`, you will use the prehistoric command-line-only version at +`/usr/bin/emacs` provided by Apple. -Windows -------- +## Windows -Download the [precompiled Emacs 26.1](https://ftp.gnu.org/gnu/emacs/windows/emacs-26/emacs-26.1-i686.zip) and unzip the zip file preserving the directory structure, and run `bin\runemacs.exe`. +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`. -Alternatively, create a desktop shortcut to `bin\runemacs.exe`, and start Emacs by double-clicking on that shortcut's icon. See [here](https://www.gnu.org/software/emacs/manual/html_node/emacs/Windows-Startup.html) for an explanation of this and other methods for launching Emacs under Windows. +Alternatively, create a desktop shortcut to `bin\runemacs.exe`, and +start Emacs by double-clicking on that shortcut's icon. See +[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 -In the following instructions, we refer to your home directory through the (UNIX) `~/` notation. On Windows, your home directory should be something like `C:\Users\yourname`. Therefore, whenever we mention the `~/org/` (resp. the `~/.emacs.d/`) directory this means we are referring to `C:\Users\yourname\org` (resp. `C:\Users\yourname\.emacs.d\`). +In the following instructions, we refer to your home directory through +the (UNIX) `~/` notation. On Windows, your home directory should be +something like `C:\Users\yourname`. Therefore, whenever we mention the +`~/org/` (resp. the `~/.emacs.d/`) directory this means we are referring +to `C:\Users\yourname\org` (resp. `C:\Users\yourname\.emacs.d\`). ### Making R and Python available to the console -When running a command, Windows will look for the command in the directories indicated in the `PATH` environment variable. If none of these directories contains the command, Windows will stop and indicate the command does not exist. To make sure R (which may be in something like `C:/Program Files/R/R-3.5.1/bin/x64/`) and Python (which may be in something like `C:/Program Files/Python/Python37/`) can easily be run from Emacs, you should thus configure the `PATH` variable accordingly. +When running a command, Windows will look for the command in the +directories indicated in the `PATH` environment variable. If none of +these directories contains the command, Windows will stop and indicate +the command does not exist. To make sure R (which may be in something +like `C:/Program Files/R/R-3.5.1/bin/x64/`) and Python (which may be in +something like `C:/Program Files/Python/Python37/`) can easily be run +from Emacs, you should thus configure the `PATH` variable accordingly. -This requires to go through the "Environment Variable" editor as explained [here](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/). +This requires to go through the "Environment Variable" editor as +explained +[here](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/). ### Installing and configuring Matplotlib (graphic python library) @@ -120,7 +188,9 @@ python -m pip install -U matplotlib ![](emacs_orgmode_images/install_matplotlib.png) -Then you will want to deactivate interactive plots in matplotlib. To this end, you first need to know where the matplotlib configuration is located. Open a python console the type the following code: +Then you will want to deactivate interactive plots in matplotlib. To +this end, you first need to know where the matplotlib configuration is +located. Open a python console the type the following code: ``` python import matplotlib @@ -129,42 +199,76 @@ matplotlib.matplotlib_fname() ![](emacs_orgmode_images/matplotlib.png) -Open the `matplotlibrc` file and modify the line starting with `backend` to make it `backend : Agg`. +Open the `matplotlibrc` file and modify the line starting with `backend` +to make it `backend : Agg`. -All platforms: pretty code in HTML export ------------------------------------------ +# A simple "reproducible research" emacs configuration -To have code pretty printing when exporting to HTML, you should install the `htmlize` package, which is done by opening emacs and typing the following command: +This section is illustrated in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +(*"Mise en place Emacs/Orgmode"* in French). Watching it before +following the instructions given in this section may help. -``` example -M-x package-install RET htmlize RET # where M-x means pressing the "Esc" key then the "x" key -``` +Emacs comes with a very basic default configuration, so almost everyone +wants to personalize it. Given the flexibility of Emacs, a configuration +can become quite complex and in fact include what would otherwise be +considered complete software packages. In the context of this MOOC, we +propose a relatively minimalist configuration oriented towards +"*reproducible research*" with Org-Mode. If you are new to Emacs, we +strongly recommended that you use it with as little modification as +possible, by following the instructions in this section. If you are a +more experienced Emacs user, you can go through the instructions and +adopt the pieces that you consider useful for you. + +It is unfortunately rather probable that some of you will run into +unforeseen problems with this configuration. If that is your case, ask a +question on the forum. We will do our best to help you. + +## Step 0: Backup and remove your previous configuration + +If you have used Emacs before, you may already have a personal +configuration. And even if not, you may have Emacs configuration files +without being aware of them, since some software packages create or +modify Emacs configuration files. In order to avoid trouble, remove +prior configurations, after making a backup elsewhere. -A simple "reproducible research" emacs configuration -==================================================== +The files that you should backup and then remove (if they exist) are: -This section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) (/"Mise en place Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help. +1. `~/.emacs` +2. `~/.emacs.el` +3. `~/.emacs.elc` -Emacs comes with very basic default configuration and it appears like everyone has its own taste. You will for example find [here](https://www.emacswiki.org/emacs/StarterKits) several default Emacs configurations that reflect the preferences of their creators. Likewise the configuration of Org-Mode is incredibly flexible (see for example [the org-mode website](https://orgmode.org/worg/org-configs/index.html) for more references). In the context of this MOOC, we propose you a relatively minimalist one that is rather "*reproducible research*" oriented by adding a few org-mode specific configurations. +There is also a directory that you should backup and then remove (if it +exists), with everything it might contain: -Step 0: Backup and download our configuration ---------------------------------------------- +1. `~/.emacs.d` -The procedure we propose will wipe your already existing custom Emacs configuration if you have one. **You should thus beforehand make a backup** of `~/.emacs` and of `~/.emacs.d/init.el` (if these files exist). +In the above filenames, `~/` stands for your home directory. Windows +users should replace it by `C:\Users\MyName`, replacing MyName by their +user name. -Then download [this archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org_archive.tgz) and uncompress it. It contains the following files and we will refer to them in the following: +## Step 1: Download our configuration + +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 rr_org/journal.org ``` -Alternatively, [the files you are looking for are available here](rr_org/). +Alternatively, [the files you are looking for are available +here](rr_org/). -If you use Windows, and if you use a desktop shortcut to start Emacs, you must include the path to the file `init.el` in the command for the shortcut. For example, if you installed Emacs as `C:\Users\MyName/emacs`, your desktop shortcut should execute the command `C:\Users\MyName\emacs\bin\runemacs.exe -l .emacs.d/init.el`. +If you use Windows, and if you use a desktop shortcut to start Emacs, +you must include the path to the file `init.el` in the command for the +shortcut. For example, if you installed Emacs as +`C:\Users\MyName/emacs`, your desktop shortcut should execute the +command `C:\Users\MyName\emacs\bin\runemacs.exe -l .emacs.d/init.el`. -Step 1: Prepare your journal ----------------------------- +## Step 2: Prepare your journal Create an `org/` directory in the top of your home: @@ -172,33 +276,42 @@ Create an `org/` directory in the top of your home: mkdir -p ~/org/ ``` -Then copy `rr_org/journal.org` file in your `~/org/` directory. This file will be your laboratory notebook and all the notes you will capture with `C-c c` will go automatically go in this file. The first entry of this notebook is populated with [many Emacs shortcuts](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) that you should give a try. - -Step 2: Set up Emacs configuration ----------------------------------- +Then copy `rr_org/journal.org` file in your `~/org/` directory. This +file will be your laboratory notebook and all the notes you will capture +with `C-c c` will go automatically go in this file. The first entry of +this notebook is populated with [many Emacs +shortcuts](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) +that you should give a try. -Copy `rr_org/init.el` in your `~/.emacs.d/` directory. +## Step 3: Put the Emacs configuration file in the right place -Alternatively, if you do not want to mess with your already existing emacs configuration, you may launch emacs with this specific configuration with the following command: `emacs -q -l rr_org/init.el`. +Create the directory `~/.emacs.d/` and copy `rr_org/init.el` into it. -Step 3: Adapt the configuration to your specific needs if required ------------------------------------------------------------------- +## Step 4: Adapt the configuration to your specific needs if required -There are two situations in which it might be necessary to modify `init.el`: +There are two situations in which it might be necessary to modify +`init.el`: -1. Your network environment forces you to use a proxy for access to Web sites (HTTP(S) protocol). -2. You have multiple installations of Python or R on your computer, or they are in unusual places and not fully configured. If you can run - - "python3" and "R" under Linux and macOS - - "Python" and "R" under Windows +1. Your network environment forces you to use a proxy for access to Web + sites (HTTP(S) protocol). +2. You have multiple installations of Python or R on your computer, or + they are in unusual places and not fully configured. If you can run + - "python3" and "R" under Linux and macOS + - "Python" and "R" under Windows + in a terminal without getting an error message, then you should not + have to do anything. - in a terminal without getting an error message, then you should not have to do anything. +If you do have to modify `init.el`, check the comments at the beginning +of the file for instructions. -If you do have to modify `init.el`, check the comments at the beginning of the file for instructions. +## Step 5: Check whether the installation is working or not -Step 4: Check whether the installation is working or not --------------------------------------------------------- +Quit Emacs if it is running, and start it again. This first start will +take a bit of time because Emacs will download a few add-on packages. +For that reason, please make sure that you have a working internet +connection for this step. -Open a new instance of Emacs and open a `foo.org` file. Copy the following lines in this file: +Then open a file `foo.org`. Copy the following lines into this file: ``` example #+begin_src shell :session foo :results output :exports both @@ -206,25 +319,50 @@ ls -la # or dir under windows #+end_src ``` -Put your cursor inside this code block and execute it with the following command: `C-c C-c` (If you are not familiar with Emacs commands, this one means '`Ctrl + C`' twice) - -A `#+RESULTS:` block with the result of the command should appear if it worked. - -In the video, we already have demonstrated the main features and shortcuts of emacs/org-mode that will help you maintain a document and benefit from literate programming. The list of features and shortcuts is demonstrated in the [first entry of your labbook](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org). - -Step 5: Open and play with your journal: ----------------------------------------- - -In step 1, you were told to create an journal in `~org/journal.org`. First you probably want to make sure this file is stored in a version control system like git. We leave it up to you to set this up but if you have any trouble, feel free to ask on the FUN forums. - -A stub of a replicable article -============================== - -This section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) (/"Écrire un article réplicable avec Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help. - -Remember, you need a working LaTeX and R environment. If you can't open a terminal and run the commands `R`, `pdflatex`, and `python`, you will not be able to generate this document. When being compiled, the article downloads the corresponding LaTeX packages so you also need to have a working `wget` command (alternatively, it uses `curl`). Once downloaded, you may still read the source () and understand how it works though. - -Download the following [archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz), uncompress it and simply `make` to generate the article. You should then be able to open the [resulting article](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf). This is summarized in the following command: +Put your cursor inside this code block and execute it with the following +command: `C-c C-c` (If you are not familiar with Emacs commands, this +one means '`Ctrl + C`' twice) + +A `#+RESULTS:` block with the result of the command should appear if it +worked. + +In the video, we already have demonstrated the main features and +shortcuts of emacs/org-mode that will help you maintain a document and +benefit from literate programming. The list of features and shortcuts is +demonstrated in the [first entry of your +labbook](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org). + +## Step 6: Open and play with your journal: + +In step 2, you were told to create a journal in `~org/journal.org`. You +probably want to make sure this file is stored in a version control +system like git. We leave it up to you to set this up but if you have +any trouble, feel free to ask on the MOOC forum. + +# A stub of a replicable article + +This section is illustrated in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +(*"Écrire un article réplicable avec Emacs/Orgmode"* in French). +Watching it before following the instructions given in this section may +help. + +Remember, you need a working LaTeX and R environment. If you can't open +a terminal and run the commands `R`, `pdflatex`, and `python`, you will +not be able to generate this document. When being compiled, the article +downloads the corresponding LaTeX packages so you also need to have a +working `wget` command (alternatively, it uses `curl`). Once downloaded, +you may still read the source +() +and understand how it works though. + +Download the following +[archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz), +uncompress it and simply `make` to generate the article. You should then +be able to open the [resulting +article](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf). +This is summarized in the following +command: ``` bash wget --no-check-certificate -O replicable_article.tgz https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz @@ -233,63 +371,99 @@ tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf **Possible issues**: -- If the `make` command fails (especially on Mac), it may be because Emacs or something else is not correctly installed. In that case, open the article directly with the following command: - + - If the `make` command fails (especially on Mac), it may be because + Emacs or something else is not correctly installed. In that case, + open the article directly with the following + command: + ``` bash emacs -q --eval "(setq enable-local-eval t)" --eval "(setq enable-local-variables t)" article.org ``` - + and export it to pdf with the following shortcut: `C-c C-e l o` -- If it still doesn't work and emacs complains about not finding ESS, it may be because you installed ESS in your home instead of system-wide. In that case, try to remove the `-q` in the previous command line to load your personal emacs configuration. -Finally, when you'll be tired of always re-executing all the source code when exporting, just look for the following line in [article.org](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org): + - If it still doesn't work and emacs complains about not finding ESS, + it may be because you installed ESS in your home instead of + system-wide. In that case, try to remove the `-q` in the previous + command line to load your personal emacs configuration. + +Finally, when you'll be tired of always re-executing all the source code +when exporting, just look for the following line in +[article.org](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org): ``` example # #+PROPERTY: header-args :eval never-export ``` -If you remove the `# ` in the beginning of the line, it will not be a comment anymore and will indicate org-mode to stop evaluating every chunk of code when exporting. +If you remove the `# ` in the beginning of the line, it will not be a +comment anymore and will indicate org-mode to stop evaluating every +chunk of code when exporting. -Emacs tips and tricks -===================== +# Emacs tips and tricks -Cheat-sheets ------------- +## Cheat-sheets -Learning Emacs and Org-Mode can be difficult as there is an inordinate amount of shortcuts. Many people have thus come up with cheat-sheats. Here is a selection in case it helps: +Learning Emacs and Org-Mode can be difficult as there is an inordinate +amount of shortcuts. Many people have thus come up with cheat-sheats. +Here is a selection in case it helps: ### Emacs -- [Common and step-by-step Emacs shortcuts for our *reproducible research* configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) -- [The official GNU emacs refcard](https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf) -- Two graphical cheat-sheats by Sacha Chua on ![](http://sachachua.com/blog/wp-content/uploads/2013/05/How-to-Learn-Emacs-v2-Large.png) and on ![](http://sachachua.com/blog/wp-content/uploads/2013/08/20130830-Emacs-Newbie-How-to-Learn-Emacs-Keyboard-Shortcuts.png). + - [Common and step-by-step Emacs shortcuts for our *reproducible + research* + configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) + - [The official GNU emacs + refcard](https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf) + - Two graphical cheat-sheats by Sacha Chua on + ![](http://sachachua.com/blog/wp-content/uploads/2013/05/How-to-Learn-Emacs-v2-Large.png) + and on + ![](http://sachachua.com/blog/wp-content/uploads/2013/08/20130830-Emacs-Newbie-How-to-Learn-Emacs-Keyboard-Shortcuts.png). ### Org-mode -- [Common and step-by-step org-mode shortcuts for our *reproducible research* configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) -- [The official org-mode refcard](https://orgmode.org/worg/orgcard.html) -- [The official description of the org-mode syntax](https://orgmode.org/worg/dev/org-syntax.html) and a [relatively concise description of the org-mode syntax](https://gist.github.com/hoeltgman/3825415). + - [Common and step-by-step org-mode shortcuts for our *reproducible + research* + configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) + - [The official org-mode + refcard](https://orgmode.org/worg/orgcard.html) + - [The official description of the org-mode + syntax](https://orgmode.org/worg/dev/org-syntax.html) and a + [relatively concise description of the org-mode + syntax](https://gist.github.com/hoeltgman/3825415). -Video tutorials ---------------- +## Video tutorials -For those of you who prefer video explanations, here is a [Youtube channel with many step by step emacs tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg). +For those of you who prefer video explanations, here is a [Youtube +channel with many step by step emacs +tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg). -Additional useful emacs packages --------------------------------- +## Additional useful emacs packages ### Company-mode -[Company-mode](http://company-mode.github.io/) is a text completion framework for Emacs. It allows to have smart completion in emacs for the most common languages. If you feel this is needed, you should follow the instructions from the official Web page: [](http://company-mode.github.io/) +[Company-mode](http://company-mode.github.io/) is a text completion +framework for Emacs. It allows to have smart completion in emacs for the +most common languages. If you feel this is needed, you should follow the +instructions from the official Web page: + ### Magit -[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is briefly illustrated in the context of this MOOC in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) ("*Utilisation Emacs/git*" in French). +[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is +briefly illustrated in the context of this MOOC in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +("*Utilisation Emacs/git*" in French). -It is very powerful and we use it on a daily basis but you should definitely understand what git does behind the scenes beforehand. If you feel this would be useful for you, you should follow [this visual walk-through](https://magit.vc/screenshots/) or [this really short "crash course"](https://www.emacswiki.org/emacs/Magit). If you installed the previous "*reproducible research*" emacs configuration, you can easily invoke magit by using `C-x g`. +It is very powerful and we use it on a daily basis but you should +definitely understand what git does behind the scenes beforehand. If you +feel this would be useful for you, you should follow [this visual +walk-through](https://magit.vc/screenshots/) or [this really short +"crash course"](https://www.emacswiki.org/emacs/Magit). If you installed +the previous "*reproducible research*" emacs configuration, you can +easily invoke magit by using `C-x g`. -Other resources ---------------- +## Other resources -- [The compact Org-mode Guide](https://orgmode.org/orgguide.pdf) -- [Many examples illustrating the use of different languages in org-mode](https://github.com/dfeich/org-babel-examples) + - [The compact Org-mode Guide](https://orgmode.org/orgguide.pdf) + - [Many examples illustrating the use of different languages in + org-mode](https://github.com/dfeich/org-babel-examples) diff --git a/module2/ressources/emacs_orgmode_fr.md b/module2/ressources/emacs_orgmode_fr.md index 2257368acec6bd02fb90ea4326b321fdbf8ff6fb..44d644830196d68c66f3346b290f7a20d74d89c7 100644 --- a/module2/ressources/emacs_orgmode_fr.md +++ b/module2/ressources/emacs_orgmode_fr.md @@ -1,49 +1,76 @@ --- -TITLE: FIXME Emacs/org-mode -Date: Tue Feb 19 19:19:03 2019 +title: FIXME Emacs/org-mode +date: Thu Feb 21 17:05:51 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). - -The next section provides information on how to install emacs. - -Table of Contents -============================================================== - -- [Installing emacs, org-mode, ess, and auctex.](#installing-emacs-org-mode-ess-and-auctex) - - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) - - [macOS](#macos) - - [Windows](#windows) - - [All platforms: pretty code in HTML export](#all-platforms-pretty-code-in-html-export) -- [A simple "reproducible research" emacs configuration](#a-simple-reproducible-research-emacs-configuration) - - [Step 0: Backup and download our configuration](#step-0-backup-and-download-our-configuration) - - [Step 1: Prepare your journal](#step-1-prepare-your-journal) - - [Step 2: Set up Emacs configuration](#step-2-set-up-emacs-configuration) - - [Step 3: Adapt the configuration to your specific needs if required](#step-3-adapt-the-configuration-to-your-specific-needs-if-required) - - [Step 4: Check whether the installation is working or not](#step-4-check-whether-the-installation-is-working-or-not) - - [Step 5: Open and play with your journal:](#step-5-open-and-play-with-your-journal) -- [A stub of a replicable article](#a-stub-of-a-replicable-article) -- [Emacs tips and tricks](#emacs-tips-and-tricks) - - [Cheat-sheets](#cheat-sheets) - - [Video tutorials](#video-tutorials) - - [Additional useful emacs packages](#additional-useful-emacs-packages) - - [Other resources](#other-resources) - -Installing emacs, org-mode, ess, and auctex. -============================================ - -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: - -- 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) -- Ubuntu (artful 17.04) ships with [emacs 25.2](https://packages.ubuntu.com/artful/emacs25) and [org-mode 9.0.9](https://packages.ubuntu.com/artful/org-mode) - -If your distribution is older than this, well, it may be a good time for upgrading... +**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). + +The next section provides information on how to install +emacs. + +# Table of Contents TOC + + - [Installing emacs, org-mode, ess, and + auctex.](#installing-emacs-org-mode-ess-and-auctex) + - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) + - [macOS](#macos) + - [Windows](#windows) + - [All platforms: pretty code in HTML + export](#all-platforms-pretty-code-in-html-export) + - [A simple "reproducible research" emacs + configuration](#a-simple-reproducible-research-emacs-configuration) + - [Step 0: Backup and download our + configuration](#step-0-backup-and-download-our-configuration) + - [Step 1: Prepare your journal](#step-1-prepare-your-journal) + - [Step 2: Set up Emacs + configuration](#step-2-set-up-emacs-configuration) + - [Step 3: Adapt the configuration to your specific needs if + required](#step-3-adapt-the-configuration-to-your-specific-needs-if-required) + - [Step 4: Check whether the installation is working or + not](#step-4-check-whether-the-installation-is-working-or-not) + - [Step 5: Open and play with your + journal:](#step-5-open-and-play-with-your-journal) + - [A stub of a replicable article](#a-stub-of-a-replicable-article) + - [Emacs tips and tricks](#emacs-tips-and-tricks) + - [Cheat-sheets](#cheat-sheets) + - [Video tutorials](#video-tutorials) + - [Additional useful emacs + packages](#additional-useful-emacs-packages) + - [Other resources](#other-resources) + +# Installing emacs, org-mode, ess, and auctex. + +## 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: + + - 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) + - Ubuntu (artful 17.04) ships with + [emacs 25.2](https://packages.ubuntu.com/artful/emacs25) and + [org-mode 9.0.9](https://packages.ubuntu.com/artful/org-mode) + +If your distribution is older than this, well, it may be a good time for +upgrading… Simply run (as root): @@ -71,59 +98,70 @@ emacs -batch --funcall "org-version" 2>&1 | grep version Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/) ``` -The version numbers you get will depend on the distribution you are running. **You really want to make sure you do not rely on org-mode 8**, which is now deprecated. - -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` - -- **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`. - -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: - -- Emacs 26.1 -- Org-mode 9.1.13 -- ESS 17.11 +The version numbers you get will depend on the distribution you are +running. You really want to make sure you do not +rely on org-mode 8, which is now deprecated. + +## 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. + +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. + +This Emacs version contains everything used in the MOOC except the +packages [ESS](https://ess.r-project.org/) (for working with the R +language) and [AUCTeX](https://www.gnu.org/software/auctex/) (for +editing LaTeX). If you use the configuration described under [A simple +"reproducible research" emacs +configuration](#a-simple-reproducible-research-emacs-configuration), +these packages will be installed automatically the first time you start +Emacs. + +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/): +. It ships with recent +versions: + + - Emacs 26.1 + - Org-mode 9.1.13 + - ESS 17.11 ### Directory naming conventions -In the following instructions, we refer to your home directory through the (UNIX) `~/` notation. On Windows, your home directory should be something like `C:\Users\yourname`. Therefore, whenever we mention the `~/org/` (resp. the `~/.emacs.d/`) directory this means we are referring to `C:\Users\yourname\org` (resp. `C:\Users\yourname\.emacs.d\`). +In the following instructions, we refer to your home directory through +the (UNIX) `~/` notation. On Windows, your home directory should be +something like `C:\Users\yourname`. Therefore, whenever we mention the +`~/org/` (resp. the `~/.emacs.d/`) directory this means we are referring +to `C:\Users\yourname\org` (resp. `C:\Users\yourname\.emacs.d\`). ### Making R and Python available to the console -When running a command, Windows will look for the command in the directories indicated in the `PATH` environment variable. If none of these directories contains the command, Windows will stop and indicate the command does not exist. To make sure R (which may be in something like `C:/Program Files/R/R-3.5.1/bin/x64/`) and Python (which may be in something like `C:/Program Files/Python/Python37/`) can easily be run from Emacs, you should thus configure the `PATH` variable accordingly. +When running a command, Windows will look for the command in the +directories indicated in the `PATH` environment variable. If none of +these directories contains the command, Windows will stop and indicate +the command does not exist. To make sure R (which may be in something +like `C:/Program Files/R/R-3.5.1/bin/x64/`) and Python (which may be in +something like `C:/Program Files/Python/Python37/`) can easily be run +from Emacs, you should thus configure the `PATH` variable accordingly. -This requires to go through the "Environment Variable" editor as explained [here](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/). +This requires to go through the "Environment Variable" editor as +explained +[here](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/). ### Installing and configuring Matplotlib (graphic python library) @@ -135,7 +173,9 @@ python -m pip install -U matplotlib ![](emacs_orgmode_images/install_matplotlib.png) -Then you will want to deactivate interactive plots in matplotlib. To this end, you first need to know where the matplotlib configuration is located. Open a python console the type the following code: +Then you will want to deactivate interactive plots in matplotlib. To +this end, you first need to know where the matplotlib configuration is +located. Open a python console the type the following code: ``` python import matplotlib @@ -144,40 +184,59 @@ matplotlib.matplotlib_fname() ![](emacs_orgmode_images/matplotlib.png) -Open the `matplotlibrc` file and modify the line starting with `backend` to make it `backend : Agg`. +Open the `matplotlibrc` file and modify the line starting with `backend` +to make it `backend : Agg`. -All platforms: pretty code in HTML export ------------------------------------------ +## All platforms: pretty code in HTML export -To have code pretty printing when exporting to HTML, you should install the `htmlize` package, which is done by opening emacs and typing the following command: +To have code pretty printing when exporting to HTML, you should install +the `htmlize` package, which is done by opening emacs and typing the +following +command: ``` example M-x package-install RET htmlize RET # where M-x means pressing the "Esc" key then the "x" key ``` -A simple "reproducible research" emacs configuration -==================================================== +# A simple "reproducible research" emacs configuration -This section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) (/"Mise en place Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help. +This section is illustrated in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +(*"Mise en place Emacs/Orgmode"* in French). Watching it before +following the instructions given in this section may help. -Emacs comes with very basic default configuration and it appears like everyone has its own taste. You will for example find [here](https://www.emacswiki.org/emacs/StarterKits) several default Emacs configurations that reflect the preferences of their creators. Likewise the configuration of Org-Mode is incredibly flexible (see for example [the org-mode website](https://orgmode.org/worg/org-configs/index.html) for more references). In the context of this MOOC, we propose you a relatively minimalist one that is rather "*reproducible research*" oriented by adding a few org-mode specific configurations. +Emacs comes with very basic default configuration and it appears like +everyone has its own taste. You will for example find +[here](https://www.emacswiki.org/emacs/StarterKits) several default +Emacs configurations that reflect the preferences of their creators. +Likewise the configuration of Org-Mode is incredibly flexible (see for +example [the org-mode +website](https://orgmode.org/worg/org-configs/index.html) for more +references). In the context of this MOOC, we propose you a relatively +minimalist one that is rather "*reproducible research*" oriented by +adding a few org-mode specific configurations. -Step 0: Backup and download our configuration ---------------------------------------------- +## Step 0: Backup and download our configuration -The procedure we propose will wipe your already existing custom Emacs configuration if you have one. **You should thus beforehand make a backup** of `~/.emacs` and of `~/.emacs.d/init.el` (if these files exist). +The procedure we propose will wipe your already existing custom Emacs +configuration if you have one. **You should thus beforehand make a +backup** of `~/.emacs` and of `~/.emacs.d/init.el` (if these files +exist). -Then download [this archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/rr_org_archive.tgz) and uncompress it. It contains the following files and we will refer to them in the following: +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: ``` example rr_org/init.el rr_org/journal.org ``` -Alternatively, [the files you are looking for are available here](rr_org/). +Alternatively, [the files you are looking for are available +here](rr_org/). -Step 1: Prepare your journal ----------------------------- +## Step 1: Prepare your journal Create an `org/` directory in the top of your home: @@ -185,33 +244,42 @@ Create an `org/` directory in the top of your home: mkdir -p ~/org/ ``` -Then copy `rr_org/journal.org` file in your `~/org/` directory. This file will be your laboratory notebook and all the notes you will capture with `C-c c` will go automatically go in this file. The first entry of this notebook is populated with [many Emacs shortcuts](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) that you should give a try. +Then copy `rr_org/journal.org` file in your `~/org/` directory. This +file will be your laboratory notebook and all the notes you will capture +with `C-c c` will go automatically go in this file. The first entry of +this notebook is populated with [many Emacs +shortcuts](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) +that you should give a try. -Step 2: Set up Emacs configuration ----------------------------------- +## Step 2: Set up Emacs configuration Copy `rr_org/init.el` in your `~/.emacs.d/` directory. -Alternatively, if you do not want to mess with your already existing emacs configuration, you may launch emacs with this specific configuration with the following command: `emacs -q -l rr_org/init.el`. - -Step 3: Adapt the configuration to your specific needs if required ------------------------------------------------------------------- +Alternatively, if you do not want to mess with your already existing +emacs configuration, you may launch emacs with this specific +configuration with the following command: `emacs -q -l rr_org/init.el`. -There are two situations in which it might be necessary to modify `init.el`: +## Step 3: Adapt the configuration to your specific needs if required -1. Your network environment forces you to use a proxy for access to Web sites (HTTP(S) protocol). -2. You have multiple installations of Python or R on your computer, or they are in unusual places and not fully configured. If you can run - - "python3" and "R" under Linux and macOS - - "Python" and "R" under Windows +There are two situations in which it might be necessary to modify +`init.el`: - in a terminal without getting an error message, then you should not have to do anything. +1. Your network environment forces you to use a proxy for access to Web + sites (HTTP(S) protocol). +2. You have multiple installations of Python or R on your computer, or + they are in unusual places and not fully configured. If you can run + - "python3" and "R" under Linux and macOS + - "Python" and "R" under Windows + in a terminal without getting an error message, then you should not + have to do anything. -If you do have to modify `init.el`, check the comments at the beginning of the file for instructions. +If you do have to modify `init.el`, check the comments at the beginning +of the file for instructions. -Step 4: Check whether the installation is working or not --------------------------------------------------------- +## Step 4: Check whether the installation is working or not -Open a new instance of Emacs and open a `foo.org` file. Copy the following lines in this file: +Open a new instance of Emacs and open a `foo.org` file. Copy the +following lines in this file: ``` example #+begin_src shell :session foo :results output :exports both @@ -219,25 +287,50 @@ ls -la # or dir under windows #+end_src ``` -Put your cursor inside this code block and execute it with the following command: `C-c C-c` (If you are not familiar with Emacs commands, this one means '`Ctrl + C`' twice) - -A `#+RESULTS:` block with the result of the command should appear if it worked. - -In the video, we already have demonstrated the main features and shortcuts of emacs/org-mode that will help you maintain a document and benefit from literate programming. The list of features and shortcuts is demonstrated in the [first entry of your labbook](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org). - -Step 5: Open and play with your journal: ----------------------------------------- - -In step 1, you were told to create an journal in `~org/journal.org`. First you probably want to make sure this file is stored in a version control system like git. We leave it up to you to set this up but if you have any trouble, feel free to ask on the FUN forums. - -A stub of a replicable article -============================== - -This section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) (/"Écrire un article réplicable avec Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help. - -Remember, you need a working LaTeX and R environment. If you can't open a terminal and run the commands `R`, `pdflatex`, and `python`, you will not be able to generate this document. When being compiled, the article downloads the corresponding LaTeX packages so you also need to have a working `wget` command (alternatively, it uses `curl`). Once downloaded, you may still read the source () and understand how it works though. - -Download the following [archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz), uncompress it and simply `make` to generate the article. You should then be able to open the [resulting article](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf). This is summarized in the following command: +Put your cursor inside this code block and execute it with the following +command: `C-c C-c` (If you are not familiar with Emacs commands, this +one means '`Ctrl + C`' twice) + +A `#+RESULTS:` block with the result of the command should appear if it +worked. + +In the video, we already have demonstrated the main features and +shortcuts of emacs/org-mode that will help you maintain a document and +benefit from literate programming. The list of features and shortcuts is +demonstrated in the [first entry of your +labbook](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org). + +## Step 5: Open and play with your journal: + +In step 1, you were told to create an journal in `~org/journal.org`. +First you probably want to make sure this file is stored in a version +control system like git. We leave it up to you to set this up but if you +have any trouble, feel free to ask on the FUN forums. + +# A stub of a replicable article + +This section is illustrated in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +(*"Écrire un article réplicable avec Emacs/Orgmode"* in French). +Watching it before following the instructions given in this section may +help. + +Remember, you need a working LaTeX and R environment. If you can't open +a terminal and run the commands `R`, `pdflatex`, and `python`, you will +not be able to generate this document. When being compiled, the article +downloads the corresponding LaTeX packages so you also need to have a +working `wget` command (alternatively, it uses `curl`). Once downloaded, +you may still read the source +() +and understand how it works though. + +Download the following +[archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz), +uncompress it and simply `make` to generate the article. You should then +be able to open the [resulting +article](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf). +This is summarized in the following +command: ``` bash wget --no-check-certificate -O replicable_article.tgz https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz @@ -246,63 +339,99 @@ tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf **Possible issues**: -- If the `make` command fails (especially on Mac), it may be because Emacs or something else is not correctly installed. In that case, open the article directly with the following command: - + - If the `make` command fails (especially on Mac), it may be because + Emacs or something else is not correctly installed. In that case, + open the article directly with the following + command: + ``` bash emacs -q --eval "(setq enable-local-eval t)" --eval "(setq enable-local-variables t)" article.org ``` - + and export it to pdf with the following shortcut: `C-c C-e l o` -- If it still doesn't work and emacs complains about not finding ESS, it may be because you installed ESS in your home instead of system-wide. In that case, try to remove the `-q` in the previous command line to load your personal emacs configuration. -Finally, when you'll be tired of always re-executing all the source code when exporting, just look for the following line in [article.org](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org): + - If it still doesn't work and emacs complains about not finding ESS, + it may be because you installed ESS in your home instead of + system-wide. In that case, try to remove the `-q` in the previous + command line to load your personal emacs configuration. + +Finally, when you'll be tired of always re-executing all the source code +when exporting, just look for the following line in +[article.org](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org): ``` example # #+PROPERTY: header-args :eval never-export ``` -If you remove the `# ` in the beginning of the line, it will not be a comment anymore and will indicate org-mode to stop evaluating every chunk of code when exporting. +If you remove the `# ` in the beginning of the line, it will not be a +comment anymore and will indicate org-mode to stop evaluating every +chunk of code when exporting. -Emacs tips and tricks -===================== +# Emacs tips and tricks -Cheat-sheets ------------- +## Cheat-sheets -Learning Emacs and Org-Mode can be difficult as there is an inordinate amount of shortcuts. Many people have thus come up with cheat-sheats. Here is a selection in case it helps: +Learning Emacs and Org-Mode can be difficult as there is an inordinate +amount of shortcuts. Many people have thus come up with cheat-sheats. +Here is a selection in case it helps: ### Emacs -- [Common and step-by-step Emacs shortcuts for our *reproducible research* configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) -- [The official GNU emacs refcard](https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf) -- Two graphical cheat-sheats by Sacha Chua on ![](http://sachachua.com/blog/wp-content/uploads/2013/05/How-to-Learn-Emacs-v2-Large.png) and on ![](http://sachachua.com/blog/wp-content/uploads/2013/08/20130830-Emacs-Newbie-How-to-Learn-Emacs-Keyboard-Shortcuts.png). + - [Common and step-by-step Emacs shortcuts for our *reproducible + research* + configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) + - [The official GNU emacs + refcard](https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf) + - Two graphical cheat-sheats by Sacha Chua on + ![](http://sachachua.com/blog/wp-content/uploads/2013/05/How-to-Learn-Emacs-v2-Large.png) + and on + ![](http://sachachua.com/blog/wp-content/uploads/2013/08/20130830-Emacs-Newbie-How-to-Learn-Emacs-Keyboard-Shortcuts.png). ### Org-mode -- [Common and step-by-step org-mode shortcuts for our *reproducible research* configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) -- [The official org-mode refcard](https://orgmode.org/worg/orgcard.html) -- [The official description of the org-mode syntax](https://orgmode.org/worg/dev/org-syntax.html) and a [relatively concise description of the org-mode syntax](https://gist.github.com/hoeltgman/3825415). + - [Common and step-by-step org-mode shortcuts for our *reproducible + research* + configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) + - [The official org-mode + refcard](https://orgmode.org/worg/orgcard.html) + - [The official description of the org-mode + syntax](https://orgmode.org/worg/dev/org-syntax.html) and a + [relatively concise description of the org-mode + syntax](https://gist.github.com/hoeltgman/3825415). -Video tutorials ---------------- +## Video tutorials -For those of you who prefer video explanations, here is a [Youtube channel with many step by step emacs tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg). +For those of you who prefer video explanations, here is a [Youtube +channel with many step by step emacs +tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg). -Additional useful emacs packages --------------------------------- +## Additional useful emacs packages ### Company-mode -[Company-mode](http://company-mode.github.io/) is a text completion framework for Emacs. It allows to have smart completion in emacs for the most common languages. If you feel this is needed, you should follow the instructions from the official Web page: [](http://company-mode.github.io/) +[Company-mode](http://company-mode.github.io/) is a text completion +framework for Emacs. It allows to have smart completion in emacs for the +most common languages. If you feel this is needed, you should follow the +instructions from the official Web page: + ### Magit -[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is briefly illustrated in the context of this MOOC in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) ("*Utilisation Emacs/git*" in French). +[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is +briefly illustrated in the context of this MOOC in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +("*Utilisation Emacs/git*" in French). -It is very powerful and we use it on a daily basis but you should definitely understand what git does behind the scenes beforehand. If you feel this would be useful for you, you should follow [this visual walk-through](https://magit.vc/screenshots/) or [this really short "crash course"](https://www.emacswiki.org/emacs/Magit). If you installed the previous "*reproducible research*" emacs configuration, you can easily invoke magit by using `C-x g`. +It is very powerful and we use it on a daily basis but you should +definitely understand what git does behind the scenes beforehand. If you +feel this would be useful for you, you should follow [this visual +walk-through](https://magit.vc/screenshots/) or [this really short +"crash course"](https://www.emacswiki.org/emacs/Magit). If you installed +the previous "*reproducible research*" emacs configuration, you can +easily invoke magit by using `C-x g`. -Other resources ---------------- +## Other resources -- [The compact Org-mode Guide](https://orgmode.org/orgguide.pdf) -- [Many examples illustrating the use of different languages in org-mode](https://github.com/dfeich/org-babel-examples) + - [The compact Org-mode Guide](https://orgmode.org/orgguide.pdf) + - [Many examples illustrating the use of different languages in + org-mode](https://github.com/dfeich/org-babel-examples) diff --git a/module2/ressources/gitlab.md b/module2/ressources/gitlab.md index 7a4e5765fb807e844657146b6e027bb6327695e0..ec59d9830a67df9eeb91f275842b0c8f3c2fc475 100644 --- a/module2/ressources/gitlab.md +++ b/module2/ressources/gitlab.md @@ -1,39 +1,59 @@ --- -TITLE: Git and GitLab -Date: Tue Feb 19 19:19:03 2019 +title: Git and GitLab +date: Tue Feb 19 19:19:03 2019 --- -**This document is particularly important if you follow the RStudio or the Org-Mode path.** **If you follow the Jupyter path, it can be ignored at first** **as we have closely integrated Jupyter and GitLab in the context of this MOOC.** - -So far, you only used git via the web interface from the GitLab we deployed for the MOOC: - -If you access this link from the FUN platform, you do not have to authenticate and you can readily read and modify all your files. This is very convenient but in most cases, you will want to have your own local copy of the repository and you will have to synchronize your local copy with the remote GitLab one. To propagate your modifications, you will obviously have to authenticate yourself on GitLab. - -This document describes the software you need to have installed on your machine and how to handle authentication. The "Configuring Git" section is illustrated in a [video tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85) (in French). - -Please read all these instructions carefully, in particular the one on "Configuring your password on GitLab". - -Table of Contents -============================================================== - -- [Installing Git](#installing-git) - - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) - - [Mac OSX and Windows](#mac-osx-and-windows) -- [Configuring Git](#configuring-git) - - [Telling Git who you are: Name and Email](#telling-git-who-you-are-name-and-email) - - [Dealing with proxies](#dealing-with-proxies) - - [Getting your default password on GitLab (and possibly changing it)](#getting-your-default-password-on-gitlab-and-possibly-changing-it) - - [Remembering your password locally](#remembering-your-password-locally) - - [Optional: authenticating through SSH](#optional-authenticating-through-ssh) -- [Using Git through the command line to synchronize your local files with Gitlab](#using-git-through-the-command-line-to-synchronize-your-local-files-with-gitlab) - -Installing Git -============== - -Linux (Debian, Ubuntu) ----------------------- - -We provide here only instructions for Debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g., RedHat, Fedora). +**This document is particularly important if you follow the RStudio or +the Org-Mode path.** **If you follow the Jupyter path, it can be ignored +at first** **as we have closely integrated Jupyter and GitLab in the +context of this MOOC.** + +So far, you only used git via the web interface from the GitLab we +deployed for the MOOC: + +If you access this link from the FUN platform, you do not have to +authenticate and you can readily read and modify all your files. This is +very convenient but in most cases, you will want to have your own local +copy of the repository and you will have to synchronize your local copy +with the remote GitLab one. To propagate your modifications, you will +obviously have to authenticate yourself on GitLab. + +This document describes the software you need to have installed on your +machine and how to handle authentication. The "Configuring Git" section +is illustrated in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85) +(in French). + +Please read all these instructions carefully, in particular the one on +"Configuring your password on +GitLab". + +# Table of Contents TOC + + - [Installing Git](#installing-git) + - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) + - [Mac OSX and Windows](#mac-osx-and-windows) + - [Configuring Git](#configuring-git) + - [Telling Git who you are: Name and + Email](#telling-git-who-you-are-name-and-email) + - [Dealing with proxies](#dealing-with-proxies) + - [Getting your default password on GitLab (and possibly changing + it)](#getting-your-default-password-on-gitlab-and-possibly-changing-it) + - [Remembering your password + locally](#remembering-your-password-locally) + - [Optional: authenticating through + SSH](#optional-authenticating-through-ssh) + - [Using Git through the command line to synchronize your local files + with + Gitlab](#using-git-through-the-command-line-to-synchronize-your-local-files-with-gitlab) + +# Installing Git + +## Linux (Debian, Ubuntu) + +We provide here only instructions for Debian-based distributions. Feel +free to contribute to this document to provide up-to-date information +for other distributions (e.g., RedHat, Fedora). Run (as root): @@ -41,165 +61,258 @@ Run (as root): apt-get update ; apt-get install git ``` -Mac OSX and Windows -------------------- - -- Download and install Git from the [Git website](https://git-scm.com/downloads). -- Optional Git clients (should not be needed if you work within RStudio): - - [SourceTree](https://www.sourcetreeapp.com/) - - [GitHub Desktop](https://desktop.github.com/) +## Mac OSX and Windows - > [Apparently](https://github.com/desktop/desktop/issues/852), this works with GitLab and https. + - Download and install Git from the [Git + website](https://git-scm.com/downloads). + - Optional Git clients (should not be needed if you work within + RStudio): + - [SourceTree](https://www.sourcetreeapp.com/) + + - [GitHub Desktop](https://desktop.github.com/) + + > [Apparently](https://github.com/desktop/desktop/issues/852), + > this works with GitLab and https. -Configuring Git -=============== +# Configuring Git -Telling Git who you are: Name and Email ---------------------------------------- +## Telling Git who you are: Name and Email 1. Open terminal. -2. Set a Git username and email: +2. Set a Git username and email: + ``` shell git config --global user.name "Mona Lisa" git config --global user.email "email@example.com" ``` 3. Confirm that you have set the Git username correctly: - + ``` shell git config --global user.name git config --global user.email ``` - + ``` example Mona Lisa email@example.com ``` -Dealing with proxies --------------------- +## Dealing with proxies -You may be behind a proxy, in which case you may have trouble cloning or fetching from a remote repository or you may get an error like `unable to access ... Couldn't resolve host ...` +You may be behind a proxy, in which case you may have trouble cloning or +fetching from a remote repository or you may get an error like `unable +to access ... Couldn't resolve host ...` -In such case, consider something like this: +In such case, consider something like +this: ``` shell git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port ``` -The `proxyPassword` will be stored in plain text (unencrypted) in your `.gitconfig` file, which you may not want. In that case, remove it from the URL and you will be prompted for it every time it is needed. - -Getting your default password on GitLab (and possibly changing it) ------------------------------------------------------------------- +The `proxyPassword` will be stored in plain text (unencrypted) in your +`.gitconfig` file, which you may not want. In that case, remove it from +the URL and you will be prompted for it every time it is needed. -**Warning (Jupyter users) :** changing your default Gitlab password will prevent you from committing in Jupyter. You will have to do the extra step of changing your `~/.git-credentials` in the Jupyter environment (possibly several times). +## Getting your default password on GitLab (and possibly changing it) -1. Get your default password using the [Gitlab credentials retrieval tool](https://app-learninglab.inria.fr/jupyterhub/services/password) as described on the [corresponding resource](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85). +**Warning (Jupyter users) :** changing your default Gitlab password will +prevent you from committing in Jupyter. You will have to do the extra +step of changing your `~/.git-credentials` in the Jupyter environment +(possibly several times). +1. Get your default password using the [Gitlab credentials retrieval + tool](https://app-learninglab.inria.fr/jupyterhub/services/password) + as described on the [corresponding + resource](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85). + +
+ ![](gitlab_images/password_retrieval.png) - - The first long and ugly character sequence is your GitLab login/id. It is easy to find once you are logged on gitlab. The second one however is your password and this webpage is the only place where you can find it. We used the FUN authentification mechanism to propagate your credentials so only you can have access to it. You'll need to use this password when trying to propagate some modifications from your computer to GitLab. - - *Note: You have to access this webpage from the FUN platform otherwise you may get a 405 error* *when trying to direcly open .* - + +
+ + The first long and ugly character sequence is your GitLab login/id. + It is easy to find once you are logged on gitlab. The second one + however is your password and this webpage is the only place where + you can find it. We used the FUN authentification mechanism to + propagate your credentials so only you can have access to it. You'll + need to use this password when trying to propagate some + modifications from your computer to GitLab. + + *Note: You have to access this webpage from the FUN platform + otherwise you may get a 405 error* *when trying to direcly open + .* + +
+ ![](gitlab_images/erreur405.png) - -2. Access [GitLab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/5571950188c946e790f06d4bc90fb5f6) from the FUN plateform (click on "Accédez à Gitlab / Access to Gitlab" Button). - - *Note: Again, you have to access Gitlab from the FUN platform otherwise you may get a 405 error* /when trying to direcly open . -3. Click on the first `Sign in` button (alternatively, you can the login/password you just retrieved and use the second `Sign in` button). - + +
+ +2. Access + [GitLab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/5571950188c946e790f06d4bc90fb5f6) + from the FUN plateform (click on "Accédez à Gitlab / Access to + Gitlab" Button). + + *Note: Again, you have to access Gitlab from the FUN platform + otherwise you may get a 405 error* /when trying to direcly open + . + +3. Click on the first `Sign in` button (alternatively, you can the + login/password you just retrieved and use the second `Sign in` + button). + +
+ ![](gitlab_images/signin.png) - -4. If you wish to modify your password, you should go to `Account > Settings > Password` and define your password using the default password you just retrieved. Again, if you use the Jupyter notebooks we have deployed for the MOOC, remember that changing your default Gitlab password will prevent you from committing in Jupyter. You will have to do the extra step of changing your Jupyter `~/.git-credentials` through a Jupyter console (see next section). - + +
+ +4. If you wish to modify your password, you should go to `Account > + Settings > Password` and define your password using the default + password you just retrieved. Again, if you use the Jupyter notebooks + we have deployed for the MOOC, remember that changing your default + Gitlab password will prevent you from committing in Jupyter. You + will have to do the extra step of changing your Jupyter + `~/.git-credentials` through a Jupyter console (see next section). + +
+ ![](gitlab_images/password.png) + +
-Remembering your password locally ---------------------------------- +## Remembering your password locally -If you clone your repository by simply pasting the GitLab URL, you will be prompted for your login and your password every time you want to propagate your local modifications, which is tedious. This is why you should ask git to remember your login and password as follows +If you clone your repository by simply pasting the GitLab URL, you will +be prompted for your login and your password every time you want to +propagate your local modifications, which is tedious. This is why you +should ask git to remember your login and password as +follows ``` shell git config --global credential.helper cache # remember my password git config --global credential.helper "cache --timeout=3600" # for one hour at most ``` -With this setup, you will be prompted for your password but it will be cached in memory and they will not be asked again before an hour. You may want to read [these instructions](https://stackoverflow.com/questions/5343068/is-there-a-way-to-skip-password-typing-when-using-https-on-github) to better understand how all this works. +With this setup, you will be prompted for your password but it will be +cached in memory and they will not be asked again before an hour. You +may want to read [these +instructions](https://stackoverflow.com/questions/5343068/is-there-a-way-to-skip-password-typing-when-using-https-on-github) +to better understand how all this works. -If you want your password to be permanently remembered, you should use this command +If you want your password to be permanently remembered, you should use +this command ``` shell git config credential.helper store ``` -Your password will be then stored in a `.git-credentials` file in plain text. On a perfectly secured machine, it may be fine... or not... ;) Use it at your own risk. +Your password will be then stored in a `.git-credentials` file in plain +text. On a perfectly secured machine, it may be fine… or not… ;) Use it +at your own risk. -Optional: authenticating through SSH ------------------------------------- +## Optional: authenticating through SSH -There are two ways of authenticating and synchronizing your local repository with GitLab: through HTTPS or through SSH. The first one is what was just described and does not require any particular software installation on your machine so this is what I recommend for this MOOC. Yet, I like the second one better (although is may seem a bit more technical), which is why I describe it here. It consists in installing SSH, creating a pair or private/public keys, and uploading your SSH public key on GitLab. This section provides with information on how to do this. +There are two ways of authenticating and synchronizing your local +repository with GitLab: through HTTPS or through SSH. The first one is +what was just described and does not require any particular software +installation on your machine so this is what I recommend for this MOOC. +Yet, I like the second one better (although is may seem a bit more +technical), which is why I describe it here. It consists in installing +SSH, creating a pair or private/public keys, and uploading your SSH +public key on GitLab. This section provides with information on how to +do this. ### Installing SSH 1. Linux (Debian, Ubuntu) - - We provide here only instructions for debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g., RedHat, Fedora). - + + We provide here only instructions for debian-based distributions. + Feel free to contribute to this document to provide up-to-date + information for other distributions (e.g., RedHat, Fedora). + Run (as root): - + ``` bash apt-get update ; apt-get install openssh-client ``` 2. macOS - + You do not have anything to do as it is installed by default. 3. Windows - - You should install the [Putty](https://www.ssh.com/ssh/putty/windows/) client. Once it is installed, look for the section on [generating an SSH key](https://www.ssh.com/ssh/putty/windows/puttygen). + + You should install the + [Putty](https://www.ssh.com/ssh/putty/windows/) client. Once it is + installed, look for the section on [generating an SSH + key](https://www.ssh.com/ssh/putty/windows/puttygen). ### Setting up SSH on GitLab -Here are [all the official explanations on how to set up your SSH key on GitLab](https://docs.gitlab.com/ee/ssh/). Alternatively, you may also want to have a look at this video: +Here are [all the official explanations on how to set up your SSH key on +GitLab](https://docs.gitlab.com/ee/ssh/). Alternatively, you may also +want to have a look at this +video: -Using Git through the command line to synchronize your local files with Gitlab -============================================================================== +# Using Git through the command line to synchronize your local files with Gitlab -This section describes a generic (through the command line) way to synchronize your local files with Gitlab. You will not need this if you follow the Jupyter path. If you follow the RStudio path, all these operations can be done through RStudio and you may want to read [the corresponding instructions](file:///jump_to_id/1a4f58a1efed437c93a9f5c5f15df428). If you follow the Org-Mode path, all these operations can be done through Magit and you may want to read [the corresponding instructions](file:///jump_to_id/508299f7373449a3939faa5b11462bc4). +This section describes a generic (through the command line) way to +synchronize your local files with Gitlab. You will not need this if you +follow the Jupyter path. If you follow the RStudio path, all these +operations can be done through RStudio and you may want to read [the +corresponding +instructions](file:///jump_to_id/1a4f58a1efed437c93a9f5c5f15df428). If +you follow the Org-Mode path, all these operations can be done through +Magit and you may want to read [the corresponding +instructions](file:///jump_to_id/508299f7373449a3939faa5b11462bc4). Here are other ways to learn Git through the command line: -- The [Software Carpentry git tutorial](http://swcarpentry.github.io/git-novice/) -- The (freely available) Pro Git book ([in English](https://git-scm.com/book/en/v2) or [in French](https://git-scm.com/book/fr/v2)). Reading the first two chapters is enough to get a good start. -- [Learn Git Branching](https://learngitbranching.js.org/) will allow to interactively learn Git and to understand with branches. + - The [Software Carpentry git + tutorial](http://swcarpentry.github.io/git-novice/) + - The (freely available) Pro Git book ([in + English](https://git-scm.com/book/en/v2) or [in + French](https://git-scm.com/book/fr/v2)). Reading the first two + chapters is enough to get a good start. + - [Learn Git Branching](https://learngitbranching.js.org/) will allow + to interactively learn Git and to understand with branches. -Now, let's start! +Now, let's start\! 1. Obtain the repository URL - + +
+ ![](rstudio_images/adresse_depot.png) + +
2. Cloning the repository - + ``` shell cd /the/directory/where/you/want/to/clone/your/repository git clone https://app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git ``` - - Alternatively, you may want to indicate now your login although I rather suggest you follow the *Remembering your password locally* instructions: - + + Alternatively, you may want to indicate now your login although I + rather suggest you follow the *Remembering your password locally* + instructions: + ``` shell git clone https://xxx@app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git ``` - + Now a directory `mooc-rr` has been created on your computer. -3. Inspect the repository +3. Inspect the repository + ``` shell cd mooc-rr ls # (Unix) @@ -207,52 +320,82 @@ Now, let's start! ``` 4. Synchronizing to GitLab - - You should indicate which files to track (`git add`) and commit them locally (`git commit`) before they can be transfered (`git push`) to GitLab. The `git status` will indicate you whether files are tracked/modified/committed/... - - Let's assume you just created a `fichier.txt` file on the top of the `mooc-rr` directory. - + + You should indicate which files to track (`git add`) and commit them + locally (`git commit`) before they can be transfered (`git push`) to + GitLab. The `git status` will indicate you whether files are + tracked/modified/committed/… + + Let's assume you just created a `fichier.txt` file on the top of the + `mooc-rr` directory. + ``` shell git status ``` - + +
+ ![](gitlab_images/status1.png) - + +
+ ``` shell git add fichier.txt git status ``` - + +
+ ![](gitlab_images/status2.png) - + +
+ ``` shell git commit -m "message commit" ``` - + +
+ ![](gitlab_images/commit_git.png) - + +
+ ``` shell git status ``` - + +
+ ![](gitlab_images/status3.png) - + +
+ The file can then be transfered to GitLab: - + ``` shell git push ``` - - At this point, git will ask you about your login/password unless you followed the previous *Remembering your password locally* instructions. - - N.B.: you will not be allowed to propagate your modifications to GitLab if other modifications (e.g., from someone else) have been propagated in between - + + At this point, git will ask you about your login/password unless you + followed the previous *Remembering your password locally* + instructions. + + N.B.: you will not be allowed to propagate your modifications to + GitLab if other modifications (e.g., from someone else) have been + propagated in between + +
+ ![](gitlab_images/rejected.png) + +
-5. Synchronizing from Gitlab: to avoid the previous problem, you need to fetch the remote GitLab modifications first and apply them locally. - +5. Synchronizing from Gitlab: to avoid the previous problem, you need + to fetch the remote GitLab modifications first and apply them + locally. + ``` shell git pull ``` - + Only then will you be able to `git push`. diff --git a/module2/ressources/gitlab_fr.md b/module2/ressources/gitlab_fr.md index 3d8a650768e559decde89c411d674eb26baad80c..fa5d43b11f3c33e3909b96000b4bd1925e06c2a7 100644 --- a/module2/ressources/gitlab_fr.md +++ b/module2/ressources/gitlab_fr.md @@ -1,6 +1,6 @@ --- -TITLE: Git et GitLab -Date: Tue Feb 19 19:19:03 2019 +title: Git et GitLab +date: Thu Feb 21 18:08:21 2019 --- **Ce document est particulièrement important si vous suivez le parcours @@ -10,14 +10,15 @@ Jupyter et GitLab dans le contexte de ce MOOC.** Jusqu'à présent, vous avez utilisé Git uniquement via l'interface web du GitLab que nous avons déployée pour le MOOC : -[](https://app-learninglab.inria.fr/gitlab/) + Si vous accédez à ce lien depuis la plate-forme FUN, vous n'avez pas à vous authentifier et vous pouvez facilement lire et modifier tous vos fichiers. C'est très pratique, mais dans la plupart des cas, vous voudrez avoir votre propre copie locale du référentiel et vous devrez synchroniser votre copie locale avec celle de GitLab. Vous devrez -évidemment vous authentifier sur GitLab pour propager vos modifications. +évidemment vous authentifier sur GitLab pour propager vos +modifications. Ce document décrit le logiciel que vous devez installer sur votre ordinateur et comment gérer l'authentification. La section @@ -26,34 +27,32 @@ vidéo](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_ (en français). Veuillez lire attentivement toutes ces instructions, en particulier -celle sur la "Configuration de votre mot de passe sur GitLab". +celle sur la "Configuration de votre mot de passe sur +GitLab". -Table des matières TOC -============================================================================================= +# Table des matières TOC -- [Installer Git](#installer-git) - - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) - - [Mac OSX et Windows](#mac-osx-et-windows) -- [Configurer Git](#configurer-git) - - [Dire à Git qui vous êtes : nom et + - [Installer Git](#installer-git) + - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) + - [Mac OSX et Windows](#mac-osx-et-windows) + - [Configurer Git](#configurer-git) + - [Dire à Git qui vous êtes : nom et email](#dire-à-git-qui-vous-êtes-nom-et-email) - - [Gérer les proxy](#gérer-les-proxy) - - [Récupérer votre mot de passe par défaut sur GitLab (et le + - [Gérer les proxy](#gérer-les-proxy) + - [Récupérer votre mot de passe par défaut sur GitLab (et le changer éventuellement)](#récupérer-votre-mot-de-passe-par-défaut-sur-gitlab-et-le-changer-éventuellement) - - [Enregistrer votre mot de passe + - [Enregistrer votre mot de passe localement](#enregistrer-votre-mot-de-passe-localement) - - [Optionnel : authentification par + - [Optionnel : authentification par SSH](#optionnel-authentification-par-ssh) -- [Utiliser Git par lignes de commandes pour synchroniser vos fichiers + - [Utiliser Git par lignes de commandes pour synchroniser vos fichiers locaux avec Gitlab](#utiliser-git-par-lignes-de-commandes-pour-synchroniser-vos-fichiers-locaux-avec-gitlab) -Installer Git -============= +# Installer Git -Linux (Debian, Ubuntu) ----------------------- +## Linux (Debian, Ubuntu) Nous ne fournissons ici que des instructions pour les distributions basées sur Debian. N'hésitez pas à contribuer à ce document en @@ -66,28 +65,27 @@ Run (as root) : apt-get update ; apt-get install git ``` -Mac OSX et Windows ------------------- +## Mac OSX et Windows -- Télécharger et installer Git depuis le [site + - Télécharger et installer Git depuis le [site Git](https://git-scm.com/downloads). -- Clients Git optionnels (ne devraient pas être nécessaires si vous + - Clients Git optionnels (ne devraient pas être nécessaires si vous travaillez dans RStudio) : - - [SourceTree](https://www.sourcetreeapp.com/) - - [GitHub Desktop](https://desktop.github.com/) - + - [SourceTree](https://www.sourcetreeapp.com/) + + - [GitHub Desktop](https://desktop.github.com/) + > Semble fonctionner avec GitLab et https (voir > [discussion](https://github.com/desktop/desktop/issues/852)). -Configurer Git -============== +# Configurer Git -Dire à Git qui vous êtes : nom et email ---------------------------------------- +## Dire à Git qui vous êtes : nom et email 1. Ouvrir un terminal. -2. Définir un nom d'utilisateur et un email dans Git : +2. Définir un nom d'utilisateur et un email dans Git : + ``` shell git config --global user.name "Mona Lisa" git config --global user.email "email@example.com" @@ -95,25 +93,25 @@ Dire à Git qui vous êtes : nom et email 3. Confirmer que vous avez correctement défini le nom d'utilisateur et l'email Git : - + ``` shell git config --global user.name git config --global user.email ``` - + ``` example Mona Lisa email@example.com ``` -Gérer les proxy ---------------- +## Gérer les proxy Vous êtes peut-être derrière un proxy, auquel cas vous pouvez avoir des problèmes de clonage ou d’extraction à partir d’un dépôt distant, ou une erreur telle que : `unable to access... Couldn't resolve host...` -Dans ce cas, envisagez quelque chose comme ceci : +Dans ce cas, envisagez quelque chose comme +ceci : ``` shell git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port @@ -122,10 +120,10 @@ git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.c Le `proxyPassword` sera stocké en texte brut (non crypté) dans votre fichier `.gitconfig`, ce que vous ne souhaitez peut-être pas. Dans ce cas, supprimez-le de l'URL et vous serez invité à le saisir chaque fois -que vous en aurez besoin. +que vous en aurez +besoin. -Récupérer votre mot de passe par défaut sur GitLab (et le changer éventuellement) ---------------------------------------------------------------------------------- +## Récupérer votre mot de passe par défaut sur GitLab (et le changer éventuellement) **Avertissement (utilisateurs Jupyter) :** changer votre mot de passe Gitlab par défaut vous empêchera de commiter les notebooks Jupyter que @@ -138,9 +136,13 @@ l’environnement Jupyter (éventuellement plusieurs fois). retrieval](https://app-learninglab.inria.fr/jupyterhub/services/password) comme décrit dans la [ressource correspondante](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85). - + +
+ ![](gitlab_images/password_retrieval.png) - + +
+ La première séquence de caractères longue et laide est votre identifiant GitLab qu'il est facile de trouver une fois que vous êtes connecté à Gitlab. Cependant la seconde séquence de caractères @@ -150,31 +152,40 @@ l’environnement Jupyter (éventuellement plusieurs fois). d'identification de sorte que seulement vous puissiez y accéder. Vous devrez utiliser ce mot de passe lorsque vous essaierez de propager des modifications de votre ordinateur vers GitLab. - + *Note : Vous devez accéder à cette page Web à partir de la* *plate-forme FUN, sinon vous risquez d'obtenir une erreur 405 en* *essayant d'accéder directement à .* - + +
+ ![](gitlab_images/erreur405.png) + +
2. Accéder à [GitLab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/xblock/block-v1:inria+41016+session02+type@lti+block@05a0ce425f1741e5bee5049040f70529/handler/preview_handler). - + *Note : Vous devez à nouveau accéder à Gitlab à partir de la plate-forme* *FUN, sinon vous risquez d'obtenir une erreur 405 en essayant d'accéder directement à* . + 3. Cliquez sur le premier bouton `Sign in`. Vous pouvez également utiliser l'identifiant/mot de passe que vous venez de récupérer et utiliser le second bouton `Sign in`. Le second bouton permet de plus de se connecter sans passer par la plateforme FUN une fois que vous connaissez votre identifiant/mot de passe. - + +
+ ![](gitlab_images/signin.png) + +
4. Si vous souhaitez modifier votre mot de passe, accédez à `Account > - Settings > Password` et définissez votre mot de passe à l'aide du + Settings > Password` et définissez votre mot de passe à l'aide du mot de passe par défaut que vous venez de récupérer. Encore une fois, si vous utilisez les notebooks Jupyter que nous avons déployés pour le MOOC, n’oubliez pas que changer votre mot de passe Gitlab @@ -182,17 +193,21 @@ l’environnement Jupyter (éventuellement plusieurs fois). l’étape supplémentaire consistant à changer votre `~/.git-credentials` Jupyter via une console Jupyter (voir section suivante). - + +
+ ![](gitlab_images/password.png) + +
-Enregistrer votre mot de passe localement ------------------------------------------ +## Enregistrer votre mot de passe localement Si vous clonez votre dépôt en collant simplement l'URL de GitLab, vous serez invité à saisir votre identifiant et votre mot de passe chaque fois que vous souhaitez propager vos modifications locales, ce qui est fastidieux. C’est pourquoi vous pouvez demander à Git de se rappeler de -votre identifiant et votre mot de passe comme suit : +votre identifiant et votre mot de passe comme +suit : ``` shell git config --global credential.helper cache # remember my password @@ -217,8 +232,7 @@ en texte brut (non-crypté). Sur une machine parfaitement sécurisée, cela peut être très bien… ou pas… ;) Utilisez cette possibilité à vos risques et périls. -Optionnel : authentification par SSH ------------------------------------- +## Optionnel : authentification par SSH Il existe deux manières d'authentifier et de synchroniser votre dépôt local avec GitLab : via HTTPS ou via SSH. Le premier est ce qui vient @@ -233,40 +247,40 @@ des informations sur la procédure à suivre. ### Installer SSH 1. Linux (Debian, Ubuntu) - + Nous ne fournissons ici que des instructions pour les distributions basées sur Debian. N'hésitez pas à contribuer à ce document en fournissant des informations à jour sur les autres distributions (RedHat, Fedora, par exemple). - + Run (as root) : - + ``` bash apt-get update ; apt-get install openssh-client ``` 2. macOS - + C'est installé par défaut donc vous n'avez rien à faire. 3. Windows - + Vous devez installer le client [Putty](https://www.ssh.com/ssh/putty/windows/). Une fois - l’installation terminée, suivez la section [PuTTYgen - Key Generator - for PuTTY on + l’installation terminée, suivez la section [PuTTYgen - Key + Generator for PuTTY on Windows](https://www.ssh.com/ssh/putty/windows/puttygen). ### Configurer SSH sur GitLab Vous trouverez [ici](https://docs.gitlab.com/ee/ssh/) les explications officielles sur la configuration de votre clé SSH sur GitLab. Vous -pouvez aussi regarder cette vidéo : +pouvez aussi regarder cette +vidéo : -Utiliser Git par lignes de commandes pour synchroniser vos fichiers locaux avec Gitlab -====================================================================================== +# Utiliser Git par lignes de commandes pour synchroniser vos fichiers locaux avec Gitlab Cette section décrit un moyen générique (par lignes de commandes) de synchroniser vos fichiers locaux avec Gitlab. Vous n'en aurez pas besoin @@ -280,41 +294,46 @@ correspondantes](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02 Voici d'autres moyens d'apprendre Git par lignes de commandes : -- Le [Software Carpentry git + - Le [Software Carpentry git tutorial](http://swcarpentry.github.io/git-novice/) -- Le livre Pro Git (gratuit) en + - Le livre Pro Git (gratuit) en [englais](https://git-scm.com/book/en/v2) ou en [français](https://git-scm.com/book/fr/v2). Les deux premiers chapitres suffisent pour bien commencer. -- Le site [Apprenez Git Branching](https://learngitbranching.js.org/) + - Le site [Apprenez Git Branching](https://learngitbranching.js.org/) permet d'apprendre Git interactivement et de comprendre les branches. -Maintenant, commençons ! +Maintenant, commençons \! 1. Récupérer l'URL du dépôt - + +
+ ![](rstudio_images/adresse_depot.png) + +
2. Cloner le dépôt - + ``` shell cd /the/directory/where/you/want/to/clone/your/repository git clone https://app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git ``` - + Alternativement, vous pouvez vouloir indiquer votre identifiant maintenant, bien que je vous suggère plutôt de suivre les instructions de la partie *Enregistrer votre mot de passe localement*. - + ``` shell git clone https://xxx@app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git ``` - + Maintenant un répertoire `mooc-rr` a été créé sur votre ordinateur. -3. Inspecter le répertoire correspondant au dépôt +3. Inspecter le répertoire correspondant au dépôt + ``` shell cd mooc-rr ls # (Unix) @@ -322,62 +341,82 @@ Maintenant, commençons ! ``` 4. Synchroniser avec GitLab - + Vous devez indiquer les fichiers à suivre (`git add`) et les valider - localement (`git commit`) avant de pouvoir les transférer - (`git push`) à GitLab. Le `git status` vous indiquera si les - fichiers sont suivis/modifiés/commités/… - + localement (`git commit`) avant de pouvoir les transférer (`git + push`) à GitLab. Le `git status` vous indiquera si les fichiers sont + suivis/modifiés/commités/… + Supposons que vous venez de créer un fichier `fichier.txt` à la racine du répertoire `mooc-rr`. - + ``` shell git status ``` - + +
+ ![](gitlab_images/status1.png) - + +
+ ``` shell git add fichier.txt git status ``` - + +
+ ![](gitlab_images/status2.png) - + +
+ ``` shell git commit -m "message commit" ``` - + +
+ ![](gitlab_images/commit_git.png) - + +
+ ``` shell git status ``` - + +
+ ![](gitlab_images/status3.png) - + +
+ Le fichier peut ensuite être transféré vers GitLab : - + ``` shell git push ``` - + À ce stade, Git vous demandera votre identifiant/mot de passe, sauf si vous avez suivi les instructions de la partie *Enregistrer votre mot de passe localement*. - + NB : vous ne serez pas autorisé à propager vos modifications dans GitLab si d'autres modifications ont été propagées entre temps (par exemple par quelqu'un d'autre). - + +
+ ![](gitlab_images/rejected.png) + +
5. Synchronisation à partir de Gitlab : pour éviter le problème - précédent, vous devez d’abord récupérer les modifications distantes - de GitLab et les appliquer localement. - + précédent, vous devez d’abord récupérer les modifications + distantes de GitLab et les appliquer localement. + ``` shell git pull ``` - + Alors seulement pourrez-vous exécuter le `git push`. diff --git a/module2/ressources/jupyter.md b/module2/ressources/jupyter.md index 2d86d4d45c761ce696783614d9ffa8e2b2a2af74..ee045ae7195fb5563e445c9e1384e282573eb825 100644 --- a/module2/ressources/jupyter.md +++ b/module2/ressources/jupyter.md @@ -1,105 +1,163 @@ --- -TITLE: Jupyter : tips and tricks, Installing and configuring -AUTHOR: Arnaud Legrand, Benoit Rospars, Konrad Hinsen -Date: Wed Mar 20 12:15:02 2019 +title: Jupyter : tips and tricks, Installing and configuring +author: Arnaud Legrand, Benoit Rospars, Konrad Hinsen +date: Wed Mar 20 12:15:02 2019 --- -Table of Contents -============================================================== - -- [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 tips and tricks -========================= - -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). - -1.1 Creating or importing a 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. - -Adding a brand new notebook in a given directory -Simply follow the following steps: - -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.: If you create a file by doing `File -> New Notebook -> - Python 3`, the new notebook will be created in the current directory. Moving it afterward is possible but a bit cumbersome (you'll have to go through the Jupyter file manager by following the menu `File -> Open`, then select it, `Shut` it `down`, and `Move` and/or `Rename`). - -Importing an already existing notebook -If your notebook is already in your GitLab project, then simply synchronize by using the `Git pull` button and use the `File -> Open` menu. Otherwise, imagine, you want to import the [following 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). -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 Running R and Python in the same notebook ---------------------------------------------- +# Table of Contents TOC + + - [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 tips and tricks + +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). + +## 1.1 Creating or importing a 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. + + - Adding a brand new notebook in a given directory + Simply follow the following steps: + + 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.: If you create a file by doing `File -> New Notebook -> + Python 3`, the new notebook will be created in the current + directory. Moving it afterward is possible but a bit cumbersome + (you'll have to go through the Jupyter file manager by following + the menu `File -> Open`, then select it, `Shut` it `down`, and + `Move` and/or `Rename`). + + - Importing an already existing notebook + If your notebook is already in your GitLab project, then simply + synchronize by using the `Git pull` button and use the `File -> + Open` menu. Otherwise, imagine, you want to import the [following + 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). + 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 Running R and Python in the same notebook `rpy2` package allows to use both languages in the same notebook by: 1. Loading `rpy2`: - + ``` python %load_ext rpy2.ipython ``` 2. Using the `%R` Ipython magic: - + ``` python %%R summary(cars) ``` - - Python objects can then even be passed to R as follows (assuming `df` is a pandas dataframe): - + + Python objects can then even be passed to R as follows (assuming + `df` is a pandas dataframe): + ``` 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. +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. -1.3 Other languages -------------------- +## 1.3 Other languages -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. +Jupyter is not limited to Python and R. Many other languages are +available: , +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. +None of these other languages have been deployed in the context of our +MOOC but you may want to read the next sections to learn how to set up +your own Jupyter on your computer and benefit from these extensions. -Since the question was asked several times, if you really need to stay with SAS, you should know that SAS can be used within Jupyter using either the [Python SASKernel](https://sassoftware.github.io/sas_kernel/) or the [Python SASPy](https://sassoftware.github.io/saspy/) package (step by step explanations about this are given [here](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md)). +Since the question was asked several times, if you really need to stay +with SAS, you should know that SAS can be used within Jupyter using +either the [Python SASKernel](https://sassoftware.github.io/sas_kernel/) +or the [Python SASPy](https://sassoftware.github.io/saspy/) package +(step by step explanations about this are given +[here](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md)). -Since proprietary software such as SAS cannot easily be inspected, we discourage its use as it hinders reproducibility by essence. But perfection does not exist anyway and using Jupyter literate programming approach allied with systematic control version and environment control will certainly help anyway. +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. -2 Installing and configuring Jupyter on your computer -===================================================== +# 2 Installing and configuring Jupyter on your computer -In this section, we explain how to set up a Jupyter environment on your own computer similar to the one deployed for this MOOC. +In this section, we explain how to set up a Jupyter environment on your +own computer similar to the one deployed for this 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. +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. -2.1 Installing Jupyter ----------------------- +## 2.1 Installing 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. +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. -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. +First, download and install the [latest version of +Miniconda](https://conda.io/miniconda.html). We use Miniconda version +`4.5.4` and Python version `3.6` on our server. -Miniconda is a light version of Anaconda, which includes Python, the Jupyter Notebook, and other commonly used packages for scientific computing and data science. +Miniconda is a light version of Anaconda, which includes Python, the +Jupyter Notebook, and other commonly used packages for scientific +computing and data science. -Then download the [moocrr environment file](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57) and create the environment using conda: +Then download the [moocrr environment +file](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57) +and create the environment using conda: ``` shell conda env create -f environment.yml @@ -114,10 +172,12 @@ source activate mooc_rr jupyter notebook ``` -2.2 Making sure Jupyter allows you to use R -------------------------------------------- +## 2.2 Making sure Jupyter allows you to use 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. +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. ### • Installing [IRKernel](https://github.com/IRkernel/IRkernel) (R package) @@ -151,7 +211,8 @@ On Linux, the rpy2 package is available in standard distributions 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 +An alternative (not really recommended if the first one is available) +consists in going through the python package manager with ``` python pip3 install rpy2 @@ -159,9 +220,12 @@ pip3 install rpy2 **Windows** -Download the `rpy2` [binary file](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) by choosing the right operating system. +Download the `rpy2` [binary +file](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) by choosing the +right operating system. -Open a DOS console and type the following command: +Open a DOS console and type the following +command: ``` shell python -m pip install rpy2‑2.9.4‑cp37‑cp37m‑win_amd64.whl # adapt filename @@ -173,44 +237,59 @@ Install also `tzlocal`: python -m pip install tzlocal ``` -2.3 Additional tips -------------------- +## 2.3 Additional tips ### • Exporting a notebook -Here is what we had to install on a recent Debian computer to make sure the notebook export via LaTeX works: +Here is what we had to install on a recent Debian computer to make sure +the notebook export via LaTeX works: ``` shell sudo apt-get install texlive-xetex wkhtmltopdf ``` -Obviously, you can convert to html or pdf using the using the `File > Download as > HTML` (or `PDF`) menu option. This can also be done from the command line with the following command: +Obviously, you can convert to html or pdf using the using the `File > +Download as > HTML` (or `PDF`) menu option. This can also be done from +the command line with the following command: ``` bash ipython3 nbconvert --to pdf Untitled.ipynb ``` -If you want to use a specific style, then the `nbconvert` exporter should be customized. This is discussed and demoed [here](http://markus-beuckelmann.de/blog/customizing-nbconvert-pdf.html). We encourage you to simply read the [doc of nbconvert](https://nbconvert.readthedocs.io/en/latest/). +If you want to use a specific style, then the `nbconvert` exporter +should be customized. This is discussed and demoed +[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/). -Instead of going directly through LaTeX and playing too much with the `nbconvert` exporter, an other option consists in exporting to Markdown and playing with [pandoc](https://pandoc.org/). Both approaches work, it's rather a matter of taste. +Instead of going directly through LaTeX and playing too much with the +`nbconvert` exporter, an other option consists in exporting to Markdown +and playing with [pandoc](https://pandoc.org/). Both approaches work, +it's rather a matter of taste. **Windows** -Download and install MiKTeX from the [MiKTeX webpage](https://miktex.org/download) by choosing the right operating system. You will be prompted to install some specific packages when exporting to pdf. +Download and install MiKTeX from the [MiKTeX +webpage](https://miktex.org/download) by choosing the right operating +system. You will be prompted to install some specific packages when +exporting to pdf. ### • Improving notebook readability Here are a few extensions that can ease your life: -- [Code folding](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook) to improve readability when browsing the notebook. - + - [Code + folding](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook) + to improve readability when browsing the 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. - + - [Hiding code](https://github.com/kirbs-/hide_code) to improve + readability when exporting. + ``` bash sudo pip3 install hide_code sudo jupyter-nbextension install --py hide_code @@ -220,8 +299,28 @@ Here are a few extensions that can ease your life: ### • Interacting with GitLab and GitHub -To ease your experience, we added pull/push buttons that allow you to commit and sync with GitLab. This development was specific to the MOOC but inspired from a previous [proof of concept](https://github.com/Lab41/sunny-side-up). We have recently discovered that someone else developed about at the same time a [rather generic version of this Jupyter plugin](https://github.com/sat28/githubcommit). Otherwise, remember that it is very easy to insert a shell cell in Jupyter in which you can easily issue git commands. This is how we work most of the time. - -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). - -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. +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. + +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). + +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. diff --git a/module2/ressources/jupyter_fr.md b/module2/ressources/jupyter_fr.md index 62d30bd5c6491b45413437c7be8cc840adbcd0d6..e6849bf9e22adfba9b6e54e903b515d1f04ef5f5 100644 --- a/module2/ressources/jupyter_fr.md +++ b/module2/ressources/jupyter_fr.md @@ -1,105 +1,194 @@ --- -TITLE: Jupyter : Trucs et astuces, installation et configuration -AUTHOR: Arnaud Legrand, Benoit Rospars, Konrad Hinsen -Date: Wed Mar 20 12:15:23 2019 +title: Jupyter : Trucs et astuces, installation et configuration +author: Arnaud Legrand, Benoit Rospars, Konrad Hinsen +date: Wed Mar 20 12:15:23 2019 --- -Table des matières -=============================================================== - -- [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: Trucs et astuces -=========================== - -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 Création ou import d'un notebook ------------------------------------- - -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. - -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`. - - N.B.: Si vous créez un notebook à partir du menu `File -> New - Notebook -> Python 3`, il sera créé dans le répertoire courant. Le déplacer après coup et un peu pénible. Il vous faudra aller dans le gestionnaire de fichiers de Jupyter (menu `File -> Open`), sélectionner le notebook, l'arrêter (`Shut =down`), puis le déplacer (`Move`) et/ou le renommer (`Rename`). - -Importer un notebook déja existant -Si le notebook qui vous intéresse est déjà dans votre projet GitLab, il vous suffit de synchroniser la copie de votre Jupyter à l'aide du bouton `Git - pull` et d'utiliser le menu `File -> Open`. Dans le cas contraire, 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: - -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.2 Exécuter du code R et du code Python dans le même 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. - -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. - +# Table des matières TOC + + - [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: Trucs et astuces + +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 Création ou import d'un notebook + +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. + + - 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`. + + N.B.: Si vous créez un notebook à partir du menu `File -> New + Notebook -> Python 3`, il sera créé dans le répertoire courant. + Le déplacer après coup et un peu pénible. Il vous faudra aller + dans le gestionnaire de fichiers de Jupyter (menu `File -> + Open`), sélectionner le notebook, l'arrêter (`Shut =down`), puis + le déplacer (`Move`) et/ou le renommer (`Rename`). + + - Importer un notebook déja existant + Si le notebook qui vous intéresse est déjà dans votre projet GitLab, + il vous suffit de synchroniser la copie de votre Jupyter à l'aide du + bouton `Git + pull` et d'utiliser le menu `File -> Open`. Dans le cas contraire, + 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: + + 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.2 Exécuter du code R et du code Python dans le même 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. + +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. Utilisez la (nouvellement activée) commande magique `%R`: - + ``` python %%R summary(cars) ``` - - Les objets Python peuvent même être passé à R de la façon suivante (ici, on suppose que `df` est une dataframe pandas): - + + 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) ``` -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 Autres langages que Python et R ------------------------------------ - -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. - -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. - -Puisque la question est posée de façon récurrente, si vous avez besoin d'utiliser le langage SAS plutôt que le langage R, il y a deux façons d'utiliser SAS avec Jupyter: soit avec le noyau [Python SASKernel](https://sassoftware.github.io/sas_kernel/), soit avec la bibliothèque [Python SASPy](https://sassoftware.github.io/saspy/) (des explications détaillés sont données [ici](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md)). - -Malgré la qualité et la stabilité de ce langage, SAS n'en reste pas moins un langage propriétaire, ce qui rend l'inspection de ses procédures très difficile et limite la réutilisation des procédures produites par d'autres chercheurs. Nous le déconseillons donc dans un objectif de recherche reproductible mais il faut aussi savoir ne pas être dogmatique. La perfection n'existe pas ;) et, même en utilisant SAS, l'utilisation de la programmation lettrée de Jupyter et d'un contrôle de version (avec gitlab) et d'environnement (avec docker par exemple) se révélera très certainement précieux. - -2 Installation et configuration de Jupyter sur votre ordinateur -=============================================================== - -Dans cette section, nous expliquons comment installer, sur votre ordinateur, un environnement Jupyter similaire à celui que nous avons déployé pour ce MOOC. - -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 Installation de Jupyter ---------------------------- - -Ces instructions permettent d'obtenir sur votre ordinateur un environnement Jupyter similaire à celui que nous avons déployé dans le cadre du MOOC. - -Téléchargez et installez la [dernière version de Miniconda](https://conda.io/miniconda.html). Sur notre serveur, nous utilisons la version `4.5.4` de Miniconda et la version `3.6` de Python. - -Miniconda est une version légère d'Anaconda, une suite logicielle incluant Python, Jupyter, R ainsi que les bibliothèques les plus couramment utilisées en calcul scientifique et en science des données. - -Téléchargez ensuite le [fichier d'environnement `mooc_rr` ](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57) et déployez votre environnement à l'aide de conda: +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 Autres langages que Python et R + +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: +, et en +particulier des langages non libres comme SAS, Mathematica, Matlab… +Notez que la maturité de ces noyaux est très variables. + +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. + +Puisque la question est posée de façon récurrente, si vous avez besoin +d'utiliser le langage SAS plutôt que le langage R, il y a deux façons +d'utiliser SAS avec Jupyter: soit avec le noyau [Python +SASKernel](https://sassoftware.github.io/sas_kernel/), soit avec la +bibliothèque [Python SASPy](https://sassoftware.github.io/saspy/) (des +explications détaillés sont données +[ici](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md)). + +Malgré la qualité et la stabilité de ce langage, SAS n'en reste pas +moins un langage propriétaire, ce qui rend l'inspection de ses +procédures très difficile et limite la réutilisation des procédures +produites par d'autres chercheurs. Nous le déconseillons donc dans un +objectif de recherche reproductible mais il faut aussi savoir ne pas +être dogmatique. La perfection n'existe pas ;) et, même en utilisant +SAS, l'utilisation de la programmation lettrée de Jupyter et d'un +contrôle de version (avec gitlab) et d'environnement (avec docker par +exemple) se révélera très certainement précieux. + +# 2 Installation et configuration de Jupyter sur votre ordinateur + +Dans cette section, nous expliquons comment installer, sur votre +ordinateur, un environnement Jupyter similaire à celui que nous avons +déployé pour ce MOOC. + +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 Installation de Jupyter + +Ces instructions permettent d'obtenir sur votre ordinateur un +environnement Jupyter similaire à celui que nous avons déployé dans le +cadre du MOOC. + +Téléchargez et installez la [dernière version de +Miniconda](https://conda.io/miniconda.html). Sur notre serveur, nous +utilisons la version `4.5.4` de Miniconda et la version `3.6` de Python. + +Miniconda est une version légère d'Anaconda, une suite logicielle +incluant Python, Jupyter, R ainsi que les bibliothèques les plus +couramment utilisées en calcul scientifique et en science des données. + +Téléchargez ensuite le [fichier d'environnement `mooc_rr` +](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57) et +déployez votre environnement à l'aide de conda: ``` shell conda env create -f environment.yml @@ -114,30 +203,38 @@ source activate mooc_rr jupyter notebook ``` -2.2 S'assurer que Jupyter vous permet d'utiliser R --------------------------------------------------- +## 2.2 S'assurer que Jupyter vous permet d'utiliser R -Si vous avez installé l'environnement de la façon décrite dans la section précédente, vous devriez déjà avoir R à votre disposition et vous n'avez donc rien à faire. Mais si vous avez procédé différemment et n'avez que Python et Jupyter à votre disposition, il vous faudra certainement suivre les étapes suivantes +Si vous avez installé l'environnement de la façon décrite dans la +section précédente, vous devriez déjà avoir R à votre disposition et +vous n'avez donc rien à faire. Mais si vous avez procédé différemment et +n'avez que Python et Jupyter à votre disposition, il vous faudra +certainement suivre les étapes +suivantes ### • Installation de [IRKernel](https://github.com/IRkernel/IRkernel) (R package) -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: - -- Installer la bibliothèque `devtools`: +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: + - Installer la bibliothèque `devtools`: + ``` r install.packages('devtools',dep=TRUE) ``` -- Définissez un proxy si nécessaire (c'est important si votre ordinateur est connecté à une entreprise qui limite l'accès à Internet): - + - Définissez un proxy si nécessaire (c'est important si votre + ordinateur est connecté à une entreprise qui limite l'accès à + Internet): + ``` r library(httr) set_config(use_proxy(url="proxy", port=80, username="username", password="password")) ``` -- Installez la bibliothèque `IRkernel`: - + - Installez la bibliothèque `IRkernel`: + ``` r devtools::install_github('IRkernel/IRkernel') IRkernel::installspec() # to register the kernel in the current R installation @@ -145,13 +242,18 @@ IRKernel vous permettra de faire des notebooks utilisant le langage R plutôt qu ### • Installation de rpy2 (Python package) -La bibliothèque `rpy2` permet à Python d'appeler R et donc de mélanger les deux langages dans le même notebook. Cette bibliothèque est en général disponible sur les distributions récentes. Par exemple sous debian ou ubuntu: +La bibliothèque `rpy2` permet à Python d'appeler R et donc de mélanger +les deux langages dans le même notebook. Cette bibliothèque est en +général disponible sur les distributions récentes. Par exemple sous +debian ou ubuntu: ``` shell sudo apt-get install python3-rpy2 python3-tzlocal ``` -Si vous ne disposez pas d'une distribution linux récente, il est possible (mais non recommandé) d'utiliser le gestionnaire de paquets de python: +Si vous ne disposez pas d'une distribution linux récente, il est +possible (mais non recommandé) d'utiliser le gestionnaire de paquets de +python: ``` python pip3 install rpy2 @@ -159,9 +261,12 @@ pip3 install rpy2 **Windows** -Téléchargez le [fichier binaire](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) `rpy2` en choisissant le bon système d'exploitation. +Téléchargez le [fichier +binaire](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) `rpy2` en +choisissant le bon système d'exploitation. -Ouvrez une console DOS et tapez les commandes suivantes: +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 @@ -173,45 +278,62 @@ Installez également `tzlocal`: python -m pip install tzlocal ``` -2.3 Conseils additionnels -------------------------- +## 2.3 Conseils additionnels ### • Exporter un notebook -Jupyter évolue rapidement et ces informations peuvent vite devenir obsolète mais voici ce qu'il peut être utile d'installer sur une debian récente pour que l'export des notebooks via LaTeX soit fonctionnel: +Jupyter évolue rapidement et ces informations peuvent vite devenir +obsolète mais voici ce qu'il peut être utile d'installer sur une debian +récente pour que l'export des notebooks via LaTeX soit fonctionnel: ``` shell sudo apt-get install texlive-xetex wkhtmltopdf ``` L'export vers HTML ou PDF peut se faire dans Jupyter via le menu `File -> Download as > HTML` (ou `PDF`). Il peut également être fait en ligne de commande de la façon suivante: +> Download as > HTML` (ou `PDF`). Il peut également être fait en ligne +de commande de la façon suivante: ``` bash ipython3 nbconvert --to pdf Untitled.ipynb ``` -Pour utiliser un style spécifique, il suffit de personnaliser l'exporter `nbconvert`. Cette personnalisation est présentée [ici](http://markus-beuckelmann.de/blog/customizing-nbconvert-pdf.html) mais nous vous encourageons à simplement lire la [documentation de nbconvert](https://nbconvert.readthedocs.io/en/latest/). +Pour utiliser un style spécifique, il suffit de personnaliser l'exporter +`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/). -Plutôt que de bidouiller trop `nbconvert`, il est aussi possible d'exporter en Markdown et d'utiliser [pandoc](https://pandoc.org/) qui est très flexible. Les deux approches sont possibles, c'est une question de goût. +Plutôt que de bidouiller trop `nbconvert`, il est aussi possible +d'exporter en Markdown et d'utiliser [pandoc](https://pandoc.org/) qui +est très flexible. Les deux approches sont possibles, c'est une question +de goût. **Windows** -Nous vous conseillons de télécharger et d'installer la distribution MiKTeX à partir du [site web de MiKTeX](https://miktex.org/download) en choisissant le bon système d'exploitation. Lors de votre premier export vers pdf, il vous sera certainement demandé d'installer des packages LaTeX spécifiques. +Nous vous conseillons de télécharger et d'installer la distribution +MiKTeX à partir du [site web de MiKTeX](https://miktex.org/download) en +choisissant le bon système d'exploitation. Lors de votre premier export +vers pdf, il vous sera certainement demandé d'installer des packages +LaTeX spécifiques. ### • Améliorer la lisibilité d'un notebook -Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire. Voici quelques extensions qui peuvent vous faciliter un peu la vie: - -- Il est possible [plier/déplier votre code](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook): +Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire. +Voici quelques extensions qui peuvent vous faciliter un peu la vie: + - Il est possible [plier/déplier votre + code](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook): + ``` shell pip3 install jupyter_contrib_nbextensions # jupyter contrib nbextension install --user # not done yet ``` -- Il est aussi possible de [contrôler la visibilité des cellules](https://github.com/kirbs-/hide_code), ce qui peut être très utile si on exporte le notebook: - + - Il est aussi possible de [contrôler la visibilité des + cellules](https://github.com/kirbs-/hide_code), ce qui peut être + très utile si on exporte le notebook: + ``` bash sudo pip3 install hide_code sudo jupyter-nbextension install --py hide_code @@ -221,8 +343,36 @@ Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire. Voici ### • Interaction avec GitLab et GitHub -Pour rendre vous simplifier la vie, nous avons rajouté des boutons `pull/push` dans Jupyter qui vous permettent de synchroniser vos modifications avec GitLab. Ce développement spécifique pour ce MOOC s'est inspiré d'une [preuve de concept](https://github.com/Lab41/sunny-side-up) précédente mais est vraiment *ad hoc*. Indépendemment et à peu près au même moment, une autre personne a développé un [Plugin Jupyter assez générique permettant de se synchroniser avec Gitlab ou Github](https://github.com/sat28/githubcommit). Si cette fonctionnalité vous intéresse, c'est donc une piste intéressante à explorer. Sinon, souvenez vous qu'il est très simple d'insérer une cellule shell dans Jupyter et dans laquelle vous pouvez facilement insérer des commandes git. C'est la façon dont nous travaillons en pratique la majorité du temps. - -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. - -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. +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. + +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. + +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 039c55e19144bea2876d0de0fe9732d182e64309..e3fa9cc0371b73dd1a7d2c944da6609395e8be5e 100644 --- a/module2/ressources/maintaining_a_journal.md +++ b/module2/ressources/maintaining_a_journal.md @@ -1,104 +1,218 @@ --- -TITLE: Maintaining a journal -Date: Wed Mar 20 12:15:41 2019 +title: Maintaining a journal +date: Wed Mar 20 12:15:41 2019 --- -Table of Contents -============================================================== - -- [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) - -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: - -- 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. - - 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). - -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. - -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/): - -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: - -- It forces you to think about what you are doing, which may help you to unblock your problem by your own. Writing down the problems in a clear way is often sufficient to see the solution appearing. -- It helps me following your progress even between the meetings. I cannot unblock you if I don't detect that you are on a wrong lead or otherwise blocked. -- It keeps a track of the steps in your work. That's good for the day where you want to write your final report (even if a final report should never be presented in the chronological order). That's good for the next after you who will be supposed to continue you effort, or to build upon it. -- That person may be yourself (if you go for a PhD program), another intern, myself or even someone else on the Internet: that's what we call Open Science, an effort where everyone can build upon the scientific work of everyone. - -I want you to write your reporting in an org file (yep, you don't have a choice here). \[..\] - -Reporting Logistics -------------------- - -Once you're setup with all software installed and somehow configured, you need to create a reporting file in a place where I can see it and where it won't get lost if your disk crashes or something. Open a dedicated git repository (on github, gitorious, gitlab, ...) for that. After your internship, your report should be archived directly in the source tree of the software that you are working on, if any. But having your reporting located in the source tree may complicate things during your work. - -Yes, it means that your file will be public at some point, but that's why we call it "Open Science", after all. Also, you should write it in English if possible. The part of your reporting that is called "Journal" (see below) may be written in French if you are more efficient this way but the rest must be in English. Don't make your tone too formal because the file is public. Make it efficient. Nobody will ever blame you for the work you did during an internship a long time ago. If you really want, we can even make this file anonymous. Just speak to me. - -You want to write your reporting before leaving work. Weekly reporting should be written on Friday, one or two hours before leaving. That's the best solution to have a nice week end without thinking about work, and still lose no information that you would need on Monday morning. - -Reporting Document Organization -------------------------------- +# Table of Contents TOC + + - [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) + +# 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: + + - 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. + - 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). + +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. + +# 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/): + +## 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: + + - It forces you to think about what you are doing, which may help you + to unblock your problem by your own. Writing down the problems in a + clear way is often sufficient to see the solution appearing. + - It helps me following your progress even between the meetings. I + cannot unblock you if I don't detect that you are on a wrong lead or + otherwise blocked. + - It keeps a track of the steps in your work. That's good for the day + where you want to write your final report (even if a final report + should never be presented in the chronological order). That's good + for the next after you who will be supposed to continue you effort, + or to build upon it. + - That person may be yourself (if you go for a PhD program), another + intern, myself or even someone else on the Internet: that's what we + call Open Science, an effort where everyone can build upon the + scientific work of everyone. + +I want you to write your reporting in an org file (yep, you don't have a +choice here). \[..\] + +## Reporting Logistics + +Once you're setup with all software installed and somehow configured, +you need to create a reporting file in a place where I can see it and +where it won't get lost if your disk crashes or something. Open a +dedicated git repository (on github, gitorious, gitlab, …) for that. +After your internship, your report should be archived directly in the +source tree of the software that you are working on, if any. But having +your reporting located in the source tree may complicate things during +your work. + +Yes, it means that your file will be public at some point, but that's +why we call it "Open Science", after all. Also, you should write it in +English if possible. The part of your reporting that is called "Journal" +(see below) may be written in French if you are more efficient this way +but the rest must be in English. Don't make your tone too formal because +the file is public. Make it efficient. Nobody will ever blame you for +the work you did during an internship a long time ago. If you really +want, we can even make this file anonymous. Just speak to me. + +You want to write your reporting before leaving work. Weekly reporting +should be written on Friday, one or two hours before leaving. That's the +best solution to have a nice week end without thinking about work, and +still lose no information that you would need on Monday morning. + +## Reporting Document Organization Your reporting document should have four main parts: -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). - -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. - -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. - -Conclusion -That's what you write in the next week of your internship. You can see it as a letter to the next guy, explaining the current state of your work, a few words about its technical organization, and what should be done next on that topic. Keep this part highly technical, the overall organization of your internship will be seen in your final report. - -The Journal part is the only part that you may write in French on need. You want to add one subsection per period to your journal. Don't make it too long, or you would waste time writing long texts that very few will ever read. Don't make it too short or it will be impossible to understand it on Monday morning (or three months after). Finding the good balance is sometimes difficult, but I will provide feedback on your first entries, so don't worry. + - 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). + - 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. + - 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. + - Conclusion + That's what you write in the next week of your internship. You can + see it as a letter to the next guy, explaining the current state of + your work, a few words about its technical organization, and what + should be done next on that topic. Keep this part highly technical, + the overall organization of your internship will be seen in your + final report. + +The Journal part is the only part that you may write in French on need. +You want to add one subsection per period to your journal. Don't make it +too long, or you would waste time writing long texts that very few will +ever read. Don't make it too short or it will be impossible to +understand it on Monday morning (or three months after). Finding the +good balance is sometimes difficult, but I will provide feedback on your +first entries, so don't worry. Each of section describing a period should contain three subsubsections: -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). - -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). - -Planned work -A few items about what you plan to work on during the next period. - -A template of reporting file is given at the end of this section. This is just a strong advice: If you really feel better with another file organization, then give it a try for one period, and ask for my feedback. I can adapt, and I do not pretend that my advice is the definitive answer. It's just the result of my experience so far. - -Notice how TODO items are written: they are given as items in the Planned work sections of the journal. As explained in the [documentation](http://orgmode.org/manual/Checkboxes.html), you simply have to write "\[ \]" in front of items that you plan to do in the future. - -You should add a \[1/\] on the "Planned work" line, so that emacs keeps track of what is done and what is still to do. Once they are done, you type C-c C-C on their lines to change the blank box \[ \] into a checked box \[X\]. Also, the \[1/\] will be changed to denote the amount of work that is still to be done. - -At any point, you can see all ongoing TODO items with the following keystrokes: "C-c / t". More information on TODOs in orgmode's [documentation](http://orgmode.org/manual/TODO-basics.html). The important thing here is that most TODO items must only be written in the *Journal* part (so that we know when they occurred). - -**Do not edit past entries of your journal**, unless you have very good reasons. If you must, make sure that you don't lose information about the path that you took (remember the Open Science thingy). You should always **add** information to past entries, such as: + - 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). + - 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). + - Planned work + A few items about what you plan to work on during the next period. + +A template of reporting file is given at the end of this section. This +is just a strong advice: If you really feel better with another file +organization, then give it a try for one period, and ask for my +feedback. I can adapt, and I do not pretend that my advice is the +definitive answer. It's just the result of my experience so far. + +Notice how TODO items are written: they are given as items in the +Planned work sections of the journal. As explained in the +[documentation](http://orgmode.org/manual/Checkboxes.html), you simply +have to write "\[ \]" in front of items that you plan to do in the +future. + +You should add a \[1/\] on the "Planned work" line, so that emacs keeps +track of what is done and what is still to do. Once they are done, you +type C-c C-C on their lines to change the blank box \[ \] into a checked +box \[X\]. Also, the \[1/\] will be changed to denote the amount of work +that is still to be done. + +At any point, you can see all ongoing TODO items with the following +keystrokes: "C-c / t". More information on TODOs in orgmode's +[documentation](http://orgmode.org/manual/TODO-basics.html). The +important thing here is that most TODO items must only be written in the +*Journal* part (so that we know when they occurred). + +**Do not edit past entries of your journal**, unless you have very good +reasons. If you must, make sure that you don't lose information about +the path that you took (remember the Open Science thingy). You should +always **add** information to past entries, such +as: ``` shell - *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information. ``` -The only exception are TODO entries, that should clearly be rewritten to DONE entries. If you need to adapt your TODO entry (because the initial goal was poorly stated or otherwise), change the initial entry from TODO to CANCELED (or check the box after stating in a subitem that it was not done but canceled, and why), and create a new TODO entry in the current period section. +The only exception are TODO entries, that should clearly be rewritten to +DONE entries. If you need to adapt your TODO entry (because the initial +goal was poorly stated or otherwise), change the initial entry from TODO +to CANCELED (or check the box after stating in a subitem that it was not +done but canceled, and why), and create a new TODO entry in the current +period section. ``` example * Introduction diff --git a/module2/ressources/maintaining_a_journal_fr.md b/module2/ressources/maintaining_a_journal_fr.md index ab3115d766418adcaec64e8348de35e6b14bef19..b8a3ba8f631a5f421e5bd93f434464d547d44690 100644 --- a/module2/ressources/maintaining_a_journal_fr.md +++ b/module2/ressources/maintaining_a_journal_fr.md @@ -1,104 +1,260 @@ --- -TITLE: Tenir un journal à jour -Date: Wed Mar 20 12:16:07 2019 +title: Tenir un journal à jour +date: Wed Mar 20 12:16:07 2019 --- -Table des matières -=============================================================== - -- [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é) - -1. Quelques exemples de cahiers de notes ou de laboratoires pouvant servir de source d'inspiration -================================================================================================== - -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 (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 (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 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. - -2. Comment rendre compte de son activité efficacement -===================================================== - -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/)). - -Le Reporting ------------- - -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: - -- Ç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. - -Je veux que vous écriviez votre compte rendu d'activité dans un fichier org-mode (et oui, vous n'avez pas le choix! ). \[..\] - -Logistique ----------- - -Une fois que vous aurez mis en place et plus ou moins configuré tous les logiciels dont vous aurez besoin, il vous faudra créer un fichier dans un endroit auquel je puisse accéder et qui ne sera pas perdu si jamais votre disque dur est endommagé, que vous vous faites voler votre ordinateur, ou autre. Pour cela, commencez par créer un dépôt git (sur github, gitorious, ou gitlab, ...). À la fin de votre stage, votre rapport devra être archivé directement dans l'arborescence du logiciel auquel vous avez contribué. Travailler directement dans cette arborescence pendant votre stage peut cependant être un peu compliqué. - -Mais, oui, cela veut dire que votre journal sera publique à un moment ou à un autre (après tout, c'est pour ça qu'on parle de science ouverte). Vous avez donc intérêt à écrire votre rapport en Anglais si c'est possible. La partie compte-rendu d'activité (votre "journal") peut être écrite en Français si vous êtes plus efficace ainsi mais le reste doit être rédigé en Anglais. Pas la peine de prendre un ton trop formel sous prétexte que le document a vocation à être publique. Soyez efficace. Personne ne vous tiendra rigueur de ce que vous avez pu écrire à l'occasion de votre stage il y a de nombreuses années. Si vous insistez, il est possible d'anonymiser ou de pseudonymiser ce document, venez m'en parler. - -Enfin, il est important d'écrire votre compte rendu avant de quitter votre bureau, tant que les choses sont fraîches dans votre esprit. En plus, cela vous libérera de la charge mentale induite par ce travail de mémorisation. Si vous décidez de faire un reporting hebdomadaire, faites le le vendredi, une ou deux heures avant de partir. C'est la meilleur façon de passer un bon week-end sans avoir à penser à votre travail et de ne perdre aucune information dont vous pourriez avoir besoin lundi matin. Même principe si vous faites un reporting quotidien. - -Organisation d'un compte rendu d'activité ------------------------------------------ - -Selon moi, une bonne pratique consiste à structurer votre compte rendu d'activité de la façon suivante: - -Résultats -Cette section résume les informations que vous avez obtenu à l'occasion de votre recherche. Elle est généralement vide au début de votre stage et prendra du volume au fur et à mesure que vous trouvez des choses. C'est aussi souvent ici qu'atterrissent les références bibliographiques par exemple mais ce n'est clairement pas l'endroit où vous stockez votre liste des choses à faire (TODO). - -Développement -Cette section présente les aspects techniques de votre travail. N'écrivez rien ici pour l'instant. Mettez tout ce que vous collectez dans la partie Journal. - -Journal -C'est ici que vous décrivez votre travail au jour le jour, de façon chronologique (jour, semaine, mois, ...). C'est la partie la plus importante de votre reporting et nous y revenons un peu plus bas. - -Conclusion -C'est la section que vous écrivez la dernière semaine (ou celle d'après) de votre stage. Vous pouvez la voir comme une lettre à la prochaine personne expliquant l'état actuel de votre travail, avec quelques informations que son organisation technique et ce qui, selon vous, sont les prochaines choses à faire et pourquoi. Cette partie peut-être hautement technique, les tenants et les aboutissants plus globaux de votre stage étant des considérations qui apparaîtront plutôt dans votre rapport final de stage. - -La partie Journal est la seul que vous avez le droit d'écrire en Français si vous êtes plus à l'aise ainsi. Pas la peine de vous "répandre", vous perdriez votre temps à écrire un long texte que très peu de personnes seront susceptibles de lire. Ne la bâclez pour autant car si elle est trop courte elle sera incompréhensible la semaine d'après (ou trois mois plus tard). Trouver le bon équilibre n'est pas toujours simple mais je vous ferai un retour sur vos premières entrées donc ne vous inquiétez pas. - -Une bonne habitude consiste à ce que chacune des entrées section décrivant une période de travail soit structurée de la façon suivante: - -Travail effectué -quelques mots sur ce que vous avez fait et son contexte. Cela peut prendre la forme d'une petite liste de 2 à 4 entrées sur ce que vous avez fait et pourquoi vous l'avez fait. - -Ponts bloquants et questions -essayez d'expliquer clairement les points de blocage que vous rencontrez ou bien les points qui vous gênent et vous ralentissent. Si vous avez finalement déjà trouvé la réponse à ces problèmes, indiquez leu dans la sous-section précédente. C'est aussi ici que vous écrirez toute question que vous aimeriez me poser. Si ce sont des interrogations personnelles (par exemple sur la logistique de votre stage, le logement, votre salaire), utilisez plutôt le mail qui restera privé entre nous (souvenez vous que ce journal a vocation a devenir un document publique). Si cette section est vide pour une période donnée, sautez la tout simplement (ne gardez pas de sous-sections vides). - -Travaux prévus -Une petite liste détaillant les points auxquels vous comptez vous attaquer dans la période à venir. - -Vous trouverez à la fin un modèle de compte rendu d'activité. Un conseil: si vraiment vous vous sentez mieux avec une autre structuration de document, essayez pour une période donnée et on fera le point. Je sais m'adapter et je ne prétends pas avoir la science infuse ni que mes conseils soient la solution ultime et universelle. C'est juste le résultat de mon expérience jusqu'ici. - -Remarquez comment les entrées commençant par le mot-clé TODO apparaissent. On le retrouvera typiquement dans les sections "Travaux prévus" du journal. Comme expliqué dans la [documentation 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. - -Dans ce cas, en rajoutant un \[1/\] à la fin de la sous-sous-section "Travaux prévus", Emacs tiendra à jour le compte des choses faites et qui restent à faire. Une fois que ce qui est décrit dans l'un des éléments d'une liste est faite, il vous suffit de faire `C-c C-C` sur cette entrée pour transformer le `[ ]` en une version cochée `[X]`. Le \[1/\] sera alors mis à jour pour refléter la quantité de travail restant. Lorsque tout aura été effectué, le mot-clé TODO passera à DONE, ce qui procure un incroyable sentiment de satisfaction. :) - -À tout moment, vous pouvez avoir accès à l'ensemble des choses à faire (TODO) à l'aide du raccourci clavier suivant: `C-c / t`. Vous trouverez plus d'informations sur les TODOs dans la [documentation d'orgmode](http://orgmode.org/manual/TODO-basics.html). Le point important à retenir ici est que la plupart des TODO doivent apparaître dans la partie journal (afin de savoir quand ils se sont posés). - -**N'éditez jamais les entrées de votre journal a posteriori**, sauf si vous avez vraiment une très bonne raison. Si cela devait arriver, assurez vous que vous ne perdez pas d'informations sur ce que vous avez fait et les choix que vous avez effectués (souvenez vous, science ouverte, tout ça tout ça). Il faut toujours **ajouter** des nouvelles informations aux anciennes, par exemple comme ceci: +# Table des matières TOC + + - [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é) + +# 1\. Quelques exemples de cahiers de notes ou de laboratoires pouvant servir de source d'inspiration + +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 (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 (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 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. + +# 2\. Comment rendre compte de son activité efficacement + +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/)). + +## Le Reporting + +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: + + - Ç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. + +Je veux que vous écriviez votre compte rendu d'activité dans un fichier +org-mode (et oui, vous n'avez pas le choix\! ). \[..\] + +## Logistique + +Une fois que vous aurez mis en place et plus ou moins configuré tous les +logiciels dont vous aurez besoin, il vous faudra créer un fichier dans +un endroit auquel je puisse accéder et qui ne sera pas perdu si jamais +votre disque dur est endommagé, que vous vous faites voler votre +ordinateur, ou autre. Pour cela, commencez par créer un dépôt git (sur +github, gitorious, ou gitlab, …). À la fin de votre stage, votre rapport +devra être archivé directement dans l'arborescence du logiciel auquel +vous avez contribué. Travailler directement dans cette arborescence +pendant votre stage peut cependant être un peu compliqué. + +Mais, oui, cela veut dire que votre journal sera publique à un moment ou +à un autre (après tout, c'est pour ça qu'on parle de science ouverte). +Vous avez donc intérêt à écrire votre rapport en Anglais si c'est +possible. La partie compte-rendu d'activité (votre "journal") peut être +écrite en Français si vous êtes plus efficace ainsi mais le reste doit +être rédigé en Anglais. Pas la peine de prendre un ton trop formel sous +prétexte que le document a vocation à être publique. Soyez efficace. +Personne ne vous tiendra rigueur de ce que vous avez pu écrire à +l'occasion de votre stage il y a de nombreuses années. Si vous insistez, +il est possible d'anonymiser ou de pseudonymiser ce document, venez m'en +parler. + +Enfin, il est important d'écrire votre compte rendu avant de quitter +votre bureau, tant que les choses sont fraîches dans votre esprit. En +plus, cela vous libérera de la charge mentale induite par ce travail de +mémorisation. Si vous décidez de faire un reporting hebdomadaire, faites +le le vendredi, une ou deux heures avant de partir. C'est la meilleur +façon de passer un bon week-end sans avoir à penser à votre travail et +de ne perdre aucune information dont vous pourriez avoir besoin lundi +matin. Même principe si vous faites un reporting quotidien. + +## Organisation d'un compte rendu d'activité + +Selon moi, une bonne pratique consiste à structurer votre compte rendu +d'activité de la façon suivante: + + - Résultats + Cette section résume les informations que vous avez obtenu à + l'occasion de votre recherche. Elle est généralement vide au début + de votre stage et prendra du volume au fur et à mesure que vous + trouvez des choses. C'est aussi souvent ici qu'atterrissent les + références bibliographiques par exemple mais ce n'est clairement + pas l'endroit où vous stockez votre liste des choses à faire (TODO). + - Développement + Cette section présente les aspects techniques de votre travail. + N'écrivez rien ici pour l'instant. Mettez tout ce que vous + collectez dans la partie Journal. + - Journal + C'est ici que vous décrivez votre travail au jour le jour, de façon + chronologique (jour, semaine, mois, …). C'est la partie la plus + importante de votre reporting et nous y revenons un peu plus bas. + - Conclusion + C'est la section que vous écrivez la dernière semaine (ou celle + d'après) de votre stage. Vous pouvez la voir comme une lettre à la + prochaine personne expliquant l'état actuel de votre travail, avec + quelques informations que son organisation technique et ce qui, + selon vous, sont les prochaines choses à faire et pourquoi. Cette + partie peut-être hautement technique, les tenants et les + aboutissants plus globaux de votre stage étant des considérations + qui apparaîtront plutôt dans votre rapport final de stage. + +La partie Journal est la seul que vous avez le droit d'écrire en +Français si vous êtes plus à l'aise ainsi. Pas la peine de vous +"répandre", vous perdriez votre temps à écrire un long texte que très +peu de personnes seront susceptibles de lire. Ne la bâclez pour autant +car si elle est trop courte elle sera incompréhensible la semaine +d'après (ou trois mois plus tard). Trouver le bon équilibre n'est pas +toujours simple mais je vous ferai un retour sur vos premières entrées +donc ne vous inquiétez pas. + +Une bonne habitude consiste à ce que chacune des entrées section +décrivant une période de travail soit structurée de la façon suivante: + + - Travail effectué + quelques mots sur ce que vous avez fait et son contexte. Cela peut + prendre la forme d'une petite liste de 2 à 4 entrées sur ce que vous + avez fait et pourquoi vous l'avez fait. + - Ponts bloquants et questions + essayez d'expliquer clairement les points de blocage que vous + rencontrez ou bien les points qui vous gênent et vous ralentissent. + Si vous avez finalement déjà trouvé la réponse à ces problèmes, + indiquez leu dans la sous-section précédente. C'est aussi ici que + vous écrirez toute question que vous aimeriez me poser. Si ce sont + des interrogations personnelles (par exemple sur la logistique de + votre stage, le logement, votre salaire), utilisez plutôt le mail + qui restera privé entre nous (souvenez vous que ce journal a + vocation a devenir un document publique). Si cette section est vide + pour une période donnée, sautez la tout simplement (ne gardez pas de + sous-sections vides). + - Travaux prévus + Une petite liste détaillant les points auxquels vous comptez vous + attaquer dans la période à venir. + +Vous trouverez à la fin un modèle de compte rendu d'activité. Un +conseil: si vraiment vous vous sentez mieux avec une autre structuration +de document, essayez pour une période donnée et on fera le point. Je +sais m'adapter et je ne prétends pas avoir la science infuse ni que mes +conseils soient la solution ultime et universelle. C'est juste le +résultat de mon expérience jusqu'ici. + +Remarquez comment les entrées commençant par le mot-clé TODO +apparaissent. On le retrouvera typiquement dans les sections "Travaux +prévus" du journal. Comme expliqué dans la [documentation +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. + +Dans ce cas, en rajoutant un \[1/\] à la fin de la sous-sous-section +"Travaux prévus", Emacs tiendra à jour le compte des choses faites et +qui restent à faire. Une fois que ce qui est décrit dans l'un des +éléments d'une liste est faite, il vous suffit de faire `C-c C-C` sur +cette entrée pour transformer le `[ ]` en une version cochée `[X]`. Le +\[1/\] sera alors mis à jour pour refléter la quantité de travail +restant. Lorsque tout aura été effectué, le mot-clé TODO passera à DONE, +ce qui procure un incroyable sentiment de satisfaction. :) + +À tout moment, vous pouvez avoir accès à l'ensemble des choses à faire +(TODO) à l'aide du raccourci clavier suivant: `C-c / t`. Vous trouverez +plus d'informations sur les TODOs dans la [documentation +d'orgmode](http://orgmode.org/manual/TODO-basics.html). Le point +important à retenir ici est que la plupart des TODO doivent apparaître +dans la partie journal (afin de savoir quand ils se sont posés). + +**N'éditez jamais les entrées de votre journal a posteriori**, sauf si +vous avez vraiment une très bonne raison. Si cela devait arriver, +assurez vous que vous ne perdez pas d'informations sur ce que vous avez +fait et les choix que vous avez effectués (souvenez vous, science +ouverte, tout ça tout ça). Il faut toujours **ajouter** des nouvelles +informations aux anciennes, par exemple comme +ceci: ``` shell - *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information. ``` -La seule exception à cet édition des entrées passées, ce sont les entrées de type TODO, qui sont dynamiques et ont vocation à être transformées en entrées de type DONE. Si vous réalisez qu'il est utile d'adapter une entrée TODO (parce que l'objectif initial a été mal formulé, est inadapté, que sais je?), faites passer l'entrée d'origine de TODO à CANCELED (et/ou cochez le `[ ]` en indiquant dans une sous-entrée que cette tâche n'a pas été faite mais annulée et pourquoi) et créez une nouvelle entrée TODO dans la section du jour. +La seule exception à cet édition des entrées passées, ce sont les +entrées de type TODO, qui sont dynamiques et ont vocation à être +transformées en entrées de type DONE. Si vous réalisez qu'il est utile +d'adapter une entrée TODO (parce que l'objectif initial a été mal +formulé, est inadapté, que sais je?), faites passer l'entrée d'origine +de TODO à CANCELED (et/ou cochez le `[ ]` en indiquant dans une +sous-entrée que cette tâche n'a pas été faite mais annulée et pourquoi) +et créez une nouvelle entrée TODO dans la section du jour. ``` example * Introduction diff --git a/module2/ressources/orgmode_examples/README.md b/module2/ressources/orgmode_examples/README.md index ba6b4d42f85105e09b0c1f5a948113d78b464cc5..73624ead407ba8f6c577a9956e067ae4ac5fa185 100644 --- a/module2/ressources/orgmode_examples/README.md +++ b/module2/ressources/orgmode_examples/README.md @@ -1,33 +1,84 @@ --- -TITLE: Document Examples -AUTHOR: Arnaud Legrand -Date: Wed Mar 20 13:03:17 2019 +title: Document Examples +author: Arnaud Legrand +date: Wed Mar 20 13:03:17 2019 --- -Table of Contents -============================================================== +# Table of Contents TOC -- [Examples from the Video](#examples-from-the-video) -- [Other examples](#other-examples) + - [Examples from the Video](#examples-from-the-video) + - [Other examples](#other-examples) -Examples from the Video -======================= +# Examples from the Video -In the MOOC video, I quickly demo how org-mode can be used in various contexts. Here are the (sometimes trimmed) corresponding org-files. These documents depend on many other external data files and are not meant to lead to reproducible documents but it will give you an idea of how it can be organized: +In the MOOC video, I quickly demo how org-mode can be used in various +contexts. Here are the (sometimes trimmed) corresponding org-files. +These documents depend on many other external data files and are not +meant to lead to reproducible documents but it will give you an idea of +how it can be organized: -1. [journal.org](journal.org): an excerpt (I've only left a few code samples and links to some resources on R, Stats, ...) from my own journal. This is a personal document where everything (meeting notes, hacking, random thoughts, ...) goes by default. Entries are created with the `C-c c` shortcut. -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): 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. -Other examples -============== +# Other examples Here are a few links to other kind of examples: -- 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). + - 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). diff --git a/module2/ressources/orgmode_examples/README_fr.md b/module2/ressources/orgmode_examples/README_fr.md index bd374808d4383cfd234ba4ef852cbfa73f1603cd..1e1ca1a11f0ddf52ab1fe40163a7417c5a2031d9 100644 --- a/module2/ressources/orgmode_examples/README_fr.md +++ b/module2/ressources/orgmode_examples/README_fr.md @@ -1,33 +1,116 @@ --- -TITLE: Quelques exemples de documents en Org-Mode -AUTHOR: Arnaud Legrand -Date: Wed Mar 20 13:01:44 2019 +title: Quelques exemples de documents en Org-Mode +author: Arnaud Legrand +date: Wed Mar 20 13:01:44 2019 --- -Table of Contents -============================================================== +# Table of Contents TOC -- [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) + - [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) -Les documents montrés en exemple dans les vidéos du MOOC -======================================================== +# Les documents montrés en exemple dans les vidéos du MOOC -Dans les vidéos, je montre rapidement comment org-mode peut être utilisé dans différents contextes (feuille de TD, journal, cahier de laboratoire, article). Voici les fichiers org-mode (quelques fois un peu épurés) correspondant. Ces documents dépendent souvent d'autres fichiers externes et ne sont pas prévu pour permettre de produire directement des documents reproductibles mais ils peuvent vous donner une idée de la façon dont ils peuvent être organisés: +Dans les vidéos, je montre rapidement comment org-mode peut être utilisé +dans différents contextes (feuille de TD, journal, cahier de +laboratoire, article). Voici les fichiers org-mode (quelques fois un peu +épurés) correspondant. Ces documents dépendent souvent d'autres fichiers +externes et ne sont pas prévu pour permettre de produire directement des +documents reproductibles mais ils peuvent vous donner une idée de la +façon dont ils peuvent être organisés: -1. [journal.org](journal.org): ceci est un extrait (je n'ai laissé que quelques exemples de programmes et de liens vers des ressources sur R, les statistiques, etc.) de mon propre journal. C'est un document personnel dans lequel tout ce que je peux faire (notes prises pendant une réunion, petit code vite fait, idées diverses et variées, notes bibliographiques, ...) atterrit par défaut. Les entrées avec la date sont créées automatiquement à l'aide du raccourci `C-c c`. -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. +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. -Autres exemples -=============== +# Autres exemples Voici à toute fin utile quelques liens vers d'autres types d'exemples: -- John Kitchin est un expert org-modiste impliqué dans les questions de recherche reproductible et qui tient à jour un [blog avec une foule d'astuces intéressantes](http://kitchingroup.cheme.cmu.edu/blog/). Vous pourriez vouloir jeter un œil au [séminaire qu'il a donné à SciPy](https://www.youtube.com/watch?v=IsSMs-4GlT8&list=FLQp2VLAOlvq142YN3JO3y8w&app=desktop). -- 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: + - 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/ressources/rstudio.md b/module2/ressources/rstudio.md index 842365d7a77d8e47cf364b9f66a4a36e0b3e74b9..58d6a87784995356af2acfbe7546d2db273ffba7 100644 --- a/module2/ressources/rstudio.md +++ b/module2/ressources/rstudio.md @@ -1,51 +1,68 @@ --- -TITLE: Rstudio -Date: Tue Feb 19 19:19:03 2019 +title: Rstudio +date: Tue Feb 19 19:19:03 2019 --- -Table of Contents -============================================================== +# Table of Contents TOC -- [Installing RStudio](#installing-rstudio) - - [Linux (debian, ubuntu)](#linux-debian-ubuntu) - - [Mac OSX and Windows](#mac-osx-and-windows) -- [RStudio documentation](#rstudio-documentation) -- [Using Git from RStudio](#using-git-from-rstudio) - - [Cloning a repository](#cloning-a-repository) - - [Modifying a file](#modifying-a-file) + - [Installing RStudio](#installing-rstudio) + - [Linux (debian, ubuntu)](#linux-debian-ubuntu) + - [Mac OSX and Windows](#mac-osx-and-windows) + - [RStudio documentation](#rstudio-documentation) + - [Using Git from RStudio](#using-git-from-rstudio) + - [Cloning a repository](#cloning-a-repository) + - [Modifying a file](#modifying-a-file) -Installing RStudio -================== +# Installing RStudio -Linux (debian, ubuntu) ----------------------- +## Linux (debian, ubuntu) -We provide here only instructions for Debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g., RedHat, Fedora). +We provide here only instructions for Debian-based distributions. Feel +free to contribute to this document to provide up-to-date information +for other distributions (e.g., RedHat, Fedora). -Today, the stable versions of the most common distributions provide recent enough versions of R: +Today, the stable versions of the most common distributions provide +recent enough versions of R: -- Debian (stretch) ships with [R 3.3.3-1](https://packages.debian.org/stretch/r-base), [knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr), and [ggplot 2.2.1](https://packages.debian.org/stretch/r-cran-ggplot2) -- Ubuntu (bionic 18.04) ships with [R 3.4.4](https://packages.ubuntu.com/bionic/r-base), and [knitr 1.17](https://packages.ubuntu.com/bionic/r-cran-knitr), and [ggplot 2.2.1](https://packages.ubuntu.com/bionic/r-cran-ggplot2) -- Ubuntu (artful 17.04) ships with [R 3.4.2](https://packages.ubuntu.com/artful/r-base), and [knitr 1.15](https://packages.ubuntu.com/artful/r-cran-knitr), and [ggplot 2.2.1](https://packages.ubuntu.com/artful/r-cran-ggplot2) + - Debian (stretch) ships with + [R 3.3.3-1](https://packages.debian.org/stretch/r-base), + [knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr), + and + [ggplot 2.2.1](https://packages.debian.org/stretch/r-cran-ggplot2) + - Ubuntu (bionic 18.04) ships with + [R 3.4.4](https://packages.ubuntu.com/bionic/r-base), and + [knitr 1.17](https://packages.ubuntu.com/bionic/r-cran-knitr), and + [ggplot 2.2.1](https://packages.ubuntu.com/bionic/r-cran-ggplot2) + - Ubuntu (artful 17.04) ships with + [R 3.4.2](https://packages.ubuntu.com/artful/r-base), and + [knitr 1.15](https://packages.ubuntu.com/artful/r-cran-knitr), and + [ggplot 2.2.1](https://packages.ubuntu.com/artful/r-cran-ggplot2) -If your distribution is older than this, well, it may be a good time for upgrading... +If your distribution is older than this, well, it may be a good time for +upgrading… ### Installing R -First, you need to install the R language and convenient packages by running (as root): +First, you need to install the R language and convenient packages by +running (as +root): ``` shell apt-get update ; sudo apt-get install r-base r-cran-knitr r-cran-ggplot2 ``` -Alternatively, if the installation of `r-cran-gplot2` or `r-cran-knitr` fails, you may want to install them locally (through the R packaging system) and manually by running the following commands in R (or RStudio): +Alternatively, if the installation of `r-cran-gplot2` or `r-cran-knitr` +fails, you may want to install them locally (through the R packaging +system) and manually by running the following commands in R (or +RStudio): ``` r install.packages("knitr") install.packages("ggplot2") ``` -If you plan to export pdf documents with LaTeX, you probably also want to run (as root): +If you plan to export pdf documents with LaTeX, you probably also want +to run (as root): ``` bash apt-get update ; apt-get install texlive-base @@ -53,7 +70,11 @@ apt-get update ; apt-get install texlive-base ### Installing RStudio -RStudio is unfortunately not packaged within Debian so the easiest is to download the corresponding Debian package on the [RStudio webpage](https://www.rstudio.com/products/rstudio/download/#download) and then to install it manually (you may have to adjust the version number in the following example). Here is how to install it: +RStudio is unfortunately not packaged within Debian so the easiest is to +download the corresponding Debian package on the [RStudio +webpage](https://www.rstudio.com/products/rstudio/download/#download) +and then to install it manually (you may have to adjust the version +number in the following example). Here is how to install it: ``` shell cd /tmp/ @@ -62,96 +83,174 @@ sudo dpkg -i rstudio-xenial-1.1.453-amd64.deb sudo apt-get update ; sudo apt-get -f install # to fix possibly missing dependencies ``` -Mac OSX and Windows -------------------- +## Mac OSX and Windows -> Some instructions on installing R and knitr must be missing. This should be tested and improved. +> Some instructions on installing R and knitr must be missing. This +> should be tested and improved. -- Download and install R from the [CRAN webpage](https://cran.r-project.org/) by choosing the right operating system. -- Download and install RStudio from the [RStudio webpage](https://www.rstudio.com/products/rstudio/download/#download) by choosing the right operating system. -- 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. -- Open RStudio and type the following commands in the console to install `knitr` and `ggplot2`: + - Download and install R from the [CRAN + webpage](https://cran.r-project.org/) by choosing the right + operating system. + - Download and install RStudio from the [RStudio + webpage](https://www.rstudio.com/products/rstudio/download/#download) + by choosing the right operating system. + - 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. + - Open RStudio and type the following commands in the console to + install `knitr` and `ggplot2`: + + ``` r install.packages("knitr", dep=TRUE) install.packages("ggplot2", dep=TRUE) ``` -RStudio documentation -===================== - -The RStudio team has created a lot of very good material and tutorials. You should definitively look at the [Cheat sheets webpage](https://www.rstudio.com/resources/cheatsheets/). In particular you may want to have look at the following ones: - -- [The RStudio IDE](https://github.com/rstudio/cheatsheets/raw/master/rstudio-ide.pdf), -- [R Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf) (here is also a [nice step-by-step presentation of Rmarkdown](https://rmarkdown.rstudio.com/)), -- The [R Markdown Reference guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf), -- [Data visualization with ggplot2](https://github.com/rstudio/cheatsheets/raw/master/data-visualization-2.1.pdf), -- [Data transformation with dplyr](https://github.com/rstudio/cheatsheets/raw/master/data-transformation.pdf) - -In case it helps, here are some (sometimes outdated) French versions of these documents: - -- [L'IDE RStudio](https://github.com/rstudio/cheatsheets/raw/master/translations/french/rstudio-IDE-cheatsheet.pdf) -- [Visualisation de données avec ggplot2](https://github.com/rstudio/cheatsheets/raw/master/translations/french/ggplot2-french-cheatsheet.pdf) -- [Transformation de données avec dplyr](https://github.com/rstudio/cheatsheets/raw/master/translations/french/data-wrangling-french.pdf) -- [Un court document sur R Markdown](https://www.fun-mooc.fr/c4x/UPSUD/42001S02/asset/RMarkdown.pdf) - -Using Git from RStudio -====================== - -If you have never used git with RStudio, **we strongly advise that you follow [our tutorial on using git from RStudio](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/d132a854b0464ad29085cedaded23136)** (/"RStudio et Gitlab"/ in French). Before proceeding, make sure you also have followed the **["git/GitLab configuration" tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)** (in French). - -Alternatively, you may want to watch [this video](https://www.youtube.com/embed/uHYcDQDbMY8) (in English). If you do not like videos, you should have a look at the [step-by-step explanations from Software Carpentry](https://swcarpentry.github.io/git-novice/14-supplemental-rstudio/index.html). It comes with many screenshots and is quite progressive. - -Cloning a repository --------------------- +# RStudio documentation + +The RStudio team has created a lot of very good material and tutorials. +You should definitively look at the [Cheat sheets +webpage](https://www.rstudio.com/resources/cheatsheets/). In particular +you may want to have look at the following ones: + + - [The RStudio + IDE](https://github.com/rstudio/cheatsheets/raw/master/rstudio-ide.pdf), + - [R + Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf) + (here is also a [nice step-by-step presentation of + Rmarkdown](https://rmarkdown.rstudio.com/)), + - The [R Markdown Reference + guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf), + - [Data visualization with + ggplot2](https://github.com/rstudio/cheatsheets/raw/master/data-visualization-2.1.pdf), + - [Data transformation with + dplyr](https://github.com/rstudio/cheatsheets/raw/master/data-transformation.pdf) + +In case it helps, here are some (sometimes outdated) French versions of +these documents: + + - [L'IDE + RStudio](https://github.com/rstudio/cheatsheets/raw/master/translations/french/rstudio-IDE-cheatsheet.pdf) + - [Visualisation de données avec + ggplot2](https://github.com/rstudio/cheatsheets/raw/master/translations/french/ggplot2-french-cheatsheet.pdf) + - [Transformation de données avec + dplyr](https://github.com/rstudio/cheatsheets/raw/master/translations/french/data-wrangling-french.pdf) + - [Un court document sur R + Markdown](https://www.fun-mooc.fr/c4x/UPSUD/42001S02/asset/RMarkdown.pdf) + +# Using Git from RStudio + +If you have never used git with RStudio, **we strongly advise that you +follow [our tutorial on using git from +RStudio](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/d132a854b0464ad29085cedaded23136)** +(*"RStudio et Gitlab"* in French). Before proceeding, make sure you also +have followed the **["git/GitLab configuration" +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)** +(in French). + +Alternatively, you may want to watch [this +video](https://www.youtube.com/embed/uHYcDQDbMY8) (in English). If you +do not like videos, you should have a look at the [step-by-step +explanations from Software +Carpentry](https://swcarpentry.github.io/git-novice/14-supplemental-rstudio/index.html). +It comes with many screenshots and is quite progressive. + +## Cloning a repository Open RStudio and do the following steps: -- Create a new version controled project: `File / New Project / Version Control` - + - Create a new version controled project: `File / New Project / + Version Control` + +
+ ![](rstudio_images/new_project.png) - + ![](rstudio_images/git.png) + +
-- Get the URL from your GitLab repository: - + - Get the URL from your GitLab repository: + +
+ ![](rstudio_images/adresse_depot.png) - -- Indicate this URL in the "Repository URL" field (*you may want to prefix this URL with `xxx@` where `xxx` is* *your Gitlab id to avoid repeatedly giving it later on*). - + +
+ + - Indicate this URL in the "Repository URL" field (*you may want to + prefix this URL with `xxx@` where `xxx` is* *your Gitlab id to avoid + repeatedly giving it later on*). + +
+ ![](rstudio_images/clone.png) + +
+ + - If you're behind a proxy, git should be configured accordingly. + Check the ["Dealing with proxies" + section](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85). -- If you're behind a proxy, git should be configured accordingly. Check the ["Dealing with proxies" section](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85). -- Git will then connect to Gitlab and fetch a whole copy of the repository. -- RStudio should restart in a mode related to Git: + - Git will then connect to Gitlab and fetch a whole copy of the + repository. + - RStudio should restart in a mode related to Git: + +
+ ![](rstudio_images/rstudio.png) + +
-- The file manager on the right, allows you to browse the version controled repository. + - The file manager on the right, allows you to browse the version + controled repository. -Modifying a file ----------------- +## Modifying a file -- Open `Module2/exo1/toy_document.Rmd` and perform a simple modification. -- Save -- Go to the Git menu to commit + - Open `Module2/exo1/toy_document.Rmd` and perform a simple + modification. - ![](rstudio_images/commit.png) + - Save + - Go to the Git menu to commit + +
+ + ![](rstudio_images/commit.png) + ![](rstudio_images/commit2.png) + +
-- Select the lines to commit and then click on `commit` - + - Select the lines to commit and then click on `commit` + +
+ ![](rstudio_images/commit5.png) - - Your modifications have now been commited on your local machine. They haven't been propagated to GitLab yet. -- Click on `push` to propagate them on GitLab - + +
+ + Your modifications have now been commited on your local machine. + They haven't been propagated to GitLab yet. + + - Click on `push` to propagate them on GitLab + +
+ ![](rstudio_images/push.png) - + ![](rstudio_images/push2.png) - + ![](rstudio_images/push3.png) - - **NB**: You won't be able to propagate your modifications on GitLab if some modifications have been done on GitLab in the meantime. ![](rstudio_images/push4.png) -- You should first merge these remote modifications locally. Click on `pull` to get these modifications on your machine. + +
+ + **NB**: You won't be able to propagate your modifications on GitLab + if some modifications have been done on GitLab in the meantime. + ![](rstudio_images/push4.png) + + - You should first merge these remote modifications locally. Click on + `pull` to get these modifications on your machine. diff --git a/module2/ressources/rstudio_fr.md b/module2/ressources/rstudio_fr.md index 0bc364904aa86dac7ba3e1c55893ae9feb68b981..4ed72527995e256425d5866b994d911762541d3e 100644 --- a/module2/ressources/rstudio_fr.md +++ b/module2/ressources/rstudio_fr.md @@ -1,51 +1,67 @@ --- -TITLE: Rstudio -Date: Tue Feb 19 19:19:03 2019 +title: Rstudio +date: Tue Feb 19 19:19:03 2019 --- -Table des matières -=============================================================== +# Table des matières TOC -- [Installer RStudio](#installer-rstudio) - - [Linux (debian, ubuntu)](#linux-debian-ubuntu) - - [Mac OSX and Windows](#mac-osx-and-windows) -- [Documentation RStudio](#documentation-rstudio) -- [Utiliser Git avec RStudio](#utiliser-git-avec-rstudio) - - [Cloner un dépôt](#cloner-un-dépôt) - - [Modifier un fichier](#modifier-un-fichier) + - [Installer RStudio](#installer-rstudio) + - [Linux (debian, ubuntu)](#linux-debian-ubuntu) + - [Mac OSX and Windows](#mac-osx-and-windows) + - [Documentation RStudio](#documentation-rstudio) + - [Utiliser Git avec RStudio](#utiliser-git-avec-rstudio) + - [Cloner un dépôt](#cloner-un-dépôt) + - [Modifier un fichier](#modifier-un-fichier) -Installer RStudio -================= +# Installer RStudio -Linux (debian, ubuntu) ----------------------- +## Linux (debian, ubuntu) -Nous ne fournissons ici que des instructions pour les distributions basées sur Debian. N’hésitez pas à contribuer à ce document en fournissant des informations à jour sur les autres distributions (RedHat, Fedora, par exemple). +Nous ne fournissons ici que des instructions pour les distributions +basées sur Debian. N’hésitez pas à contribuer à ce document en +fournissant des informations à jour sur les autres distributions +(RedHat, Fedora, par exemple). -Aujourd'hui, les versions stables des distributions les plus courantes fournissent des versions assez récentes de R : +Aujourd'hui, les versions stables des distributions les plus courantes +fournissent des versions assez récentes de R : -- Debian (stretch) est livré avec [R 3.3.3-1](https://packages.debian.org/stretch/r-base), [knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr), et [ggplot 2.2.1](https://packages.debian.org/stretch/r-cran-ggplot2) -- Ubuntu (bionic 18.04) est livré avec [R 3.4.4](https://packages.ubuntu.com/bionic/r-base), [knitr 1.17](https://packages.ubuntu.com/bionic/r-cran-knitr), et [ggplot 2.2.1](https://packages.ubuntu.com/bionic/r-cran-ggplot2) -- Ubuntu (artful 17.04) est livré avec [R 3.4.2](https://packages.ubuntu.com/artful/r-base), [knitr 1.15](https://packages.ubuntu.com/artful/r-cran-knitr), et [ggplot 2.2.1](https://packages.ubuntu.com/artful/r-cran-ggplot2) + - Debian (stretch) est livré avec + [R 3.3.3-1](https://packages.debian.org/stretch/r-base), + [knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr), et + [ggplot 2.2.1](https://packages.debian.org/stretch/r-cran-ggplot2) + - Ubuntu (bionic 18.04) est livré avec + [R 3.4.4](https://packages.ubuntu.com/bionic/r-base), + [knitr 1.17](https://packages.ubuntu.com/bionic/r-cran-knitr), et + [ggplot 2.2.1](https://packages.ubuntu.com/bionic/r-cran-ggplot2) + - Ubuntu (artful 17.04) est livré avec + [R 3.4.2](https://packages.ubuntu.com/artful/r-base), + [knitr 1.15](https://packages.ubuntu.com/artful/r-cran-knitr), et + [ggplot 2.2.1](https://packages.ubuntu.com/artful/r-cran-ggplot2) -Si votre distribution est plus ancienne, c'est peut-être l'occasion de la mettre à jour... +Si votre distribution est plus ancienne, c'est peut-être l'occasion de +la mettre à jour… ### Installer R -Pour commencer, vous devez installer le langage R et quelques packages en exécutant (à la racine) : +Pour commencer, vous devez installer le langage R et quelques packages +en exécutant (à la +racine) : ``` shell apt-get update ; sudo apt-get install r-base r-cran-knitr r-cran-ggplot2 ``` -Si l'installation de `r-cran-knitr` ou `r-cran-gplot2` échoue, vous pouvez également installer ces packages manuellement en exécutant les commandes suivantes sous R (ou RStudio) : +Si l'installation de `r-cran-knitr` ou `r-cran-gplot2` échoue, vous +pouvez également installer ces packages manuellement en exécutant les +commandes suivantes sous R (ou RStudio) : ``` r install.packages("knitr") install.packages("ggplot2") ``` -Si vous envisagez d'exporter des documents pdf avec LaTeX, il faudra probablement aussi exécuter (à la racine) : +Si vous envisagez d'exporter des documents pdf avec LaTeX, il faudra +probablement aussi exécuter (à la racine) : ``` shell apt-get update ; apt-get install texlive-base @@ -53,7 +69,11 @@ apt-get update ; apt-get install texlive-base ### Installer RStudio -RStudio n’est malheureusement pas intégré à Debian. Le plus simple est de télécharger le paquet Debian correspondant sur le [site RStudio](https://www.rstudio.com/products/rstudio/download/#download), puis de l’installer manuellement (vous devrez peut-être adapter le numéro de version) : +RStudio n’est malheureusement pas intégré à Debian. Le plus simple est +de télécharger le paquet Debian correspondant sur le [site +RStudio](https://www.rstudio.com/products/rstudio/download/#download), +puis de l’installer manuellement (vous devrez peut-être adapter le +numéro de version) : ``` shell cd /tmp/ @@ -62,100 +82,178 @@ sudo dpkg -i rstudio-xenial-1.1.453-amd64.deb sudo apt-get update ; sudo apt-get -f install # to fix possibly missing dependencies ``` -Mac OSX and Windows -------------------- +## Mac OSX and Windows -- Télécharger et installer R depuis le [site CRAN](https://cran.r-project.org/) en choisissant le bon système d'exploitation. -- Télécharger et installer RStudio depuis le [site RStudio](https://www.rstudio.com/products/rstudio/download/#download) en choisissant le bon système d'exploitation. -- Télécharger et installer MiKTeX depuis le [site MiKTeX](https://miktex.org/download) en choisissant le bon système d'exploitation. Vous serez amené à installer différents packages lors du premier export pdf. -- Ouvrir RStudio et exécuter les commandes suivantes dans la console pour installer `knitr` et `ggplot2` + - Télécharger et installer R depuis le [site + CRAN](https://cran.r-project.org/) en choisissant le bon système + d'exploitation. + - Télécharger et installer RStudio depuis le [site + RStudio](https://www.rstudio.com/products/rstudio/download/#download) + en choisissant le bon système d'exploitation. + - Télécharger et installer MiKTeX depuis le [site + MiKTeX](https://miktex.org/download) en choisissant le bon système + d'exploitation. Vous serez amené à installer différents packages + lors du premier export pdf. + - Ouvrir RStudio et exécuter les commandes suivantes dans la console + pour installer `knitr` et `ggplot2` + + ``` r install.packages("knitr", dep=TRUE) install.packages("ggplot2", dep=TRUE) ``` -Documentation RStudio -===================== - -L’équipe de RStudio a créé différents matériels et tutoriels très bien faits. Nous vous recommandons de consulter les [fiches mémo](https://www.rstudio.com/resources/cheatsheets/). En particulier, vous pourriez être intéressés par celles-ci : - -- [RStudio IDE](https://github.com/rstudio/cheatsheets/raw/master/rstudio-ide.pdf), -- [R Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf) (here is also a [nice step-by-step presentation of Rmarkdown](https://rmarkdown.rstudio.com/)), -- The [R Markdown Reference guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf), -- [Data visualization with ggplot2](https://github.com/rstudio/cheatsheets/raw/master/data-visualization-2.1.pdf), -- [Data transformation with dplyr](https://github.com/rstudio/cheatsheets/raw/master/data-transformation.pdf) - -Voici aussi les versions françaises de certains documents mais elles ne sont pas toujours à jour : - -- [IDE RStudio](https://github.com/rstudio/cheatsheets/raw/master/translations/french/rstudio-IDE-cheatsheet.pdf) -- [Visualisation de données avec ggplot2](https://github.com/rstudio/cheatsheets/raw/master/translations/french/ggplot2-french-cheatsheet.pdf) -- [Transformation de données avec dplyr](https://github.com/rstudio/cheatsheets/raw/master/translations/french/data-wrangling-french.pdf) -- [Un court document sur R Markdown](https://www.fun-mooc.fr/c4x/UPSUD/42001S02/asset/RMarkdown.pdf) - -Utiliser Git avec RStudio -========================= - -La première chose à faire est de configurer Git sur votre ordinateur. Pour ce faire, vous pouvez suivre la vidéo [configurer Git pour Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85) (en français) et le document [Git et Gitlab](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/gitlab_fr.org) correspondant (en français). - -Vous pourrez alors utiliser Git avec RStudio. Pour ce faire, vous pouvez suivre la vidéo [RStudio - Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/d132a854b0464ad29085cedaded23136) (en français) dont les étapes sont reprises ci-dessous. - -*(Nous vous signalons aussi cette* [vidéo](https://www.youtube.com/embed/uHYcDQDbMY8) *(en anglais) ainsi que le* [tuto pas à pas](https://swcarpentry.github.io/git-novice/14-supplemental-rstudio/index.html) *(en anglais) de Software Carpentry.)* - -Cloner un dépôt ---------------- +# Documentation RStudio + +L’équipe de RStudio a créé différents matériels et tutoriels très bien +faits. Nous vous recommandons de consulter les [fiches +mémo](https://www.rstudio.com/resources/cheatsheets/). En particulier, +vous pourriez être intéressés par celles-ci : + + - [RStudio + IDE](https://github.com/rstudio/cheatsheets/raw/master/rstudio-ide.pdf), + - [R + Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf) + (here is also a [nice step-by-step presentation of + Rmarkdown](https://rmarkdown.rstudio.com/)), + - The [R Markdown Reference + guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf), + - [Data visualization with + ggplot2](https://github.com/rstudio/cheatsheets/raw/master/data-visualization-2.1.pdf), + - [Data transformation with + dplyr](https://github.com/rstudio/cheatsheets/raw/master/data-transformation.pdf) + +Voici aussi les versions françaises de certains documents mais elles ne +sont pas toujours à jour : + + - [IDE + RStudio](https://github.com/rstudio/cheatsheets/raw/master/translations/french/rstudio-IDE-cheatsheet.pdf) + - [Visualisation de données avec + ggplot2](https://github.com/rstudio/cheatsheets/raw/master/translations/french/ggplot2-french-cheatsheet.pdf) + - [Transformation de données avec + dplyr](https://github.com/rstudio/cheatsheets/raw/master/translations/french/data-wrangling-french.pdf) + - [Un court document sur R + Markdown](https://www.fun-mooc.fr/c4x/UPSUD/42001S02/asset/RMarkdown.pdf) + +# Utiliser Git avec RStudio + +La première chose à faire est de configurer Git sur votre ordinateur. +Pour ce faire, vous pouvez suivre la vidéo [configurer Git pour +Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85) +(en français) et le document [Git et +Gitlab](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/gitlab_fr.org) +correspondant (en français). + +Vous pourrez alors utiliser Git avec RStudio. Pour ce faire, vous pouvez +suivre la vidéo [RStudio - +Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/d132a854b0464ad29085cedaded23136) +(en français) dont les étapes sont reprises ci-dessous. + +*(Nous vous signalons aussi cette* +[vidéo](https://www.youtube.com/embed/uHYcDQDbMY8) *(en anglais) ainsi +que le* [tuto pas à +pas](https://swcarpentry.github.io/git-novice/14-supplemental-rstudio/index.html) +*(en anglais) de Software Carpentry.)* + +## Cloner un dépôt Ouvrir RStudio et procéder comme suit : -- Créer un nouveau projet sous contrôle de version : `File / New - Project / Version Control` - + - Créer un nouveau projet sous contrôle de version : `File / New + Project / Version Control` + +
+ ![](rstudio_images/new_project.png) - + ![](rstudio_images/git.png) + +
-- Récupérer l'URL du dépôt Gitlab - + - Récupérer l'URL du dépôt Gitlab + +
+ ![](rstudio_images/adresse_depot.png) - -- Indiquez cette URL dans le champ "Repository URL" *(vous voudrez* *peut-être préfixer cette URL avec `xxx@` où `xxx` est votre identifiant* *Gitlab pour éviter d'avoir à le ressaisir ultérieurement)*. - + +
+ + - Indiquez cette URL dans le champ "Repository URL" *(vous voudrez* + *peut-être préfixer cette URL avec `xxx@` où `xxx` est votre + identifiant* *Gitlab pour éviter d'avoir à le ressaisir + ultérieurement)*. + +
+ ![](rstudio_images/clone.png) + +
+ + - Si vous êtes derrière un proxy, il faut le définir dans Git (voir le + paragraphe "Gérer les proxy" de la page sur [Git et + Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)). -- Si vous êtes derrière un proxy, il faut le définir dans Git (voir le paragraphe "Gérer les proxy" de la page sur [Git et Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)). -- Git se connecte à Gitlab et récupère une copie complète du dépôt. -- RStudio redémarre dans un mode lié à Git : + - Git se connecte à Gitlab et récupère une copie complète du dépôt. + - RStudio redémarre dans un mode lié à Git : + +
+ ![](rstudio_images/rstudio.png) + +
-- Le gestionnaire de fichiers à droite vous permet de parcourir le dépôt sous contrôle de version. + - Le gestionnaire de fichiers à droite vous permet de parcourir le + dépôt sous contrôle de version. -Modifier un fichier -------------------- +## Modifier un fichier -- Ouvrir le fichier `Module2/exo1/toy_document.Rmd` et le modifier. -- Enregistrer. -- Aller dans le menu Git pour effectuer le commit. + - Ouvrir le fichier `Module2/exo1/toy_document.Rmd` et le modifier. - ![](rstudio_images/commit.png) + - Enregistrer. + - Aller dans le menu Git pour effectuer le commit. + +
+ + ![](rstudio_images/commit.png) + ![](rstudio_images/commit2.png) + +
-- Sélectionner les lignes à commiter puis cliquer sur `commit`. - + - Sélectionner les lignes à commiter puis cliquer sur `commit`. + +
+ ![](rstudio_images/commit5.png) - - Les modifications ont été commitées uniquement sur la machine. Elles n'ont pas été propagées sur Gitlab. -- Cliquer sur `push` pour les propager sur Gitlab. - + +
+ + Les modifications ont été commitées uniquement sur la machine. Elles + n'ont pas été propagées sur Gitlab. + + - Cliquer sur `push` pour les propager sur Gitlab. + +
+ ![](rstudio_images/push.png) - + ![](rstudio_images/push2.png) - + ![](rstudio_images/push3.png) - - **NB :** Vous ne pouvez pas propager vos modifications sur GitLab si des modifications ont été faites sur GitLab entre-temps. - + +
+ + **NB :** Vous ne pouvez pas propager vos modifications sur GitLab si + des modifications ont été faites sur GitLab entre-temps. + +
+ ![](rstudio_images/push4.png) + +
-- Il faut d’abord récupérer ces modifications distantes sur votre machine locale. Pour ce faire cliquer sur `pull`. + - Il faut d’abord récupérer ces modifications distantes sur votre + machine locale. Pour ce faire cliquer sur `pull`. diff --git a/module2/slides/ressources.md b/module2/slides/ressources.md index 6c50410f717c46bfb8a5af0a85c6b45e4867c2e6..1c1c387d85043f5435e29fd25dade5924a1d5fcc 100644 --- a/module2/slides/ressources.md +++ b/module2/slides/ressources.md @@ -1,94 +1,109 @@ --- -TITLE: Computational Documents -Date: Wed Mar 20 13:19:19 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. +This document gathers most references mentioned in the videos. This is a +rather crude +list. -Table of Contents -============================================================== +# Table of Contents TOC -- [M2-S0: Computational Documents](#m2-s0-computational-documents) -- [M2-S1: A few Recent Controversial Studies](#m2-s1-a-few-recent-controversial-studies) - - [Economy: Austerity in Fiscal Policy](#economy-austerity-in-fiscal-policy) - - [Functional MRI](#functional-mri) - - [Incorrect Protein Structures](#incorrect-protein-structures) - - [Other domains](#other-domains) -- [M2-S2: Why is This so Difficult?](#m2-s2-why-is-this-so-difficult) - - [Mistakes](#mistakes) - - [Going Public?](#going-public) -- [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) - - [Exemples of Org-Mode documents](#exemples-of-org-mode-documents) + - [M2-S0: Computational Documents](#m2-s0-computational-documents) + - [M2-S1: A few Recent Controversial + Studies](#m2-s1-a-few-recent-controversial-studies) + - [Economy: Austerity in Fiscal + Policy](#economy-austerity-in-fiscal-policy) + - [Functional MRI](#functional-mri) + - [Incorrect Protein Structures](#incorrect-protein-structures) + - [Other domains](#other-domains) + - [M2-S2: Why is This so Difficult?](#m2-s2-why-is-this-so-difficult) + - [Mistakes](#mistakes) + - [Going Public?](#going-public) + - [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) + - [Exemples of Org-Mode + documents](#exemples-of-org-mode-documents) -M2-S0: Computational Documents -============================== +# M2-S0: Computational Documents -M2-S1: A few Recent Controversial Studies -========================================= +# M2-S1: A few Recent Controversial Studies -Economy: Austerity in Fiscal Policy ------------------------------------ +## Economy: Austerity in Fiscal Policy -- [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, + - [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, -Functional MRI --------------- +## Functional MRI -- 2010: [Bennett et al. and the dead salmon](https://www.researchgate.net/publication/255651552_Neural_correlates_of_interspecies_perspective_taking_in_the_post-mortem_Atlantic_Salmon_an_argument_for_multiple_comparisons_correction) ☺ -- 2016: [Eklund, Nichols, and Knutsson](http://www.pnas.org/content/113/28/7900.abstract). [A bug in fmri software could invalidate 15 years of brain research](http://www.sciencealert.com/a-bug-in-fmri-software-could-invalidate-decades-of-brain-research-scientists-discover) (*40 000 articles*) -- 2016: But it's [more subtle than it looks like](https://www.cogneurosociety.org/debunking-the-myth-that-fmri-studies-are-invalid/). [Nichols](http://blogs.warwick.ac.uk/nichols/entry/bibliometrics_of_cluster/). *≈ 3 600 impacted studies* + - 2010: [Bennett et al. and the dead + salmon](https://www.researchgate.net/publication/255651552_Neural_correlates_of_interspecies_perspective_taking_in_the_post-mortem_Atlantic_Salmon_an_argument_for_multiple_comparisons_correction) + ☺ + - 2016: [Eklund, Nichols, and + Knutsson](http://www.pnas.org/content/113/28/7900.abstract). [A bug + in fmri software could invalidate 15 years of brain + research](http://www.sciencealert.com/a-bug-in-fmri-software-could-invalidate-decades-of-brain-research-scientists-discover) + (*40 000 articles*) + - 2016: But it's [more subtle than it looks + like](https://www.cogneurosociety.org/debunking-the-myth-that-fmri-studies-are-invalid/). + [Nichols](http://blogs.warwick.ac.uk/nichols/entry/bibliometrics_of_cluster/). + *≈ 3 600 impacted studies* -Incorrect Protein Structures ----------------------------- +## 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 -------------- +## Other domains -- [Oncology](http://www.nature.com/nrd/journal/v10/n9/full/nrd3439-c1.html?foxtrotcallback=true): "*half of published studies, even in prestigious journals, can't be reproduced in industrial labs*" -- [Psychology](http://theconversation.com/we-found-only-one-third-of-published-psychology-research-is-reliable-now-what-46596): "*attempting to reproduce 100 previously published findings*, *only one-third of published psychology research was found to be reliable*" + - [Oncology](http://www.nature.com/nrd/journal/v10/n9/full/nrd3439-c1.html?foxtrotcallback=true): + "*half of published studies, even in prestigious journals, can't be + reproduced in industrial + labs*" + - [Psychology](http://theconversation.com/we-found-only-one-third-of-published-psychology-research-is-reliable-now-what-46596): + "*attempting to reproduce 100 previously published findings*, *only + one-third of published psychology research was found to be + reliable*" -M2-S2: Why is This so Difficult? -================================ +# M2-S2: Why is This so Difficult? -Mistakes --------- +## Mistakes -- [Computers broke science](http://theconversation.com/how-computers-broke-science-and-what-we-can-do-to-fix-it-49938) -- [Programming and data manipulation mistakes in Genomics](https://qz.com/768334/years-of-genomics-research-is-riddled-with-errors-thanks-to-a-bunch-of-botched-excel-spreadsheets/) + - [Computers broke + science](http://theconversation.com/how-computers-broke-science-and-what-we-can-do-to-fix-it-49938) + - [Programming and data manipulation mistakes in + Genomics](https://qz.com/768334/years-of-genomics-research-is-riddled-with-errors-thanks-to-a-bunch-of-botched-excel-spreadsheets/) -Going Public? -------------- +## Going Public? -- Someone may [benefit from my hard work](http://www.nature.com/news/the-top-100-papers-1.16224) + - Someone may [benefit from my hard + work](http://www.nature.com/news/the-top-100-papers-1.16224) -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 Requirements for producing a **pdf**: -- Internally, *pandoc*, *knitr* or *emacs/org-mode* -- *LaTeX* should be installed + - Internally, *pandoc*, *knitr* or *emacs/org-mode* - - - - is a must-have - - - - + - *LaTeX* should be installed + + - + - is a + must-have + - + - -M2-S6: Comparative Study -======================== +# M2-S6: Comparative Study -[Exemples of Org-Mode documents](../ressources/orgmode_examples/README.org) ---------------------------------------------------------------------------- +## [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 9f969f94529028967aeba922777c9647018e9bd2..670deb108d5bf72cc4bc23cb827f15bf93e1a8ec 100644 --- a/module2/slides/ressources_fr.md +++ b/module2/slides/ressources_fr.md @@ -1,96 +1,117 @@ --- -TITLE: Le document computationnel -Date: Wed Mar 20 13:19:19 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 ----------------------------------------------------------------- +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 TOC + + - [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é + - 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 -- -- + - + - is a + must-have + - + - -M2-S6: Analyse comparée des différents outils -============================================= +# M2-S6: Analyse comparée des différents outils -[Exemples de document Org-Mode](../ressources/orgmode_examples/README_fr.org) ------------------------------------------------------------------------------ +## [Exemples de document Org-Mode](../ressources/orgmode_examples/README_fr.org) diff --git a/module4/ressources/resources_environment.md b/module4/ressources/resources_environment.md index d2458d3bc133234c707e0996847783bcbab06b8d..8373b151c4e7ca5f62fca16a3e334ece80947ba0 100644 --- a/module4/ressources/resources_environment.md +++ b/module4/ressources/resources_environment.md @@ -1,27 +1,38 @@ --- -TITLE: Tracking environment information -Date: Tue Feb 19 19:19:03 2019 +title: Tracking environment information +date: Tue Feb 19 19:19:03 2019 --- -Table of Contents -============================================================== - -- [Getting information about your Git repository](#getting-information-about-your-git-repository) -- [Getting information about Python(3) libraries](#getting-information-about-python3-libraries) - - [Getting information about your system](#getting-information-about-your-system) - - [Getting the list of installed packages and their version](#getting-the-list-of-installed-packages-and-their-version) - - [How to list imported modules?](#how-to-list-imported-modules) - - [Saving and restoring an environment with pip](#saving-and-restoring-an-environment-with-pip) - - [Installing a new package or a specific version](#installing-a-new-package-or-a-specific-version) -- [Getting information about R libraries](#getting-information-about-r-libraries) - - [Getting the list imported modules and their version](#getting-the-list-imported-modules-and-their-version) - - [Getting the list of installed packages and their version](#getting-the-list-of-installed-packages-and-their-version-1) - - [Installing a new package or a specific version](#installing-a-new-package-or-a-specific-version-1) - -Getting information about your Git repository -============================================= - -When taking notes, it may be difficult to remember which version of the code or of a file was used. This is what version control is useful for. Here are a few useful commands that we typically insert at the top of our notebooks in shell cells +# Table of Contents TOC + + - [Getting information about your Git + repository](#getting-information-about-your-git-repository) + - [Getting information about Python(3) + libraries](#getting-information-about-python3-libraries) + - [Getting information about your + system](#getting-information-about-your-system) + - [Getting the list of installed packages and their + version](#getting-the-list-of-installed-packages-and-their-version) + - [How to list imported modules?](#how-to-list-imported-modules) + - [Saving and restoring an environment with + pip](#saving-and-restoring-an-environment-with-pip) + - [Installing a new package or a specific + version](#installing-a-new-package-or-a-specific-version) + - [Getting information about R + libraries](#getting-information-about-r-libraries) + - [Getting the list imported modules and their + version](#getting-the-list-imported-modules-and-their-version) + - [Getting the list of installed packages and their + version](#getting-the-list-of-installed-packages-and-their-version-1) + - [Installing a new package or a specific + version](#installing-a-new-package-or-a-specific-version-1) + +# Getting information about your Git repository + +When taking notes, it may be difficult to remember which version of the +code or of a file was used. This is what version control is useful for. +Here are a few useful commands that we typically insert at the top of +our notebooks in shell cells ``` shell git log -1 @@ -65,9 +76,12 @@ Untracked files: no changes added to commit (use "git add" and/or "git commit -a") ``` -*Note: the -u indicates that git should also display the contents of new directories it did not previously know about.* +*Note: the -u indicates that git should also display the contents of new +directories it did not previously know about.* -Then, we often include commands at the end of our notebook indicating how to commit the results (adding the new files, committing with a clear message and pushing). E.g., +Then, we often include commands at the end of our notebook indicating +how to commit the results (adding the new files, committing with a clear +message and pushing). E.g., ``` shell git add resources.org; @@ -87,15 +101,17 @@ To gitlab.inria.fr:learninglab/mooc-rr/mooc-rr-ressources.git 6359f8c..1f8a567 master -> master ``` -Obviously, in this case you need to save the notebook before running this cell, hence the output of this final command (with the new git hash) will not be stored in the cell. This is not really a problem and is the price to pay for running git from within the notebook itself. +Obviously, in this case you need to save the notebook before running +this cell, hence the output of this final command (with the new git +hash) will not be stored in the cell. This is not really a problem and +is the price to pay for running git from within the notebook itself. -Getting information about Python(3) libraries -============================================= +# Getting information about Python(3) libraries -Getting information about your system -------------------------------------- +## Getting information about your system -This topic is discussed on [StackOverflow](https://stackoverflow.com/questions/3103178/how-to-get-the-system-info-with-python). +This topic is discussed on +[StackOverflow](https://stackoverflow.com/questions/3103178/how-to-get-the-system-info-with-python). ``` python import platform @@ -106,10 +122,14 @@ print(platform.uname()) uname_result(system='Linux', node='icarus', release='4.15.0-2-amd64', version='#1 SMP Debian 4.15.11-1 (2018-03-20)', machine='x86_64', processor='') ``` -Getting the list of installed packages and their version --------------------------------------------------------- +## Getting the list of installed packages and their version -This topic is discussed on [StackOverflow](https://stackoverflow.com/questions/20180543/how-to-check-version-of-python-modules). When using `pip` (the Python package installer) within a shell command, it is easy to query the version of all installed packages (note that on your system, you may have to use either `pip` or `pip3` depending on how it is named and which versions of Python are available on your machine +This topic is discussed on +[StackOverflow](https://stackoverflow.com/questions/20180543/how-to-check-version-of-python-modules). +When using `pip` (the Python package installer) within a shell command, +it is easy to query the version of all installed packages (note that on +your system, you may have to use either `pip` or `pip3` depending on how +it is named and which versions of Python are available on your machine Here is for example how I get this information on my machine: @@ -137,7 +157,10 @@ wcwidth==0.1.7 webencodings==0.5 ``` -In a Jupyter notebook, this can easily be done by using the `%%sh` magic. Here is for example what you could do and get on the Jupyter notebooks we deployed for the MOOC (note that here, you should simply use the `pip` command): +In a Jupyter notebook, this can easily be done by using the `%%sh` +magic. Here is for example what you could do and get on the Jupyter +notebooks we deployed for the MOOC (note that here, you should simply +use the `pip` command): ``` python %%sh @@ -162,9 +185,13 @@ xlrd==1.1.0 zope.interface==4.5.0 ``` -In the rest of this document, I will assume the correct command is `pip` and I will not systematically insert the `%%sh` magic. +In the rest of this document, I will assume the correct command is `pip` +and I will not systematically insert the `%%sh` magic. -Once you know which packages are installed, you can easily get additional information about a given package and in particular check whether it was installed "locally" through pip or whether it is installed system-wide. Again, in a shell command: +Once you know which packages are installed, you can easily get +additional information about a given package and in particular check +whether it was installed "locally" through pip or whether it is +installed system-wide. Again, in a shell command: ``` shell pip show pandas @@ -194,10 +221,15 @@ Location: /home/alegrand/.local/lib/python3.6/site-packages Requires: patsy, pandas ``` -How to list imported modules? ------------------------------ +## How to list imported modules? -Without resorting to pip (that will list all available packages), you may want to know which modules are loaded in a Python session as well as their version. Inspired by [StackOverflow](https://stackoverflow.com/questions/4858100/how-to-list-imported-modules), here is a simple function that lists loaded package (that have a `__version__` attribute, which is unfortunately not completely standard). +Without resorting to pip (that will list all available packages), you +may want to know which modules are loaded in a Python session as well as +their version. Inspired by +[StackOverflow](https://stackoverflow.com/questions/4858100/how-to-list-imported-modules), +here is a simple function that lists loaded package (that have a +`__version__` attribute, which is unfortunately not completely +standard). ``` python def print_imported_modules(): @@ -249,24 +281,30 @@ urllib.request 3.6 zlib 1.0 ``` -Saving and restoring an environment with pip --------------------------------------------- +## Saving and restoring an environment with pip -The easiest way to go is as follows: +The easiest way to go is as +follows: ``` shell pip3 freeze > requirements.txt # to obtain the list of packages with their version pip3 install -r requirements.txt # to install the previous list of packages, possibly on an other machine ``` -If you want to have several installed Python environments, you may want to use [Pipenv](https://docs.pipenv.org/). I doubt it allows to track correctly FORTRAN or C dynamic libraries that are wrapped by Python though. +If you want to have several installed Python environments, you may want +to use [Pipenv](https://docs.pipenv.org/). I doubt it allows to track +correctly FORTRAN or C dynamic libraries that are wrapped by Python +though. -Installing a new package or a specific version ----------------------------------------------- +## Installing a new package or a specific version -The Jupyter environment we deployed on our servers for the MOOC is based on the version 4.5.4 of Miniconda and Python 3.6. In this environment you should simply use the `pip` command (remember on your machine, you may have to use `pip3`). +The Jupyter environment we deployed on our servers for the MOOC is based +on the version 4.5.4 of Miniconda and Python 3.6. In this environment +you should simply use the `pip` command (remember on your machine, you +may have to use `pip3`). -If I query the current version of `statsmodels` in a shell command, here is what I will get. +If I query the current version of `statsmodels` in a shell command, here +is what I will get. ``` shell pip show statsmodels @@ -308,19 +346,20 @@ Location: /opt/conda/lib/python3.6/site-packages Requires: scipy, patsy, pandas ``` -It is even possible to install a specific (possibly much older) version, e.g.,: +It is even possible to install a specific (possibly much older) version, +e.g.,: ``` shell pip install statsmodels==0.6.1 ``` -Getting information about R libraries -===================================== +# Getting information about R libraries -Getting the list imported modules and their version ---------------------------------------------------- +## Getting the list imported modules and their version -The best way seems to be to rely on the `devtools` package (if this package is not installed, you should install it first by running in `R` the command `install.packages("devtools")`). +The best way seems to be to rely on the `devtools` package (if this +package is not installed, you should install it first by running in `R` +the command `install.packages("devtools")`). ``` r sessionInfo() @@ -375,39 +414,55 @@ Packages ---------------------------------------------------------------------- withr 2.1.2 2018-03-15 CRAN (R 3.5.0) ``` -Some actually advocate that [writing a reproducible research compendium is best done by writing an R package](https://github.com/ropensci/rrrpkg). Those of you willing to have a clean R dependency management should thus have a look at [Packrat](https://rstudio.github.io/packrat/). +Some actually advocate that [writing a reproducible research compendium +is best done by writing an R +package](https://github.com/ropensci/rrrpkg). Those of you willing to +have a clean R dependency management should thus have a look at +[Packrat](https://rstudio.github.io/packrat/). -Getting the list of installed packages and their version --------------------------------------------------------- +## Getting the list of installed packages and their version -Finally, it is good to know that there is a built-in R command (`installed.packages`) allowing to retrieve and list the details of all packages installed. +Finally, it is good to know that there is a built-in R command +(`installed.packages`) allowing to retrieve and list the details of all +packages installed. ``` r head(installed.packages()) ``` -| Package | LibPath | Version | Priority | Depends | Imports | LinkingTo | Suggests | Enhances | License | LicenseisFOSS | Licenserestrictsuse | OStype | MD5sum | NeedsCompilation | Built | | -|----------------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------|-------------|----------------------------------------------------------------|----------------------------------------------------------------|-----------|---------------|---------------------------------------|--------------------------------------|--------------------------|--------------------------------|-------------------|--------|------------------|-------|-------| -| BH | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.66.0-1 | nil | nil | nil | nil | nil | nil | BSL-1.0 | nil | nil | nil | nil | no | 3.5.1 | | -| Formula | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.2-3 | nil | R (>= 2.0.0), stats | nil | nil | nil | nil | GPL-2 | GPL-3 | nil | nil | nil | nil | no | 3.5.1 | -| Hmisc | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 4.1-1 | nil | lattice, survival (>= 2.40-1), Formula, ggplot2 (>= 2.2) | methods, latticeExtra, cluster, rpart, nnet, acepack, foreign, | | | | | | | | | | | | -| gtable, grid, gridExtra, data.table, htmlTable (>= 1.11.0), | | | | | | | | | | | | | | | | | -| viridis, htmltools, base64enc | nil | chron, rms, mice, tables, knitr, ff, ffbase, plotly (>= | | | | | | | | | | | | | | | -| 4.5.6) | nil | GPL (>= 2) | nil | nil | nil | nil | yes | 3.5.1 | | | | | | | | | -| Matrix | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.2-14 | recommended | R (>= 3.2.0) | methods, graphics, grid, stats, utils, lattice | nil | expm, MASS | MatrixModels, graph, SparseM, sfsmisc | GPL (>= 2) | file LICENCE | nil | nil | nil | nil | yes | 3.5.1 | -| StanHeaders | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 2.17.2 | nil | nil | nil | nil | RcppEigen, BH | nil | BSD3clause + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | | -| acepack | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.4.1 | nil | nil | nil | nil | testthat | nil | MIT + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | | +| Package | LibPath | Version | Priority | Depends | Imports | LinkingTo | Suggests | Enhances | License | LicenseisFOSS | Licenserestrictsuse | OStype | MD5sum | NeedsCompilation | Built | | +| ------------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- | ----------- | ---------------------------------------------------------- | -------------------------------------------------------------- | --------- | ------------- | ------------------------------------- | ------------------------------------ | ------------------------ | ------------------------------ | ----------------- | ------ | ---------------- | ----- | ----- | +| BH | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.66.0-1 | nil | nil | nil | nil | nil | nil | BSL-1.0 | nil | nil | nil | nil | no | 3.5.1 | | +| Formula | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.2-3 | nil | R (\>= 2.0.0), stats | nil | nil | nil | nil | GPL-2 | GPL-3 | nil | nil | nil | nil | no | 3.5.1 | +| Hmisc | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 4.1-1 | nil | lattice, survival (\>= 2.40-1), Formula, ggplot2 (\>= 2.2) | methods, latticeExtra, cluster, rpart, nnet, acepack, foreign, | | | | | | | | | | | | +| gtable, grid, gridExtra, data.table, htmlTable (\>= 1.11.0), | | | | | | | | | | | | | | | | | +| viridis, htmltools, base64enc | nil | chron, rms, mice, tables, knitr, ff, ffbase, plotly (\>= | | | | | | | | | | | | | | | +| 4.5.6) | nil | GPL (\>= 2) | nil | nil | nil | nil | yes | 3.5.1 | | | | | | | | | +| Matrix | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.2-14 | recommended | R (\>= 3.2.0) | methods, graphics, grid, stats, utils, lattice | nil | expm, MASS | MatrixModels, graph, SparseM, sfsmisc | GPL (\>= 2) | file LICENCE | nil | nil | nil | nil | yes | 3.5.1 | +| StanHeaders | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 2.17.2 | nil | nil | nil | nil | RcppEigen, BH | nil | BSD3clause + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | | +| acepack | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.4.1 | nil | nil | nil | nil | testthat | nil | MIT + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | | -Installing a new package or a specific version ----------------------------------------------- +## Installing a new package or a specific version -This section is mostly a cut and paste from the [recent post by Ian Pylvainen](https://support.rstudio.com/hc/en-us/articles/219949047-Installing-older-versions-of-packages) on this topic. It comprises a very clear explanation of how to proceed. +This section is mostly a cut and paste from the [recent post by Ian +Pylvainen](https://support.rstudio.com/hc/en-us/articles/219949047-Installing-older-versions-of-packages) +on this topic. It comprises a very clear explanation of how to proceed. ### Installing a pre-compiled version -If you're on a Debian or a Ubuntu system, it may be difficult to access a specific version without breaking your system. So unless you are moving to the latest version available in your Linux distribution, **we strongly recommend you to build from source**. In this case, you'll need to make sure you have the necessary toolchain to build packages from source (e.g., gcc, FORTRAN, etc.). On Windows, this may require you to install [Rtools](https://cran.r-project.org/bin/windows/Rtools/). +If you're on a Debian or a Ubuntu system, it may be difficult to access +a specific version without breaking your system. So unless you are +moving to the latest version available in your Linux distribution, **we +strongly recommend you to build from source**. In this case, you'll need +to make sure you have the necessary toolchain to build packages from +source (e.g., gcc, FORTRAN, etc.). On Windows, this may require you to +install [Rtools](https://cran.r-project.org/bin/windows/Rtools/). -If you're on Windows or OS X and looking for a package for an **older version of R** (R 2.1 or below), you can check the [CRAN binary archive](https://cran-archive.r-project.org/bin/). Once you have the URL, you can install it using a command similar to the example below: +If you're on Windows or OS X and looking for a package for an **older +version of R** (R 2.1 or below), you can check the [CRAN binary +archive](https://cran-archive.r-project.org/bin/). Once you have the +URL, you can install it using a command similar to the example +below: ``` r packageurl <- "https://cran-archive.r-project.org/bin/windows/contrib/2.13/BBmisc_1.0-58.zip" @@ -416,7 +471,10 @@ install.packages(packageurl, repos=NULL, type="binary") ### Using devtools -The simplest method to install the version you need is to use the `install_version()` function of the `devtools` package (obviously, you need to install `devtools` first, which can be done by running in `R` the command `install.packages("devtools")`). For instance: +The simplest method to install the version you need is to use the +`install_version()` function of the `devtools` package (obviously, you +need to install `devtools` first, which can be done by running in `R` +the command `install.packages("devtools")`). For instance: ``` r require(devtools) @@ -425,16 +483,24 @@ install_version("ggplot2", version = "0.9.1", repos = "http://cran.us.r-project. ### Installing from source code -Alternatively, you may want to install an older package from source If devtools fails or if you do not want to depend on it, you can install it from source via `install.packages()` directed using the right URL. This URL can be obtained by browsing the [CRAN Package Archive](https://cran.r-project.org/src/contrib/Archive). +Alternatively, you may want to install an older package from source If +devtools fails or if you do not want to depend on it, you can install it +from source via `install.packages()` directed using the right URL. This +URL can be obtained by browsing the [CRAN Package +Archive](https://cran.r-project.org/src/contrib/Archive). -Once you have the URL, you can install it using a command similar to the example below: +Once you have the URL, you can install it using a command similar to the +example +below: ``` r packageurl <- "http://cran.r-project.org/src/contrib/Archive/ggplot2/ggplot2_0.9.1.tar.gz" install.packages(packageurl, repos=NULL, type="source") ``` -If you know the URL, you can also install from source via the command line outside of R. For instance (in bash): +If you know the URL, you can also install from source via the command +line outside of R. For instance (in +bash): ``` shell wget http://cran.r-project.org/src/contrib/Archive/ggplot2/ggplot2_0.9.1.tar.gz @@ -443,7 +509,12 @@ R CMD INSTALL ggplot2_0.9.1.tar.gz ### Potential issues -There are a few potential issues that may arise with installing older versions of packages: +There are a few potential issues that may arise with installing older +versions of packages: -- You may be losing functionality or bug fixes that are only present in the newer versions of the packages. -- The older package version needed may not be compatible with the version of R you have installed. In this case, you will either need to downgrade R to a compatible version or update your R code to work with a newer version of the package. + - You may be losing functionality or bug fixes that are only present + in the newer versions of the packages. + - The older package version needed may not be compatible with the + version of R you have installed. In this case, you will either need + to downgrade R to a compatible version or update your R code to work + with a newer version of the package. diff --git a/module4/ressources/resources_environment_fr.md b/module4/ressources/resources_environment_fr.md index 4b367ba0b950d417ee9384646a8cef9b43aa1621..24a9877d32f229f658a3b587ace5bfdae1324b3e 100644 --- a/module4/ressources/resources_environment_fr.md +++ b/module4/ressources/resources_environment_fr.md @@ -1,27 +1,41 @@ --- -TITLE: Informations sur l'environnement -Date: Tue Feb 19 19:19:03 2019 +title: Informations sur l'environnement +date: Tue Feb 19 19:19:03 2019 --- -Table des matières -=============================================================== - -- [Obtenir des informations sur votre dépôt Git](#obtenir-des-informations-sur-votre-dépôt-git) -- [Obtenir des informations sur les librairies Python 3](#obtenir-des-informations-sur-les-librairies-python-3) - - [Obtenir des informations sur votre système](#obtenir-des-informations-sur-votre-système) - - [Lister les packages installés et leur version](#lister-les-packages-installés-et-leur-version) - - [Lister les packages importés (chargés dans une session Python) et leur version](#lister-les-packages-importés-chargés-dans-une-session-python-et-leur-version) - - [Sauvegarder et restaurer un environnement avec pip](#sauvegarder-et-restaurer-un-environnement-avec-pip) - - [Installer un nouveau package ou une version spécifique](#installer-un-nouveau-package-ou-une-version-spécifique) -- [Obtenir des informations sur les packages R](#obtenir-des-informations-sur-les-packages-r) - - [Lister les packages installés et leur version](#lister-les-packages-installés-et-leur-version-1) - - [Lister les packages importés (chargés dans une session R) et leur version](#lister-les-packages-importés-chargés-dans-une-session-r-et-leur-version) - - [Installer un nouveau package ou une version spécifique](#installer-un-nouveau-package-ou-une-version-spécifique-1) - -Obtenir des informations sur votre dépôt Git -============================================ - -Lorsqu'on prend des notes, il peut être difficile de se rappeler quelle version de code ou de fichier a été utilisée. C'est l'intérêt du contrôle de versions. Voici quelques commandes utiles que nous insérons généralement au début de nos notebooks dans des cellules shell : +# Table des matières TOC + + - [Obtenir des informations sur votre dépôt + Git](#obtenir-des-informations-sur-votre-dépôt-git) + - [Obtenir des informations sur les librairies Python + 3](#obtenir-des-informations-sur-les-librairies-python-3) + - [Obtenir des informations sur votre + système](#obtenir-des-informations-sur-votre-système) + - [Lister les packages installés et leur + version](#lister-les-packages-installés-et-leur-version) + - [Lister les packages importés (chargés dans une session Python) + et leur + version](#lister-les-packages-importés-chargés-dans-une-session-python-et-leur-version) + - [Sauvegarder et restaurer un environnement avec + pip](#sauvegarder-et-restaurer-un-environnement-avec-pip) + - [Installer un nouveau package ou une version + spécifique](#installer-un-nouveau-package-ou-une-version-spécifique) + - [Obtenir des informations sur les packages + R](#obtenir-des-informations-sur-les-packages-r) + - [Lister les packages installés et leur + version](#lister-les-packages-installés-et-leur-version-1) + - [Lister les packages importés (chargés dans une session R) et + leur + version](#lister-les-packages-importés-chargés-dans-une-session-r-et-leur-version) + - [Installer un nouveau package ou une version + spécifique](#installer-un-nouveau-package-ou-une-version-spécifique-1) + +# Obtenir des informations sur votre dépôt Git + +Lorsqu'on prend des notes, il peut être difficile de se rappeler quelle +version de code ou de fichier a été utilisée. C'est l'intérêt du +contrôle de versions. Voici quelques commandes utiles que nous insérons +généralement au début de nos notebooks dans des cellules shell : ``` shell git log -1 @@ -65,9 +79,12 @@ Untracked files: no changes added to commit (use "git add" and/or "git commit -a") ``` -*Note : L'option -u indique que Git doit aussi afficher le contenu des répertoires nouvellement créés.* +*Note : L'option -u indique que Git doit aussi afficher le contenu des +répertoires nouvellement créés.* -Nous ajoutons aussi souvent des commandes à la fin des notebooks pour indiquer comment commiter les résultats (ajout des nouveaux fichiers, commit avec un message clair et commande push). Par exemple : +Nous ajoutons aussi souvent des commandes à la fin des notebooks pour +indiquer comment commiter les résultats (ajout des nouveaux fichiers, +commit avec un message clair et commande push). Par exemple : ``` shell git add resources.org; @@ -87,15 +104,18 @@ To gitlab.inria.fr:learninglab/mooc-rr/mooc-rr-ressources.git 6359f8c..1f8a567 master -> master ``` -Évidemment, dans ce cas il faut enregistrer le notebook avant d'exécuter cette cellule, donc le résultat de cette dernière commande (avec le nouveau Git hash) ne sera pas stocké dans la cellule. Ce n'est pas vraiment un problème et c'est le prix à payer pour exécuter Git à partir du notebook lui-même. +Évidemment, dans ce cas il faut enregistrer le notebook avant d'exécuter +cette cellule, donc le résultat de cette dernière commande (avec le +nouveau Git hash) ne sera pas stocké dans la cellule. Ce n'est pas +vraiment un problème et c'est le prix à payer pour exécuter Git à partir +du notebook lui-même. -Obtenir des informations sur les librairies Python 3 -==================================================== +# Obtenir des informations sur les librairies Python 3 -Obtenir des informations sur votre système ------------------------------------------- +## Obtenir des informations sur votre système -Cette question est discutée sur [StackOverflow](https://stackoverflow.com/questions/3103178/how-to-get-the-system-info-with-python). +Cette question est discutée sur +[StackOverflow](https://stackoverflow.com/questions/3103178/how-to-get-the-system-info-with-python). ``` python import platform @@ -106,10 +126,14 @@ print(platform.uname()) uname_result(system='Linux', node='icarus', release='4.15.0-2-amd64', version='#1 SMP Debian 4.15.11-1 (2018-03-20)', machine='x86_64', processor='') ``` -Lister les packages installés et leur version ---------------------------------------------- +## Lister les packages installés et leur version -Cette question est discutée sur [StackOverflow](https://stackoverflow.com/questions/20180543/how-to-check-version-of-python-modules). Il est facile d'obtenir la version de tous les packages installés en exécutant `pip` (l'installateur de packages Python) dans une commande shell (la commande peut être `pip` or `pip3` selon la configuration de votre ordinateur). +Cette question est discutée sur +[StackOverflow](https://stackoverflow.com/questions/20180543/how-to-check-version-of-python-modules). +Il est facile d'obtenir la version de tous les packages installés en +exécutant `pip` (l'installateur de packages Python) dans une commande +shell (la commande peut être `pip` or `pip3` selon la configuration de +votre ordinateur). Voici par exemple comment j'obtiens ces informations sur ma machine : @@ -137,7 +161,10 @@ wcwidth==0.1.7 webencodings==0.5 ``` -Dans un notebook Jupyter, cela peut facilement être fait en utilisant la commande magique `%%sh`. Voici par exemple ce que vous pouvez faire et obtenir avec les notebooks Jupyter que nous avons déployés pour le MOOC (notez qu’ici vous devez simplement utiliser la commande `pip`) : +Dans un notebook Jupyter, cela peut facilement être fait en utilisant la +commande magique `%%sh`. Voici par exemple ce que vous pouvez faire et +obtenir avec les notebooks Jupyter que nous avons déployés pour le MOOC +(notez qu’ici vous devez simplement utiliser la commande `pip`) : ``` python %%sh @@ -162,9 +189,14 @@ xlrd==1.1.0 zope.interface==4.5.0 ``` -Dans la suite de ce document, je supposerai que la commande correcte est `pip` et je ne vais pas systématiquement insérer la commande magique `%%sh`. +Dans la suite de ce document, je supposerai que la commande correcte est +`pip` et je ne vais pas systématiquement insérer la commande magique +`%%sh`. -Une fois que vous savez quels packages sont installés, vous pouvez facilement obtenir des informations supplémentaires sur un package donné et notamment vérifier s'il a été installé "localement" via pip ou s'il est installé à l'échelle du système. À nouveau dans une commande shell : +Une fois que vous savez quels packages sont installés, vous pouvez +facilement obtenir des informations supplémentaires sur un package donné +et notamment vérifier s'il a été installé "localement" via pip ou s'il +est installé à l'échelle du système. À nouveau dans une commande shell : ``` shell pip show pandas @@ -194,10 +226,15 @@ Location: /home/alegrand/.local/lib/python3.6/site-packages Requires: patsy, pandas ``` -Lister les packages importés (chargés dans une session Python) et leur version ------------------------------------------------------------------------------- +## Lister les packages importés (chargés dans une session Python) et leur version -Vous pouvez vouloir savoir quels packages sont chargés dans une session Python ainsi que leur version sans recourir à pip (qui listera tous les packages disponibles). Inspiré par [StackOverflow](https://stackoverflow.com/questions/4858100/how-to-list-imported-modules), voici une fonction simple qui liste les packages chargés (ayant un attribut `__version__`, qui n’est malheureusement pas tout à fait standard). +Vous pouvez vouloir savoir quels packages sont chargés dans une session +Python ainsi que leur version sans recourir à pip (qui listera tous les +packages disponibles). Inspiré par +[StackOverflow](https://stackoverflow.com/questions/4858100/how-to-list-imported-modules), +voici une fonction simple qui liste les packages chargés (ayant un +attribut `__version__`, qui n’est malheureusement pas tout à fait +standard). ``` python def print_imported_modules(): @@ -249,24 +286,31 @@ urllib.request 3.6 zlib 1.0 ``` -Sauvegarder et restaurer un environnement avec pip --------------------------------------------------- +## Sauvegarder et restaurer un environnement avec pip -La façon la plus simple de faire est la suivante : +La façon la plus simple de faire est la +suivante : ``` shell pip3 freeze > requirements.txt # to obtain the list of packages with their version pip3 install -r requirements.txt # to install the previous list of packages, possibly on an other machine ``` -Si vous voulez avoir plusieurs environnements Python sur votre ordinateur, vous pouvez vouloir utiliser [Pipenv](https://docs.pipenv.org/) (mais je doute que cela permette de tracer correctement les bibliothèques dynamiques FORTRAN ou C encapsulées dans Python). +Si vous voulez avoir plusieurs environnements Python sur votre +ordinateur, vous pouvez vouloir utiliser +[Pipenv](https://docs.pipenv.org/) (mais je doute que cela permette de +tracer correctement les bibliothèques dynamiques FORTRAN ou C +encapsulées dans Python). -Installer un nouveau package ou une version spécifique ------------------------------------------------------- +## Installer un nouveau package ou une version spécifique -L’environnement Jupyter que nous avons déployé sur nos serveurs pour le MOOC est basé sur Miniconda 4.5.4 et Python 3.6. Dans cet environnement, vous devez simplement utiliser la commande `pip` (vous devrez peut-être utiliser `pip3` sur votre ordinateur). +L’environnement Jupyter que nous avons déployé sur nos serveurs pour le +MOOC est basé sur Miniconda 4.5.4 et Python 3.6. Dans cet environnement, +vous devez simplement utiliser la commande `pip` (vous devrez peut-être +utiliser `pip3` sur votre ordinateur). -Voici ce que j'obtiens si j'interroge la version actuelle de `statsmodels` dans une commande shell. +Voici ce que j'obtiens si j'interroge la version actuelle de +`statsmodels` dans une commande shell. ``` shell pip show statsmodels @@ -308,40 +352,41 @@ Location: /opt/conda/lib/python3.6/site-packages Requires: scipy, patsy, pandas ``` -Il est même possible d’installer une version spécifique (peut-être beaucoup plus ancienne), par exemple : +Il est même possible d’installer une version spécifique (peut-être +beaucoup plus ancienne), par exemple : ``` shell pip install statsmodels==0.6.1 ``` -Obtenir des informations sur les packages R -=========================================== +# Obtenir des informations sur les packages R -Lister les packages installés et leur version ---------------------------------------------- +## Lister les packages installés et leur version -Il existe une commande R intégrée (`installed.packages`) permettant de récupérer et de lister les détails de tous packages installés. +Il existe une commande R intégrée (`installed.packages`) permettant de +récupérer et de lister les détails de tous packages installés. ``` r head(installed.packages()) ``` -| Package | LibPath | Version | Priority | Depends | Imports | LinkingTo | Suggests | Enhances | License | LicenseisFOSS | Licenserestrictsuse | OStype | MD5sum | NeedsCompilation | Built | | -|----------------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------|-------------|----------------------------------------------------------------|----------------------------------------------------------------|-----------|---------------|---------------------------------------|--------------------------------------|--------------------------|--------------------------------|-------------------|--------|------------------|-------|-------| -| BH | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.66.0-1 | nil | nil | nil | nil | nil | nil | BSL-1.0 | nil | nil | nil | nil | no | 3.5.1 | | -| Formula | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.2-3 | nil | R (>= 2.0.0), stats | nil | nil | nil | nil | GPL-2 | GPL-3 | nil | nil | nil | nil | no | 3.5.1 | -| Hmisc | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 4.1-1 | nil | lattice, survival (>= 2.40-1), Formula, ggplot2 (>= 2.2) | methods, latticeExtra, cluster, rpart, nnet, acepack, foreign, | | | | | | | | | | | | -| gtable, grid, gridExtra, data.table, htmlTable (>= 1.11.0), | | | | | | | | | | | | | | | | | -| viridis, htmltools, base64enc | nil | chron, rms, mice, tables, knitr, ff, ffbase, plotly (>= | | | | | | | | | | | | | | | -| 4.5.6) | nil | GPL (>= 2) | nil | nil | nil | nil | yes | 3.5.1 | | | | | | | | | -| Matrix | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.2-14 | recommended | R (>= 3.2.0) | methods, graphics, grid, stats, utils, lattice | nil | expm, MASS | MatrixModels, graph, SparseM, sfsmisc | GPL (>= 2) | file LICENCE | nil | nil | nil | nil | yes | 3.5.1 | -| StanHeaders | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 2.17.2 | nil | nil | nil | nil | RcppEigen, BH | nil | BSD3clause + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | | -| acepack | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.4.1 | nil | nil | nil | nil | testthat | nil | MIT + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | | +| Package | LibPath | Version | Priority | Depends | Imports | LinkingTo | Suggests | Enhances | License | LicenseisFOSS | Licenserestrictsuse | OStype | MD5sum | NeedsCompilation | Built | | +| ------------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- | ----------- | ---------------------------------------------------------- | -------------------------------------------------------------- | --------- | ------------- | ------------------------------------- | ------------------------------------ | ------------------------ | ------------------------------ | ----------------- | ------ | ---------------- | ----- | ----- | +| BH | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.66.0-1 | nil | nil | nil | nil | nil | nil | BSL-1.0 | nil | nil | nil | nil | no | 3.5.1 | | +| Formula | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.2-3 | nil | R (\>= 2.0.0), stats | nil | nil | nil | nil | GPL-2 | GPL-3 | nil | nil | nil | nil | no | 3.5.1 | +| Hmisc | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 4.1-1 | nil | lattice, survival (\>= 2.40-1), Formula, ggplot2 (\>= 2.2) | methods, latticeExtra, cluster, rpart, nnet, acepack, foreign, | | | | | | | | | | | | +| gtable, grid, gridExtra, data.table, htmlTable (\>= 1.11.0), | | | | | | | | | | | | | | | | | +| viridis, htmltools, base64enc | nil | chron, rms, mice, tables, knitr, ff, ffbase, plotly (\>= | | | | | | | | | | | | | | | +| 4.5.6) | nil | GPL (\>= 2) | nil | nil | nil | nil | yes | 3.5.1 | | | | | | | | | +| Matrix | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.2-14 | recommended | R (\>= 3.2.0) | methods, graphics, grid, stats, utils, lattice | nil | expm, MASS | MatrixModels, graph, SparseM, sfsmisc | GPL (\>= 2) | file LICENCE | nil | nil | nil | nil | yes | 3.5.1 | +| StanHeaders | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 2.17.2 | nil | nil | nil | nil | RcppEigen, BH | nil | BSD3clause + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | | +| acepack | /home/alegrand/R/x8664-pc-linux-gnu-library/3.5 | 1.4.1 | nil | nil | nil | nil | testthat | nil | MIT + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | | -Lister les packages importés (chargés dans une session R) et leur version -------------------------------------------------------------------------- +## Lister les packages importés (chargés dans une session R) et leur version -Le meilleur moyen semble être d'utiliser le package `devtools`. Si le package n'est pas installé, vous devez d'abord l'installer en exécutant la commande `install.packages("devtools",dep=TRUE)` dans `R`). +Le meilleur moyen semble être d'utiliser le package `devtools`. Si le +package n'est pas installé, vous devez d'abord l'installer en exécutant +la commande `install.packages("devtools",dep=TRUE)` dans `R`). ``` r sessionInfo() @@ -396,20 +441,39 @@ Packages ---------------------------------------------------------------------- withr 2.1.2 2018-03-15 CRAN (R 3.5.0) ``` -Certains suggèrent même [l'écriture d'un package R pour faciliter la recherche reproductible](https://github.com/ropensci/rrrpkg). +Certains suggèrent même [l'écriture d'un package R pour faciliter la +recherche reproductible](https://github.com/ropensci/rrrpkg). -Ceux d'entre vous qui souhaitent disposer d'une gestion des dépendances "propre" en R peuvent aussi jeter un coup d'œil à [Packrat](https://rstudio.github.io/packrat/). +Ceux d'entre vous qui souhaitent disposer d'une gestion des dépendances +"propre" en R peuvent aussi jeter un coup d'œil à +[Packrat](https://rstudio.github.io/packrat/). -Installer un nouveau package ou une version spécifique ------------------------------------------------------- +## Installer un nouveau package ou une version spécifique -Cette section est principalement un copier-coller du [récent post de Ian Pylvainen](https://support.rstudio.com/hc/en-us/articles/219949047-Installing-older-versions-of-packages) sur ce sujet. Il comprend une explication très claire de la façon de procéder. +Cette section est principalement un copier-coller du [récent post de Ian +Pylvainen](https://support.rstudio.com/hc/en-us/articles/219949047-Installing-older-versions-of-packages) +sur ce sujet. Il comprend une explication très claire de la façon de +procéder. ### Installer une version pré-compilée -Si vous êtes sur un système Debian ou Ubuntu, il peut être difficile d’accéder à une version spécifique sans casser votre système. Donc, sauf si vous passez à la dernière version disponible pour votre distribution Linux, **nous vous recommandons fortement d'installer les packages à l'aide des fichiers source**. Dans ce cas, vous devez vous assurer que vous disposez de l'ensemble des outils nécessaires pour créer des packages à partir des sources (par exemple : gcc, FORTRAN, etc.). Sous Windows, il se peut que vous deviez installer [Rtools](https://cran.r-project.org/bin/windows/Rtools/). - -Si vous utilisez Windows ou OS X et recherchez un package pour une **ancienne version de R** (version 2.1 ou inférieure), vous pouvez le rechercher sur l'[archive binaire du site CRAN](https://cran-archive.r-project.org/bin/). Une fois que vous avez l'URL, vous pouvez l'installer à l'aide d'une commande similaire à l'exemple ci-dessous : +Si vous êtes sur un système Debian ou Ubuntu, il peut être difficile +d’accéder à une version spécifique sans casser votre système. Donc, +sauf si vous passez à la dernière version disponible pour votre +distribution Linux, **nous vous recommandons fortement d'installer les +packages à l'aide des fichiers source**. Dans ce cas, vous devez vous +assurer que vous disposez de l'ensemble des outils nécessaires pour +créer des packages à partir des sources (par exemple : gcc, FORTRAN, +etc.). Sous Windows, il se peut que vous deviez installer +[Rtools](https://cran.r-project.org/bin/windows/Rtools/). + +Si vous utilisez Windows ou OS X et recherchez un package pour une +**ancienne version de R** (version 2.1 ou inférieure), vous pouvez le +rechercher sur l'[archive binaire du site +CRAN](https://cran-archive.r-project.org/bin/). Une fois que vous avez +l'URL, vous pouvez l'installer à l'aide d'une commande similaire à +l'exemple +ci-dessous : ``` r packageurl <- "https://cran-archive.r-project.org/bin/windows/contrib/2.13/BBmisc_1.0-58.zip" @@ -418,7 +482,11 @@ install.packages(packageurl, repos=NULL, type="binary") ### Utiliser devtools -La méthode la plus simple pour installer la version dont vous avez besoin consiste à utiliser la fonction `install_version()` du package `devtools` (vous devez évidemment avoir préalablement installé `devtools`, ce qui peut être fait en exécutant `R` la commande `install.packages("devtools",dep=TRUE)`). Par exemple: +La méthode la plus simple pour installer la version dont vous avez +besoin consiste à utiliser la fonction `install_version()` du package +`devtools` (vous devez évidemment avoir préalablement installé +`devtools`, ce qui peut être fait en exécutant `R` la commande +`install.packages("devtools",dep=TRUE)`). Par exemple: ``` r require(devtools) @@ -427,16 +495,25 @@ install_version("ggplot2", version = "0.9.1", repos = "http://cran.us.r-project. ### Installer à partir du code source -Vous pouvez également installer un ancien package à partir de son code source. Si vous ne réussissez pas avec devtools ou si vous ne voulez pas dépendre de ce package, vous pouvez l’installer à partir du source à l'aide de la commande `install.packages()` en utilisant la bonne URL. Cette URL peut être obtenue en naviguant dans [l'archive de packages du site CRAN](https://cran.r-project.org/src/contrib/Archive). +Vous pouvez également installer un ancien package à partir de son code +source. Si vous ne réussissez pas avec devtools ou si vous ne voulez pas +dépendre de ce package, vous pouvez l’installer à partir du source à +l'aide de la commande `install.packages()` en utilisant la bonne URL. +Cette URL peut être obtenue en naviguant dans [l'archive de packages du +site CRAN](https://cran.r-project.org/src/contrib/Archive). -Une fois que vous avez l'URL, vous pouvez l'installer à l'aide d'une commande similaire à l'exemple ci-dessous : +Une fois que vous avez l'URL, vous pouvez l'installer à l'aide d'une +commande similaire à l'exemple +ci-dessous : ``` r packageurl <- "http://cran.r-project.org/src/contrib/Archive/ggplot2/ggplot2_0.9.1.tar.gz" install.packages(packageurl, repos=NULL, type="source") ``` -Si vous connaissez l'URL, vous pouvez également installer à partir du source par ligne de commande en dehors de R. Par exemple (en bash) : +Si vous connaissez l'URL, vous pouvez également installer à partir du +source par ligne de commande en dehors de R. Par exemple (en +bash) : ``` shell wget http://cran.r-project.org/src/contrib/Archive/ggplot2/ggplot2_0.9.1.tar.gz @@ -445,7 +522,14 @@ R CMD INSTALL ggplot2_0.9.1.tar.gz ### Problèmes potentiels -Quelques problèmes sont susceptibles de survenir lors de l'installation d'anciennes versions de packages : - -- Vous pouvez perdre des fonctionnalités ou des corrections de bugs qui ne sont présentes que dans les versions les plus récentes des packages. -- L'ancienne version de package requise peut ne pas être compatible avec la version de R que vous avez installée. Dans ce cas, vous devrez soit rétrograder R vers une version compatible, soit mettre à jour votre code R pour qu'il fonctionne avec une version plus récente du package. +Quelques problèmes sont susceptibles de survenir lors de l'installation +d'anciennes versions de packages : + + - Vous pouvez perdre des fonctionnalités ou des corrections de bugs + qui ne sont présentes que dans les versions les plus récentes des + packages. + - L'ancienne version de package requise peut ne pas être compatible + avec la version de R que vous avez installée. Dans ce cas, vous + devrez soit rétrograder R vers une version compatible, soit mettre à + jour votre code R pour qu'il fonctionne avec une version plus + récente du package. diff --git a/module4/ressources/resources_refs.md b/module4/ressources/resources_refs.md index 9ec7b5315433b73f15cc7ad01fb66251404282c6..5a96c0c81da298f82867c28fcef09ac4ba96f766 100644 --- a/module4/ressources/resources_refs.md +++ b/module4/ressources/resources_refs.md @@ -1,87 +1,199 @@ --- -TITLE: Additional references -Date: Tue Feb 19 19:19:03 2019 +title: Additional references +date: Tue Feb 19 19:19:03 2019 --- -Table of Contents -============================================================== - -- ["Thoughts" on language/software stability](#thoughts-on-languagesoftware-stability) -- [Controlling your software environment](#controlling-your-software-environment) -- [Preservation/Archiving](#preservationarchiving) -- [Workflows](#workflows) -- [Numerical and statistical issues](#numerical-and-statistical-issues) -- [Publication practices](#publication-practices) -- [Experimentation](#experimentation) - -"Thoughts" on language/software stability -========================================= - -As we explained, the programming language used in an analysis has a clear influence on the reproducibility of your analysis. It is not a characteristic of the language itself but rather a consequence of the development philosophy of the underlying community. For example C is a very stable language with a [very clear specification designed by a committee](https://en.wikipedia.org/wiki/C_(programming_language)#ANSI_C_and_ISO_C) (even though some compilers may not respect this norm). - -On the other end of the spectrum, [Python](https://en.wikipedia.org/wiki/Python_(programming_language)) had a much more organic development based on a readability philosophy and valuing continuous improvement over backwards-compatibility. Furthermore, Python is commonly used as a wrapping language (e.g., to easily use C or FORTRAN libraries) and has its own packaging system. All these design choices tend to make reproducibility often a bit painful with Python, even though the community is slowly taking this into account. The transition from Python 2 to the not fully backwards compatible Python 3 has been a particularly painful process, not least because the two languages are so similar that is it not always easy to figure out if a given script or module is written in Python 2 or Python 3. It isn't even rare to see Python scripts that work under both Python 2 and Python 3, but produce different results due to the change in the behavior of integer division. - -[R](https://en.wikipedia.org/wiki/R_(programming_language)), in comparison is much closer (in terms of developer community) to languages like [SAS](https://en.wikipedia.org/wiki/SAS_(software)), which is heavily used in the pharmaceutical industry where statistical procedures need to be standardized and rock solid/stable. R is obviously not immune to evolutions that break old versions and hinder reproducibility/backward compatibility. Here is a relatively recent [true story about this](http://members.cbio.mines-paristech.fr/~thocking/HOCKING-reproducible-research-with-R.html) and some colleagues who worked on the [statistics introductory course with R on FUN](https://www.fun-mooc.fr/courses/UPSUD/42001S06/session06/about) reported us several issues with a few functions (`plotmeans` from `gplots`, `survfit` from `survival`, or `hclust`) whose default parameters had changed over the years. It is thus probably good practice to give explicit values for all parameters (which can be cumbersome) instead of relying on default values, and to restrict your dependencies as much as possible. - -This being said, the R development community is generally quite careful about stability. We (the authors of this MOOC) believe that open source (which allows to inspect how computation is done and to identify both mistakes and sources of non-reproducibility) is more important than the rock solid stability of SAS, which is proprietary software. - -Yet, if you really need to stay with SAS, you should know that SAS can be used within Jupyter using the [Python SASPy](https://sassoftware.github.io/saspy/) and the [Python SASKernel](https://sassoftware.github.io/sas_kernel/) packages (step by step explanations about this are given [here](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)). Using such literate programming approach allied with systematic version and environment control will always help. Similar solutions exist for many languages ([list of Jupyter kernels](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels)). - -Controlling your software environment -===================================== - -As we mentioned in the video sequences, there are several solutions to control your environment: - -- The easy (preserve the mess) ones: [CDE](http://www.pgbovine.net/cde.html) or [ReproZip](https://vida-nyu.github.io/reprozip/) -- The more demanding (encourage cleanliness) where you start with a clean environment and install only what's strictly necessary (and document it): - - The very well known [Docker](https://www.docker.io/) - - [Singularity](https://singularity.lbl.gov/) or [Spack](https://spack.io/), which are more targeted toward the specific needs of high performance computing users - - [Guix](https://www.gnu.org/software/guix/), [Nix](https://nixos.org/) that are very clean (perfect?) solutions to this dependency hell and which we recommend - -It may be hard to understand the difference between these different approaches and decide which one is better in your context. - -Here is a webinar where some of these tools are demoed in a reproducible research context: [Controling your environment (by Michael Mercier and Cristian Ruiz)](https://github.com/alegrand/RR_webinars/blob/master/2_controling_your_environment/index.org) - -You may also want to have a look at [the Popper conventions](http://falsifiable.us/) ([webinar by Ivo Gimenez through google hangout](https://github.com/alegrand/RR_webinars/blob/master/11_popper/index.org)) or at the [presentation of Konrad Hinsen on Active Papers](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org) (). - -Preservation/Archiving -====================== - -Ensuring software is properly archived, i.e, is safely stored so that it can be accessed in a perennial way, can be quite tricky. If you have never seen [Roberto Di Cosmo presenting the Software Heritage project](https://github.com/alegrand/RR_webinars/blob/master/5_archiving_software_and_data/index.org), this is a must see. [](https://www.softwareheritage.org/) - -For regular data, we highly recommend using [](https://www.zenodo.org/) whenever the data is not sensitive. - -Workflows -========= - -In the video sequences, we mentioned workflow managers (original application domain in parenthesis): - -- [Galaxy](https://galaxyproject.org/) (genomics), [Kepler](https://kepler-project.org/) (ecology), [Taverna](https://taverna.apache.org/) (bio-informatics), [Pegasus](https://pegasus.isi.edu/) (astronomy), [Collective Knowledge](http://cknowledge.org/) (compiling optimization), [VisTrails](https://www.vistrails.org) (image processing) -- Light-weight: [dask](http://dask.pydata.org/) (python), [drake](https://ropensci.github.io/drake/) (R), [swift](http://swift-lang.org/) (molecular biology), [snakemake](https://snakemake.readthedocs.io/) (like `make` but more expressive and in `python`)... -- Hybrids: [SOS-notebook](https://vatlab.github.io/sos-docs/)... - -You may want to have a look at this webinar: \[\[\]\[Reproducible Science in Bio-informatics: Current Status, Solutions and Research Opportunities (by Sarah Cohen Boulakia, Yvan Le Bras and Jérôme Chopard).\]\] - -Numerical and statistical issues -================================ - -We have mentioned these topics in our MOOC but we could by no way cover them properly. We only suggest here a few interesting talks about this. - -- \[\[\]\[In this talk, Pierre Dragicevic provides a nice illustration of the consequences of statistical uncertainty and of how some concepts (e.G. p-values) are commonly badly understood.\]\] -- \[\[\]\[Nathalie Revol, Philippe Langlois and Stef Graillat present the main challenges encountered when trying to achieve numerical reproducibility and present recent research work on this topic.\]\] - -Publication practices -===================== +# Table of Contents TOC + + - ["Thoughts" on language/software + stability](#thoughts-on-languagesoftware-stability) + - [Controlling your software + environment](#controlling-your-software-environment) + - [Preservation/Archiving](#preservationarchiving) + - [Workflows](#workflows) + - [Numerical and statistical + issues](#numerical-and-statistical-issues) + - [Publication practices](#publication-practices) + - [Experimentation](#experimentation) + +# "Thoughts" on language/software stability + +As we explained, the programming language used in an analysis has a +clear influence on the reproducibility of your analysis. It is not a +characteristic of the language itself but rather a consequence of the +development philosophy of the underlying community. For example C is a +very stable language with a [very clear specification designed by a +committee](https://en.wikipedia.org/wiki/C_\(programming_language\)#ANSI_C_and_ISO_C) +(even though some compilers may not respect this norm). + +On the other end of the spectrum, +[Python](https://en.wikipedia.org/wiki/Python_\(programming_language\)) +had a much more organic development based on a readability philosophy +and valuing continuous improvement over backwards-compatibility. +Furthermore, Python is commonly used as a wrapping language (e.g., to +easily use C or FORTRAN libraries) and has its own packaging system. All +these design choices tend to make reproducibility often a bit painful +with Python, even though the community is slowly taking this into +account. The transition from Python 2 to the not fully backwards +compatible Python 3 has been a particularly painful process, not least +because the two languages are so similar that is it not always easy to +figure out if a given script or module is written in Python 2 or Python +3. It isn't even rare to see Python scripts that work under both Python +2 and Python 3, but produce different results due to the change in the +behavior of integer division. + +[R](https://en.wikipedia.org/wiki/R_\(programming_language\)), in +comparison is much closer (in terms of developer community) to languages +like [SAS](https://en.wikipedia.org/wiki/SAS_\(software\)), which is +heavily used in the pharmaceutical industry where statistical procedures +need to be standardized and rock solid/stable. R is obviously not immune +to evolutions that break old versions and hinder +reproducibility/backward compatibility. Here is a relatively recent +[true story about +this](http://members.cbio.mines-paristech.fr/~thocking/HOCKING-reproducible-research-with-R.html) +and some colleagues who worked on the [statistics introductory course +with R on +FUN](https://www.fun-mooc.fr/courses/UPSUD/42001S06/session06/about) +reported us several issues with a few functions (`plotmeans` from +`gplots`, `survfit` from `survival`, or `hclust`) whose default +parameters had changed over the years. It is thus probably good practice +to give explicit values for all parameters (which can be cumbersome) +instead of relying on default values, and to restrict your dependencies +as much as possible. + +This being said, the R development community is generally quite careful +about stability. We (the authors of this MOOC) believe that open source +(which allows to inspect how computation is done and to identify both +mistakes and sources of non-reproducibility) is more important than the +rock solid stability of SAS, which is proprietary software. + +Yet, if you really need to stay with SAS, you should know that SAS can +be used within Jupyter using the [Python +SASPy](https://sassoftware.github.io/saspy/) and the [Python +SASKernel](https://sassoftware.github.io/sas_kernel/) packages (step by +step explanations about this are given +[here](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)). +Using such literate programming approach allied with systematic version +and environment control will always help. Similar solutions exist for +many languages ([list of Jupyter +kernels](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels)). + +# Controlling your software environment + +As we mentioned in the video sequences, there are several solutions to +control your environment: + + - The easy (preserve the mess) ones: + [CDE](http://www.pgbovine.net/cde.html) or + [ReproZip](https://vida-nyu.github.io/reprozip/) + - The more demanding (encourage cleanliness) where you start with a + clean environment and install only what's strictly necessary (and + document it): + - The very well known [Docker](https://www.docker.io/) + - [Singularity](https://singularity.lbl.gov/) or + [Spack](https://spack.io/), which are more targeted toward the + specific needs of high performance computing users + - [Guix](https://www.gnu.org/software/guix/), + [Nix](https://nixos.org/) that are very clean (perfect?) + solutions to this dependency hell and which we recommend + +It may be hard to understand the difference between these different +approaches and decide which one is better in your context. + +Here is a webinar where some of these tools are demoed in a reproducible +research context: [Controling your environment (by Michael Mercier and +Cristian +Ruiz)](https://github.com/alegrand/RR_webinars/blob/master/2_controling_your_environment/index.org) + +You may also want to have a look at [the Popper +conventions](http://falsifiable.us/) ([webinar by Ivo Gimenez through +google +hangout](https://github.com/alegrand/RR_webinars/blob/master/11_popper/index.org)) +or at the [presentation of Konrad Hinsen on Active +Papers](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org) +(). + +# Preservation/Archiving + +Ensuring software is properly archived, i.e, is safely stored so that it +can be accessed in a perennial way, can be quite tricky. If you have +never seen [Roberto Di Cosmo presenting the Software Heritage +project](https://github.com/alegrand/RR_webinars/blob/master/5_archiving_software_and_data/index.org), +this is a must see. + +For regular data, we highly recommend using +whenever the data is not sensitive. + +# Workflows + +In the video sequences, we mentioned workflow managers (original +application domain in parenthesis): + + - [Galaxy](https://galaxyproject.org/) (genomics), + [Kepler](https://kepler-project.org/) (ecology), + [Taverna](https://taverna.apache.org/) (bio-informatics), + [Pegasus](https://pegasus.isi.edu/) (astronomy), [Collective + Knowledge](http://cknowledge.org/) (compiling optimization), + [VisTrails](https://www.vistrails.org) (image processing) + - Light-weight: [dask](http://dask.pydata.org/) (python), + [drake](https://ropensci.github.io/drake/) (R), + [swift](http://swift-lang.org/) (molecular biology), + [snakemake](https://snakemake.readthedocs.io/) (like `make` but more + expressive and in `python`)… + - Hybrids: [SOS-notebook](https://vatlab.github.io/sos-docs/)… + +You may want to have a look at this webinar: +\[\[\]\[Reproducible +Science in Bio-informatics: Current Status, Solutions and Research +Opportunities (by Sarah Cohen Boulakia, Yvan Le Bras and Jérôme +Chopard).\]\] + +# Numerical and statistical issues + +We have mentioned these topics in our MOOC but we could by no way cover +them properly. We only suggest here a few interesting talks about + this. + + - \[\[\]\[In + this talk, Pierre Dragicevic provides a nice illustration of the + consequences of statistical uncertainty and of how some concepts + (e.G. p-values) are commonly badly + understood.\]\] + - \[\[\]\[Nathalie + Revol, Philippe Langlois and Stef Graillat present the main + challenges encountered when trying to achieve numerical + reproducibility and present recent research work on this topic.\]\] + +# Publication practices You may want to have a look at the following two webinars: -- [Enabling open and reproducible research at computer systems’ conferences (by Grigori Fursin)](https://github.com/alegrand/RR_webinars/blob/master/8_artifact_evaluation/index.org). In particular, this talk discusses *artifact evaluation* that is becoming more and more popular. -- [Publication Modes Favoring Reproducible Research (by Konrad Hinsen and Nicolas Rougier)](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org). In this talk, the motivation for the [ReScience journal](http://rescience.github.io/) initiative are presented. -- [Simine Vazire - When Should We be Skeptical of Scientific Claims?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), which is discussing publication practices in social sciences and in particular HARKing (Hypothesizing After the Results are Known), p-hacking, etc. - -Experimentation -=============== - -Experimentation was not covered in this MOOC, although it is an essential part of science. The main reason is that practices and constraints can vary so wildly from one domain to another that it could not be properly covered in a first edition. We would be happy to gather references you consider as interesting in your domain so do not hesitate to provide us with such references by using the forum and we will update this page. - -- [A recent talk by Lucas Nussbaum on Experimental Testbeds in Computer Science](https://github.com/alegrand/RR_webinars/blob/master/9_experimental_testbeds/index.org). + - [Enabling open and reproducible research at computer systems’ + conferences (by Grigori + Fursin)](https://github.com/alegrand/RR_webinars/blob/master/8_artifact_evaluation/index.org). + In particular, this talk discusses *artifact evaluation* that is + becoming more and more popular. + - [Publication Modes Favoring Reproducible Research (by Konrad Hinsen + and Nicolas + Rougier)](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org). + In this talk, the motivation for the [ReScience + journal](http://rescience.github.io/) initiative are presented. + - [Simine Vazire - When Should We be Skeptical of Scientific + Claims?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), which is + discussing publication practices in social sciences and in + particular HARKing (Hypothesizing After the Results are Known), + p-hacking, etc. + +# Experimentation + +Experimentation was not covered in this MOOC, although it is an +essential part of science. The main reason is that practices and +constraints can vary so wildly from one domain to another that it could +not be properly covered in a first edition. We would be happy to gather +references you consider as interesting in your domain so do not hesitate +to provide us with such references by using the forum and we will update +this page. + + - [A recent talk by Lucas Nussbaum on Experimental Testbeds in + Computer + Science](https://github.com/alegrand/RR_webinars/blob/master/9_experimental_testbeds/index.org). diff --git a/module4/ressources/resources_refs_fr.md b/module4/ressources/resources_refs_fr.md index 3aeabe39365a84f8c8256f4d03ead6946937f59f..9ff6606c21418297ddf64d804ebcd7a8b75bb6f9 100644 --- a/module4/ressources/resources_refs_fr.md +++ b/module4/ressources/resources_refs_fr.md @@ -1,87 +1,208 @@ --- -TITLE: Références complémentaires -Date: Tue Feb 19 19:19:03 2019 +title: Références complémentaires +date: Tue Feb 19 19:19:03 2019 --- -Table des matières -=============================================================== - -- [Réflexions sur la stabilité des langages de programmation](#réflexions-sur-la-stabilité-des-langages-de-programmation) -- [Contrôler votre environnement logiciel](#contrôler-votre-environnement-logiciel) -- [Préservation/Archivage](#préservationarchivage) -- [Workflows](#workflows) -- [Problèmes numériques et statistiques](#problèmes-numériques-et-statistiques) -- [Pratiques de publication](#pratiques-de-publication) -- [Expérimentation](#expérimentation) - -Réflexions sur la stabilité des langages de programmation -========================================================= - -Comme nous l'avons expliqué, le langage de programmation utilisé dans une analyse a une influence évidente sur la reproductibilité de l'analyse. Ce n'est pas une caractéristique du langage lui-même mais plutôt une conséquence de la philosophie de développement de la communauté sous-jacente. Par exemple, C est un langage très stable avec une [spécification très claire conçue par un comité](https://en.wikipedia.org/wiki/C_(programming_language)#ANSI_C_and_ISO_C) (même si certains compilateurs ne respectent cette norme). - -À l’autre bout du spectre, [Python](https://en.wikipedia.org/wiki/Python_(programming_language)) a connu un développement beaucoup plus organique basé sur une philosophie de lisibilité et valorisant l'amélioration continue par rapport à la compatibilité ascendante. De plus, Python est couramment utilisé comme langage de wrapping (par exemple pour utiliser facilement les bibliothèques C ou FORTRAN) et dispose de son propre système de packaging. Tous ces choix de conception ont souvent tendance à rendre la reproductibilité un peu pénible avec Python, même si la communauté en tient lentement compte. La transition de Python 2 à Python 3, qui n'est pas totalement compatible avec les versions antérieures, a été un processus particulièrement pénible, notamment parce que les deux langages sont si similaires qu'il n'est pas toujours facile de savoir si un script ou un module donné est écrit en Python 2 ou Python 3. Il n'est même pas rare de voir des scripts Python qui fonctionnent sous Python 2 et Python 3, mais produisent des résultats différents en raison du changement de comportement de la division entière. - -[R](https://en.wikipedia.org/wiki/R_(programming_language)), en comparaison, est beaucoup plus proche (en termes de communauté de développeurs) de langages comme [SAS](https://en.wikipedia.org/wiki/SAS_(logiciel)), très utilisé dans l'industrie pharmaceutique où les procédures statistiques doivent être standardisées et stables/solides. R n’est évidemment pas à l’abri des évolutions qui cassent les anciennes versions et gênent la reproductibilité/compatibilité avec les versions antérieures. Voici une [véritable histoire relativement récente à ce sujet](http://members.cbio.mines-paristech.fr//thocking/HOCKING-reproducible-research-with-R.html) et des collègues qui ont travaillé sur le [MOOC d'initiation à la statistique avec R sur FUN](https://www.fun-mooc.fr/courses/course-v1:UPSUD+42001+session10/about) nous ont signalé plusieurs problèmes concernant quelques fonctions (`gplots::plotmeans`, `survival::survfit` ou `hclust`) dont les paramètres par défaut ont changé au fil des ans. Il est donc probablement utile de donner des valeurs explicites pour tous les paramètres (ce qui peut être fastidieux) au lieu de s’appuyer sur des valeurs par défaut et de restreindre autant que possible vos dépendances. - -Ceci étant dit, la communauté de développement R est généralement très prudente en matière de stabilité. Nous (les auteurs de ce MOOC) pensons que l'open source (qui permet de contrôler le calcul et d'identifier les erreurs et les sources de non-reproductibilité) est plus important que la stabilité à toute épreuve de SAS, qui est un logiciel propriétaire. - -Cependant, si vous avez vraiment besoin de rester sous SAS, sachez que SAS peut être utilisé dans Jupyter en utilisant les packages Python [SASPy](https://sassoftware.github.io/saspy/) et [SASKernel](https://sassoftware.github.io/sas_kernel/) (tuto pas à pas [ici](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)). L'utilisation d'une telle approche de programmation alphabète alliée à un contrôle systématique de la version et de l'environnement est un plus. Des solutions similaires existent pour de nombreux langages ([liste des kernels Jupyter](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels)). - -Contrôler votre environnement logiciel -====================================== - -Comme nous l'avons mentionné dans les séquences vidéo, plusieurs solutions permettent de contrôler votre environnement : - -- Les faciles (autorisant le désordre) : [CDE](http://www.pgbovine.net/cde.html) ou [ReproZip](https://vida-nyu.github.io/reprozip/) -- Les plus exigeants (encourageant la propreté) où vous commencez avec un environnement propre et n’installez que ce qui est strictement nécessaire (et le documentez) : - - Le très connu [Docker](https://www.docker.io/) - - [Singularity](https://singularity.lbl.gov/) ou [Spack](https://spack.io/), qui sont plus ciblés sur les besoins spécifiques des utilisateurs d'informatique de haute performance - - [Guix](https://www.gnu.org/software/guix/), [Nix](https://nixos.org/) qui sont des solutions très propres (parfaites ?) à cet enfer de dépendance et que nous recommandons - -Il peut être difficile de comprendre la différence entre ces différentes approches et de décider laquelle est la meilleure dans votre contexte. - -Voici un webinaire où certains de ces outils sont présentés dans un contexte de recherche reproductible : [Controling your environment (by Michael Mercier and Cristian Ruiz)](https://github.com/alegrand/RR_webinars/blob/master/2_controling_your_environment/index.org). - -Vous voudrez peut-être aussi jeter un coup d’œil sur la convention [Popper](http://falsifiable.us/) ([webinaire par Ivo Gimenez par Google hangout](https://github.com/alegrand/RR_webinars/blob/master/11_popper/index.org)) ou sur la [présentation de Konrad Hinsen](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org) sur [Active Papers](http://www.activepapers.org/). - -Préservation/Archivage -====================== - -S'assurer que le logiciel est correctement archivé, c'est-à-dire qu'il est stocké de manière sécurisée afin de pouvoir y accéder de manière pérenne, peut être assez délicat. Si vous n'avez jamais vu la [présentation du projet Software Heritage par Roberto Di Cosmo](https://github.com/alegrand/RR_webinars/blob/master/5_archiving_software_and_data/index.org), c'est à voir absolument. [](https://www.softwareheritage.org/) - -Pour les données, nous vous recommandons vivement d’utiliser [](https://www.zenodo.org/) lorsque les données ne sont pas sensibles. - -Workflows -========= - -Dans les séquences vidéo, nous avons mentionné les gestionnaires de flux de travaux (domaine d'application d'origine entre parenthèses) : - -- workflows assez complexes : [Galaxy](https://galaxyproject.org/) (génomique), [Kepler](https://kepler-project.org/) (écologie), [Taverna](https://taverna.apache.org/) (bioinformatique), [Pegasus](https://pegasus.isi.edu/) (astronomie), [Collective Knowledge](http://cknowledge.org/) (optimisation de la compilation), [VisTrails](https://www.vistrails.org) (traitement d'image) -- workflows plus légers : [dask](http://dask.pydata.org/) (Python), [drake](https://ropensci.github.io/drake/) (R), [swift](http://swift-lang.org/) (biologie moléculaire), [snakemake](https://snakemake.readthedocs.io/) (comme `make` mais plus expressif et en `Python`)... -- hybride à mi-chemin entre le notebook et le workflow : [SOS-notebook](https://vatlab.github.io/sos-docs/) - -Vous voudrez peut-être consulter ce webinaire : \[\[\]\[Science Reproducible en Bioinformatique : état actuel, solutions et opportunités de recherche (par Sarah Cohen Boulakia, Yvan Le Bras and Jérôme Chopard)\]\]. - -Problèmes numériques et statistiques -==================================== - -Nous avons mentionné ces sujets dans notre MOOC mais nous ne pourrions en aucun cas les couvrir correctement. Nous ne suggérons ici que quelques présentations intéressantes à ce sujet. - -- \[\[\]\[Pierre Dragicevic donne une belle illustration des conséquences de l’incertitude statistique et de la manière dont certains concepts (par exemple les p-values) sont généralement mal compris\]\]. -- \[\[\]\[Nathalie Revol, Philippe Langlois et Stef Graillat présentent les principaux problèmes rencontrés en essayant d'obtenir une reproductibilité numérique et présentent les travaux de recherche récents en la matière\]\]. - -Pratiques de publication -======================== +# Table des matières TOC + + - [Réflexions sur la stabilité des langages de + programmation](#réflexions-sur-la-stabilité-des-langages-de-programmation) + - [Contrôler votre environnement + logiciel](#contrôler-votre-environnement-logiciel) + - [Préservation/Archivage](#préservationarchivage) + - [Workflows](#workflows) + - [Problèmes numériques et + statistiques](#problèmes-numériques-et-statistiques) + - [Pratiques de publication](#pratiques-de-publication) + - [Expérimentation](#expérimentation) + +# Réflexions sur la stabilité des langages de programmation + +Comme nous l'avons expliqué, le langage de programmation utilisé dans +une analyse a une influence évidente sur la reproductibilité de +l'analyse. Ce n'est pas une caractéristique du langage lui-même mais +plutôt une conséquence de la philosophie de développement de la +communauté sous-jacente. Par exemple, C est un langage très stable avec +une [spécification très claire conçue par un +comité](https://en.wikipedia.org/wiki/C_\(programming_language\)#ANSI_C_and_ISO_C) +(même si certains compilateurs ne respectent cette norme). + +À l’autre bout du spectre, +[Python](https://en.wikipedia.org/wiki/Python_\(programming_language\)) +a connu un développement beaucoup plus organique basé sur une +philosophie de lisibilité et valorisant l'amélioration continue par +rapport à la compatibilité ascendante. De plus, Python est couramment +utilisé comme langage de wrapping (par exemple pour utiliser facilement +les bibliothèques C ou FORTRAN) et dispose de son propre système de +packaging. Tous ces choix de conception ont souvent tendance à rendre la +reproductibilité un peu pénible avec Python, même si la communauté en +tient lentement compte. La transition de Python 2 à Python 3, qui n'est +pas totalement compatible avec les versions antérieures, a été un +processus particulièrement pénible, notamment parce que les deux +langages sont si similaires qu'il n'est pas toujours facile de savoir si +un script ou un module donné est écrit en Python 2 ou Python 3. Il n'est +même pas rare de voir des scripts Python qui fonctionnent sous Python 2 +et Python 3, mais produisent des résultats différents en raison du +changement de comportement de la division entière. + +[R](https://en.wikipedia.org/wiki/R_\(programming_language\)), en +comparaison, est beaucoup plus proche (en termes de communauté de +développeurs) de langages comme +[SAS](https://en.wikipedia.org/wiki/SAS_\(logiciel\)), très utilisé dans +l'industrie pharmaceutique où les procédures statistiques doivent être +standardisées et stables/solides. R n’est évidemment pas à l’abri des +évolutions qui cassent les anciennes versions et gênent la +reproductibilité/compatibilité avec les versions antérieures. Voici une +[véritable histoire relativement récente à ce +sujet](http://members.cbio.mines-paristech.fr//thocking/HOCKING-reproducible-research-with-R.html) +et des collègues qui ont travaillé sur le [MOOC d'initiation à la +statistique avec R sur +FUN](https://www.fun-mooc.fr/courses/course-v1:UPSUD+42001+session10/about) +nous ont signalé plusieurs problèmes concernant quelques fonctions +(`gplots::plotmeans`, `survival::survfit` ou `hclust`) dont les +paramètres par défaut ont changé au fil des ans. Il est donc +probablement utile de donner des valeurs explicites pour tous les +paramètres (ce qui peut être fastidieux) au lieu de s’appuyer sur des +valeurs par défaut et de restreindre autant que possible vos +dépendances. + +Ceci étant dit, la communauté de développement R est généralement très +prudente en matière de stabilité. Nous (les auteurs de ce MOOC) pensons +que l'open source (qui permet de contrôler le calcul et d'identifier les +erreurs et les sources de non-reproductibilité) est plus important que +la stabilité à toute épreuve de SAS, qui est un logiciel propriétaire. + +Cependant, si vous avez vraiment besoin de rester sous SAS, sachez que +SAS peut être utilisé dans Jupyter en utilisant les packages Python +[SASPy](https://sassoftware.github.io/saspy/) et +[SASKernel](https://sassoftware.github.io/sas_kernel/) (tuto pas à pas +[ici](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)). +L'utilisation d'une telle approche de programmation alphabète alliée à +un contrôle systématique de la version et de l'environnement est un +plus. Des solutions similaires existent pour de nombreux langages +([liste des kernels +Jupyter](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels)). + +# Contrôler votre environnement logiciel + +Comme nous l'avons mentionné dans les séquences vidéo, plusieurs +solutions permettent de contrôler votre environnement : + + - Les faciles (autorisant le désordre) : + [CDE](http://www.pgbovine.net/cde.html) ou + [ReproZip](https://vida-nyu.github.io/reprozip/) + - Les plus exigeants (encourageant la propreté) où vous commencez avec + un environnement propre et n’installez que ce qui est strictement + nécessaire (et le documentez) : + - Le très connu [Docker](https://www.docker.io/) + - [Singularity](https://singularity.lbl.gov/) ou + [Spack](https://spack.io/), qui sont plus ciblés sur les besoins + spécifiques des utilisateurs d'informatique de haute performance + - [Guix](https://www.gnu.org/software/guix/), + [Nix](https://nixos.org/) qui sont des solutions très propres + (parfaites ?) à cet enfer de dépendance et que nous recommandons + +Il peut être difficile de comprendre la différence entre ces différentes +approches et de décider laquelle est la meilleure dans votre contexte. + +Voici un webinaire où certains de ces outils sont présentés dans un +contexte de recherche reproductible : [Controling your environment (by +Michael Mercier and Cristian +Ruiz)](https://github.com/alegrand/RR_webinars/blob/master/2_controling_your_environment/index.org). + +Vous voudrez peut-être aussi jeter un coup d’œil sur la convention +[Popper](http://falsifiable.us/) ([webinaire par Ivo Gimenez par Google +hangout](https://github.com/alegrand/RR_webinars/blob/master/11_popper/index.org)) +ou sur la [présentation de Konrad +Hinsen](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org) +sur [Active Papers](http://www.activepapers.org/). + +# Préservation/Archivage + +S'assurer que le logiciel est correctement archivé, c'est-à-dire qu'il +est stocké de manière sécurisée afin de pouvoir y accéder de manière +pérenne, peut être assez délicat. Si vous n'avez jamais vu la +[présentation du projet Software Heritage par Roberto Di +Cosmo](https://github.com/alegrand/RR_webinars/blob/master/5_archiving_software_and_data/index.org), +c'est à voir absolument. + +Pour les données, nous vous recommandons vivement d’utiliser + lorsque les données ne sont pas sensibles. + +# Workflows + +Dans les séquences vidéo, nous avons mentionné les gestionnaires de flux +de travaux (domaine d'application d'origine entre parenthèses) : + + - workflows assez complexes : [Galaxy](https://galaxyproject.org/) + (génomique), [Kepler](https://kepler-project.org/) (écologie), + [Taverna](https://taverna.apache.org/) (bioinformatique), + [Pegasus](https://pegasus.isi.edu/) (astronomie), [Collective + Knowledge](http://cknowledge.org/) (optimisation de la compilation), + [VisTrails](https://www.vistrails.org) (traitement d'image) + - workflows plus légers : [dask](http://dask.pydata.org/) (Python), + [drake](https://ropensci.github.io/drake/) (R), + [swift](http://swift-lang.org/) (biologie moléculaire), + [snakemake](https://snakemake.readthedocs.io/) (comme `make` mais + plus expressif et en `Python`)… + - hybride à mi-chemin entre le notebook et le workflow : + [SOS-notebook](https://vatlab.github.io/sos-docs/) + +Vous voudrez peut-être consulter ce webinaire : +\[\[\]\[Science +Reproducible en Bioinformatique : état actuel, solutions et opportunités +de recherche (par Sarah Cohen Boulakia, Yvan Le Bras and Jérôme +Chopard)\]\]. + +# Problèmes numériques et statistiques + +Nous avons mentionné ces sujets dans notre MOOC mais nous ne pourrions +en aucun cas les couvrir correctement. Nous ne suggérons ici que +quelques présentations intéressantes à ce + sujet. + + - \[\[\]\[Pierre + Dragicevic donne une belle illustration des conséquences de + l’incertitude statistique et de la manière dont certains concepts + (par exemple les p-values) sont généralement mal + compris\]\]. + - \[\[\]\[Nathalie + Revol, Philippe Langlois et Stef Graillat présentent les principaux + problèmes rencontrés en essayant d'obtenir une reproductibilité + numérique et présentent les travaux de recherche récents en la + matière\]\]. + +# Pratiques de publication Vous souhaiterez peut-être consulter les webinaires suivants : -- [Permettre une recherche ouverte et reproductible lors de conférences sur les systèmes informatiques (par Grigori Fursin)](https://github.com/alegrand/RR_webinars/blob/master/8_artifact_evaluation/index.org). En particulier, cette discussion aborde *l'évaluation des artefacts* qui devient de plus en plus populaire. -- [Modalités de publication favorisant la recherche reproductible (par Konrad Hinsen et Nicolas Rougier)](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org). Présentation des motivations de l'intiative [ReScience journal](http://rescience.github.io/). -- [Simine Vazire - Quand devrions-nous être sceptiques face aux affirmations scientifiques ?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), qui traite des pratiques de publication dans les sciences sociales et en particulier HARKing (Hypothèses après que les résultats sont connus), p-hacking, etc. - -Expérimentation -=============== - -L'expérimentation n'est pas couverte dans ce MOOC bien qu'il s'agisse d'un élément essentiel de la science. La raison principale est que les pratiques et les contraintes varient tellement d'un domaine à l'autre que ce thème ne pouvait pas être correctement couvert dans une première édition. Nous serions heureux de rassembler les références que vous jugez intéressantes dans votre domaine. N'hésitez donc pas à nous les fournir à l'aide du forum. Nous les intégrerons dans cette page. - -- [Une récente conférence de Lucas Nussbaum sur les bancs d’essais expérimentaux en informatique](https://github.com/alegrand/RR_webinars/blob/master/9_experimental_testbeds/index.org). + - [Permettre une recherche ouverte et reproductible lors de + conférences sur les systèmes informatiques (par Grigori + Fursin)](https://github.com/alegrand/RR_webinars/blob/master/8_artifact_evaluation/index.org). + En particulier, cette discussion aborde *l'évaluation des artefacts* + qui devient de plus en plus populaire. + - [Modalités de publication favorisant la recherche reproductible (par + Konrad Hinsen et Nicolas + Rougier)](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org). + Présentation des motivations de l'intiative [ReScience + journal](http://rescience.github.io/). + - [Simine Vazire - Quand devrions-nous être sceptiques face aux + affirmations + scientifiques ?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), qui + traite des pratiques de publication dans les sciences sociales et en + particulier HARKing (Hypothèses après que les résultats sont + connus), p-hacking, etc. + +# Expérimentation + +L'expérimentation n'est pas couverte dans ce MOOC bien qu'il s'agisse +d'un élément essentiel de la science. La raison principale est que les +pratiques et les contraintes varient tellement d'un domaine à l'autre +que ce thème ne pouvait pas être correctement couvert dans une première +édition. Nous serions heureux de rassembler les références que vous +jugez intéressantes dans votre domaine. N'hésitez donc pas à nous les +fournir à l'aide du forum. Nous les intégrerons dans cette page. + + - [Une récente conférence de Lucas Nussbaum sur les bancs d’essais + expérimentaux en + informatique](https://github.com/alegrand/RR_webinars/blob/master/9_experimental_testbeds/index.org).