Jupyter : Trucs et astuces, installation et configuration

Les sources de ce document sont disponibles sur gitlab.
Version du 2020-08-25.

Jupyter : Trucs et astuces, installation et configuration

Quand vous aurez suivi les instructions suivantes, vous pourrez ouvrir des notebooks Jupyter en tapant une commande shell/DOS :

jupyter notebook

Table des matières

Jupyter : Trucs et astuces
Installation et configuration de Jupyter sur votre ordinateur

Jupyter : Trucs et astuces

Cette 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) 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é

À partir du menu : File -> Open. Ceci vous permet d'accéder au gestionnaire de fichiers de Jupyter.
Naviguez jusque dans le répertoire dans lequel vous souhaitez créer votre notebook.
Utilisez le bouton en haut à droite : New -> Notebook: Python 3.
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 est 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 (Shutdown), puis le déplacer (Move) et/ou le renommer (Rename).

Importer un notebook déjà 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 rédigé par quelqu'un d'autre, procédez de la façon suivante :

Téléchargez le fichier sur votre répertoire. Pour ce Notebook hébergé sur un GitLab, cliquez sur Open raw (l'icône avec un petit </> ) et sauvegardez (Ctrl-S sur la plupart des navigateurs) son contenu (un long fichier texte au format JSON).
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.
Utilisez le bouton en haut à droite Upload pour transférer le document de votre ordinateur vers le serveur Jupyter et confirmez l'upload.
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 (les détails d'installation sont donnés plus bas dans ce document). Il vous faut tout d'abord ouvrir un notebook Python.

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.
```
%load_ext rpy2.ipython
```
Utilisez la (nouvellement activée) commande magique %R :
```
%%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) :
```
%%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.

Un exemple de notebook utilisant R et Python est proposé ici.

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 variable.

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.

Vous trouverez ici une liste de notebooks Jupyter illustrant comment différents langages (Python, R, SAS) peuvent être utilisés dans Jupyter.

SAS

SAS est un logiciel de statistiques propriétaires qui est très couramment utilisé dans le domaine de la santé. 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 (l'équivalent du IRKernel), soit avec la bibliothèque Python SASPy (l'équivalent de rpy2).

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.

SASPy

Installer saspy via pip, par exemple comme ceci :
```
python -m pip install saspy
```
Sous Windows, il vous faudra probablement modifier le fichier C:\Program Files\Python\Python37\Lib\site-packages\saspy\sascfg.py et l'adapter à votre propre système. Dans les deux captures d'écran suivantes, la fenêtre de gauche correspond à la version originale du fichier et celle de droite à la version modifiée :
Voici un exemple de notebook Python/SAS.
N.B. : L'export du format HTML (et donc SAS) vers le format PDF via LaTeX ne fonctionne pas (notebook_{htmlexportpdfvialatex}.pdf). Jusqu'à présent il était possible de faire l'export depuis Pandoc. Une façon de faire était d'exporter le notebook au format HTML (ou Markdown) dans Jupyter puis d'exécuter la commande suivante :
```
pandoc --variable=geometry:a4paper --variable=geometry:margin=1in notebook_sas.html -o  notebook_sas.pdf  
```
L’extension notebook-as-pdf permet maintenant l’export direct du format HTML vers le format PDF (notebook_{htmlexportpdfviahtml}.pdf) et donc l’export des notebooks SAS au format PDF (notebook_JupyterSAS.pdf). (Choisir l'export PDF via HTML.)
Une référence, plus complète, et bien utile en cas de difficultés : https://sassoftware.github.io/saspy/

SASKernel

Le sas_kernel utilise saspy donc la première chose à faire est d'installer saspy en suivant les instructions précédentes.
Installez sas_kernel à l'aide de pip, par exemple comme ceci :
```
python -m pip install sas_kernel  
```
Yous pourrez alors créer des notebooks utilisant SAS nativement :

Vous pouvez remarquer la petite icône SAS en haut à droite.
À toute fin utile, voici un exemple de notebooks SAS.
Une référence, plus complète, et bien utile en cas de difficultés : https://sassoftware.github.io/sas_kernel/install.htmlxo.

Améliorer la lisibilité d'un notebook

Lorsque les notebooks s'allongent, ils deviennent vite difficiles à lire. Voici quelques extensions (la liste officielle de ces extensions est ici) qui peuvent vous faciliter un peu la vie :

Il est possible plier/déplier votre code :

pip3 install jupyter_contrib_nbextensions
# jupyter contrib nbextension install --user # not done yet

Il est aussi possible de contrôler la visibilité des cellules, ce qui peut être très utile si on exporte le notebook :
```
sudo pip3 install hide_code
sudo jupyter-nbextension  install --py hide_code
jupyter-nbextension  enable --py hide_code
jupyter-serverextension enable --py hide_code
```
Vous pourrez alors choisir Hide_code dans le menu de Jupyter :

Cela devrait vous permettre d'obtenir ce genre de panneau de configuration pour chaque cellule :

Il vous faudra utiliser les icônes pour faire l'export en pdf ou en html plutôt que de passer par le menu.

N.B. : Dans la première édition de ce MOOC, certains participants nous ont rapporté avoir eu des difficultés à faire fonctionner cette extension sous Windows.
Table des matières: L'extention toc(2) améliore également beaucoup la navigation et la capacité à avoir une vue d'ensemble du notebook.

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.

Installation de Jupyter (et de Python, R…)

Téléchargez d'abord la dernière version de Miniconda. 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.

Sur notre serveur, nous utilisons la version 4.5.4 de Miniconda et la version 3.6 de Python. En théorie, vous pourriez télécharger le fichier d'environnement mooc_rr et reproduire un environnement identique sur votre ordinateur. Malheureusement, notre serveur date de 2018 et conda a beaucoup changé entretemps, au point que la reconstruction de cet environnement n'est plus possible. Nous vous montrons par la suite comment obtenir un environnement équivalent mais avec des versions plus récentes de tous les logiciels.

Installez Miniconda en suivant les instructions fournies. Si le logiciel d'installation (ce n'est pas systématique) vous pose la question

Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no]

acceptez avec yes. Puis vous verrez le conseil

=> For changes to take effect, close and re-open your current shell. <=

qu'il faut absolument suivre pour que la suite se passe bien.

Important : il vous faudra exécuter plusieurs commandes dans le shell conda.

Voici d'abord comment ouvrir ce shell (comme expliqué dans la documentation Anaconda) :

Windows : Click Start, search, ou bien sélectionnez Anaconda Prompt dans le menu.
macOS : Cmd+Space pour ouvrir Spotlight Search et tapez “terminal” pour ouvrir le shell.
Linux–CentOS : Open Applications - System Tools - terminal.
Linux–Ubuntu : Open the Dash by clicking the upper left Ubuntu icon, then type “terminal”.

La première commande à exécuter dans le shell est

conda update -n base -c defaults conda

pour mettre à jour tous les logiciels dans la distribution conda.

Nous pouvons maintenant créer un environnement conda pour le parcours Jupyter de ce MOOC :

conda create -n mooc-rr-jupyter

et l'activer :

conda activate mooc-rr-jupyter

Il n'est pas strictement nécessaire d'activer un environnement pour s'en servir, mais c'est la façon la plus facile qui suscite le moins d'erreurs. Vous devez répéter cette activation chaque fois que vous ouvrez un nouveau terminal, avant de pouvoir utiliser cet environnement.

Le prochain pas est l'installation de tous les logiciels dont nous avons besoin et qui font partie de la distribution Miniconda :

conda install jupyter python numpy matplotlib pandas r r-irkernel rpy2 tzlocal simplegeneric

Il reste deux paquets que ne font pas partie de Miniconda. Nous récupérons le premier de la source indépendante conda-forge :

conda install -c conda-forge r-parsedate

et le deuxième du dépôt principal du langage Python, PyPI :

pip install isoweek

Vous pouvez maintenant lancer Jupyter :

jupyter notebook

et travailler avec nos exemples et exercices.

LaTeX pour la génération de PDF

Si vous voulez convertir vos notebooks en PDF, vous devez aussi installer LaTeX sur votre ordinateur. Nous expliquons cette procédure dans une ressource spécifique.

JupyterLab

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, 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 JupyterLab sur votre ordinateur (avec l'environnement mooc-rr-jupyter activé) :

conda install jupyterlab

Pour le lancer :

jupyter lab

Interaction avec GitLab et git

Pour 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 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. 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 vous pouvez facilement y insérer des commandes Git. C'est la façon dont nous travaillons en pratique la majorité du temps. Si vous optez pour cette solution, il vous faudra configurer Git sur votre ordinateur. Pour ce faire, vous pouvez suivre la vidéo configurer Git pour Gitlab et le document Git et Gitlab correspondant.

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 permettant d'ignorer ces numéros lorsque l'on commite des notebooks Jupyter. Il y eu de longues discussions à ce sujet sur StackOverflow, the Jupyter Forum, et NextJournal, qui détaillent différentes options.

Enfin, pour ceux qui utilisent JupyterLab plutôt que le Jupyter de base, un plugin Git pour JupyterLab a été développé et offre des fonctionnalités de suivi de version dignes d'un IDE classique.