vehicle_id_persistence¶
vehicle_id_persistence
¶
vehicle_id_persistence(vehicle_panel: DataFrame, *, lags: tuple[str, ...] = ('1h', '12h', '24h'), time_col: str = 'fetched_at', id_col: str = 'vehicle_id') -> DataFrame
Characterise whether a feed rotates or persists its vehicle_id values.
Two purely empirical statistics per system (no survival model): the rolling
Jaccard overlap of the live id-set lag apart, and the observed lifespan
(last minus first sighting) of each id. A feed that rotates ids hourly drives
jaccard_24h toward 0 and the median lifespan toward the polling step; a feed
that keeps ids stable keeps both high. The inverse of this persistence is the
ceiling on origin-destination identifiability, so this is the check that tells a
study whether trip-level analysis is even admissible.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
vehicle_panel
|
DataFrame
|
Long frame of free-floating vehicle snapshots with |
required |
lags
|
tuple of str
|
Offsets (pandas aliases) at which to compute the id-set Jaccard overlap. |
("1h", "12h", "24h")
|
time_col
|
str
|
Snapshot-time and vehicle-id column names. |
'fetched_at'
|
id_col
|
str
|
Snapshot-time and vehicle-id column names. |
'fetched_at'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
One row per |
See Also
detect_ghost_vehicles : Track individual units, which needs stable ids.
vehicle_idle_time : The idle-share series, also id-dependent.
reconcile_fleet_state : The deduplicated fleet tally.
Examples:
A feed that replaces every id between snapshots has zero one-step overlap:
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "vehicle_id": ["a0", "a1", "b0", "b1", "c0", "c1"],
... "fetched_at": pd.to_datetime(
... ["2026-01-01T00:00Z"] * 2 + ["2026-01-01T01:00Z"] * 2
... + ["2026-01-01T02:00Z"] * 2),
... })
>>> float(vehicle_id_persistence(panel, lags=("1h",))["jaccard_1h"].iloc[0])
0.0