diff --git a/module2/module2_ressources_jupyter_fr.org b/module2/module2_ressources_jupyter_fr.org new file mode 100644 index 0000000000000000000000000000000000000000..c1aad4e30e64ea0dd7e107242072ddc0b15f1edc --- /dev/null +++ b/module2/module2_ressources_jupyter_fr.org @@ -0,0 +1,369 @@ +# -*- mode: org -*- +#+TITLE: Jupyter : Trucs et astuces, installation et configuration +#+AUTHOR: Arnaud Legrand, Benoit Rospars, Konrad Hinsen +#+DATE: Février 2020 +#+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 : +#+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]] + - [[#améliorer-la-lisibilité-dun-notebook][Améliorer la lisibilité d'un notebook]] +- [[#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...)]] + - [[#latex-pour-la-génération-de-pdf][LaTeX pour la génération de PDF]] + - [[#jupyterlab][JupyterLab]] + - [[#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=) +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'icône 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.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. : L'export du format HTML (et donc SAS) vers le format PDF via LaTeX ne fonctionne pas + ([[file:../../documents/notebooks/notebook_html_export_pdf_via_latex.pdf][notebook_html_export_pdf_via_latex.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 : + #+begin_src shell :results output :exports both + pandoc --variable=geometry:a4paper --variable=geometry:margin=1in notebook_sas.html -o notebook_sas.pdf + #+end_src + + L’extension [[https://pypi.org/project/notebook-as-pdf/][notebook-as-pdf]] permet maintenant l’export + direct du format HTML vers le format PDF + ([[file:../../documents/notebooks/notebook_html_export_pdf_via_html.pdf][notebook_html_export_pdf_via_html.pdf]]) + et donc l’export des notebooks SAS au format PDF + ([[file:../../documents/notebooks/notebook_Jupyter_SAS.pdf][notebook_Jupyter_SAS.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/]] + +*[[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]]. + +** 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 [[https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions.html][ici]]) 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. +- Table des matières: L'extention [[https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/toc2/README.html][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 [[https://conda.io/miniconda.html][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 +[[https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57][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 +#+begin_quote +Do you wish the installer to initialize Miniconda3 +by running conda init? [yes|no] +#+end_quote +acceptez avec =yes=. Puis vous verrez le conseil +#+begin_quote +==> For changes to take effect, close and re-open your current shell. <== +#+end_quote +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 +[[https://docs.anaconda.com/anaconda/install/verify-install/][documentation Anaconda]]) : +- Windows : Click Start, search, ou bien sélectionnez Anaconda Prompt dans le menu. + [[file:Conda_images/win-anaconda-prompt.png]] +- 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 +#+begin_src shell :results output :exports both +conda update -n base -c defaults conda +#+end_src +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 : +#+begin_src shell :results output :exports both +conda create -n mooc-rr-jupyter +#+end_src +et l'activer : +#+begin_src shell :results output :exports both +conda activate mooc-rr-jupyter +#+end_src +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 : +#+begin_src shell :results output :exports both +conda install jupyter python numpy matplotlib pandas r r-irkernel rpy2 tzlocal simplegeneric +#+end_src +Il reste deux paquets que ne font pas partie de Miniconda. Nous +récupérons le premier de la source indépendante [[https://conda-forge.org/][conda-forge]] : +#+begin_src shell :results output :exports both +conda install -c conda-forge r-parsedate +#+end_src +et le deuxième du dépôt principal du langage Python, [[https://pypi.org/][PyPI]] : +#+begin_src shell :results output :exports both +pip install isoweek +#+end_src + +Vous pouvez maintenant lancer Jupyter : +#+begin_src shell :results output :exports both +jupyter notebook +#+end_src +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 [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+self-paced/jump_to_id/19c2b1de7766484bae73f3ab133463c6][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, [[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 JupyterLab sur votre ordinateur +(avec l'environnement =mooc-rr-jupyter= activé) : +#+begin_src shell :results output :exports both +conda install jupyterlab +#+end_src + +Pour le lancer : +#+begin_src shell :results output :exports both +jupyter lab +#+end_src +** 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 [[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+self-paced/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 de longues discussions à ce sujet sur +[[https://stackoverflow.com/questions/18734739/using-ipython-notebooks-under-version-control][StackOverflow]], [[https://discourse.jupyter.org/t/how-to-version-control-jupyter-notebooks/566/14][the Jupyter Forum]], et [[https://nextjournal.com/schmudde/how-to-version-control-jupyter][NextJournal]], qui détaillent 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.