API recommandée¶

Cette page donne le chemin d’usage à privilégier. Les fonctions internes restent documentées dans la référence complète, mais l’apprentissage du package doit commencer par ces cinq blocs.

from pathlib import Path
import xyt_gps as xyt

project_root = Path("..").resolve()
output_root = project_root / "data" / "outputs"
experiment_name = "experiment-a"
clean_dir = output_root / "4-clean-data" / experiment_name

Chemin court recommandé¶

Pour découvrir le package, commencer par ce point d'entrée. Il charge les données si raw n'est pas fourni, construit le MobilityDataset, puis calcule les indicateurs génériques.

config = xyt.ProjectConfig()
raw = xyt.RawGpsData(storyline=storyline, trips=trips, journeys=journeys)

raw, dataset, indicators = xyt.run_mobility_pipeline(
    config,
    raw=raw,
    resample_missing_days=True,
    mode_col="mode_niv1",
)

Le résultat peut aussi être inspecté comme un objet nommé :

result = xyt.run_mobility_pipeline(config)

result.raw
result.dataset
result.indicators

Quand les tables GPS sont déjà chargées avec pandas, passer raw directement :

result = xyt.run_mobility_pipeline(config, raw=raw)

Import par sous-module¶

L'import import xyt_gps as xyt reste pratique pour les notebooks. Pour lire le code ou explorer l'API par responsabilité, préférer les sous-modules :

import xyt_gps.io as xyt_io
import xyt_gps.transform as xyt_transform
import xyt_gps.quality as xyt_quality
import xyt_gps.spatial_quality as xyt_spatial_quality
import xyt_gps.indicators as xyt_indicators

Ce pattern évite de parcourir la liste complète des symboles exportés au niveau racine.

1. Préparer l’entrée¶

Objectif : charger ou construire des tables GPS prêtes à être transformées.

Besoin	Fonction ou objet	Sortie
définir le projet	`ProjectConfig`, `Phase`, `TimeSlice`	configuration explicite
déclarer les mappings	`mode_purpose_mapping()`	`MobilityMappings`
vérifier les colonnes attendues	`expected_gps_schema()`, `check_raw_import_columns()`	rapport de colonnes
échantillonner un gros export	`RawSampleConfig.by_users(n)`, `RawSampleConfig.random_rows(n)`	configuration d’échantillon
charger des fichiers sources	`load_gps_export()`, `load_gps_sources()`	`RawGpsData`
utiliser des données de démonstration	`load_sample_gps()`	`RawGpsData`
valider les tables brutes	`validate_gps_raw()`	rapports de validation

Cas minimal :

config = xyt.ProjectConfig()

raw = xyt.RawGpsData(
    storyline=storyline,
    trips=trips,
    journeys=journeys,
    user_statistics=user_statistics,
)

xyt.check_raw_import_columns(
    raw.storyline,
    raw.user_statistics,
    trips=raw.trips,
    journeys=raw.journeys,
    raise_on_error=True,
)

Repères de nommage :

Fonction	Usage
`load_gps_export()`	charge un export unique à partir de `ProjectConfig`
`load_gps_source()`	charge un export unique et ajoute des métadonnées de source
`load_gps_sources()`	charge et concatène plusieurs sources

2. Transformer¶

Objectif : convertir les tables GPS en tables de mobilité liées entre elles.

Besoin	Fonction ou objet	Sortie
lancer la préparation complète	`prepare_mobility_dataset()`	`MobilityDataset`
traiter plusieurs sources	`prepare_mobility_datasets()`	`MobilityDataset` concaténé
inspecter les tables	`mobility_dataset_tables()`	dictionnaire de tables
écrire les tables structurées	`write_mobility_dataset()`	Parquet, CSV ou pickle

dataset = xyt.prepare_mobility_dataset(
    raw,
    config,
    resample_missing_days=True,
    clean_leg_geometries=True,
    add_length_outlier_flags=True,
    add_signal_quality_flags=True,
)

tables = xyt.mobility_dataset_tables(dataset)

3. Contrôler¶

Objectif : rendre visibles les limites de suivi et les choix de nettoyage.

Besoin	Fonction	Sortie
présence journalière	`build_daily_tracking_presence()`	table user-jour
participation hebdomadaire	`build_weekly_participation_grid()`	score 0-7 par semaine
rapport qualité	`build_tracking_quality_report()`	rapports utilisateur
sélection utilisateur	`build_user_selection_table()`	table de décision
qualité GPS	`add_signal_quality_flags()`, `build_user_signal_quality_stats()`	flags leg/user
contrôle cartographique	`plot_gps_traces()`	carte HTML/Folium

participation = xyt.build_weekly_participation_grid(dataset.storyline, config)
xyt.plot_participation_heatmap(participation)

plot_participation_heatmap() ajoute par défaut un séparateur rouge entre deux semaines lorsque la colonne de phase change. Cela permet de lire la participation relativement aux périodes du protocole, sans devoir recalculer les semaines calendaires.

4. Produire les indicateurs¶

Objectif : enrichir les legs et produire des indicateurs génériques, sans faire l’analyse thématique finale.

Besoin	Fonction	Sortie
enrichir CO2	`add_co2_occupancy_metrics()`	legs enrichis
enrichir santé	`add_health_metrics()`	legs enrichis
construire les motifs quotidiens	`build_mobility_motifs()`	motifs par jour
construire le profil horaire	`build_daily_demand_profile()`	courbes 5 minutes
calculer les indicateurs	`compute_mobility_indicators()`	`IndicatorResult`
écrire les indicateurs	`write_indicator_result()`	tables exportées
visualiser les indicateurs	`plot_indicator_bars()`	HTML

indicators = xyt.compute_mobility_indicators(
    dataset,
    mode_col="mode_niv1",
    include_zero_days=True,
    include_excursions=True,
    include_airplane=False,
    use_weights=True,
    weight_col="weight",
)

Les paramètres à rendre visibles dans un rapport d’indicateurs sont :

Paramètre	Rôle
`include_zero_days`	inclut les jours suivis sans déplacement dans les moyennes journalières
`include_excursions`	inclut ou exclut les legs/trips marqués comme excursions
`include_airplane`	inclut ou exclut les étapes et déplacements avion ; par défaut ils sont exclus
`use_weights`	calcule les moyennes population avec la pondération utilisateur
`weight_col`	nom de la colonne de pondération dans `user_stats`

plot_indicator_bars() lit ces informations depuis IndicatorResult.metadata et les affiche dans une carte d’identité de l’export HTML. L’export ajoute aussi une ligne Tous modes, en rose, pour chaque indicateur affiché. Cette ligne donne le total ou la moyenne tous modes confondus selon la métrique calculée, puis les modes détaillés restent visibles en dessous. La largeur de Tous modes et celle des modes détaillés utilisent deux échelles de référence distinctes, afin que le total tous modes ne réduise pas artificiellement les barres par mode.

Lorsque les legs contiennent des heures de début et de fin, compute_mobility_indicators() ajoute aussi un profil de demande par tranche de 5 minutes. plot_indicator_bars() l’affiche dans la carte d’identité sous forme de courbes par phase : une courbe tous modes confondus et des courbes par mode. La valeur affichée correspond au nombre moyen de personnes en déplacement sur une journée de la phase, ce qui rend les phases comparables même lorsqu’elles n’ont pas la même durée.

La carte d’identité contient aussi une heatmap horaire des fréquentations. Elle agrège par défaut les tranches de 5 minutes en heures pour rester lisible dans un export HTML. Un sélecteur permet de passer de Tous modes à un mode spécifique. Lorsque les legs contiennent une colonne de motif ou de purpose, la heatmap peut aussi être lue par motifs agrégés, en complément de la lecture par jours de semaine.

Si les données ont été filtrées avec filter_mobility_dataset_by_users(), la carte d’identité peut afficher un ratio du type 35/67 : le premier chiffre correspond aux utilisateurs conservés dans le calcul, le second aux utilisateurs présents dans l’export GPS avant filtre.

5. Préparer les exports dashboard¶

Objectif : produire des tables interrogeables et cartographiables.

Besoin	Fonction	Sortie
ajouter des tranches horaires	`add_time_slices()`	colonne `time_slice`
convertir les legs en points H3	`legs_to_h3_points()`	`leg_points_h3`
agréger la fréquentation	`aggregate_h3_frequencies()`	`h3_frequency`
produire des counts larges	`build_h3_count_matrix()`	`h3_count_matrix`
construire toutes les tables spatiales	`build_spatial_analytics_tables()`	dictionnaire de tables
écrire les exports	`write_spatial_analytics_tables()`	Parquet + CSV par défaut, pickle optionnel
créer une base SQL locale	`write_duckdb_spatial_database()`	`.duckdb`
cartographier H3	`plot_h3_frequency_map()`	carte Folium

spatial_tables = xyt.build_spatial_analytics_tables(
    dataset,
    h3_resolution=[8, 9],
    frequency_group_cols=["h3_resolution", "h3_cell", "mode_niv1", "time_slice"],
)

xyt.write_spatial_analytics_tables(
    spatial_tables,
    clean_dir / "spatial-analytics",
    formats=("parquet", "csv"),
)

À garder en tête¶

Le cas par défaut ne suppose ni expérimentation, ni phase. Les phases, pondérations, questionnaires et découpages temporels sont des couches de configuration à ajouter seulement lorsqu’elles existent dans le projet.