OD&IS

Created: March 5, 2025 5:54 PM type: documentation

DataForGood saison 13. OD&IS est une application permettant à l’association J’Accueille de visualiser des données utiles à l’insertion et l’implantation de personnes en situation de migration, vers des territoires adaptés à leurs besoins en termes de logement, santé, services publics, éducation etc…

Le but de ce projet est de récupérer et traiter les différentes sources de données utiles, de façon fiable, répétable et régulièrement mise à jour.

Installation

Pour prendre en main ce repository et installer les dépendances du projet :

• Guide d'installation

cp .env.dist .env
poetry install

Ce projet utilise une base de données PostgreSQL. Pour démarrer la base de données en local :

docker compose up -d

La base de données sera ensuite accessible sur localhost:5432

Pour initialiser ou réinitialiser la base de données :

poetry run python bin/db.py init

Approche : ELT + architecture médaillon

Pour récupérer les données et les modeler selon les besoins de J’Accueille, ce projet implémente une approche ELT : Extract-Load-Transform.

L’architecture de données est dite en "médaillon" avec trois niveaux de “maturité” des données : bronze (données brutes), silver (données nettoyées, recoupées) et gold (données traitées prêtes à l'emploi pour l’application).

Une approche ELT avec une architecture de données en médaillon, ça donne donc la suite de tâches suivante :

1. On extrait les données OpenData de toutes nos sources intéressantes ( = Extract )
2. On charge toutes ces données brutes dans la couche “bronze” de la base ( = Load )
3. On effectue toutes les transformations nécessaires pour aller de la couche Bronze à la Silver puis la Gold ( = Transform )

Utilisation

Extraction

L’extraction de données se fait grâce à des Extracteurs (des classes Python), qui se basent sur le fichier de configuration “datasources.yaml”, et appellent les différentes API ciblées.

Le fichier “datasources.yaml” répertorie toutes nos sources de données et est organisé autour de trois grandes notions :

• Les API sur lesquelles on va chercher la donnée ( APIs INSEE, API du ministère du logement, etc…)
• Les “Domaines” de donnée qui regroupent les jeux de données en thématiques : géographie, logement, emploi etc
• Au sein de chaque Domaine, des “Sources” qui représentent les informations sur les jeux de données précis à récupérer

Le script "odis.py” est le principal script en ligne de commande pour récupérer des jeux de données en choisissant un Domaine, et un ou plusieurs Sources. Par défaut, si on ne précise pas de Source, les données sont extraites pour toutes les Sources définies pour le Domaine choisi.

# Extraire tous les datasets source du domaine "geographical_references"
poetry run python bin/odis.py extract --domain geographical_references

# Extraire seulement les datasets "regions" et "departements du domaine "geographical_references"
poetry run python bin/odis.py extract --domain geographical_references --sources regions departements

Pour comprendre en détail comment ça fonctionne :

Comprendre la configuration déclarative des sources de données

Comprendre les Extracteurs de données

Sonder les sources disponibles

La commande “explain” permet de voir facilement comment les API, Domaines et Sources sont définis dans la configuration. Si l’option “explain” est passée, le script n’extrait aucune donnée mais montre seulement les infos sur les configurations demandées.

# Voir la liste des API, domaines et sources disponibles
poetry run python bin/odis.py explain

# Voir les définitions de tous les datasets source du domaine "geographical_references"
poetry run python bin/odis.py explain --domain geographical_references 

# Voir les définitions détaillées de l'API DiDo
poetry run python bin/odis.py explain --api DiDo

# Voir les définitions détaillées de plusieurs API INSEE
poetry run python bin/odis.py explain --api INSEE.Melodi INSEE.Metadonneees

# Voir les définitions détaillées d'une source de données et de son API
poetry run python bin/odis.py explain --api DiDo --domain logement --source dido_catalogue 

Chargement des données brutes

La commande "load" permet de charger un fichier local dans la base de données.

poetry run python bin/odis.py load --domain geographical_references --source regions

Télécharger la méthodologie et les modèles de données cibles

Il s'agit d'une méthodologie reprenant les opérations de transformation effectuées (manuellement) depuis les données sources. Puis d'un ensemble de csv qui correspondent aux données transformées cibles.

poetry run python ./common/utils/download_target_data.py

Lancer le projet DBT

Installation de dbt

pip install dbt-core
# Adapter pour PostgreSQL
pip install dbt-postgres
# Vérifier l’installation
dbt --version

Installation des dépendances

dbt deps

Se placer sur le dossier DBT pour commencer à travailler

(pour reconnaître votre dbt_project.yml)

cd dbt_odis

Toutes les commandes DBT intégrées directement dans la CI ici :

• Commandes DBT