# -*- mode: org -*-
#+TITLE:     Jupyter : Trucs et astuces, installation et configuration
#+AUTHOR:    Arnaud Legrand, Benoit Rospars, Konrad Hinsen
#+DATE: June, 2018
#+STARTUP: overview indent
#+OPTIONS: num:nil toc:t
#+PROPERTY: header-args :eval never-export

* Table des matières                                         :TOC:
- [[#jupyter-trucs-et-astuces][Jupyter: Trucs et astuces]]
  - [[#création-ou-import-dun-notebook][Création ou import d'un notebook]]
  - [[#exécuter-du-code-r-et-du-code-python-dans-le-même-notebook][Exécuter du code R et du code Python dans le même notebook]]
  - [[#autres-langages-que-python-et-r][Autres langages que Python et R]]
- [[#installation-et-configuration-de-jupyter-sur-votre-ordinateur][Installation et configuration de Jupyter sur votre ordinateur]]
  - [[#installation-de-jupyter][Installation de Jupyter]]
  - [[#sassurer-que-jupyter-vous-permet-dutiliser-r][S'assurer que Jupyter vous permet d'utiliser R]]
  - [[#conseils-additionnels][Conseils additionnels]]

* Jupyter: Trucs et astuces
Cette [[https://www.dataquest.io/blog/jupyter-notebook-tips-tricks-shortcuts/][page web]] (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).
** 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 [[https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb][autre notebook]] 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 [[https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb][Notebook
     hébergé sur un gitLab]], 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.
** 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.
   #+begin_src python :results output :exports both
   %load_ext rpy2.ipython
   #+end_src
2. Utilisez la (nouvellement activée) commande magique =%R=:
   #+begin_src python :results output :exports both
   %%R 
   summary(cars)
   #+end_src
   Les objets Python peuvent même être passé à R de la façon suivante
   (ici, on suppose que =df= est une dataframe pandas):
   #+begin_src python :results output :exports both
   %%R -i df
   plot(df)
   #+end_src
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.
** 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][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 [[https://sassoftware.github.io/sas_kernel/][Python SASKernel]], soit
avec la bibliothèque [[https://sassoftware.github.io/saspy/][Python SASPy]] (des explications détaillés sont
données [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md][ici]]).

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.
* 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, [[https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906][JupyterLab]], 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.

** 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 [[https://conda.io/miniconda.html][dernière version de Miniconda]]. 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 [[https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57][fichier d'environnement =mooc_rr= ]] et déployez
votre environnement à l'aide de conda:
#+begin_src shell :results output :exports both
conda env create -f environment.yml

# Windows activate the environment
activate mooc_rr

# Linux and MacOS activate the environment
source activate mooc_rr

# Linux, MacOS and Windows: launch the notebook
jupyter notebook
#+end_src
** 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
*** • Installation de [[https://github.com/IRkernel/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=:
  #+begin_src R :results output :session *R* :exports both
  install.packages('devtools',dep=TRUE)
  #+end_src
- Définissez un proxy si nécessaire (c'est important si votre
  ordinateur est connecté à une entreprise qui limite l'accès à
  Internet):
  #+begin_src R :results output :session *R* :exports both
  library(httr)
  set_config(use_proxy(url="proxy", port=80, username="username", password="password")) 
  #+end_src
- Installez la bibliothèque =IRkernel=:
  #+begin_src R :results output :session *R* :exports both
  devtools::install_github('IRkernel/IRkernel')
  IRkernel::installspec()  # to register the kernel in the current R installation
  #+end_src
*** • 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:
#+begin_src shell :results output :exports both
sudo apt-get install python3-rpy2 python3-tzlocal
#+end_src
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:
#+begin_src python :results output :exports both
pip3 install rpy2
#+end_src

*Windows*

Téléchargez le [[https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2][fichier binaire]] =rpy2= en choisissant le bon système
d'exploitation.

Ouvrez une console DOS et tapez les commandes suivantes:
#+begin_src shell :results output :exports both
python -m pip install rpy2‑2.9.4‑cp37‑cp37m‑win_amd64.whl # adapt filename
#+end_src

Installez également =tzlocal=:
#+begin_src shell :results output :exports both
python -m pip install tzlocal
#+end_src
** 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:
#+begin_src shell :results output :exports both
sudo apt-get install texlive-xetex wkhtmltopdf
#+end_src

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:
#+begin_src sh :results output :exports both
ipython3 nbconvert --to pdf Untitled.ipynb
#+end_src

Pour utiliser un style spécifique, il suffit de personnaliser
l'exporter =nbconvert=. Cette personnalisation est présentée [[http://markus-beuckelmann.de/blog/customizing-nbconvert-pdf.html][ici]] mais
nous vous encourageons à simplement lire la [[https://nbconvert.readthedocs.io/en/latest/][documentation de
nbconvert]].

Plutôt que de bidouiller trop =nbconvert=, il est aussi possible
d'exporter en Markdown et d'utiliser [[https://pandoc.org/][pandoc]] 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 [[https://miktex.org/download][site web de MiKTeX]] 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 [[https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook][plier/déplier votre code]]:
  #+begin_src shell :results output :exports both
  pip3 install jupyter_contrib_nbextensions
  # jupyter contrib nbextension install --user # not done yet
  #+end_src
- Il est aussi possible de [[https://github.com/kirbs-/hide_code][contrôler la visibilité des cellules]], ce
  qui peut être très utile si on exporte le notebook:
  #+begin_src sh :results output :exports both
  sudo pip3 install hide_code
  sudo jupyter-nbextension  install --py hide_code
  jupyter-nbextension  enable --py hide_code
  jupyter-serverextension enable --py hide_code
  #+end_src
  
*** • 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 [[https://github.com/Lab41/sunny-side-up][preuve de concept]] 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 [[https://github.com/sat28/githubcommit][Plugin Jupyter assez générique permettant de se
synchroniser avec Gitlab ou Github]]. 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 [[https://gist.github.com/pbugnion/ea2797393033b54674af][git hooks
spécifiques]] permettant d'ignorer ces numéros lorsque l'on committe des
notebooks Jupyter. Il y au une longue discussion à ce sujet sur
[[https://stackoverflow.com/questions/18734739/using-ipython-notebooks-under-version-control][StackOverflow]] qui détaille différentes options.

Enfin, pour ceux qui utilisent [[https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906][JupyterLab]] plutôt que le Jupyter de
base, un [[https://github.com/jupyterlab/jupyterlab-git][plugin git pour JupyterLab]] a été développé et offre des
fonctionnalités de suivi de version dignes d'un IDE classique.

