Configuration projet¶

ProjectConfig regroupe les paramètres qui ne doivent pas être cachés dans les fonctions de transformation.

Le cas par défaut est volontairement générique : pas d'expérience analytique et pas de découpage en phases. Les phases ne sont nécessaires que si l'analyse doit comparer plusieurs périodes d'un protocole.

config = xyt.ProjectConfig()

Avec cette configuration minimale, prepare_mobility_dataset() produit les tables de mobilité sans colonne Phase. Les indicateurs regroupent alors les résultats dans une période analytique nommée All.

Pour charger des fichiers structurés par noms inférés, il faut en revanche renseigner les champs utilisés dans les noms de fichiers :

from pathlib import Path

project_root = Path("..").resolve()
raw_data_dir = project_root / "data" / "raw" / "gps"
transformed_dir = project_root / "data" / "outputs" / "2-transformed-data"

config = xyt.ProjectConfig(
    experiment_name="mobility-study",
    motiontag_project_name="gps-provider-project",
    period="2026-04-01--2026-06-30",
    raw_data_dir=raw_data_dir,
    export_dir=transformed_dir,
    target_crs="EPSG:4326",
    operations_crs="EPSG:2056",
)

Voir aussi Structure de projet recommandée pour organiser project_root, data/, config/ et notebooks/.

Paramètres principaux¶

Paramètre	Rôle	Exemple
`experiment_name`	nom analytique optionnel du projet	`"mobility-study"`
`motiontag_project_name`	nom fournisseur utilisé dans les fichiers, requis pour `load_gps_export()`	`"gps-provider-project"`
`period`	période encodée dans les noms de fichiers, requise pour `load_gps_export()`	`"2026-04-01--2026-06-30"`
`raw_data_dir`	dossier des exports bruts	`project_root / "data" / "raw" / "gps"`
`export_dir`	dossier de sortie optionnel	`project_root / "data" / "outputs" / "2-transformed-data"`
`target_crs`	CRS des données exportées	`"EPSG:4326"`
`operations_crs`	CRS métrique pour les opérations spatiales	`"EPSG:2056"`
`phases`	périodes analytiques optionnelles	`Phase("Phase1", "2026-04-01", "2026-04-21")`
`tracking_thresholds`	seuils de suivi	`TrackingThresholds(min_total_tracked_days=7)`
`spatial_quality_thresholds`	seuils qualité spatiale	`SpatialQualityThresholds(outlier_quantiles_by_mode=(0.98, 0.99))`
`matching_thresholds`	seuils de matching	`MatchingThresholds(leg_trip_journey_tolerance="5s")`
`mappings`	modes et motifs	`mode_purpose_mapping()` ou mapping propre au projet
`time_slices`	tranches horaires réutilisables	`TimeSlice("HPM", "07:10", "09:00")`

Par défaut, le package définit deux périodes de pointe et une période résiduelle :

Code	Intervalle	Rôle
`HPM`	07:10-09:00	heure de pointe du matin
`HPS`	17:30-20:00	heure de pointe du soir
`HC`	reste de la journée	heures creuses

Exemple complet avec qualité GPS¶

from pathlib import Path
import xyt_gps as xyt

project_root = Path("..").resolve()

config = xyt.ProjectConfig(
    experiment_name="mobility-study",
    motiontag_project_name="gps-provider-project",
    period="2026-04-01--2026-06-30",
    raw_data_dir=project_root / "data" / "raw" / "gps",
    export_dir=project_root / "data" / "outputs" / "2-transformed-data",
    phases=(
        xyt.Phase("Phase1", "2026-04-01", "2026-04-21"),
        xyt.Phase("Phase2", "2026-04-22", "2026-05-31"),
        xyt.Phase("Phase3", "2026-06-01", "2026-06-30"),
    ),
    tracking_thresholds=xyt.TrackingThresholds(
        min_days_by_phase={"Phase1": 7, "Phase2": 21, "Phase3": 7},
        min_total_tracked_days=7,
    ),
    spatial_quality_thresholds=xyt.SpatialQualityThresholds(
        outlier_quantiles_by_mode=(0.98, 0.99),
        bad_signal_user_quantile=0.995,
        signal_loss_mode_column="mode",
    ),
)

Découper ou non l'analyse par phase¶

Sans phase :

config = xyt.ProjectConfig()
dataset = xyt.prepare_mobility_dataset(raw, config)
indicators = xyt.compute_mobility_indicators(dataset)

Avec deux ou trois phases :

config = xyt.ProjectConfig(
    phases=(
        xyt.Phase("Phase1", "2026-04-01", "2026-04-21"),
        xyt.Phase("Phase2", "2026-04-22", "2026-05-31"),
    ),
)

Le nombre de phases n'est pas fixé par le package. Les cas Déclic à trois phases sont un usage particulier, pas une contrainte générale.

Dans le dictionnaire livré le 2025-08-15, les colonnes de sortie observées incluent par exemple relative_signal_loss, low_quality_legs_1 et bad_signal_user. Elles correspondent aux fonctions de qualité GPS intégrées dans xyt_gps.spatial.

Options de transformation¶

ProjectConfig décrit le projet : nom, phases, mappings, seuils et systèmes de coordonnées. Les options d'exécution sont passées directement à prepare_mobility_dataset() pour rester visibles au moment où la transformation est lancée.

Le comportement par défaut est le plus prudent : il applique le nettoyage géométrique léger, les flags de longueurs extrêmes et les flags de qualité GPS.

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

Pour un export déjà nettoyé et documenté en amont :

dataset = xyt.prepare_mobility_dataset(
    raw,
    config,
    add_length_outlier_flags=False,
    add_signal_quality_flags=False,
)

Il faut éviter de désactiver une étape uniquement parce qu’elle ralentit ou complique l’analyse. Une étape optionnelle peut être désactivée lorsque son équivalent a déjà été réalisé et documenté.

Quand add_signal_quality_flags=False, le package écrit signal_quality_computed=False dans dataset.user_stats. Les colonnes comme bad_signal_user ne doivent alors pas être interprétées comme un résultat de qualité GPS. Pour filtrer les utilisateurs dans ce cas, il faut appeler build_user_selection_table(..., exclude_bad_signal_users=False) et citer le contrôle amont utilisé.

Règle pratique¶

Si un paramètre change l’interprétation des résultats, il doit être visible dans ProjectConfig ou documenté dans les pages d’hypothèses. Les phases de ProjectConfig sont aussi utilisées par compute_mobility_indicators(..., include_zero_days=True) pour construire le calendrier personne-jour, notamment les jours sans mouvement.