Structure de projet recommandée

xyt_gps n'impose pas une arborescence de projet. Les fonctions acceptent des Path Python ou des chemins texte. Pour garder les notebooks lisibles et réutilisables, il est recommandé de définir les chemins une seule fois au début du projet.

Principe

Un projet d'analyse GPS peut être organisé ainsi :

project_root/
├── config/
│   ├── project_config.json
│   └── mappings.yml
├── data/
│   ├── raw/                     # exports GPS originaux, non versionnés
│   ├── external/                # zones, questionnaires, pondérations
│   └── outputs/
│       ├── 0-landed-data/       # données homogénéisées avant package
│       ├── 2-transformed-data/  # tables de mobilité structurées
│       ├── 3-enriched-data/     # enrichissements et indicateurs
│       └── 4-clean-data/        # base propre pour analyses et dashboards
│           ├── cleaned-base/    # tables de mobilité prêtes à analyser
│           ├── indicators/      # indicateurs personne-jour, phase, population
│           ├── spatial-analytics/
│           ├── figures/
│           ├── qa-reports/
│           ├── reference-data/
│           ├── metadata/
│           └── database/
├── notebooks/
│   ├── 00_data_landing.ipynb
│   ├── 01_data_loading.ipynb
│   ├── 02_quality_check.ipynb
│   ├── 03_spatial_cleaning.ipynb
│   ├── 04_enrich_indicators.ipynb
│   └── 05_export_cleaned_dataset.ipynb
└── reports/
    └── figures/

Les dossiers data/raw/ et data/outputs/ doivent rester ignorés par git, surtout lorsque les données contiennent des traces GPS ou des informations personnelles.

Variables de chemins

Dans un notebook, définir explicitement :

from pathlib import Path

project_root = Path("..").resolve()
data_root = project_root / "data"
output_root = data_root / "outputs"

raw_data_dir = data_root / "raw" / "gps"
external_data_dir = data_root / "external"
landing_dir = output_root / "0-landed-data"
transformed_dir = output_root / "2-transformed-data"
enriched_dir = output_root / "3-enriched-data"
clean_dir = output_root / "4-clean-data"

Ces noms sont des conventions de travail, pas des paramètres imposés par le package. Ils permettent de lire la chaîne de traitement sans chemins absolus et sans hypothèse propre à un ordinateur.

Dans 4-clean-data, le sous-dossier à utiliser en priorité pour les analyses thématiques est cleaned-base/. Il contient les tables de mobilité stabilisées : storyline, legs, staypoints, trips, journeys, user_stats, map_track_trip_journey, map_legs_staypoints, et si disponibles public_transport_legs, user_presence, occupancy_co2 et health.

Lien avec ProjectConfig

ProjectConfig.raw_data_dir décrit le dossier d'entrée utilisé par load_gps_export(). ProjectConfig.export_dir peut servir de dossier de sortie par défaut, mais les fonctions d'export acceptent aussi un chemin explicite.

import xyt_gps as xyt

config = xyt.ProjectConfig(
    experiment_name="mobility-study",
    raw_data_dir=raw_data_dir,
    export_dir=transformed_dir,
)

Si les tables sont déjà chargées avec pandas, raw_data_dir n'est pas nécessaire :

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

Convention utilisée dans ce dépôt

Les notebooks historiques de ce dépôt utilisent encore des dossiers nommés Notebooks/ et Data/Output/. Ce sont des conventions du projet Déclic, pas des contraintes du package. Pour un nouveau projet destiné à être partagé, une arborescence en minuscules comme notebooks/, data/ et config/ est plus standard.