Graphe du package¶

Page de maintenance

Cette page aide à comprendre la structure interne du dépôt. Pour utiliser le package, commencer par l'API recommandée.

Cette page synthétise le graphe local produit avec graphify pour comprendre xyt_gps selon les cinq blocs de l'API publique.

Corpus scanné¶

Le corpus graphify a été construit volontairement sans données, sans sorties de notebooks, sans environnement virtuel et sans archives historiques. Il contient :

le code source package-xyt-gps/src/xyt_gps ;
la documentation MkDocs ;
le README.md et pyproject.toml du package ;
une synthèse textuelle des notebooks Notebooks/Package-ready sans sorties de cellules ;
un document d'orientation FIVE_BLOCKS.md qui rattache le package aux cinq blocs publics.

Résultat de détection :

Type	Nombre
fichiers code	30
fichiers documentaires	34
mots approximatifs	62 297
fichiers sensibles ignorés	0

L'extraction sémantique graphify complète nécessite une clé LLM MOONSHOT_API_KEY ou ANTHROPIC_API_KEY. En l'absence de clé, le graphe produit localement est un graphe structurel extrait du code : imports, fonctions, classes et relations déterministes.

Artifacts locaux :

graphify-out/xyt_gps_5blocks/graph_structural.json
graphify-out/xyt_gps_5blocks/GRAPH_TREE.html
graphify-out/xyt_gps_5blocks_corpus/

Lecture par blocs¶

1. Préparer l'entrée¶

Modules principaux :

config.py : ProjectConfig, Phase, TimeSlice, seuils de suivi et de qualité GPS ;
schema.py : schéma attendu, contrôle des colonnes, validation brute ;
io.py : chemins d'import, chargement multi-sources, échantillonnage ;
mappings.py : mapping modes et motifs ;
sample_data.py et synthetic.py : données de test et génération synthétique.

Rôle : obtenir des tables GPS homogènes, explicites et contrôlées avant toute transformation.

2. Transformer¶

Modules principaux :

parsing.py : dates, EWKB, phases, nettoyage des valeurs nulles limitées ;
prepare_tables.py : préparation de storyline, trips, journeys ;
mobility_tables.py : split staypoints/legs, identifiant personne-jour, flags de longueurs extrêmes ;
relations.py : tables de correspondance legs, staypoints, trips et journeys ;
user_stats.py : statistiques utilisateur, suivi, resampling et pondération ;
transform.py : orchestration du workflow et assemblage du MobilityDataset ;
models.py : objets de données structurants ;
export.py : export du dataset de mobilité.

Rôle : convertir les exports GPS en tables relationnelles de mobilité : storyline, legs, staypoints, trips, journeys, user_stats et tables de mapping.

3. Contrôler et nettoyer¶

Modules principaux :

quality_tracking.py : présence quotidienne et participation hebdomadaire ;
quality_reports.py : trous de suivi, phases, qualité de tracking ;
quality_selection.py : sélection utilisateur et filtrage explicite ;
quality_diagnostics.py : longueurs extrêmes, confirmations, précision des modes ;
quality_resampling.py : resampling des jours manquants ;
spatial_geometry.py : nettoyage de géométries et distances entre points ;
spatial_quality.py : perte de signal GPS, flags et agrégats utilisateur ;
spatial_zones.py : zones territoriales, OD, relations à une aire et excursions ;
spatial.py : façade d'import conservée pour l'API publique.

Rôle : rendre visibles les limites de suivi et les choix de nettoyage avant les indicateurs.

4. Enrichir et produire les indicateurs¶

Modules principaux :

enrichment.py : occupation, CO2, santé ;
motifs.py : motifs de mobilité quotidiens ;
indicators.py : indicateurs personne-jour, personne-phase, population ;
viz_indicators.py : cartes HTML d'identité des indicateurs.

Rôle : produire les indicateurs génériques et les enrichissements nécessaires à une base de mobilité exploitable.

5. Préparer les exports dashboard¶

Modules principaux :

spatial_time.py : tranches horaires réutilisables ;
spatial_h3.py : points H3, fréquentation, matrices de counts ;
spatial_exports.py : exports Parquet/CSV/pickle et DuckDB ;
viz_maps.py : cartes GPS et H3 ;
viz_participation.py : heatmap de participation.

Rôle : produire des tables interrogeables et cartographiables pour un dashboard, des contrôles SQL locaux et des matrices origine-destination.

Points de vigilance du graphe¶

Le graphe confirme une organisation lisible en cinq blocs, mais trois points méritent de rester surveillés :

transform.py est revenu à un rôle d'orchestration. Les nouvelles transformations spécialisées doivent continuer à être placées dans des modules dédiés.
Le découpage spatial est maintenant explicite. Si le bloc OD/H3 grossit encore, il devra rester séparé des fonctions de qualité GPS.
Les visualisations sont déjà séparées par usage (viz_maps, viz_indicators, viz_participation). Cette séparation doit être conservée.

Régénérer localement¶

Depuis la racine du dépôt :

graphify extract graphify-out/xyt_gps_5blocks_corpus \
  --out graphify-out/xyt_gps_5blocks \
  --no-cluster

Cette commande nécessite une clé LLM pour l'extraction sémantique. Pour une extraction structurelle sans clé, utiliser le script local de préparation graphify déjà exécuté dans cette session ou relancer la génération du corpus avant de refaire l'extraction.