Aller au contenu

Structure du dépôt

Cette page explicite le rôle des principaux dossiers. La règle générale est simple : le pipeline actif vit à la racine du dépôt ; External/ et Data/ sont des espaces locaux non versionnés.

Vue d'ensemble

.
├── Data/GPS/
├── External/
├── Notebooks/
├── config/
├── docs/
├── Output/
├── Rapport/
├── scripts/
├── src/
├── tests/
├── mkdocs.yml
├── requirements.txt
└── README.md

Dossiers actifs

src/ contient le package Python local. C'est là que doivent être ajoutées les fonctions réutilisables : jointure waypoints-legs, règles géométriques, adaptateurs ReLUT, consolidation par leg_id, exports et contrôles.

scripts/ contient les points d'entrée exécutables du pipeline. Ils appellent le package src/parking_search_prediction/ et écrivent dans Output/.

Notebooks/ contient les supports de relecture. Ils doivent rester exécutables de haut en bas, avec les paramètres en haut de notebook. Ils ne doivent pas devenir le lieu principal de la logique métier.

config/ contient les fichiers YAML. Les chemins doivent rester relatifs à la racine du dépôt pour permettre le partage du code sans chemins absolus locaux. Le chargeur de configuration résout config/default.yaml depuis les dossiers de travail usuels du projet : racine du dépôt, scripts/ ou Notebooks/.

tests/ contient les tests unitaires minimaux permettant de contrôler les éléments critiques : jointure temporelle, critères spatiaux et règles de classification.

docs/ contient la documentation MkDocs. Elle documente la méthode, les limites, les points ouverts et l'utilisation du pipeline.

Rapport/ contient les sources des livrables rédigés. Le sous-dossier Rapport/suivi/ est réservé aux journaux internes, audits de reprise et points ouverts. Ces documents peuvent mentionner l'historique de l'archive. Le rapport d'étude final ne doit pas exposer cet historique comme une contrainte projet.

Données et sorties locales

Data/GPS/ est l'emplacement attendu des données d'entrée. Il contient trois sources possibles :

Data/GPS/anonymous/
Data/GPS/declic/
Data/GPS/pl23/

Ces données ne sont pas versionnées. Elles peuvent contenir des données GPS individuelles ou des exports lourds.

Output/ contient les sorties régénérables : Parquet, CSV, figures, cartes HTML et rapports JSON de run. Ces fichiers ne sont pas versionnés par défaut. Le contenu d'Output/ doit pouvoir être supprimé et régénéré à partir de Data/, config/, src/, scripts/ et Notebooks/.

Rôle exact d'External/

External/ sert uniquement à conserver des clones Git locaux qui ne font pas partie du dépôt courant.

Deux dossiers peuvent y exister :

External/parking-search-prediction/
External/parking_cruising/

External/parking-search-prediction/ est la dépendance ReLUT contenant le modèle ParkingSearchPrediction.h5. Le pipeline local peut lire ce modèle, mais ne doit pas modifier le dépôt externe.

External/parking_cruising/ est l'ancien projet spatial Action Située. Il sert de référence pour reprendre des idées, seuils, visualisations ou morceaux de code. Il ne doit pas être exécuté comme une étape cachée du pipeline actuel. Tout élément repris doit être recopié ou réimplémenté dans src/, scripts/, config/, Notebooks/ ou docs/, puis documenté dans Rapport/suivi/.

En pratique :

External/ = référence et dépendances clonées
src/ + scripts/ + config/ + Notebooks/ = pipeline actuel

Validation des chemins

La portabilité des chemins est contrôlée à trois niveaux :

  • les chemins déclarés dans config/default.yaml et config/full_waypoints.yaml sont relatifs à la racine du dépôt ;
  • le test tests/test_paths_config.py vérifie la résolution de la configuration depuis la racine, scripts/ et Notebooks/ ;
  • les notebooks versionnés sont nettoyés de leurs sorties exécutées afin de ne pas stocker de chemins absolus locaux.

À propos de l'ancien dossier ParkingSearchPrediction/

L'ancien dossier ParkingSearchPrediction/ a été supprimé de la structure active. Il ne doit plus être recréé pour le pipeline courant.

Le nom ParkingSearchPrediction reste utilisé uniquement pour désigner le modèle ReLUT externe ParkingSearchPrediction.h5, rangé dans External/parking-search-prediction/model/.

Règle de contribution

Pour ajouter une fonctionnalité :

  1. ajouter ou modifier la logique dans src/ ;
  2. exposer l'étape dans scripts/ si elle doit être exécutable en batch ;
  3. documenter les paramètres dans config/ ;
  4. ajouter une cellule de relecture dans le notebook concerné ;
  5. ajouter un test simple si la règle influence la classification ;
  6. documenter les hypothèses et limites dans docs/ ou Rapport/suivi/.

Cette règle évite que le projet se fragmente entre notebooks, archives externes et scripts locaux non documentés.