# -*- 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 Quand vous aurez suivi les instructions suivantes, vous pourrez ouvrir des notebooks jupyter en tapant une commande shell/DOS command: #+begin_src shell :results output :exports both jupyter notebook #+end_src * 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-et-de-python-r-][Installation de Jupyter (et de Python, R...)]] - [[#sassurer-que-jupyter-vous-permet-dutiliser-r][S'assurer que Jupyter vous permet d'utiliser R]] - [[#latex-pour-la-génération-de-pdf][LaTeX pour la génération de PDF]] - [[#conseils-additionnels][Conseils additionnels]] - [[#interaction-avec-gitlab-et-git][Interaction avec GitLab et git]] * 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 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 [[https://app-learninglab.inria.fr/gitlab/moocrr-session2/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-session2/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= (les détails d'installation sont donnés plus bas dans ce document). 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. Un exemple de notebook utilisant R et Python est proposé [[file:../../documents/notebooks/notebook_Jupyter_Python_R.ipynb][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][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 [[file:../../documents/notebooks/][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 [[https://sassoftware.github.io/sas_kernel/][Python SASKernel]] (l'équivalent du =IRKernel=), soit avec la bibliothèque [[https://sassoftware.github.io/saspy/][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. *[[https://sassoftware.github.io/saspy/][SASPy]]* - Installer =saspy= via =pip=, par exemple comme ceci : #+begin_src shell :results output :exports both python -m pip install saspy #+end_src - Sous Windows, il vous faudra probablement modifier le fichier =C:\Program Files\Python\Python37\Lib\site-packages\saspy\sascfg_sav.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 : #+BEGIN_CENTER [[file:jupyter_images/sascfg1.png]] #+END_CENTER #+BEGIN_CENTER [[file:jupyter_images/sascfg2.png]] #+END_CENTER - Voici un [[file:../../documents/notebooks/notebook_Jupyter_Python_SAS.ipynb][exemple de notebook Python/SAS]]. - N.B. : Lors de la première édition du MOOC, certains participants nous on rapporté avoir rencontré des difficultés pour exporter leurs notebooks SAS au format PDF. Ils sont néanmoins parvenus à leur fin en passant par pandoc. Par exemple, exportez en HTML (ou en markdown) dans jupyter puis exécutez la commande suivante : #+begin_src shell :results output :exports both pandoc --variable=geometry:a4paper --variable=geometry:margin=1in notebook_sas.html -o notebook_sas.pdf #+end_src - Une référence, plus complète, et bien utile en cas de difficultés : [[https://sassoftware.github.io/saspy/]] *[[https://sassoftware.github.io/sas_kernel/install.html][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 : #+begin_src shell :results output :exports both python -m pip install sas_kernel #+end_src - Yous pourrez alors créer des notebooks utilisant SAS nativement : #+BEGIN_CENTER [[file:jupyter_images/new_notebook.png]] #+END_CENTER #+BEGIN_CENTER [[file:jupyter_images/notebook_SAS.png]] #+END_CENTER Vous pouvez remarquer la petite icône SAS en haut à droite. - À toute fin utile, voici un [[file:../../documents/notebooks/notebook_Jupyter_SAS.ipynb][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]]. * 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 (et de Python, R...) 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. *Windows* Pour windows, il ne sera probablement pas possible de compiler la toute dernière version et il faudra installer la version binaire de la façon suivante. Dans une console R ou bien dans Rstudio : #+begin_src R :results output :session *R* :exports both install.packages('IRkernel',dep=TRUE) IRkernel::installspec() # to register the kernel in the current R installation #+end_src Voir ce qui suit pour un exemple d'utilisation de notebook R. *Linux ou Mac* Pour installer la toute dernière version d'IRkernel, dans une console R ou bien dans Rstudio : - 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 Vous pourrez alors créer des notebooks utilisant directement R : [[file:jupyter_images/new_notebook.png]] [[file:jupyter_images/notebook_R.png]] On remarque l'icône du logiciel R en haut à droite. Vous trouverez ici [[file:../../documents/notebooks/notebook_Jupyter_R.ipynb][un exemple de notebook R]]. *** • 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. *Linux ou Mac* 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, placez vous dans le dossier de téléchargement, et exécutez la commande suivante : #+begin_src shell :results output :exports both python -m pip install rpy2‑2.9.4‑cp37‑cp37m‑win_amd64.whl # adaptez le nom de fichier #+end_src Installez également =tzlocal= : #+begin_src shell :results output :exports both python -m pip install tzlocal #+end_src En cas de difficulté, vous pouvez vouloir vous référer à [[https://stackoverflow.com/questions/14882477/rpy2-install-on-windows-7][StackOverflow]] (N.B. : quand nous avons essayé, nous n'avons pas eu besoin de définir les variables d'environnement =R_HOME= et =R_USER=). Vous pouvez alors lancer Jupyter et créer un notebook Python utilisant R en suivant les instructions données au début de ce document (cherchez =rpy2=). ** 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 [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/19c2b1de7766484bae73f3ab133463c6][ressource spécifique]]. ** Conseils additionnels *** • Exporter un notebook Jupyter évolue rapidement et ces informations peuvent vite devenir obsolètes 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 trop bidouiller =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 difficiles à 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 Vous pourrez alors choisir =Hide_code= dans le menu de Jupyter : #+BEGIN_CENTER [[file:jupyter_images/menu_hide_code.png]] #+END_CENTER Cela devrait vous permettre d'obtenir ce genre de panneau de configuration pour chaque cellule : #+BEGIN_CENTER [[file:jupyter_images/hide_code.png]] #+END_CENTER Il vous faudra utiliser les icônes pour faire l'export en pdf ou en html plutôt que de passer par le menu. #+BEGIN_CENTER [[file:jupyter_images/export_hide_code.png]] #+END_CENTER 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. ** • Interaction avec GitLab et git 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 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 [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85][configurer Git pour Gitlab]] et le document [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/gitlab_fr.org][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 [[https://gist.github.com/pbugnion/ea2797393033b54674af][git hooks spécifiques]] permettant d'ignorer ces numéros lorsque l'on commite des notebooks Jupyter. Il y eu 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.