Workflow projet xyt_gps¶
Cette page décrit la structure cible du projet et la correspondance entre les notebooks prêts à l'emploi, les tables multi-fichiers et les fonctions du package.
Principe général¶
Le package se lit plus simplement en cinq blocs :
| Bloc | Objet principal | Sortie typique |
|---|---|---|
| 1. Préparer l’entrée | homogénéiser les sources GPS avant usage du package | landing_dir |
| 2. Transformer | produire les tables de mobilité structurées | MobilityDataset, transformed_dir |
| 3. Contrôler | qualifier le suivi, le signal GPS, les utilisateurs et les états intermédiaires | rapports qualité, participation, filtres utilisateurs |
| 4. Produire les indicateurs | enrichir CO2/santé et calculer les indicateurs génériques | IndicatorResult, enriched_dir |
| 5. Exporter la base propre | consolider les tables transformées, enrichies et cartographiques | clean_dir, GeoParquet, H3, DuckDB, HTML |
Le package xyt_gps doit rester utilisable étape par étape. L'orchestrateur prepare_mobility_dataset() est utile, mais chaque étape importante doit aussi exister comme fonction explicite afin de pouvoir contrôler les états intermédiaires.
Les notebooks de production de ce dépôt sont rangés dans
Notebooks/Package-ready/ avec une numérotation continue : landing, loading,
qualité, spatial, enrichissement et indicateurs. Pour un nouveau projet, voir
la page Structure de projet recommandée.
À partir du loading, une exécution traite une seule expérience. Les sorties sont
rangées sous 2-transformed-data/<experiment_name>,
3-enriched-data/<experiment_name> et 4-clean-data/<experiment_name>. Cette
organisation réduit les ambiguïtés de configuration lorsque les phases ou les
règles de suivi diffèrent entre expériences. Les analyses multi-expériences
concatènent ensuite les bases propres au début des notebooks thématiques.
Le package ne couvre pas les analyses thématiques finales. Il doit aller jusqu'à la production d'une base de mobilité analysable : tables de mobilité structurées, indicateurs génériques, enrichissements transversaux documentés et exports.
Périmètre cible¶
| Bloc | Rôle | Dans le package |
|---|---|---|
| 1. Préparer l’entrée | homogénéiser les sources et produire une base prête à ingérer | support par notebooks et utils hors coeur package |
| 2. Transformer | transformer les exports GPS en objets de mobilité contrôlés | oui |
| 3. Contrôler | diagnostiquer suivi, signal GPS, outliers, zones et participation | oui |
| 4. Produire les indicateurs | préparer les enrichissements CO2/santé et les indicateurs génériques | oui |
| 5. Préparer les exports dashboard | produire GeoParquet, H3, DuckDB et cartes HTML | oui, comme couche optionnelle |
| analyses thématiques | figures, interprétations et analyses spécifiques | non |
Les enrichissements CO2 et santé doivent être intégrés avec le même principe que la préparation des données : fonctions petites, paramètres explicites, docstrings courtes, documentation des hypothèses et notebooks d'exemple. Ils ne doivent pas contenir l'interprétation thématique finale.
Repères historiques¶
La documentation d’usage emploie les termes landing, préparation,
contrôle qualité, spatial, enrichissement, indicateurs et export
analytique. Les correspondances avec les anciens notebooks sont conservées dans
la page de maintenance Migration des notebooks historiques.
Structure des données GPS¶
La base GPS est multi-fichier. Les tables principales sont :
| Table | Rôle | Identifiants importants |
|---|---|---|
storyline |
table brute ou landed contenant les segments Stay et Track |
storyline_id, id, user_id, trip_id si disponible |
staypoints |
activités ou arrêts dérivés de storyline |
activity_id, user_id |
legs |
déplacements élémentaires dérivés de storyline |
leg_id, user_id, user_id_day, trip_id si disponible |
trips |
niveau déplacement fourni ou reconstruit | trip_id, user_id, journey_id après matching |
journeys |
niveau journée ou chaîne de déplacements fourni | journey_id, user_id |
user_stats |
statistiques et informations utilisateur | user_id |
public_transport_legs |
enrichissement optionnel | identifiant leg ou trip selon fournisseur |
map_track_trip_journey |
table de construction | leg_id, trip_id, journey_id |
map_legs_staypoints |
table de construction | previous_leg_id, activity_id, next_leg_id |
Les tables doivent pouvoir être liées par identifiants stables. Les tables de construction sont conservées pour rendre les jointures vérifiables. Quand une relation source est incomplète, la table de mapping garde le leg_id mais laisse la clé parente à NA plutôt que de créer un lien invalide.
user_stats est la table de suivi à l'échelle utilisateur. Si une personne est présente dans user_statistics mais n'a aucune trace exploitable dans storyline, elle est conservée avec active_days_count = 0. Cela permet de distinguer absence de tracking et absence de ligne dans les données.
Sorties de production¶
La chaîne actuelle produit plusieurs niveaux de sortie. Le package n'impose pas leur emplacement : les notebooks doivent définir des variables de chemin au début du traitement.
| Variable | Exemple de dossier | Contenu | Usage |
|---|---|---|---|
landing_dir |
data/outputs/0-landed-data/<experiment_name>/complete |
tables homogénéisées, manifest, README, user_presence, column_alias_report, rapports de colonnes |
base prête à ingérer |
anonymized_landing_dir |
data/outputs/0-landed-data/<experiment_name>/anonymized |
copie anonymisée si le projet en produit une | validation sans exposer les données personnelles directes |
transformed_dir |
data/outputs/2-transformed-data/<experiment_name> |
storyline, legs, staypoints, trips, journeys, user_stats, user_presence, mappings, qualité et participation |
base structurée de mobilité |
spatial_analytics_dir |
data/outputs/2-transformed-data/<experiment_name>/spatial-analytics |
points de legs indexés H3 et fréquentation par cellule | carte de fréquentation simple à partir des legs transformés |
enriched_dir |
data/outputs/3-enriched-data/<experiment_name> |
legs_enriched, tables CO2/santé, indicateurs, rapports QA, figures HTML |
enrichissements et indicateurs génériques |
clean_dir |
data/outputs/4-clean-data/<experiment_name> |
tables de mobilité propres, legs enrichis, indicateurs personne-jour, H3, DuckDB, manifest | base analysable pour les notebooks thématiques et dashboards |
clean_spatial_dir |
data/outputs/4-clean-data/<experiment_name>/spatial-analytics |
agrégations H3 enrichies et matrice large de counts | requêtes dashboard, filtres analytiques, prototypes SQL |
Les contrôles clés exportés avec 3-enriched-data sont :
qa_key_checks.csv: clés manquantes, uniques et dupliquées ;qa_link_checks.csv: liens invalides ou absents entre tables ;qa_phase_coverage.csv: lignes par table et par phase, y comprisOther;qa_analysis_scope.csv: volume conservé dans le périmètre analytique.
Data-landing¶
Bloc 1 du package.
Objectif : ouvrir des sources hétérogènes et produire des tables landed homogènes.
| Étape | Fonction ou notebook | Statut |
|---|---|---|
| ouvrir les fichiers sources | Notebooks/Package-ready/00_data_landing.ipynb et Notebooks/Package-ready/utils/data_landing.py |
en place |
| concaténer plusieurs fichiers bruts | build_landed_tables() |
en place |
| conserver les configs de base | landing_config.json |
en place |
| produire un manifest | landing_manifest.json |
en place |
produire user_presence |
build_user_presence() |
en place |
| produire un README de livraison | write_landing_output() |
en place |
| détecter les colonnes alias ou dupliquées | scan_landing_alias_columns() |
en place |
| vérifier le schéma attendu | xyt.expected_gps_schema() |
en place dans le notebook landing |
| harmoniser ou compléter les colonnes attendues | fonctions landing utils | partiel, à documenter source par source |
Le landing doit accepter des données avec ou sans expérience et avec ou sans phase. Si les phases existent, elles sont décrites dans la configuration. Si elles n'existent pas, le loading doit fonctionner avec un ProjectConfig() minimal.
Data-loading¶
Bloc 2 du package.
Objectif : charger les tables landed et construire les tables de mobilité inspectables.
| Étape | Fonction package | Paramètres principaux | Statut |
|---|---|---|---|
| charger les tables landed | pandas.read_parquet(), pandas.read_csv() |
chemins landing_dir |
notebook |
| revérifier le schéma | expected_gps_schema(), check_raw_import_columns(), validate_gps_raw() |
trips, journeys, raise_on_error |
en place |
| contrôler et nettoyer les nulls critiques | prepare_storyline() |
drop_nan_threshold=0.01 |
en place |
| parser EWKB en Shapely | prepare_storyline() |
target_crs |
en place |
| parser les dates | prepare_storyline(), prepare_trips(), prepare_journeys() |
colonnes connues | en place |
| agréger modes et motifs | mode_purpose_mapping(), apply_storyline_mappings(), apply_trip_journey_mappings() |
mappings par table et niveau | en place |
| gérer phases et expériences | ProjectConfig, Phase, concat_mobility_datasets() |
experiment_name, phases |
en place pour phases par expérience |
| resampler les jours manquants | resample_missing_stays() |
resample_missing_days |
en place |
| distinguer jours observés et resamplés | build_user_stats() |
resampled_days_count, observed_active_days_count |
en place |
enrichir user_stats |
build_user_stats() |
user_statistics, sociodemo, weights |
en place partiel |
| pondérer | build_user_stats() |
weights, weight_col, default_weight=1.0 |
en place |
| scinder storyline | split_storyline() |
aucun | en place |
ajouter user_id_day |
add_user_id_day() |
aucun | en place |
| ajouter durée aux legs et staypoints | split_storyline() |
dates de début/fin | en place |
| flagger valeurs extrêmes | add_length_quantile_flags() |
quantiles, group_col, length_col |
en place |
| matcher legs, trips, journeys | build_track_trip_journey_map() |
tolerance, trip_id si disponible |
en place |
| matcher legs et staypoints | build_legs_staypoints_map() |
tolerance |
en place |
| propager excursions | add_excursion_flags_to_trips_journeys(), add_excursion_stats_to_user_stats() |
excursion_col |
en place |
| calculer excursions géographiques | add_excursion_flags() |
area, area_path, center, radius_m, mode |
en place |
| exporter les tables transformées | write_mobility_dataset() |
formats=("parquet", "csv", "pickle"), extra_tables={...} |
en place |
| exporter les tables spatiales dashboard | legs_to_h3_points(), aggregate_h3_frequencies(), write_spatial_analytics_exports() |
h3_resolution, sample_distance_m, frequency_group_cols |
en place optionnel |
| produire une base SQL locale | write_duckdb_spatial_database() |
load_spatial, require_spatial_extension |
en place optionnel |
| exporter participation | build_weekly_participation_grid() |
exclude_resampled=True |
en place dans notebook |
| contrôler la qualité du suivi | build_tracking_gap_report(), summarize_leg_lengths_by_mode(), build_user_confirmation_rates() |
notebooks de diagnostic | en place |
| nettoyer/enrichir spatialement | add_spatial_zone_labels(), add_leg_origin_destination_zones(), classify_leg_relation_to_area() |
zones, CRS, seuils signal | en place optionnel |
Enrichissements et indicateurs¶
Bloc 4 du package.
Après la préparation des données, le package doit préparer les enrichissements nécessaires aux indicateurs génériques, sans basculer dans l'analyse thématique.
| Étape | Entrées | Sorties attendues | Principe |
|---|---|---|---|
| enrichissement CO2 | legs, trips, journeys, mappings de modes, facteurs CO2, taux d'occupation |
émissions par leg et agrégations personne-jour ou période | facteurs visibles et sourcés |
| enrichissement santé | legs, modes, durées, distances, vitesses, hypothèses METs ou calories |
indicateurs santé élémentaires par leg et agrégations | hypothèses paramétrables |
| indicateurs et export analytique | tables enrichies | base de mobilité analysable et export final | indicateurs génériques, non interprétation thématique |
Le notebook de référence pour ce niveau est :
Il lit transformed_dir, calcule les enrichissements, exporte enriched_dir
et produit des visualisations HTML compatibles avec le design du dashboard.
Le notebook Notebooks/Package-ready/05_export_cleaned_dataset.ipynb consolide
ensuite transformed_dir et enriched_dir dans clean_dir. Les notebooks
thématiques lisent uniquement clean_dir / "cleaned-base".
La base finale est rangée par usage : cleaned-base pour les tables de mobilité
directement analysables, indicators pour les indicateurs, spatial-analytics
pour H3 et cartes, qa-reports pour les contrôles, reference-data pour les
référentiels, metadata pour les manifests, figures pour les exports HTML et
database pour DuckDB.
Exports dashboard¶
Bloc 5 du package.
Ce bloc transforme les données déjà préparées en formats adaptés aux plateformes de visualisation et aux requêtes analytiques :
| Besoin | Fonction | Sortie |
|---|---|---|
| points de legs indexés H3 | legs_to_h3_points() |
leg_points_h3 |
| fréquentation par cellule et dimensions | aggregate_h3_frequencies() |
h3_frequency |
| counts larges par mode, motif et tranche horaire | build_h3_count_matrix() |
h3_count_matrix |
| construction complète des tables spatiales | build_spatial_analytics_tables() |
dictionnaire de tables |
| export spatial dashboard | write_spatial_analytics_tables() |
fichiers .parquet et .csv par défaut, .pkl optionnel |
| base SQL locale | write_duckdb_spatial_database() |
fichier .duckdb |
| carte de contrôle | plot_h3_frequency_map() |
HTML interactif |
Les paramètres structurants sont h3_resolution, time_slices,
frequency_group_cols, count_dimension_sets et sample_distance_m.
Paramètres structurants¶
Les paramètres à définir explicitement au début du loading sont :
| Paramètre | Exemple | Rôle |
|---|---|---|
project_root |
Path("..").resolve() |
racine du projet d'analyse, pas du package |
data_root |
project_root / "data" |
racine locale des données, ignorée par git |
output_root |
data_root / "outputs" |
racine des tables produites |
experiment_name |
declic-mobility-vague1 |
identifie l'expérience traitée par l'exécution courante |
landing_dir |
output_root / "0-landed-data" / experiment_name / "anonymized" |
source des tables landed |
transformed_dir |
output_root / "2-transformed-data" / experiment_name |
destination des tables structurées de mobilité |
enriched_dir |
output_root / "3-enriched-data" / experiment_name |
destination des enrichissements, indicateurs et figures |
clean_dir |
output_root / "4-clean-data" / experiment_name |
destination de la base propre finale pour analyses thématiques |
spatial_analytics_dir |
transformed_dir / "spatial-analytics" |
destination des points H3 et agrégats spatiaux |
h3_resolution |
9 |
taille des cellules pour les cartes de fréquentation |
sample_distance_m |
None ou 50 |
utilise les sommets des legs ou échantillonne les lignes |
phases |
Phase("Phase1", "2025-01-01", "2025-01-21") |
optionnel, découpage analytique |
mappings |
xyt.mode_purpose_mapping() |
regroupement modes et motifs |
drop_nan_threshold |
0.01 |
seuil de nulls critiques acceptable |
RESAMPLE_MISSING_DAYS |
True |
ajoute des Resampled_stay |
ADD_EXCURSION_FLAGS |
False par défaut |
active une règle géographique d'excursion |
EXCURSION_CENTER |
(6.1558, 46.2073) |
centre si règle par cercle |
EXCURSION_RADIUS_M |
350000 |
rayon en mètres |
weight_col |
weight |
pondération utilisateur |
Nommage des fonctions¶
Le package suit les conventions Python :
| Élément | Convention | Exemple |
|---|---|---|
| fonctions | snake_case |
prepare_storyline() |
| classes et dataclasses | PascalCase |
ProjectConfig |
| constantes | UPPER_CASE |
GPS_SCHEMAS |
| helpers internes | _snake_case |
_phase_week_calendar() |
Les noms publics doivent rester génériques lorsque la fonction ne dépend pas strictement d’un fournisseur GPS. Par exemple :
- utiliser
expected_gps_schema()dans les notebooks ; - utiliser
validate_gps_raw()pour valider les tables brutes ; - utiliser
prepare_mobility_dataset()pour construire leMobilityDataset; - utiliser
mode_purpose_mapping()pour créer une configuration de mapping lisible ; - garder
MobilityMappingscomme dataclass de configuration avancée.
Couverture de la séquence demandée¶
| Point demandé | Couverture actuelle |
|---|---|
| ouvrir, concaténer et documenter les sources | couvert dans Notebooks/Package-ready/00_data_landing.ipynb et Notebooks/Package-ready/utils/data_landing.py |
produire manifest, README, user_presence |
couvert dans le landing |
| détecter colonnes équivalentes ou divergentes | couvert avec column_alias_report.csv |
| vérifier le contrat de colonnes en landing et loading | couvert avec expected_gps_schema() et check_raw_import_columns() |
| gérer des données avec ou sans expérimentation | couvert par ProjectConfig() minimal et par le notebook loading |
| gérer des phases si elles existent | couvert par Phase et ProjectConfig(phases=...) |
| parser EWKB et dates | couvert par prepare_storyline(), prepare_trips(), prepare_journeys() |
| agréger modes et motifs | couvert par mode_purpose_mapping() et les fonctions apply_*_mappings() |
| resampler les jours manquants | couvert par resample_missing_stays() ; les jours observés et resamplés sont séparés dans user_stats |
enrichir user_stats |
couvert pour suivi, qualité GPS, excursions, poids par défaut et tables utilisateur simples |
| questionnaires hétérogènes | partiel : exportés séparément au landing ; consolidation analytique à définir par projet |
| pondération | couvert techniquement avec weights, weight_col, default_weight=1.0 ; méthode de pondération à documenter si utilisée |
scinder storyline en staypoints et legs |
couvert par split_storyline() |
ajouter user_id_day, durées, outliers |
couvert par add_user_id_day(), split_storyline(), add_length_quantile_flags() |
| matcher legs, trips, journeys | couvert par build_track_trip_journey_map() ; utilise trip_id s'il existe |
| matcher legs et staypoints | couvert par build_legs_staypoints_map() |
| motifs de boucle quotidiens | couvert par build_mobility_motifs() et summarize_mobility_motifs() |
| excursions depuis zone ou cercle | couvert par add_excursion_flags() ; activation et zone à définir par projet |
| propager excursions aux trips, journeys et user_stats | couvert par add_excursion_flags_to_trips_journeys() et add_excursion_stats_to_user_stats() |
| public transport | partiel : table landing conservée ; contrat de jointure stable à finaliser |
| export transformé parquet/pickle/csv | couvert par write_mobility_dataset() |
| export spatial pour dashboard | couvert par legs_to_h3_points(), aggregate_h3_frequencies(), write_spatial_analytics_exports() et write_duckdb_spatial_database() |
| qualité de suivi | couvert par build_tracking_gap_report(), summarize_phase_tracking(), build_user_confirmation_rates() et le notebook Notebooks/Package-ready/02_quality_check.ipynb |
| nettoyage spatial | couvert par spatial_geometry.py, spatial_quality.py, spatial_zones.py et le notebook Notebooks/Package-ready/03_spatial_cleaning.ipynb ; les couches territoriales restent à fournir par projet |
Points encore à finaliser¶
| Point | Décision proposée |
|---|---|
| phases propres à chaque utilisateur | utiliser user_presence pour produire une table de périodes utilisateur, puis adapter participation et indicateurs |
| public transport enrichi | définir le contrat de jointure stable avec legs ou trips |
| questionnaires | conserver des exports séparés, puis créer une table sociodémo consolidée si nécessaire |
| comparaison historique package/notebook | remplacée par Notebooks/Package-ready/01_data_loading.ipynb et les contrôles d'exports anonymisés |
| exports pickle | pris en charge via formats=("pickle",) ou formats=("pkl",) ; Parquet reste préférable pour les tables tabulaires durables |
| tests de non-régression historiques | comparer les exports package avec des sorties notebook de référence anonymisées |