Le notebook
et la programmation lettrée

Documenter ses traitements

Journées annuelles du réseau Mate-SHS, 17 mai 2022

Hugues Pecout (CIST, CNRS) - Timothée Giraud (RIATE, CNRS)
Sébastien Rey (IDEES, Université Rouen-Normandie)

Bonjour à tou·te·s

Ingénieurs CNRS en sciences de l’information géographique

    • Le langage R comme outil principal
    • Production régulière de notebook R
    • Responsables du projet Rzine

    • Ingénieur de recherche
    • Geomatique/Informatique
    • Coord. du GT Notebook
    • Membre du projet Rzine

Le notebook











Définition

Interface de programmation qui permet de combiner des sections en langage naturel et des sections en langage informatique

De nombreuses dénominations existent :

    • Article exécutable
    • Document computationnel
    • Document électronique interactif
    • Bloc-note
    • Cahiers de programmation
    • Cahier électronique d’analyse
    • Calepin électronique
    • Carnet de code
    • Manifeste algorithmique
    • Notebook !

Un notebook permet d’appliquer le paradigme de programmation lettrée, qui facilite le partage, le travail collaboratif et la reproductibilité

Une logique… des pratiques

La mise en forme du texte se fait à l’aide d’un langage de balisage (Markdown, html…)

Anatomie d’un notebook

Simple fichier texte

Notebook sans code ?

Stylo d’Human-Num

Développé par le CRC-EN avec le support Érudit et de la TGIR Huma-Num

Sinon, il existe beaucoup d’éditeurs libres (CodiMD…)

Le Markdown (Gruber, 2004)

Fichier Markdown (.md)

# Mon premier Markdown

![](https://gapn.hypotheses.org/files/2020/10/mate-300x61.jpg)

## Journées annuelles 2022 :satisfied:

-> Consultez [**le programme**](https://ja-mate2022.sciencesconf.org/resource/page/id/1) !

### A. Interventions pévues

1. *Le notebook et la programmation lettrée*
    - Notebook ?
    - Historique
    - Dernière génération
    - Notebook + Git
    - Exemple Quarto
    
3. *Le projet Rzine*
    - Le *projet Rzine*
    - Le [*site web*](rzine.fr)
    - La *collection*
    
### B. Intervenants

| Nom    | Prénom      | 
| ------ | ----------- |
| Giraud | Timothée    |
| Pecout | Hugues      | 
| Rey    | Sébastien   |


> Le texte brut balisé en Markdown reste lisible pour l'humain, se stocke dans un simple fichier texte et de nombreux outils libres permettent de l'éditer.

-> Visualiser sur HackMD

Texte mis en forme (sortie html)

Exemple de Notebook

Le Notebook Rmarkdown

Fichier source (.rmd)

---
title: "Documenter mes traitements"
output: html_document
---

<img src="https://gapn.hypotheses.org/files/2020/10/mate-300x61.jpg" width="100%">

## Introduction

Ce document présente une **chaîne de traitement statistique** appliquée à des données particulières...

### Les données 
Tableau de données utilisé :

```{r chunk1, eval=TRUE, echo=FALSE}
DT::datatable(cars,  options = list(pageLength = 5))
```

### Résumé statistique

```{r chunk2, eval=TRUE, echo=TRUE}
summary(cars)
```

## Visualisation

Visualisons les données, mais je ne vous montre pas mon code !

```{r plot, echo=FALSE, fig.height=4, fig.width=10}
plot(cars,
     pch = 20, 
     cex = 3, 
     col= "red")    
```

## Info session

```{r , echo=FALSE, fig.height=8, fig.width=10}
sessionInfo()    
```

Fichier en sortie (.html)

« Kniter » un .rmd











Les prémices

Ancêtres du notebook :

    • 1970 : Scratchpad (Axiom)
    • 1987 : MathCad
    • 1988 : Mathematica
    • 1989 : Maple
    • 2011 : IPython

Émergence de la recherche reproductible

En 1976, Jon Claerbout publie l’ouvrage :
Fundamentals of Geophysical Data Processing

Cette 1ère version, non-reproductible, sera le début d’un long travail de recherche sur la reproductibilité de ses travaux… Via des notebooks.

Émergence du Literate Programming

Le concept de programmation lettrée pensé et mis en oeuvre (1977-78) par Donald Knuth est lié à l’histoire des notebooks.

Programmation lettrée

La programmation lettrée est une approche de la programmation qui se veut différente du paradigme de programmation structurée.

Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
Donald Knuth, LP Website citations page

The practitioner of literate programming (…) strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding (…).
Donald Knuth, LP Website citations page

Le paradigme de la programmation lettrée, tel qu’il a été conçu par Knuth, s’éloigne dans son écriture de l’ordonnancement imposé par l’ordinateur, et à la place autorise les développeurs à utiliser un ordre imposé par la logique et le fil de leur pensée.

Multiplication des NB et des plateformes

S. Lau, I. Drosos, J. M. Markel and P. J. Guo, “The Design Space of Computational Notebooks: An Analysis of 60 Systems in Academia and Industry,” 2020 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC), 2020

Dernière génération

2022, l’année

Quarto permet l’utilisation de R, Python, Julia, Javascript (OJS)…

Programmation lettrée & Notebook


LP, Notebook & Reproductibilité











Git, GitHub, GitLab

Git est un système de gestion de version distribué pour :

    • tracker les changement dans les fichiers texte
    • gérer l’historique du code source
    • partager le code dans des dépots distants


GitHub et GitLab hébèrgent des dépots distants et des services pour gérer des projets (issue tracker, collaboration, hébergement web, CI/CD).

Notebook + Git

  • Les sources des notebooks sont des fichiers texte
    • ➡️ Suivi des modifications (commit, branches, etc.)
  • Certains ont besoin d’être compilé
    • ➡️ Continuous Integration
  • Certains peuvent être déployés sur le web
    • ➡️ Continuous Deployment

Exemple notebook Quarto




+ + + +




Cliquez-ici !











Conclusion

Un format de publication
scientifique légitime

Nombreux templates,
multiples usages

    • Article
    • Manuel
    • Rapports
    • Livre
    • Tutoriel
    • Cours - Exercice
    • Blog - Site web
    • curriculum vitae
    • Diaporama

Ceci est un notebook…

# Chargement des librairies
library(sf)
library(leaflet)

# Création d'un point (localisation centre des colloques)
ptsfg <- st_point(c(2.36652, 48.9071886))
ptsfc <- st_sfc(ptsfg, crs = (4326))
ptdf <- data.frame(id= 1, name = "Vous êtes ici !")
Here <- st_sf(ptdf,geometry = ptsfc)


# Affichage du point - carte interactive
mamap <- leaflet(Here, width = 950, height = 550) %>%
  addTiles() %>%
  addMarkers(data = Here, popup = "❤️mate-shs❤️")

Vous êtes ici !

Merci de votre attention


Diapositives libres (CC BY-SA 4.0)

Slides : https://huguespecout.github.io/notebook_mateshs/#/

Code source : https://github.com/HuguesPecout/notebook_mateshs


Contact

(GT Notebook)


@rzine_shs

Info session


## R version 4.2.0 (2022-04-22 ucrt)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows 10 x64 (build 25115)
## 
## Matrix products: default
## 
## locale:
## [1] LC_COLLATE=French_France.utf8  LC_CTYPE=French_France.utf8   
## [3] LC_MONETARY=French_France.utf8 LC_NUMERIC=C                  
## [5] LC_TIME=French_France.utf8    
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] leaflet_2.1.1 sf_1.0-7     
## 
## loaded via a namespace (and not attached):
##  [1] Rcpp_1.0.8.3       rstudioapi_0.13    knitr_1.39         magrittr_2.0.3    
##  [5] units_0.8-0        R6_2.5.1           rlang_1.0.2        fastmap_1.1.0     
##  [9] stringr_1.4.0      tools_4.2.0        revealjs_0.9       grid_4.2.0        
## [13] xfun_0.30          KernSmooth_2.23-20 cli_3.3.0          e1071_1.7-9       
## [17] DBI_1.1.2          jquerylib_0.1.4    crosstalk_1.2.0    htmltools_0.5.2   
## [21] class_7.3-20       yaml_2.3.5         digest_0.6.29      htmlwidgets_1.5.4 
## [25] sass_0.4.1         evaluate_0.15      rmarkdown_2.14     proxy_0.4-26      
## [29] stringi_1.7.6      compiler_4.2.0     bslib_0.3.1        classInt_0.4-3    
## [33] jsonlite_1.8.0