# Carnet (Notebook)

## Carnet du scientifique

Le carnet est depuis toujours utilisé par les scientifiques pour documenter leurs hypothèses, leurs expériences, leurs mesures et leurs analyses initiales ou leurs interprétations. C'est un outil d'aide  mémoire qui organise du texte, des formules mathématiques, des données ou des figures.

```{figure} /assets/img/carnets_historiques.png
:alt: Exemples de carnets historiques
:width: 80%
:align: center

Exemples de carnets scientifiques historiques
```

## Carnet électronique

```{image} /assets/img/carnet_electronique_structure.png
:alt: Exemple de notebook
:width: 60%
:align: right
```

Un carnet électronique est une succession ordonnée de **cellules**, tantôt en langage naturel, tantôt en langage informatique.

Les <span style="color:#aad400">**cellules en langage naturel**</span> se composent de texte formaté, d'expressions mathématiques, de tableaux de données et/ou de médias (images, vidéos ...).

Les <span style="color:#dd55ff">**cellules en langage informatique**</span> se composent d'une partie avec le code et d'une partie avec le résultat de l'exécution du code (données, graphiques...).

Mais au-delà de sa structure qui alterne texte enrichi et code informatique, la puissance du carnet électronique apparait lorsqu'il est manipulé par un logiciel adapté. Il permet à l'utilisateur de modifier le contenu des cellules et :
- pour une cellule de texte formaté, demander à voir le nouveau rendu, et 
- pour les cellules de code informatique, demander une nouvelle exécution en voir le nouveau rendu des résultats. 

```{admonition} Point fort de l'utilisation d'un carnet électronique
Réunir depuis la même interface utilisateur
- l'édition et la visualisation de textes enrichis,
- l'édition, visualisation et **exécution** de codes informatiques,
- la **visualisation des résultats** d'exécution du code informatique contenu dans une cellule.
```

Techniquement, pour obtenir cette interaction entre l'utilisateur et le carnet, les logiciels utilisés disposent de deux composantes

```{image} /assets/img/struct_authoring_appli.png
:width: 30%
:align: right
```

- un noyau d'exécution (*kernel*) qui assure l'exécution des cellules de code de programmation et renvoie les résultats
- une application avec deux aspects 
    - une interface utilisateur (*GUI* ou *front-end*) qui gère les interactions avec l'utilisateur
    - une dorsale (*back-end*) qui, selon les demandes de l'utilisateur, émet des requêtes d'exécution de code au noyau et met à jour le fichier qui stocke le carnet électronique.

Le logiciel Mathematica a été un pionnier dans l'utilisation des carnets électroniques en 1987 dans sa version 1.0. Il a popularisé cette approche interactive du calcul scientifique. 

```{figure} /assets/img/carnet_mathematica.png
:alt: Exemple de carnet Mathematica
:width: 60%
:align: center

Exemple de carnet Mathematica {cite:p}`wolfram_introducing_2023`
```

Cependant, encore aujourd'hui dans sa version *Wolfram Mathematica*, le format de ses carnets reste fermé et entièrement propriétaire, ce qui limite son usage pour l'échange entre scientifiques.

## Carnet Jupyter

### Structure d'un carnet Jupyter

Un carnet Jupyter (Jupyter notebook) est une structure de données ouverte ([nbformat](https://nbformat.readthedocs.io/)) contenant du texte, du code source, des résultats d'exécution (texte, figure, tableau...) et des métadonnées. Du point de vue de l'utilisateur, un carnet Jupyter est une succession de cellules de trois types différents :

- Texte brut (qui ne sera pas formaté)
- Texte formaté et enrichi d'expressions mathématiques des liens vers des images, des vidéos ... (langage de balisage Markdown)
- Code informatique (avec une partie dédiée aux résultats de l'exécution du code)

| type de cellule   | langage du contenu de la cellule |
| ----------------- | -------- |
| Texte brut       |   -   |
| Texte formaté     | [Markdown](https://daringfireball.net/projects/markdown/)  ([Tutoriel](https://www.markdowntutorial.com/))|
| Code informatique | Python, Julia, R, C++, Matlab ... |

L'illustration ci-après présente deux vues différentes d'un même carnet Jupyter. Ce dernier est constitué de deux cellules, la première est une cellule de texte au format Markdown et la seconde est une cellule de code Python. À gauche les cellules sont telles qu'elles sont éditées et à droite elles présentent leur rendu.

```{figure} /assets/img/notebook_lokta_volterra_compare.png
:width: 100%
:align: center
```

Un carnet Jupyter est sauvegardé dans un fichier à l'extension `.ipynb` (<font color="#f37726">**IPy**</font>thon <font color="#f37726">**n**</font>ote<font color="#f37726">**b**</font>ook). Le format de sauvegarde est basé sur le format texte ouvert [JSON](https://json.org/json-fr.html) (JavaScript Object Notation). Cela apporte deux avantages :

- grâce au format texte, le fichier d'un carnet Jupyter est bien adapté aux logiciels de gestion de versions (*version control system*) comme [CVS](https://cvs.nongnu.org/), [Mercurial](https://www.mercurial-scm.org/) ou [Git](https://git-scm.com/) [^note1].
- si nécessaire, le fichier d'un carnet Jupyter est facile à lire et à modifier par un humain avec un simple éditeur de texte, même si au quotidien, l'édition d'un carnet Jupyter se fait au moyen d'éditeurs spécialisés, par exemple "Jupyter Notebook" ou "Jupyter Lab".

[^note1]: Avec les mêmes cellules de texte et les mêmes cellules de code, un carnet peut avoir des sorties (résultats d'exécution) différentes à cause de données d'entrées différentes. Les logiciels de gestion de versions vont alors considérer que le carnet à changer de version, or tant que les cellules de texte et de code restent identiques, il est légitime de considérer que carnet reste dans la même version. Pour éviter de considérer ces versions identiques de carnets (hormis les sorties) comme des versions différentes, avant d'utiliser un logiciel de gestion de version, il est possible d'utiliser le script [`nbstripout`](https://github.com/kynan/nbstripout) qui permet la suppression des sorties et de certaines métadonnées d'un carnet, et l'écriture de la version « nettoyée » dans le fichier original. Pour éviter de lancer manuellement le script, `nbstripout` peut également configurer `git` pour lui demander d'agir systématiquement comme un filtre avant toutes opérations de comparaison.


### Exemples de carnets Jupyter en ligne

| Titre et lien | Description | Auteurs |
|---------------|-------------|---------|
| [Équations Lotka-Volterra](https://nbviewer.org/urls/gitlab.dsi.universite-paris-saclay.fr/bruno.denis/intro_jupyter/-/raw/main/notebooks/lokta_volterra.ipynb) | Exemple basic intégré à ce livre et déjà présenté ci-dessus | *Bruno Denis*, ENS Paris-Saclay, France |
| [Evaluation of a force sensor](https://nbviewer.org/github/agmarrugo/sensors-actuators/blob/master/notebooks/Ex6_4_evaluation_force_sensor.ipynb) | Analyse de résultat de mesure en travaux pratiques | *Andrés Marrugo*, Universidad Tecnológica de Bolívar, Bolivie |
| [Biharmonic equation and Stresses in Polar coordinates](https://nbviewer.org/github/jeevanjyoti4/elasticity/blob/master/PolarCoordinates_Definitions.ipynb) | Calcul symbolique pour obtenir l'équation $\left ( \frac{\partial^4}{\partial x^4} + 2 \frac{\partial^4}{\partial x^2\partial y^2} + \frac{\partial^4}{\partial y^4} \right ) \Phi = 0$ en coordonnées polaires| *Jeevanjyoti Chakraborty*, IIT , Inde |
| [Rigid-body transformations in a plane (2D)](https://nbviewer.org/github/demotu/BMC/blob/master/notebooks/Transformation2D.ipynb) | Cours interactif sur les transformations planes appliquées aux chaines cinématiques avec Python | *Marcos Duarte* et *Renato Naville Watanabe*, Federal University of ABC, Brésil |


## Cas d'utilisation courants

### Démonstration / présentation de calcul scientifique

Un carnet Jupyter permet de démonter l'opérationnalité d'un code en l'exécutant facilement devant un auditoire. Les données d'entrée peuvent être facilement modifiées pour illustrer à loisir le propos du présentateur ou de la présentatrice. Les résultats d'exécution peuvent être immédiatement présentés sous une forme lisible (graphique, tableau...). 

Il est également possible de transformer un carnet Jupyter sous la forme d'un élégant diaporama avec l'extension RISE.

### Partage de travaux reproductibles

Dans un contexte scientifique, il est important de montrer que des résultats proposés à la communauté sont reproductibles. Un carnet Jupyter permet de mêler narration et code. La narration explique comment reproduire les résultats pas à pas, alors que les codes à exécuter démontrent la reproductivité effective des travaux.

Au-delà de la reproductivité des travaux, il faut aussi assurer la reproductivité de l'environnement d'exécution pour s'assurer de la compatibilité de chaque bibliothèque intervenant dans l'exécution du code. Pour cela, le projet Jupyter propose Binder qui s'appuie sur les conteneurs Docker ce qui permet de partager à la fois le carnet et l'environnement d'exécution.

### Exploration en science des données

L'utilisation de carnets Jupyter répond particulièrement bien à certaines activités importantes de la science des données. 

- Collecte des données - lire des fichiers CVS, Excel et des bases de données SQL avec `Pandas`, extraire des données via des APIs web avec `Requests` ou moissonneur dans les sites web `Scrapy`
- Exploration des données (EDA) - analyser de manière exploratoire les données pour comprendre leurs principales caractéristiques en visualisant des données (tables avec `Pandas` et graphiques avec `Matplotlib`, `Plotly` ou `Seaborn`) et en recherchant des tendances et des relations (calcul statistique, corrélation avec `Numpy` ou `Scipy`).
- Sélection de modèles et entrainement - choisir les modèles de machine learning appropriés en fonction du problème à résoudre (régression, classification, clustering avec `Scikit-learn`, deep learning avec `TensorFlow` ou `Keras`) et entrainer ces modèles sur les données collectées.

### Utilisation en classe

Les carnets Jupyter sont à bien des égards bien adaptée à l'enseignement des technologies de l'information et des methodes numériques. Dans {cite:p}`al-gahmi_jupyter_2022`, les auteurs pointent les principaux usages de Jupiter en enseignement d'informatique à Weber State University dans l'état de l'Utah aux USA :
- lecture interactive,
- implémentation de programmes simples étape par étape
- correction par les étidiant(e)s de code erronés qui leur sont fournis,
- prise de notes interactive en classe,
- évaluations formatives à faible enjeu,
- évaluations sommatives.

Cependant Jupyter est un un outil qui s'écarte considérablement d'un éditeur de texte standard ou d'un environnement de développement intégré. Cela induit des  pièges potentiels surprenants, dans {cite:p}`johnson_benefits_2020` les auteurs abordent les forces et les faiblesses des carnet Jupyter pour l'enseignement, et recommandent un ensemble de bonnes pratiques.

Localement à l'Université Paris-Saclay la communauté Jupyter c'est strucutée autour du site https://jupyter.gitlab.dsi.universite-paris-saclay.fr/


### Calcul intensif

Les interfaces utilisateur riches comme Jupyter ont le potentiel de rendre l'interaction avec un supercalculateur plus facile et plus productive. 

Pour les utilisateurs et les utilisatrices scientifiques, l'interface utilisateur riche idéale offre une plateforme familière, réactive, introspective, modulaire et personnalisable sur laquelle ils peuvent construire, exécuter, capturer, documenter, réexécuter et partager des flux de travail.

 Du point de vue du fournisseur ou de l'administrateur système, Juyter est facile à configurer, à déployer en toute sécurité, à mettre à jour, à personnaliser et à prendre en charge. 
 
La philosophie de conception du projet Jupyter, qui repose sur l'extensibilité, l'abstraction et le déploiement agnostique, a permis à des centres de calcul intensif tels que le National Energy Research Scientific Computing Center d'introduire des capacités de calcul intensif avancées dans l'environnement du carnet Jupyter {cite:p}`barba_pythonjupyter_2021`, {cite:p}`thomas_interactive_2021`.