API locale

Cette page documente les modules locaux du banc de test. Les fonctions restent volontairement simples : elles servent à rendre le pipeline relançable et à éviter que la logique soit dispersée dans les notebooks.

Configuration

parking_search_prediction.config

resolve_config_path(config_path)

Resolve a config file path robustly from common project working dirs.

The documented usage is to run commands from the repository root. In practice, notebooks and ad-hoc terminal sessions are often started from Notebooks/ or scripts/. For relative config paths, this resolver first tries the current working directory, then the repository root inferred from this package location, then parent directories of the current working directory.

Préparation des données

parking_search_prediction.data_prep

read_storyline_tracks(config)

Read storyline Track rows and normalize them as transport legs.

started_at and finished_at are interpreted as UTC. This matches the observed Déclic Mobilité export, where the timezone-adjusted values are supplied separately in *_in_timezone columns.

read_declic_legs(config)

Read Déclic Mobilité cleaned legs from parquet and normalize them.

The cleaned base already stores UTC-aware started_at and finished_at values. Each waypoint is later matched to the half-open interval containing its timestamp, by user.

attach_waypoints_to_legs(waypoints, tracks)

Attach each waypoint to the Track interval containing its timestamp.

Intervals are half-open: leg_started_at <= timestamp < leg_finished_at. If Track intervals overlap, the most recently started Track is retained but the point is marked overlapping_tracks and excluded from car filtering.

filter_car_waypoints(waypoints_with_legs, config)

Keep unambiguously matched waypoints belonging to configured car modes.

Validation

parking_search_prediction.validation

Modèle ReLUT

parking_search_prediction.relut_model

Indicateurs

parking_search_prediction.metrics

Temps géométrique et consolidation

parking_search_prediction.spatial_detection

run_spatial_detection(config)

Run the standalone spatial detection step.

This step applies the spatial rules and writes the spatial candidate table. It does not merge with temporal predictions; that is handled by the final spatial/temporal comparison step.

Analyses exploratoires géométriques

parking_search_prediction.spatial_eda

SpatialEdaOutputs dataclass

Paths written by the spatial exploratory analysis step.

spatial_eda_output_paths(config)

Return standard output paths for the spatial EDA step.

build_candidate_profile(candidates)

Summarise key spatial indicators for all rows and eligible rows.

The profile is intentionally compact: it gives order-of-magnitude checks for distances, durations, speeds and spatial flags before threshold selection.

build_threshold_sensitivity(candidates, distance_thresholds_m, tortuosity_thresholds)

Evaluate broad and conservative spatial rules over threshold grids.

build_metric_grid_stats(candidates, grid_size_m=1000)

Aggregate spatial indicators on a simple Swiss metric grid.

The historical PL23 notebook used H3. The current environment does not ship the h3 dependency, so this function uses a reproducible square grid in EPSG:2056. The output plays the same role for EDA: locate areas where destination-side cruising indicators concentrate.

make_spatial_distribution_plots(candidates, paths)

Write distribution plots for core spatial indicators.

make_threshold_sensitivity_plot(sensitivity, paths)

Write a compact threshold sensitivity plot.

make_grid_map(grid_stats, paths, min_eligible_legs=10)

Write an HTML map of broad candidate counts by metric grid cell.

make_spatial_examples_map(candidates, paths, max_examples=20, random_seed=42)

Write a map of sampled spatial candidates for visual inspection.

run_spatial_eda(config, distance_thresholds_m=None, tortuosity_thresholds=None, grid_size_m=1000, max_examples=None)

Run the spatial EDA step and write reports, figures and maps.

This step is exploratory: it helps evaluate the implications of thresholds and spatial hypotheses before or alongside the reproducible detection step.

Temps géométrique PL23

parking_search_prediction.pl23_spatial

pl23_spatial_output_paths(config)

Return standard output paths for the PL23 spatial workflow.

build_pl23_spatial_candidates(config)

Build PL23 spatial parking-cruising candidates from the local Situee dump.

The function intentionally does not call Google Maps or public OSRM. Without a controlled router/cache, dist_excess and the historical Base_3 cannot be reproduced strictly. It writes comparable geometric candidate flags and a documented proxy table for review.

build_pl23_group_summary(gdf)

Summarise PL23 spatial indicators by historical descriptive dimensions.

run_pl23_spatial_detection(config)

Run the integrated PL23 spatial analysis and write reproducible outputs.

Sorties complémentaires géométriques

parking_search_prediction.geometric_complements

GeometricComplementPaths dataclass

Standard files produced by the complementary geometric analysis.

geometric_complement_paths(config)

Return output paths for complementary geometric figures and tables.

load_geometric_candidates(config)

Load available geometric candidate tables produced by steps 22 and 23.

The complementary outputs are intentionally downstream-only: they do not recompute detection flags. They reuse the candidate tables already generated by the main pipeline and add descriptive views useful for reports and technical review.

make_geometric_cumplots(candidates, config)

Create cumulative distribution plots for the main geometric indicators.

make_survey_parking_graphs(candidates, config)

Create simple survey graphs for declared home/work parking availability.

build_h3_thematic_stats(candidates)

Aggregate geometric indicators by destination H3 cell.

make_h3_thematic_map(h3_stats, config)

Create a Folium map with H3 thematic layers for geometric indicators.

build_commune_summary(candidates, config)

Aggregate candidates by commune if a boundary layer is configured.

make_commune_map(summary, communes, config)

Create a simple commune thematic map when boundaries are available.

run_geometric_complements(config)

Generate complementary figures and tables for the geometric time step.

Routage et dist_excess

parking_search_prediction.routing

RoutingOutputPaths dataclass

Canonical outputs for routed dist_excess processing.

The route candidates are built from spatial detection outputs. They are intentionally separate from the spatial candidates so routing can be run, cached and audited independently of the core detection workflow.

make_route_id(source_dataset, leg_id, origin_lon, origin_lat, destination_lon, destination_lat, *, mode, weighting)

Create a deterministic route id for caching and route/result joins.

build_routing_candidates(config)

Build route jobs needed to compute routed dist_excess.

The route origin is the last entry point into the destination buffer. The route destination is the end point of the car leg. This matches the archived spatial approach and avoids routing the complete leg, which would dilute the parking-search signal with the ordinary access trip.

write_xyt_payload_jsonl(candidates, path, *, geometry=True)

Write one xyt-compatible route payload per line for external execution.

route_candidates_with_xyt(config)

Call a running local xyt_routing HTTP API for prepared route candidates.

compute_dist_excess(candidates, route_results, config)

Merge route results and compute routed excess distance indicators.

build_routing_geometry_correspondence(merged, config)

Build a route-level table linking observed and routed geometries.

The observed geometry is the final GPS-derived segment inside the destination buffer. The routed geometry is the local shortest-distance reference returned by xyt_routing. Both are linked by route_id and leg_id.

write_routing_geometry_comparison_map(correspondence, config)

Write an HTML map comparing observed final GPS segments and routed paths.

apply_dist_excess_to_spatial_candidates(config)

Write routed spatial candidate tables after a route cache has been produced.

Spatialisation réseau ReLUT

parking_search_prediction.network_relut

NetworkRelutOutputPaths dataclass

Canonical outputs for ReLUT-weighted routed network aggregation.

TemporalProfile dataclass

Probability profile indexed by remaining distance to the parking point.

build_relut_weighted_route_segments(config)

Create route-segment observations weighted by ReLUT probabilities.

Each routed geometry is split on its native OSRM geometry vertices. The probability assigned to an edge is interpolated from ReLUT point predictions using the edge midpoint's remaining distance to the routed destination.

build_relut_weighted_full_leg_observed_segments(config)

Create an observed full-leg network layer weighted by ReLUT probabilities.

This output complements the routed search-portion layer. It uses the complete observed leg geometries from the spatial detection output, not OD routes recomputed on OSRM. The naming is therefore intentionally explicit: observed_network_relut_full_legs.

aggregate_relut_weighted_network_segments(route_segments, config)

Aggregate route segment observations into a network-level layer.

write_relut_network_map(aggregated, config, *, output_path_override=None, title='Probabilité ReLUT moyenne', max_segments_key='map_max_segments', min_routes_key='map_min_routes_per_segment', min_probability_key='map_min_probability', write_legacy_copy=False)

Write an HTML map of aggregated routed network segments.

write_full_leg_probability_sample_map(config)

Write an inspectable sample map of complete original legs.

This is the main review map for ReLUT probabilities. Contrary to the network aggregation maps, it does not aggregate routes and it does not use the OSRM routed search portion. It draws sampled complete observed leg geometries from the Déclic spatial table and colors their native segments by interpolated ReLUT probability.

run_routed_network_relut(config)

Run the ReLUT-weighted routed network aggregation and write outputs.

Analyses exploratoires temporelles

parking_search_prediction.temporal_eda

TemporalEdaOutputs dataclass

Paths written by the temporal exploratory analysis step.

temporal_eda_output_paths(config)

Return standard output paths for the temporal EDA step.

load_waypoints_caronly(config)

Load car-only waypoints produced by the preparation step.

build_waypoint_profile(waypoints)

Build compact data-quality and distribution indicators for car waypoints.

build_segment_sensitivity(waypoints, config, gap_minutes_grid)

Evaluate temporal segmentation sensitivity over several gap thresholds.

make_waypoint_distribution_plots(waypoints, paths)

Write basic distribution plots for temporal input quality.

make_segment_sensitivity_plot(sensitivity, paths)

Write a plot showing how segmentation reacts to gap thresholds.

make_temporal_examples_map(waypoints, config, paths, max_examples=12)

Write an HTML map of temporal segmentation examples before model inference.

run_temporal_eda(config, gap_minutes_grid=None, max_examples=None)

Run temporal EDA from prepared car-only waypoints.

The temporal EDA does not run the model. It checks waypoint quality, sampling frequency and segmentation sensitivity before inference.

Résultats par temps de méthode

parking_search_prediction.results

ResultsOutputPaths dataclass

Paths written by the per-approach results step.

results_output_paths(config)

Return standard output paths for per-approach result summaries.

load_spatial_candidates(config)

Load Déclic spatial candidates, preferring routed outputs when present.

load_temporal_predictions(config)

Load ReLUT predictions produced by the temporal detection step.

load_pl23_spatial_candidates(config)

Load integrated PL23 spatial candidates when the optional step was run.

summarize_spatial_results(spatial)

Summarise spatial detections under primary, broad and conservative rules.

summarize_temporal_results(predictions)

Summarise temporal predictions at segment level.

summarize_pl23_spatial_results(pl23_spatial)

Summarise the optional PL23 spatial reimplementation.

make_results_duration_distance_plot(spatial, temporal_segment_summary, paths, pl23_spatial=None)

Compare detected distance and duration distributions on Déclic only.

PL23 is intentionally not plotted here. It is an archive replay source for the spatial method, not an analytical counterpart to Déclic. Spatial versus temporal comparisons are valid only when they share the same source and leg identifiers.

build_quantification_by_approach(spatial, temporal_segment_summary, config, pl23_spatial=None)

Quantify detected cruising in time, distance and CO2 by approach.

The function may report multiple data sources, but it does not compare them analytically. Déclic spatial and Déclic temporal rows can support a spatial/temporal comparison when they cover the same legs. PL23 rows are an archive spatial replay and must be interpreted separately.

build_co2_sensitivity(quantification, config)

Expand the quantification table over configured CO2 factors.

make_quantification_plot(quantification, paths)

Write a compact Déclic figure for distance, duration and CO2.

PL23 rows are excluded to avoid presenting two different survey/data sources as analytically comparable volumes.

run_results_by_approach(config)

Write separate spatial and temporal result summaries.

This step deliberately does not merge approaches. It lets analysts inspect each method/source on its own before moving to the Déclic spatial/temporal comparison table. PL23 is reported as a spatial archive replay, not as a source to compare against Déclic.

Indicateurs territoriaux opérationnels

parking_search_prediction.territorial_indicators

TerritorialIndicatorPaths dataclass

Standard files produced by the operational territorial indicators step.

territorial_indicator_paths(config)

Return output paths for step 44 territorial indicators.

load_spatial_sources_for_territorial_indicators(config)

Load available spatial candidate tables for territorial indicators.

Routed candidate tables are preferred because they carry dist_excess_m. The function returns source-specific frames and does not compare the sources analytically.

build_spatial_scenario_indicators(frames, config)

Build source-specific scenario indicators for spatial cruising outputs.

build_temporal_profile_indicators(config)

Build a compact operational row for ReLUT temporal predictions.

build_territorial_scenarios(config)

Build the main scenario table used in the client-facing report.

build_typology_table(frames, config)

Describe behaviour-like signals among detected spatial candidates.

build_time_profile(frames, config)

Aggregate eligible and detected spatial legs by local arrival hour.

build_destination_profile(frames)

Aggregate detected legs by destination purpose when a purpose variable exists.

build_h3_hotspots(frames, config)

Aggregate spatial indicators by H3 destination cell for hotspot analysis.

build_network_hotspots(config)

Create a top-segment table from routed ReLUT network aggregation.

make_scenario_figure(scenarios, config)

Plot operational scenario indicators for reporting.

make_typology_figure(typology, config)

Plot the behavioural signal mix for the central routed scenario.

make_time_profile_figure(time_profile, config)

Plot detected legs by local arrival hour.

make_h3_hotspots_figure(h3_hotspots, config)

Plot top H3 cells by detected search duration.

make_h3_hotspot_map(h3_hotspots, config)

Create a simple H3 hotspot map for operational restitution.

run_territorial_indicators(config)

Generate operational indicators for territorial reporting.

This step does not alter the detection methods. It reorganises already produced outputs into a client-facing structure: scenarios, behavioural signal typology, H3 hotspots, temporal profiles, destination profiles and network hotspots.

Visualisations

parking_search_prediction.viz

Pipeline

parking_search_prediction.pipeline

run_all(config, *, include_pl23=False, include_routing_preparation=False, include_routing=False, include_network_relut=False, include_territorial_indicators=False)

Run the complete documented workflow on the configured data scope.

The sequence mirrors the notebooks: 01 prepare inputs, 21 spatial EDA, 22 spatial detection on Déclic, optional 23 spatial detection on PL23, optional 25 routing candidate preparation, 31 temporal EDA, 32 temporal detection/review, 41 per-approach results and 42 final spatial/temporal comparison on Déclic.

PL23 is opt-in because the source GPKG is several GB and the step can be materially slower than the default Déclic sample run.