Notebook Jupyter & Python

Création d’un Jupyter Book

A. Créer un projet

Il y a plusieurs façon de travailler :

vous pouvez utiliser un Jupyter Lab en local, accessible via votre Navigateur
vous pouvez utiliser votre IDE préféré (VSCode, Pycharm, etc) avec une extension Jupyter.
ou encore vous pouvez utiliser seulement le serveur de Jupyter Book avec ou sans Jupyter Server.

Avertissement

Si vous prenez la première ou la deuxième option avec un plugin pour gérer la syntaxe myst, il faut savoir que la partie execution de code n’est pour le moment fonctionnelle qu’avec des fichiers dont l’extension est .ipynb (contenu json et binaire), celle-ci n’est pas encore géré pour des fichiers dont l’extension est en markdown .md (contenu texte ). Cela devrait évoluer d’ici les prochains mois.

Vous trouverez aussi sur le site de Jupyter, une aide pour choisir entre les deux formats : ipynb et myst md

Note

Pour rappel, dans ce TP nous utilisons la nouvelle pile logicielle en développement : Jupyter Book v2 (https://next.jupyterbook.org/) encapsule/est équivalent à MystMd. Le nom du client change, mais les deux docs sont équivalentes et complémentaires. L’explication du pourquoi du comment ici.

A ne pas confondre avec Myst Parser qui est un plugin pour Sphynx et Jupyter Book v1 qui correspondent à la version actuelle, probablement amené à disparaitre ces prochaines années.

A tout moment vous pouvez vous rapporter à ce glossaire

Si vous êtes déjà famillier d’un de ces options vous pouvez l’utiliser, pour ce tutorial nous vous proposons d’utiliser la troisième solution en ligne de commande (CLI) Jupyter Book.

La plupart des modifications et options d’un projet se font au travers du myst.yml qui doit être dans votre répertoire projet.

Créer un dossier pour votre projet et ajouter y un fichier myst.yml

C’est ce fichier qui fait de votre dossier un projet Myst/Jupyter Book reconnu par la commande jupyter book

Ce fichier contient deux grand blocs d’options :

myst.yml

version: 1
project :
...

site:
...

1. Le bloc project: définit les options d’entête du projet, et la façon dont celui-ci se comporte et doit être rendu par Jupyter
1. Le bloc site: définit les options du site web, pour sa construction et son export

Pour le bloc project:, et comme nous voulons executer le code des chunks, avec un Jupyter Server en local, il faudra plus tard ajouter des options dans un bloc jupyter.

Mise en garde

Par défaut MystMd/Jupyter Book v2 n’execute pas les chunks de code sauf si vous l’avez spécifié !

Pour le moment on laisse cette partie project: vide et nous y reviendrons plus tard.

Pour le bloc site:, nous définissons le template article-theme, c’est celui que nous allons utiliser.

Voici une configuration minimale pour ce fichier myst.yml, maintenant il faut définir un fichier de contenu.

version: 1
project:
  title: "Ceci est un titre"
site:
  template: article-theme

B. Créer un fichier index.md

Le format de fichier reste le même, mais le markdown qui va être géré par Jupyter est un markdown étendu, avec des nouvelles fonctionalités propre au langage Myst.

Nous allons créer un fichier index.md dans lequel nous allons placer peu à peu notre code markdown étendu.

Note

Vous avez le choix de donner n’importe quel nom au fichier source de votre notebbok. Le même nom sera utilisé pour le fichier en sortie (notebook compilé). Par exemple : toto.qmd → toto.html

Parce que nous souhaitons déployé le fichier de sortie (.html) sur une page web, il est fortement recommandé de nommer ce fichier “index”. (Pourquoi ?)

Ajouter le contenu suivant à votre index.md

---
title: "mon_book_jupyter"
---

A présent vous pouvez lancer une première fois la commande suivante pour render votre site sur localhost:3000

jupyter book start -d

Si vous modifier votre fichier index.md, le site localhost:3000 se met à jour automatiquement.

Astuce

Pour quitter le serveur, ou tout autre processus dans un powershell ou sous linux, c’est le raccourci Ctrl + C

C. Créer un fichier .md executable !

Pour que le fichier soit executés, il faut revenir sur notre fichier de configuration de projet myst.yml pour ajouter la partie qui le relie au Jupyter Server :

version: 1

project:
  jupyter:
    server:
      url: http://localhost:8888/
      token: '' 

site:
  template: article-theme

Pour que le fichier index.md soit reconnu comme executable, il est important d’indiquer le nom du kernel (ici python3, mais vous pouvez voir le nom du votre avec jupyter kernelspec list) nécessaire à la compilation des chunk dans l’entête.

---
title: "Entre école thématique et AG de laboratoire"
kernelspec:
  display_name: Python 3 (ipykernel)
  language: python
  name: python3
---

L’entête d’un chunk de code executable est {code-cell} python, et celui d’un chunk non executable est {code} python ou {.python} si vous voulez garder la compatibilité avec d’autres systèmes.

Vous pouvez d’ores et déjà ajouter un petit bloc de code à votre index.md pour tester la bonne execution de celui-ci avec les commandes de la prochaine partie :

a = 21
b = 21
print("La réponse est", a + b)

N’hésitez pas à regarder la documentation complète sur le sujet

C. Build ce fichier avec Jupyter Book

Mise en garde

A l’heure actuelle, et comme la version de Jupyter Book v2 est encore en développement assez intensif, il n’y a qu’une seule solution pour construire et/ou executer vos documents, c’est de passer par la commande client jupyter book en mode console.

Lorsqu’un document MystMd est construit, les blocs de code ne sont pas automatiquement executés. Pour les executer il faut le spécifier dans la ligne de commande avec l’option --execute

Avant de pouvoir executer ce fichier, nous avons besoin de lancer le serveur Jupyter qui hébergera le kernel Python que nous avons déclaré plus haut dans les fichiers de configuration.

Windows
Linux

En fonction de comment vous souhaitez travailler il y a plusieurs options pour travailler.

Comme nous voulons executer du code, jupyter book a besoin d’accéder à un jupyter server avec un kernel python.

Start-Process jupyter-server -ArgumentList  "--IdentityProvider.token=''", "--ServerApp.allow_origin='*'", "--ServerApp.disable_check_xsrf=True", "--ip=0.0.0.0", "--port 8888"

Ensuite on lance Jupyter Book en mode execution de code, avec une variable d’environnement qui lui permet de trouver jupyter-server.

$Env:JUPYTER_BASE_URL="http://localhost:8888" ; jupyter book start --execute -d

Vous pouvez ensuite modifier le code avec votre éditeur de choix, sauvegarder, et le code sera remis à jour directement dans localhost:3000 !

Note

Il est également possible de lancer un Jupyter Lab, qui contient lui aussi un Jupyter Server et un Kernel, à la place du Jupyter Server. Cela vous permet de modifier le fichier md dans le navigateur à l’adresse localhost:8888 (clic droit, open md) et d’avoir une prévisualisation (clic droit, preview md ).

Start-Process jupyter lab -ArgumentList  "--IdentityProvider.token=''", "--ServerApp.allow_origin='*'", "--ServerApp.disable_check_xsrf=True", "--ip=0.0.0.0", "--port 8888"

Vérifier la configuration de votre fichier myst.yml, c’est dans ce dernier que l’on définit le nom du kernel python que l’on va utiliser pour le site :

version: 1

project:
  jupyter:
    server:
      url: http://localhost:8888/
      token: '' 

site:
  template: article-theme

Lancer Jupyter Server en background ( symbole & en bout de ligne) dans votre terminal

jupyter server --IdentityProvider.token='' --ServerApp.allow_origin='*' --ip=0.0.0.0 --port 8888 --ServerApp.disable_check_xsrf=True &

Astuce

Pour reprendre la main sur un processus qui tourne en tache de fond dans un terminal, vous pouvez taper la commande fg

Lancer Jupyter Book en mode execution

export JUPYTER_BASE_URL="http://localhost:8888"
jupyter book start --execute -d

Astuce

Pour quitter le serveur, ou tout autre processus en cours sous linux, c’est le raccourci Ctrl + C, une fois voire plusieurs fois.

Note

jupyter-lab --IdentityProvider.token='' --ServerApp.allow_origin='*' --ip=0.0.0.0 --port 8888 --ServerApp.disable_check_xsrf=True &

Rédaction d’un Jupyter Book

L’entête (YAML) d’un notebook contient l’ensemble des métadonnées et variables générales du document.

Dans un fichier notebook Jupyter, l’entête est balisé par trois tirets :

---
title: "mon_book_jupyter"
subtitle: "Tranche de vie d'un professeur en Géographie"
---

A. Entête d’un Jupyter Book

1. Complétez le YAML an ajoutant les variables suivantes :

Titre, sous-titre et résumé → documentation
Auteur(s) → documentation
Date → documentation

Exemple :

---
title: "Entre école thématique et AG de laboratoire"
subtitle: "Tranche de vie d'un professeur en Géographie"
authors:
  - name: Raphaëlle Krummeich
    orcid: 0000-0002-6170-8243
    affiliations:
      - UMR IDEES, Université de Rouen Normandie
date: 2022-05-11
license: CC-BY-4.0
---

Il est également possible de déterminer des entêtes de façon globale, en intégrant ce même bloc authors: dans le bloc project: du fichier myst.yml :

myst.yml

project:
  . ..
   authors:
     - name: Raphaëlle Krummeich
     orcid: 0000-0002-6170-8243
     affiliation: idees
  affiliations:
    - id: idees
      institution: UMR IDEES, Université de Rouen Normandie
      institution: UMR Géographie-cités, CNRS

Pour avoir une vue globale des options disponibles pour l’entête d’un document Jupyter Book, vous pouvez consulter le site officiel de MystMd et/ou Jupyter Book :

https://mystmd.org/

2. Gérez l’apparence de la table des matières (TOC) → documentation

Important

Il y a encore assez peu d’options pour les TOC, celles-ci sont proposées de façon automatique en fonction aussi des templates : article et book (theme par défaut)

Il y a deux catégories de tables des matières qui correspondent aussi à la structure proposée par Myst par défaut :

a gauche (primary sidebar) pour une navigation par chapitre
a droite (secondary sidebar) pour une navigation par titre à l’intérieur de chaque chapitre

Les deux catégories se définissent dans le myst.yml à la racine du projet.

Pour le menu de gauche, le bloc de chapitre toc: est défini dans le bloc project:

version: 1
project:
  toc:
    - file: root.md
    - file: first-child.md
    - file: second-child.md

Pour cacher le menu de gauche et/ou de droite, cela se passe dans le deuxième grand bloc du myst.yml :

site:
  options:
    hide_toc: true
    hide_outline: true

YAML - Indentation et séparation

Il est impératif de respecter l’indentation attendue avec le langage YAML. Sinon.. ❌

B. Fichiers annexes liés

Différents types de fichier peuvent être liés à un notebook Jupyter, comme une feuille de style ou un fichier contenant des références bibliographiques. Pour cela, il est nécessaire de renseigner des métadonnées dans le YAML de l’en-tête.

Par exemple, pour lié un fichier de références bibliographiques au notebook :

Téléchargez le fichier exemple biblio.bib qui contient des références en format BibTExtrait :

@book{giraud_2024_10560265,
  author       = {Giraud, Timothée and
                  Pecout, Hugues},
  title        = {Géomatique avec R},
  publisher    = {Zenodo},
  year         = 2024,
  month        = jan,
  doi          = {10.5281/zenodo.10560265},
  url          = {https://doi.org/10.5281/zenodo.10560265},
}

Ajoutez ce fichier à la racine de votre projet.
Dans l’en-tête, au même niveau que title: indiquez le nom du fichier dans la variable bibliography :

---
title: "Entre école thématique et AG de laboratoire"
bibliography: biblio.bib
---

Pour appeler une référence bibliographique renseignée dans le fichier BibTeX, utilser le symbol @ et l’ID de la référence bibliographique ciblée, dans votre index.md :

---
title: ...
bibliography: biblio.bib
---

::: {.callout-caution}

Ceci est une tentative de traduction en _Python_ et _Myst Markdown_ du travail [expert](https://mon-super-notebook-eb33d0.gitpages.huma-num.fr/) réalisé par Hugues, aussi connu pour leur travaux sur **R pour la Géomatique** @giraud_2024_10560265

:::

Ainsi, la référence bibliographique appelée sera correctement affichée dans le corps du document.
Exemple : “Giraud et Pecout (2024)” et automatiquement affichée en fin de document de la manière suivante.

C. Du fichier .py au .md

Téléchargez le script de code Python mis à disposition : script.py, puis intégrez l’ensemble du code et des commentaires contenu dans le script dans votre fichier .qmd.

a. Texte balisé en markdown

Transposez les commentaires du script (+ explications, interprétations, déroulé de l’exploration..) en utilisant le langage de balisage markdown pour la mise en forme → documentation.

b. Code morcelé en plusieurs `chunk`

Transposez les lignes de code du script dans plusieurs blocs de code (appelés chunk).

Du script unique à plusieurs chunk

Morcelez les lignes de code par bloc comme indiqué en commentaire dans les scripts.

L’objectif est de construire un document intelligible qui permet de comprendre et d’apprécier toute la chaine de traitement présentée sans avoir à éxécuter le code. Transposez ainsi le script dans votre document Python en respectant le paradigme de la programmation lettrée !

Exemple :

---
title: "Entre école tématique et AG de laboratoire"
subtitle: "Tranche de vie d'un professeur en Géographie"
---

## Introduction

## Packages & données

### Liste des packages

Les packages utilisés pour réaliser cette analyse exploratoire sont les suivants :


Les packages utilisés pour réaliser cette analyse exploratoire sont les suivants :

- `geopandas` : pour manipuler des données géographiques vectorielles
- `geocode` : pour géocoder des adresses
- `folium` : visualiser des données géo. sur un fond de carte interactif
- `requests` : pour faire appel via l'API REST à OSRM routage (calcul d'itinéraire)
- `polyline` : pour décrypter le format géométrique renvoyé par OSRM
- `session_info` : pour afficher les infos de session


Pour installer les packages :

```{code-cell} python
:tags: [skip-execution, hide-input]
pip install geopandas[all] 
pip install polyline
pip install session_info
```

Chargement des librairies :

```{code-cell} python
import geopandas as gpd
import pandas as pd
import matplotlib.pyplot as plt
import folium
import requests
import polyline
import session_info
```



### Les adresses des événements

Seule deux adresses vont être utilisées comme données pour réaliser cette exploration :

-   **Le lieux de l'école thématique** : 

> *140, route des Allards, 17310 Saint-Pierre-d'Oléron*

-   **Le lieux de l'Assemblée générale** : 

>*1, allée Momplaisir, 17370 Saint Trojan Les Bains*

c. Gérer les options des `chunks`

Plusieurs options peuvent être appliquées aux blocs de code du document. Cela permet par exemple de contrôler leur comportement au moment de leur éxecution, quelques exemples :

Option	Description
`skip-execution`	Le code ne sera pas éxécuté, mais seulement affichés.
`remove-input`	Supprime l’affichage du bloc de code dans le document
`remove-output`	Supprime l’affichage des résultats générés par le bloc
`hide-input`	Masque l’affichage du bloc code dans le document, dépliable
`hide-output`	Masque l’affichage du résultat dans le document, dépliable
`remove-cell`	Masque l’ensemble de la cellule
`remove-stderr`	Masque les erreurs dans le document

Les options des chunks

De nombreuses options sont disponibles pour paramétrer le comportement des chunks et des résultats générés → voir la documentation #1 #2

Pour ajouter des options à un chunk, utilisez la syntaxe :tags: sous la première ligne du chunk :

```{code-cell python}
:tags: [skip-execution, hide-input]
pip install geopandas[all] 
pip install polyline
pip install session_info
```
```

Dans le cas ci-dessus, le code ne sera pas éxécuté.

Enfin, il est possible d’executer du code directement Inline, c’est à dire directement dans les paragraphes, grâce à la syntaxe {eval}

Besoin d’aide ?

⚠️ Un exemple de notebook terminé est mis à disposition sur ce dépôt GitLab ⚠️

Les références

Giraud, Timothée, et Hugues Pecout. 2024. Géomatique avec R. Zenodo. https://doi.org/10.5281/zenodo.10560265.

Création d’un Jupyter Book

A. Créer un projet

B. Créer un fichier index.md

C. Créer un fichier .md executable !

C. Build ce fichier avec Jupyter Book

Rédaction d’un Jupyter Book

A. Entête d’un Jupyter Book

B. Fichiers annexes liés

C. Du fichier .py au .md

a. Texte balisé en markdown

b. Code morcelé en plusieurs chunk

c. Gérer les options des chunks

Les références

b. Code morcelé en plusieurs `chunk`

c. Gérer les options des `chunks`