index.qmd

---
title: "Un tableau de bord du trafic aérien avec {{< fa brands r-project >}} ou {{< fa brands python >}}"
number-sections: true
eval-r-chunk: true
filters:
   - include-code-files
---

```{=html}
<a href="https://datalab.sspcloud.fr/launcher/ide/rstudio?name=Funathon%202024%20-%20sujet%202&version=2.4.5&s3=default&kubernetes.role=«admin»&git.cache=«36000»&git.repository=«https%3A%2F%2Fgithub.com%2FInseeFrLab%2Ffunathon2024_sujet2»&networking.user.enabled=true&autoLaunch=false" target="_blank" rel="noopener"><img src="https://img.shields.io/badge/SSP%20Cloud-Ouvrir_dans_RStudio-blue?logo=rstudio&amp;logoColor=blue" alt="Onyxia"></a>
<a href="https://datalab.sspcloud.fr/launcher/ide/vscode-python?name=Funathon%202024%20-%20sujet%202&version=2.5.7&s3=default&kubernetes.role=«admin»&git.cache=«36000»&git.repository=«https%3A%2F%2Fgithub.com%2Finseefrlab%2Ffunathon2024_sujet2.git»&networking.user.enabled=true&autoLaunch=false" target="_blank" rel="noopener"><img src="https://img.shields.io/badge/SSP%20Cloud-Ouvrir_dans_VSCode-blue?logo=vscode&amp;logoColor=blue" alt="Onyxia"></a>
```

<br>


```{=html}
<table>
  <thead>
    <tr>
      <th>Niveau technique</th>
      <th>Enjeux</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><span class="level-button level-debutant">Débutant</span></td>
      <td>Suivre les consignes, tester les exemples, reprendre et comprendre les corrections. <b>Ne pas se préoccuper de la fin du tutoriel (l'ouverture vers la mise en production)</b>.</td>
    </tr>
    <tr>
      <td><span class="level-button level-intermediaire">Intermédiaire</span></td>
      <td>Chercher à faire les exercices et ne regarder les aides que si nécessaire. <b>Ne pas se préoccuper de la fin du tutoriel (l'ouverture vers la mise en production)</b>.</td>
    </tr>
    <tr>
      <td><span class="level-button level-expert">Expert</span></td>
      <td>Faire les premiers exercices en autonomie. <b>L'objectif principal est de faire la partie mise en production</b>.</td>
    </tr>
  </tbody>
</table>
```

{{< include "parts/01-intro.qmd" >}}


# Exploration des données de trafic aérien

Pour pouvoir proposer un tableau de bord pertinent, le premier geste à avoir
est d'explorer soi-même les données. L'objectif de cette partie est de guider
le travail exploratoire. Le travail ultérieur sur l'application visera à
consolider et généraliser ces explorations de données.


## Préliminaire : récupérer le projet squelette avec `Git` {{< fa brands git-alt >}}

{{< include "parts/02-recuperation.qmd" >}}


## Architecture du projet

Le projet récupéré comporte de nombreux fichiers. Nous allons
progressivement les découvrir dans ce tutoriel. A l'heure actuelle,
on peut se concentrer sur les fichiers suivants:

::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

```{.r}
funathon_sujet2/
├── renv.lock
├── correction/R/
├── correction/global.R
├── correction/server.R
└── correction/ui.R
```


Le premier fichier (`renv.lock`) correspond à la liste des _packages_ nécessaires
pour reproduire l'environnement. Il a été généré automatiquement grâce à
un écosystème `renv` particulièrement adapté pour assurer la reproductibilité
de projets {{< fa brands r-project >}} (voir la suite).

Les fichiers `server.R` et `ui.R` constituent le coeur de notre application
`Shiny`. Ils représentent, respectivement, le moteur de calcul (le serveur)
et l'interface utilisateur de notre application. Nous reviendrons sur ce concept. Le fichier `global.R` stocke
un certain nombre d'objets utiles à l'application mais qui n'ont pas besoin
d'être recalculés à chaque action sur l'interface graphique. Nous allons progressivement construire ces fichiers pendant les différents exercices. De nombreuses fonctions sont reportées dans les fichiers au sein du dossier `R/`.


<details>
<summary>
Observer la composition de ce fichier (100 premières lignes)
</summary>
```{.yaml include="renv.lock" filename="renv.lock" end-line=100}
```
</details>


## {{< fa brands python >}}

```{.r}
funathon_sujet2/
├── pyproject.toml
├── correction/src/
└── correction/app.py
```


Le premier fichier (`pyproject.toml`) correspond à la liste des _packages_ nécessaires
pour reproduire l'environnement. Il s'agit d'un
outil particulièrement adapté pour assurer la reproductibilité
de projets {{< fa brands python >}} (voir la suite).

Le fichier `app.py` constitue le coeur de notre application
`Streamlit`. Ils représentent, respectivement, le moteur de calcul (le serveur)
et l'interface utilisateur de notre application. Nous reviendrons sur ce concept. Par ailleurs, de nombreuses fonctions utiles pour l'application sont reportées dans les fichiers au sein du dossier `src/` (abréviation de "source").

<details>
<summary>
Observer la composition de ce fichier
</summary>
```{.yaml include="pyproject.toml" filename="pyproject.toml"}
```
</details>


:::





## Installer les _packages_ nécessaires pour ce tutoriel

{{< include "parts/03-restaurer.qmd" >}}


# Récupérer les données

## Objectifs

Dans cette partie, vous allez explorer les données utilisées pour construire le tableau de bord, avec trois objectifs:

- vous familiariser avec les sources statistiques sur le trafic aérien;
- développer des fonctions permettant d'importer automatiquement ces données;
- découvrir comment vous pouvez organiser ces fonctions pour qu'elles puissent être facilement utilisées par l’application web (_spoiler alert_: c'est là que le dossier `R/` ou `src/` va servir).

## Sources

Les sources statistiques utilisées dans ce tutoriel sont listées dans le fichier `sources.yaml`. Il y a quatre sources différentes:

- Le trafic au niveau de chaque aéroport (format _CSV_);
- Le nombre de passagers pour différentes liaisons (format _CSV_);
- Le trafic pour différentes compagnies (format _CSV_);
- Les localisations des aéroports (format _geojson_).

Une bonne pratique, lorsqu'on utilise plusieurs sources,
est de lister celles-ci dans un fichier `YAML` plutôt que de les inscrire
en brut dans le code. Ce dernier sera plus lisible grâce à cette approche.

<details>
<summary>

Voir le fichier `sources.yml`

</summary>
```{.yaml include="sources.yml" filename="sources.yml"}
```
</details>


## Importer la liste des sources disponibles

{{< include "parts/99-exo1.qmd" >}}

## Importer les premières bases

Nous pouvons maintenant utiliser cette fonction
pour lister tous nos URL des sources.

::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

```{r}
urls <- create_data_list("sources.yml")
```

## {{< fa brands python >}}

```{.python}
urls = create_data_list("sources.yml")
```

:::

{{< include "parts/99-exo2.qmd" >}}

# Exploration des données

```{r}
#| label: intermediates-exo2
#| echo: false
#| output: false
source("intermediates/exo2.R")
```

## Objectifs

Dans cette partie, vous allez exploiter les données pour produire trois valorisations qui seront ensuite intégrées dans l'application web:

1. un graphique dynamique présentant le trafic pour un aéroport donné;
2. un tableau HTML affichant des données sur le trafic;
3. une carte des aéroports.

Une fois que ces valorisations seront prêtes, nous pourrons nous pencher sur leur intégration dans une application interactive.

## Prérequis: créer le script `main`

Pour commencer, vous allez créer un fichier fichier `main.R` ({{< fa brands r-project >}}) ou `main.py` ({{< fa brands python >}}) à la racine du dépôt. Ensuite, vous pouvez y copier le code suivant.


::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

```{.r include="intermediates/exo3.R" end-line=26}
```

## {{< fa brands python >}}


```{.python include="intermediates/exo3.py" end-line=24}
```

:::::


## Valorisation 1: Le trafic par aéroport


```{r}
#| output: false
#| echo: false
source("intermediates/exo3.R")
```



La première valorisation qui sera intégrée dans l'application web est un graphique décrivant le trafic aérien au niveau d'un aéroport. Nous allon d'abord créer une figure minimale (avec `ggplot` {{< fa brands r-project >}} ou son équivalent {{< fa brands python >}} `plotnine`) pour vérifier que
nos données ont bien la dimension temporelle attendue. Cependant, comme `Shiny` est un système interactif, nous allons ensuite utiliser la librairie [`Plotly`](https://plotly.com/r/) pour faire des figures dynamiques: il s'agit d'une librairie `Javascript` qui peut être appelée grâce à des librairies clientes en {{< fa brands r-project >}} ou {{< fa brands python >}}.

{{< include "parts/99-exo3.qmd" >}}


## Valorisation 2: Tableau HTML pour afficher des données

La deuxième valorisation qui sera intégrée dans l'application web est un tableau
permettant de visualiser certaines données directement dans le _dashboard_.
Il existe plusieurs _packages_ pour faire cela, que ce soit en {{< fa brands r-project >}} ou {{< fa brands python >}}.

L'écosystème le plus
complet pour construire ce tableau est développé par `Posit` et
est quasi équivalent qu'on fasse du {{< fa brands r-project >}} ou du {{< fa brands python >}} (il est plus complet en {{< fa brands r-project >}} car plus ancien dans ce langage).
Il s'agit du _package_ [`GT`](https://gt.rstudio.com/) ({{< fa brands r-project >}}) ou [`Great Tables`](https://posit-dev.github.io/great-tables/articles/intro.html) ({{< fa brands python >}}). En peu de temps,
ces _packages_ sont devenus incontournables et proposent des fonctionnalités bien
plus complètes que les solutions qui existaient par le passé, notamment [`DT`](https://rstudio.github.io/DT/).


Pour le prochain exercice, vous pourrez utiliser les objets suivants. Copiez-les à la fin de votre script `main`.

::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

```{r}
#| echo: true
YEARS_LIST  <- as.character(2018:2025)
MONTHS_LIST <- 1:12
```

## {{< fa brands python >}}


```{.python}
YEARS_LIST = [str(year) for year in range(2018, 2023)]
MONTHS_LIST = list(range(1, 13))
```


:::::


{{< include "parts/99-exo4.qmd" >}}


## Valorisation 3: Carte des aéroports

La troisième valorisation qui sera intégrée dans l'application web est une carte interactive
du trafic de nos aéroports. Cette carte va être assez basique. Si vous
désirez mettre en oeuvre des visualisations plus complexes, vous pouvez
tout à fait le faire.

Pour cet exercice, nous allons fixer une date pour prototyper notre
code. Cela nous facilitera la transformation ultérieure en fonction.


::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

```{r}
month <- 1
year <- 2019
```

Voici également une palette de couleurs qui sera utile à la fin de l'exercice.

```{r}
palette <- c("green", "blue", "red")
```

## {{< fa brands python >}}

```{r}
month = 1
year = 2019
```

Voici également une palette de couleurs qui sera utile à la fin de l'exercice.

```{r}
palette = c("green", "blue", "red")
```

:::::


{{< include "parts/99-exo5.qmd" >}}

# Création de l'application

Maintenant tous les ingrédients sont là pour transformer cette chaîne en application
interactive. L'architecture de notre application sera la suivante :

![Architecture de notre application (ici illustrée par l'exemple {{< fa brands r-project >}})](img/ui-r.png)

Comme toute application _web_, `Shiny` ou `Streamlit` reposent sur deux piliers :

- l'interface utilisateur (UI) qui présente au navigateur des actions possibles et affiche des _output_ adaptés;
- le serveur qui répond à ces actions de l'utilisateur, produit les _outputs_ et les envoie à l'interface.

`Shiny` ou `Streamlit` fonctionnent un peu différemment dans la manière de faire interagir ces deux éléments:

- `Shiny` nécessite deux fichiers: un pour l'interface graphique (`ui.R`) et l'autre pour le serveur (`server.R`). L'aller-retour entre ces deux fichiers se fait par des objets communs, les _inputs_ du serveur (qui sont les éléments de l'interface graphique) et les _outputs_ du serveur (le résultat des calculs, à afficher sur la page web) ;
- `Streamlit` propose de tout mettre dans un fichier. Les éléments de l'interface graphique sont à la fois des _widgets_ qui seront représentés sur la page et des objets `Python` ayant une valeur correspondant à celle sélectionnée sur la page.


{{< include "parts/99-exo6.qmd" >}}

{{< include "parts/99-exo7.qmd" >}}




# Partager cette application : une ouverture vers la mise en production

<td><span class="level-button level-expert">Expert</span></td>

::: {.callout-warning}
## Difficulté technique de cette partie
Cette partie est __plus avancée__ car elle fait appel à des notions techniques assez complexes
dont certaines sortent, à proprement parler, du champ de compétences des _data scientists_.

Il est néanmoins fort utile de découvrir celles-ci afin d'être autonome dans la mise à disposition
de ses applications, un format de valorisation de plus en plus commun.
:::

Dans cette partie, on propose de déployer l'application sur le `SSPCloud` et de la rendre accessible depuis Internet. L'exercice constitue une introduction à la mise en production d'applications dans un environnement _cloud_. Pour aller plus loin, n'hésitez pas à consulter [ce cours de 3e année de l'ENSAE](https://ensae-reproductibilite.github.io/website/).



## Conteneurisation de l'application

Pour déployer son application, la première étape consiste à la [conteneuriser](https://ensae-reproductibilite.github.io/website/chapters/portability.html#les-conteneurs), ce qui signifie la mettre dans une sorte de boîte virtuelle contenant tout ce dont l'application a besoin pour fonctionner. Le conteneur sépare l'application de son environnement extérieur, ce qui permet d'éviter les conflits avec d'autres applications ou dépendances sur le même système. Puisque le conteneur contient tout ce dont l'application a besoin (comme les bibliothèques et les dépendances), l'application peut être déplacée et exécutée sur n'importe quel système qui supporte les conteneurs, sans se soucier des différences entre ces systèmes.

Ainsi, conteneuriser une application permet de la rendre plus facile à déployer, plus fiable et plus portable (en utilisant efficacement les ressources du système). `Docker` est un outil populaire pour créer et gérer des conteneurs. Le fichier `Dockerfile` contient le code nécessaire pour construire l'image `Docker` de l'application finale située dans le répertoire `correction`. Vous pouvez consulter la [documentation `Docker`](https://docs.docker.com/build/building/packaging/) pour tenter de comprendre comment l'image est construite.

Nous ne vous demandons pas de construire l'image vous-même, l'image est déjà publique sur [`Dockerhub`](https://hub.docker.com/r/inseefrlab/funathon2024-sujet2/) et peut-être utilisée pour déployer l'application. Néanmoins, il est intéressant, pour comprendre la logique de fonctionnement de Docker, de regarder la recette de construction de cette image

::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

```{.python include="docker/Dockerfile" filename="Dockerfile"}
```

## {{< fa brands python >}}

```{.python include="docker/Dockerfile_python" filename="Dockerfile"}
```

:::::


Les principales étapes de cette construction d'image sont les suivantes :

* 1️⃣ On part d'une image de base qui correspond à celle dans laquelle on a développé notre application et qui fonctionnait. On pourrait partir d'un environnement plus minimaliste (une machine Linux avec seulement `R` installé, comme les images [`rocker`](https://rocker-project.org/)) mais nous aurions peut-être à installer des librairies système en plus par un processus d'essai-erreur coûteux en temps.

::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.python include="docker/Dockerfile" filename="Dockerfile" end-line=1}
```

</details>

## {{< fa brands python >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.python include="docker/Dockerfile_python" filename="Dockerfile" end-line=1}
```

</details>


:::::



* 2️⃣ On ajoute dans le conteneur les fichiers indispensables au fonctionnement de notre application. Le conteneur, par défaut, n'a pas les fichiers de notre projet, on doit donc dire à `Docker` quels fichiers on désire avoir dans notre application.

::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.r include="docker/Dockerfile" filename="Dockerfile" start-line=3 end-line=10}
```

</details>


## {{< fa brands python >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.python include="docker/Dockerfile_python" filename="Dockerfile" start-line=3 end-line=10}
```

</details>

:::::


* 3️⃣ On définit des paramètres sur le routage de notre application dans le conteneur (seulement nécessaire pour la solution {{< fa brands r-project >}}). Ces paramètres nous seront utiles ultérieurement, lors du déploiement.

::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.r include="docker/Dockerfile" filename="Dockerfile" start-line=13 end-line=16}
```

</details>

## {{< fa brands python >}}

Cette étape n'est pas nécessaire.

:::::

* 4️⃣ On restaure l'environnement avec `renv` ({{< fa brands r-project >}}) ou `uv` ({{< fa brands python >}}). De cette manière, on est assuré que l'application aura le même environnement que celui que nous avons prévu lors de la phase de développement.

::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.r include="docker/Dockerfile" filename="Dockerfile" start-line=18 end-line=18}
```

</details>

## {{< fa brands python >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.python include="docker/Dockerfile_python" filename="Dockerfile" start-line=13 end-line=14}
```

</details>

:::::


* 5️⃣ On définit la commande qui sera exécutée au lancement de notre application. En l'occurrence, c'est une ligne de commande Linux pour lancer l'application `Shiny` ou `Streamlit`

::::: {.panel-tabset group="language"}

## {{< fa brands r-project >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.r include="docker/Dockerfile" filename="Dockerfile" start-line=20 end-line=21}
```

</details>

## {{< fa brands python >}}

<details>
<summary>
Partie du `Dockerfile` en question
</summary>

```{.python include="docker/Dockerfile_python" filename="Dockerfile" start-line=16 end-line=17}
```

</details>

:::::

Si le `Dockerfile` est la recette pour créer notre application, où se trouve la cuisine pour préparer
notre plat ? En général, on passe par des systèmes d'intégration continue, des serveurs mis à disposition
en complément de forges `Git` pour tester le `Dockerfile`. Pour en savoir plus sur l'intégration continue,
vous pouvez consulter le [cours de 3e année de l'ENSAE](https://ensae-reproductibilite.github.io/website/chapters/portability.html#les-conteneurs).

Voici le fichier `.github/workflows/app.yaml` qui contient la suite d'instruction donnée aux serveurs
de `Github` pour exécuter notre chaine de production de l'image `Docker`. Celui-ci est quasiment une reprise mot pour mot de l'exemple de la [documentation Github](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action).

<details>
<summary>
Le _workflow_ `Github` en question ({{< fa brands r-project >}} et {{< fa brands python >}})
</summary>

```{.python include=".github/workflows/app.yaml" filename=".github/workflows/app.yaml"}
```

</details>

## Utilisation de l'image Docker pour mettre à disposition le `Shiny` ou `Streamlit`

Nous avons créé une image Docker qui est disponible sur Dockerhub, le réseau social de Docker.
Pour rendre celle-ci vivante, nous devons la déployer dans un conteneur.

::: {.callout-tip collapse="false" icon=false}
## `<i class="bi bi-book"></i>`{=html} Exercice 7 : Déploiement de l'application Shiny

L'image peut à présent être récupérée et déployée. Dans notre cas, on va la déployer sur un cluster Kubernetes, l'infrastructure sous-jacente du SSP Cloud. Le fonctionnement de Kubernetes est technique et nous ne rentrerons pas dans les détails ici. Les fichiers nécessaires au déploiement se trouvent dans un dépôt séparé (https://github.com/InseeFrLab/funathon2024_sujet2_cd), nommé dépôt [Git-ops](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action).

Afin de déployer l'application, suivre les instructions suivantes :

- Ouvrir un `Terminal`;
- Clôner le dépôt (`git clone https://github.com/InseeFrLab/funathon2024_sujet2_cd`)
- Se placer à la racine du projet (`cd funathon2024_sujet2_cd`);
- Inspecter les fichiers `shiny/deployment.yml`, `shiny/service.yml` et `shiny/ingress.yml` (parcours {{< fa brands r-project >}}) ou `streamlit/deployment.yml`, `streamlit/service.yml` et `streamlit/ingress.yml` (parcours {{< fa brands python >}}) et repérer les éléments suivants :
    - L'emplacement où est spécifié l'image à déployer;
    - L'emplacement où sont spécifiées les ressources computationnelles allouées;
    - L'emplacement où est spécifiée l'URL à laquelle sera exposée l'application sur Internet. La modifier (à 2 reprises) pour y indiquer une adresse personalisée pour le déploiement. Seule contrainte, elle doit être de la forme `*.lab.sspcloud.fr`;
- Appliquer les contrats Kubernetes avec la commande `kubectl apply -f shiny/` ou `kubectl apply -f streamlit/` selon le langage utilisé ;
- Vérifier le lancement du conteneur avec la commande `kubectl get pods`. Le nom associé devrait être de la forme `funathon2024-sujet2-deployment-*`;
- Attendre que le conteneur obtienne le statut `Running`.
- Copier le nom associé à votre service et faire `kubectl logs <nom_copié>`.

3. Entrer dans un navigateur l'URL spécifiée dans le fichier `streamlit/ingress.yaml` ou `shiny/ingress.yaml`, et vérifier que l'application fonctionne correctement ! Jouer avec et observer, dans le terminal que vous aviez ouvert, l'évolution de vos _logs_ quand vous faites une action.
:::