Skip to content

M
mooc-rr-ressources
Commit 42247da7 authored by Arnaud Legrand's avatar Arnaud Legrand
Browse files
Options

Integrate all the SAS explanations in the Jupyter documentation.

parent d6ee75ed
Hide whitespace changes
Inline Side-by-side
Showing with 165 additions and 216 deletions
documents/tuto_jupyter_windows/tuto_jupyter_windows.md deleted 100755 → 0
View file @ d6ee75ed
Table des matières
=================
- [1 Installer Python](#1-installer-python)
- [2 Installer le package Jupyter](#2-installer-le-package-jupyter)
- [3 Installer les modules complémentaires](#3-installer-les-modules-compl%C3%A9mentaires)
- [4 Lancer Jupyper](#4-lancer-jupyper)
- [5 Autres langages](#5-autres-langages)
- [5.1 Le package R IRKernel](#51-le-package-r-irkernel-permet-dex%C3%A9cuter-du-code-r-dans-un-notebook-r)
- [5.2 Le package Python rpy2](#52-le-package-python-rpy2-permet-dex%C3%A9cuter-du-code-r-dans-un-notebook-python)
- [5.3 Le package Python SASPy](#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)
- [5.4 Le package Python SASKernel](#54-le-package-python-saskernel-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-sas)
# 1 Installer Python
- Installer Python
- Ajouter les chemins de Python et Python\Scripts dans dans la variable PATH de Windows
La façon de procéder est très bien expliquée [ici](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/).
---
# 2 Installer le package Jupyter
- Méthode pour installer un package
- Ouvrir une invite de commande dos
- Exécuter la commande suivante
```
pip install jupyter
```
NB : Le raccourci `^v` ne fonctionne pas dans l'invite de commande dos. La fonction "coller" est disponible avec le bouton droit de la souris.
---
# 3 Installer les modules complémentaires
- Ouvrir une invite de commande dos
- Exécuter les commandes suivantes
## **jupyter_contrib_nbextensions** pour replier le code à l'affichage
```
pip install jupyter_contrib_nbextensions
```
## **hide_code** pour choisir ce qui est exporté
```
pip install hide_code
jupyter-nbextension install --py hide_code
jupyter-nbextension enable --py hide_code
jupyter-serverextension enable --py hide_code
```
Choisir `Hide_code` dans le menu
![menu_hide_code](documents/tuto_jupyter_windows/images/menu_hide_code.png)
On obtient ceci
![hide_code](documents/tuto_jupyter_windows/images/hide_code.png)
Utiliser les icônes ci-dessous pour l'export
![export_hide_code](documents/tuto_jupyter_windows/images/export_hide_code.png)
NB : Certains ont rencontrés des problèmes lors de l'export sous Windows lors de la 1ère session du Mooc.
# 4 Lancer Jupyper
- Ouvrir une invite de commande dos
- Exécuter la commande suivante
```
jupyter notebook
```
---
# 5 Autres langages
Jupyper permet par défaut d'exécuter du code Python. Des packages permettent d'exécuter d'autres langages.
## 5.1 Le package R [IRKernel](https://cran.r-project.org/web/packages/IRkernel/IRkernel.pdf) permet d'exécuter du code R dans un notebook R
- Lancer R ou RStudio
- Installer le package `IRkernel`
```
install.packages('IRkernel',dep=TRUE)
IRkernel::installspec() # to register the kernel in the current R installation
```
- On peut alors créer un notebook R
![new_notebook](documents/tuto_jupyter_windows/images/new_notebook.png)
![notebook_R](documents/tuto_jupyter_windows/images/notebook_R.png)
On remarque l'icône du logiciel R en haut à droite.
- [Exemple de notebook R](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/notebooks/notebook_Jupyter_R.ipynb)
- Lien utile : https://irkernel.github.io/installation/
---
## 5.2 Le package Python **rpy2** permet d'exécuter du code R dans un notebook Python
- Le package `rpy2` s'installe difficilement par méthode standard.
- Télécharger le fichier binaire qui correspond au système d'exploitation [ici](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2)
- Ouvrir une invite de commande dos
- Se placer dans le dossier de téléchargement
- Exécuter la commande suivante
```
python -m pip install rpy2‑2.9.4‑cp37‑cp37m‑win_amd64.whl # adapter le nom du fichier
```
- Lancer Jupiter et créer un notebook Python
- Exécuter la commande suivante
```
%load_ext rpy2.ipython
```
- Installer le package `tzlocal` à l'aide de la commande `pip`
- [Exemple de notebook Python/R](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/notebooks/notebook_Jupyter_Python_R.ipynb)
- Lien utile : https://stackoverflow.com/questions/14882477/rpy2-install-on-windows-7
NB : Je n'ai pas eu besoin de définir les variables d'environnement R_HOME et R_USER.
---
## 5.3 Le package Python [SASPy](https://sassoftware.github.io/saspy/) permet d'exécuter du code SAS dans un notebook Python
- Installer le package `saspy` à l'aide de la commande `pip`
- Modifier le fichier C:\Program Files\Python\Python37\Lib\site-packages\saspy\sascfg_sav.py pour l'adapter à votre système
Dans les deux images ci-dessous, la fenêtre de gauche correspond au fichier initial et celle de droite au fichier modifié.
![sascfg1](documents/tuto_jupyter_windows/images/sascfg1.png)
![sascfg2](documents/tuto_jupyter_windows/images/sascfg2.png)
- [Exemple de notebook Python/SAS](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/notebooks/notebook_Jupyter_Python_SAS.ipynb)
- NB : L'export Jupyter vers pdf ne fonctionne pas pour les sorties HTML et donc SAS. Il est possible de faire l'export depuis pandoc.
- Exporter le document au format HTML
- Exécuter la commande suivante
```
pandoc --variable=geometry:a4paper --variable=geometry:margin=1in notebook_sas.html -o notebook_sas.pdf
```
mais ça ne marche pas pour tous les tableaux et on perd la coloration syntaxique.
---
## 5.4 Le package Python [SASKernel](https://sassoftware.github.io/sas_kernel/) permet d'exécuter du code SAS dans un notebook SAS
- Le package `sas_kernel` est basé sur le package `saspy`. Installer `saspy` en suivant les instructions de la section 4.3 si ce n'est déjà fait.
- Installer le package `sas_kernel` à l'aide de la commande `pip`
- On peut alors créer un notebook SAS
![new_notebook](documents/tuto_jupyter_windows/images/new_notebook.png)
![notebook_SAS](documents/tuto_jupyter_windows/images/notebook_SAS.png)
On remarque l'icône du logiciel SAS en haut à droite.
- [Exemple de notebook SAS](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/notebooks/notebook_Jupyter_SAS.ipynb)
- NB : L'export Jupyter vers pdf ne fonctionne pas pour les sorties HTML et donc SAS. Il est possible de faire l'export depuis pandoc.
- Exporter le document au format HTML
- Exécuter la commande suivante
```
pandoc --variable=geometry:a4paper --variable=geometry:margin=1in notebook_sas.html -o notebook_sas.pdf
```
mais ça ne marche pas pour tous les tableaux et on perd la coloration syntaxique.
- Lien utile : https://sassoftware.github.io/sas_kernel/install.html
module2/ressources/jupyter.org
View file @ 42247da7
......@@ -6,14 +6,22 @@
#+OPTIONS: num:nil toc:t
#+PROPERTY: header-args :eval never-export
Once you will have followed all these installation instructions, you
will be able to run jupyter notebooks by simply typing in a shell/DOS
command:
#+begin_src shell :results output :exports both
jupyter notebook
#+end_src
* Table of Contents :TOC:
- [[#jupyter-tips-and-tricks][Jupyter tips and tricks]]
- [[#creating-or-importing-a-notebook][Creating or importing a notebook]]
- [[#running-r-and-python-in-the-same-notebook][Running R and Python in the same notebook]]
- [[#other-languages][Other languages]]
- [[#installing-and-configuring-jupyter-on-your-computer][Installing and configuring Jupyter on your computer]]
- [[#installing-jupyter][Installing Jupyter]]
- [[#installing-jupyter-and-python-r-][Installing Jupyter (and Python, R, ...)]]
- [[#making-sure-jupyter-allows-you-to-use-r][Making sure Jupyter allows you to use R]]
- [[#latex-for-pdf-export][LaTeX for PDF export]]
- [[#additional-tips][Additional tips]]
* Jupyter tips and tricks
......@@ -54,6 +62,10 @@ situations however where you may want to play with other notebooks.
notebook and confirm the upload.
4. Open the freshly uploaded notebook through the Jupyter file
manager.
You will find [[file:../../documents/notebooks/][here]] a list of jupyter notebooks that illustrate how
different languages (python, R, SAS) can be used in Jupyter.
** Running R and Python in the same notebook
It used to be impossible with earlier versions of Jupyter but it is
now very easy thanks to the the =rpy2= package (see the details of the
......@@ -90,15 +102,63 @@ 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 [[https://sassoftware.github.io/sas_kernel/][Python SASKernel]] or the [[https://sassoftware.github.io/saspy/][Python SASPy]] package (step by step
explanations about this are given [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md][here]]).
*** SAS
SAS is a proprietary statistical software which is very commonly used
in health research. 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 [[https://sassoftware.github.io/sas_kernel/][Python SASKernel]] (similar to the
=IRKernel=) or the [[https://sassoftware.github.io/saspy/][Python SASPy]] package (similar to the =rpy2= package).
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.
*[[https://sassoftware.github.io/saspy/][SASPy]]*
- Install =saspy= with the =pip= command. E.g.,
#+begin_src shell :results output :exports both
python -m pip install saspy
#+end_src
- On Windows, you will have to modify the file =C:\Program
Files\Python\Python37\Lib\site-packages\saspy\sascfg_sav.py= and to
adapt it to your own system. In both following screenshots, the left
window corresponds to the initial file and the right window
corresponds to the modified one:
#+BEGIN_CENTER
[[file:jupyter_images/sascfg1.png]]
#+END_CENTER
#+BEGIN_CENTER
[[file:jupyter_images/sascfg2.png]]
#+END_CENTER
- Here is a [[file:../../documents/notebooks/notebook_Jupyter_Python_SAS.ipynb][example of Python/SAS notebook]].
- NB : Some people from the first edition of the MOOC reported us that
the pdf export did not not seem to work for SAS notebooks. However,
they could obtain pdf files through pandoc. E.g., export in HTML (or
markdown) in jupyter and then run:
#+begin_src shell :results output :exports both
pandoc --variable=geometry:a4paper --variable=geometry:margin=1in notebook_sas.html -o notebook_sas.pdf
#+end_src
- Useful link: https://sassoftware.github.io/saspy/
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.
*[[https://sassoftware.github.io/sas_kernel/install.html][SASKernel]]*
- The =sas_kernel= is based on the =saspy= so first instll =saspy= by
following the previous instructions.
- Install the =sas_kernel= package through =pip=. E.g.,
#+begin_src shell :results output :exports both
python -m pip install sas_kernel
#+end_src
- You will then be able to create SAS notebooks
#+BEGIN_CENTER
[[file:jupyter_images/new_notebook.png]]
#+END_CENTER
#+BEGIN_CENTER
[[file:jupyter_images/notebook_SAS.png]]
#+END_CENTER
Please note the top right SAS icon.
- Here is a [[file:../../documents/notebooks/notebook_Jupyter_SAS.ipynb][example of SAS notebook]].
- Useful link: https://sassoftware.github.io/sas_kernel/install.html
* Installing and configuring Jupyter on your computer
In this section, we explain how to set up a Jupyter environment on
......@@ -110,7 +170,7 @@ 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.
** Installing Jupyter
** Installing Jupyter (and Python, R, ...)
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.
......@@ -268,6 +328,21 @@ Here are a few extensions that can ease your life:
jupyter-serverextension enable --py hide_code
#+end_src
Then in jupyter, choose =Hide_code= in the menu
#+BEGIN_CENTER
[[file:jupyter_images/menu_hide_code.png]]
#+END_CENTER
You should then obtain this:
#+BEGIN_CENTER
[[file:jupyter_images/hide_code.png]]
#+END_CENTER
You should then use the icons to export rather than going through
the menu:
#+BEGIN_CENTER
[[file:jupyter_images/export_hide_code.png]]
#+END_CENTER
NB: In the first edition of the MOOC some people had issues making
it work under Windows.
*** • 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
......
module2/ressources/jupyter_fr.org
View file @ 42247da7
......@@ -12,8 +12,9 @@
- [[#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]]
- [[#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]]
* Jupyter: Trucs et astuces
......@@ -108,11 +109,17 @@ 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]]).
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
......@@ -123,6 +130,55 @@ objectif de recherche reproductible mais il faut aussi savoir ne pas
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]].
- NB : 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é::
https://sassoftware.github.io/saspy/
*[[https://sassoftware.github.io/sas_kernel/install.html][SASKernel]]*
- Le =sas_kernel= utilise =saspy= docn 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é:
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
......@@ -136,7 +192,7 @@ 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
** 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.
......@@ -307,7 +363,23 @@ vie:
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
NB: 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 GitHub
Pour rendre vous simplifier la vie, nous avons rajouté des boutons
=pull/push= dans Jupyter qui vous permettent de synchroniser vos
......
module2/ressources/jupyter_images/new_notebook.png 100755 → 100644
View file @ 42247da7
File mode changed from 100755 to 100644
module2/ressources/jupyter_images/notebook_R.png 100755 → 100644
View file @ 42247da7
File mode changed from 100755 to 100644
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment