Ce projet, développé par des bénévoles de Data For Good lors de la saison 13, vise à créer une carte interactive pour Générations Futures.
L'objectif est de consolider, analyser et cartographier les données sur la qualité de l'eau potable en France à partir de sources de données ouvertes.
pipelines/
: Consolidation et préparation des donnéesanalytics/
: Analyse des donnéeswebapp/
: Développement du site web interactif
Ce projet utilise uv pour la gestion des dépendances Python. Il est préréquis pour l'installation de ce projet.
Installation sur Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Installation sur Mac ou linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Une fois installé, il suffit de lancer la commande suivante pour installer la version de Python adéquate, créer un environnement virtuel et installer les dépendances du projet.
uv sync
A l'usage, si vous utilisez VSCode, l'environnement virtuel sera automatiquement activé lorsque vous ouvrirez le projet. Sinon, il suffit de l'activer manuellement avec la commande suivante :
source .venv/bin/activate
Ou alors, utilisez la commande uv run ...
(au lieu de python ...
) pour lancer un script Python. Par exemple:
uv run pipelines/run.py run build_database
Allez dans settings, python interpreter, add interpreter, puis selectionnez existing venv et allez chercher le path du python executable dans .venv (.venv/Scripts/Python.exe pour windows)
utilisez les commandes uv run
pour lancer un script Python depuis votre terminal
- Installation de Node.js (pour le développement du site web)
Pour le développement du site web, il est nécessaire d'installer Node.js. Pour cela, il suffit de suivre les instructions sur le site officiel.
Pour installer les dépendances du site web, il suffit de lancer les commandes suivantes :
cd webapp
npm install
Tout le code dans pipelines sera installé en tant que package python automatiquement à chaque uv_sync
Une fois l'environnement python setup avec uv, vous pouvez lancer data_pipeline/run.py pour remplir la database
Le téléchargement des données peut se faire de plusieurs manières :
- Téléchargement des données de la dernière année (par défaut)
uv run pipelines/run.py run build_database --refresh-type last
- Téléchargement de toutes les données
uv run pipelines/run.py run build_database --refresh-type all
- Téléchargement de données d'années spécifiques
uv run pipelines/run.py run build_database --refresh-type custom --custom-years 2018,2024,...
- Suppression des tables, puis téléchargement des données de la dernière année
uv run pipelines/run.py run build_database --refresh-type last --drop-tables
La librarie dbt est celle choisie pour une construction rapide et simple de modèles de données optimisé pour l'analytics.
🚩Remarque : Pour lancer chaque commande individuellement, veillez à bien vous placer dans le dossier dbt_ (cd dbt_
) avant de lancer les commandes.
La commande uv run dbt deps
permet de télécharger les dépendances du projet dbt.
Exécutée lors de la création de la base de données, la commande uv run dbt build
est une commande qui permet de réaliser l'ensemble des actions suivantes :
- Lancer la création des tables issues des données brutes (
uv run dbt run
) - Réaliser les test de qualité des données (
uv run dbt test
) - Mettre sous forme de table les fichiers csv ajoutés dans le dossiers seeds (
uv run dbt seed
)
Une autre commande uv run dbt docs generate
permet de générer la documentation des modèles de données renseignée dans les fichiers _xxx__models.yml
au format html. L'utilisation de la commande uv run dbt docs serve
permet de lancer un serveur local pour visualiser la documentation.
Pour plus d'informations concernant la manière d'organiser un projet dbt, se référer à la documentation officielle et notamment à la section .
Les modèles de données sont organisés dans le dossier dbt_/models
. La structure suit les recommandations de la documentation officielle. Il est conseillé prendre le temps la lire afin de bien comprendre la structure du projet:
- models/staging/ : Modèles de données avec des transformation basiques (TRIM, REPLACE, typage, ...). Cette couche est surtout utilisée pour faire un état des données existantes, les documenter et tester la qualité.
- models/intermediate/ : Modèles de données avec des transformation plus complexes (GROUP BY, JOIN, WHERE, ...). Cette couche est surtout utile pour faire une jointure entre les différentes tables et faire un premier filtrage des données. Celle-ci est très utile pour de l'analyse de données
- models/analytics/ : Modèles de données final, qui est requêter par le site web pour construire les visualisations. Cette donnée est propre et la schématisation des données est optimisée pour le chargement des visualisations.
La documentation du projet dbt est disponible sur le lien suivant: documentation dbt
Vous pouvez simplement télécharger la base de données en cliquant sur le lien de téléchargement suivant: https://pollution-eau-s3.s3.fr-par.scw.cloud/prod/database/data.duckdb
Vous pouvez également lancer la commande suivante :
uv run pipelines/run.py run download_database
Elle téléchargera la base, et la placera à l'emplacement utilisé par tout le monde (à savoir, database/data.duckdb
). Un raccourci pour cette commande est accessible en un clic dans la barre des tâches de VS Code (ligne tout en bas) : "Download Dabatase".
Depuis Scaleway via boto3 pour stockage objet S3
Des versions de développement et de production de la base de données sont à disposition sur le stockage object.
Un module a été créé dans storage_client.py pour faciliter la connection au S3 hébergé sur Scaleway. Il faut bien configurer ses credentials Scaleway et son environnement. Pour cela, il faut créer un fichier .env
dans le dossier pipelines/config, avec les secrets ci-dessous dedans pour que la connexion fonctionne :
SCW_ACCESS_KEY={ACCESS_KEY}
SCW_SECRET_KEY={SECRET_KEY}
où {ACCESS_KEY}
et {SECRET_KEY}
sont les credentials obtenus via le coffre-fort vaultwarden mis en place (pour cela, il suffit de demander à un chef de projet sur Slack).
Vous trouverez un exemple avec le fichier .env.example
⚠ Attention: Ne jamais faire de commit des access key et secret key.
Une fois les credentials obtenus et mis dans le fichier pipelines/config/.env
, vous pouvez alors lancer la commande suivante :
uv run pipelines/run.py run download_database --use-boto3
Vous pouvez également spécifier l'option --env {dev|prod}
.
Le notebook test_storage_utils.ipynb montre un exemple d'utilisation de l'utils pour charger et lire des csv sur le bucket S3 du projet.
Les analyses se font via jupyter notebook
uv run jupyter notebook
Pour lancer les tests, il suffit de lancer la commande suivante à la racine du projet:
uv run pytest -s
L'option -s
permet d'afficher les prints dans le terminal.
Lancer la commande suivante pour s'assurer que le code satisfait bien tous les pre commit avant de créer votre pull request
pre-commit run --all-files
Pour contribuer, il est recommandé d'utiliser un fork du projet. Cela permet d'éviter la gestion des demandes d'accès au dépôt principal.
- Dans un premier temps, cliquez sur Fork pour récupérer le projet dans votre espace GitHub.
- Créez votre branche de travail à partir de la branche main, en respectant la nomenclature suivante :
- feature/nom_de_la_feature pour une nouvelle fonctionnalité
- hotfix/nom_du_hotfix pour une correction rapide
- Poussez votre code vers votre dépôt distant.
- Créez une pull request en spécifiant :
- Base repository : dataforgood/13_pollution_eau/main
- Head repository : YourGithubAccount/13_pollution_eau/your_branch
- Pour faciliter la revue de la pull request :
- Liez la pull request à un ticket NocoDB en ajoutant le lien du ticket dans la description.
- Rédigez une description détaillée de la pull request afin de fournir un maximum d’informations sur les modifications apportées.