Schéma brut d'import GPS¶

Cette page décrit le contrat minimal utilisé par xyt_gps pour charger des exports GPS déjà structurés en plusieurs tables.

Les données GPS réelles ne sont pas documentées ligne à ligne. La page décrit uniquement les tables et colonnes nécessaires au chargement.

Fichiers attendus¶

Les chemins sont construits a partir de ProjectConfig :

{raw_data_dir}/StorylineWithTripId.{motiontag_project_name}.{period}.csv
{raw_data_dir}/StorylineWithUserAnnotations.{motiontag_project_name}.{period}.csv
{raw_data_dir}/Trips.{motiontag_project_name}.{period}.csv
{raw_data_dir}/Journeys.{motiontag_project_name}.{period}.csv
{raw_data_dir}/UserStatistics.{motiontag_project_name}.{period}.csv

Pour storyline, le package cherche d'abord StorylineWithTripId, puis StorylineWithUserAnnotations.

Import multi-projets¶

Le package permet de charger plusieurs expériences ou périodes en une seule passe, par exemple :

raw = xyt.load_gps_sources([declic_config, declic_ziplo_config])
dataset = xyt.prepare_mobility_datasets([declic_config, declic_ziplo_config])

Chaque ProjectConfig porte ses propres valeurs :

experiment_name ;
motiontag_project_name ;
period ;
raw_data_dir ;
phases et seuils de suivi ;
mappings modes et motifs.

Cette structure évite d'appliquer par erreur les dates de phase d'une expérimentation à une autre. Elle évite aussi d'appliquer implicitement une nomenclature de modes ou de motifs qui ne correspondrait pas au projet.

Lors d'un import multi-source, les colonnes suivantes sont ajoutees aux tables brutes :

xyt_source_id
experiment_name
motiontag_project_name
period

Par défaut, les identifiants sont préfixés pour éviter les collisions entre projets :

{experiment_name}__{period}::{id_original}

Les valeurs originales sont conservees lorsque possible :

raw_id
raw_user_id
raw_trip_id

Sampling au chargement¶

Lorsque les exports bruts sont trop lourds, load_gps_export() et load_gps_sources() acceptent un parametre sample.

Deux modes sont prevus :

# Garde toutes les lignes de 5 utilisateurs tires au hasard.
raw = xyt.load_gps_export(
    config,
    sample=xyt.RawSampleConfig.by_users(5, random_state=42, chunksize=100_000),
)

# Garde 1000 lignes aleatoires par table.
# Pour storyline, les lignes Track sont privilegiees afin d'inspecter des legs.
raw = xyt.load_gps_export(
    config,
    sample=xyt.RawSampleConfig.random_rows(1000, random_state=42),
)

Le mode by_users est le plus coherent pour tester la chaine de transformation, car il conserve toutes les traces des utilisateurs selectionnes dans storyline, trips, journeys et user_statistics.

Dans la version actuelle, by_users est aussi le mode adapté aux exports lourds : le package lit d'abord uniquement la colonne user_id de storyline, sélectionne les utilisateurs, puis filtre les tables CSV par chunks. Le paramètre chunksize contrôle la taille de lecture en mémoire.

Le mode random_rows sert surtout a inspecter rapidement le format et obtenir des legs aleatoires parmi l'ensemble des utilisateurs. Il ne garantit pas une coherence relationnelle complete entre tables.

Mappings modes et motifs¶

Les mappings de modes et de motifs sont stockes dans ProjectConfig.mappings.

Ils couvrent actuellement :

storyline_purpose_niv1
storyline_mode_niv1
storyline_mode_niv2
storyline_mode_mrmt
trip_purpose_mrmt
trip_mode_niv1
trip_mode_niv2
trip_mode_mrmt
default_mode
default_purpose

Ces mappings sont structurants : ils definissent les categories produites par les colonnes mode_niv1, mode_niv2, mode_mrmt, purpose_niv1 et purpose_mrmt.

Leur modification doit donc etre traçable au niveau de la configuration projet, et non cachee dans une fonction de transformation.

Données testset¶

Des données de démonstration sont disponibles pour tester le package sans export GPS complet :

package-xyt-gps/examples/sample_data/sample_data_marced_motiontag.pkl

raw = xyt.load_sample_gps()

Le pickle source contient une storyline uniquement. La fonction pseudonymise user_id, ajoute des trip_id aux lignes Track, puis derive des tables Trips, Journeys et UserStatistics minimales afin de produire un RawGpsData compatible avec les validations et le tutoriel.

Ce testset est pédagogique. Les tables dérivées ne doivent pas être interprétées comme des exports fournisseur originaux.

Tables et colonnes minimales¶

storyline¶

Colonnes obligatoires :

id
user_id
type
started_at
finished_at
started_on
geometry

Colonnes recommandees :

created_at
updated_at
started_at_in_timezone
finished_at_in_timezone
confirmed_at_in_timezone
created_at_in_timezone
updated_at_in_timezone
purpose
mode
detected_mode
length
trip_id

La colonne geometry doit contenir des geometries EWKB hexadecimales compatibles avec shapely.wkb.loads.

trips¶

Colonnes obligatoires :

id
user_id
started_at
finished_at

Colonnes recommandees :

duration
distance
tracks_count
created_at
purpose
main_mode
modes

journeys¶

Colonnes obligatoires :

id
user_id
started_at
finished_at

Colonnes recommandees :

duration
distance
tracks_count_without_walks
trips_count
tracks_count
created_at
purpose
main_mode
modes

user_statistics¶

Colonnes obligatoires :

id

Colonnes recommandees :

first_tracked_at
latest_tracked_at
days_in_range_count
active_days_count
inactive_days_count

Validation implementee¶

Pour un notebook de chargement, commencer par check_raw_import_columns(). Cette fonction vérifie la structure des colonnes de storyline, trips, journeys et user_statistics, sans parser les dates ou les géométries :

structure_report = xyt.check_raw_import_columns(
    storyline_raw,
    user_statistics_raw,
    trips=trips_raw,
    journeys=journeys_raw,
    raise_on_error=True,
)

La fonction plus complète validate_gps_raw() est utilisée en interne par la transformation. Elle vérifie :

les colonnes obligatoires manquantes ;
les colonnes recommandees manquantes ;
les taux de valeurs manquantes sur geometry, started_at et finished_at ;
un seuil de 1 % de valeurs manquantes sur les colonnes critiques, avant parsing.

La fonction expected_gps_schema() retourne le schéma attendu sous forme de DataFrame, pour inspection dans un notebook.

Limites actuelles¶

Le schema reste un premier contrat. Il doit être confirmé sur chaque nouveau format fournisseur avec :

les types exacts des colonnes ;
les variantes de noms selon les exports ;
les colonnes liees aux annotations utilisateur ;
les cas ou trip_id est absent de la storyline.