Audit free-floating & ghost fleets¶
Free-floating systems break the station paradigm: the truth lives in the
vehicles / free_bike_status feed, not in station_status. This scenario is
the one no syntactic validator can do — it reconciles both sides of a hybrid
fleet, finds vehicles that are declared but never move (inflating the advertised
supply), and measures whether the live fleet is collapsing into a few blocks.
Self-contained (synthetic panel, no network), run in CI.
Requirements
None for the core (bundled / synthetic data). [geo] only if you add the
optional geofencing step (measuring density against the real service area).
What the script does:
- Reconciles the fleet.
reconcile_fleet_statemerges the dockedstation_statusand the free-floatingvehiclesfeed into one labelled tally, avoiding the double-count that inflates a naive sum. - Finds the ghosts.
detect_ghost_vehiclesflags vehicles that stay put across the panel — declared in the feed but never rented, padding the operator's headline fleet size. - Measures spatial collapse.
spatial_entropytracks the Shannon entropy of the live distribution: a falling entropy means the fleet is piling up in a few cells rather than serving the city.
Run it:
Full source:
"""Audit a free-floating (and hybrid) fleet: ghosts and spatial collapse.
Self-contained (synthetic free-floating panel + a docked snapshot, no network):
python 07_free_floating_fleets.py
Free-floating systems break the station paradigm: the truth lives in
``free_bike_status``/``vehicles``, not ``station_status``. This reconciles both
sides into one tally, flags vehicles that never move (declared but inactive
"ghosts" inflating the advertised supply), and measures whether the live fleet
collapses into a few blocks (a falling spatial entropy).
"""
import pandas as pd
import gbfs_toolkit as gb
def main() -> None:
# Three daily snapshots. g1/g2 never move (ghosts); m1-m3 roam the city.
days = pd.to_datetime(["2026-06-01T08:00Z", "2026-06-02T08:00Z", "2026-06-03T08:00Z"])
tracks = {
"g1": [(48.850, 2.350)] * 3,
"g2": [(48.860, 2.360)] * 3,
"m1": [(48.850, 2.350), (48.870, 2.380), (48.880, 2.390)],
"m2": [(48.860, 2.360), (48.840, 2.340), (48.835, 2.330)],
"m3": [(48.852, 2.362), (48.866, 2.372), (48.874, 2.362)],
}
vehicles = pd.DataFrame(
[
{
"system_id": "ff",
"vehicle_id": vid,
"lat": la,
"lon": lo,
"fetched_at": t,
"is_disabled": False,
"is_reserved": False,
}
for vid, pts in tracks.items()
for t, (la, lo) in zip(days, pts, strict=True)
]
)
# A docked snapshot for the hybrid side.
station_status = pd.DataFrame(
{
"system_id": "ff",
"station_id": ["s1", "s2"],
"num_bikes_available": [4, 7],
"num_docks_available": [6, 3],
}
)
# 1. One labelled tally across docked + free-floating (latest snapshot).
latest = vehicles[vehicles["fetched_at"] == days[-1]]
print(
"Reconciled fleet tally:", gb.reconcile_fleet_state(station_status, latest).to_dict(), "\n"
)
# 2. Ghost vehicles: present in the feed but immobile over the panel.
ghosts = gb.detect_ghost_vehicles(vehicles, idle_days=1.0, move_threshold_m=50.0).reset_index()
flagged = ghosts.loc[ghosts["is_ghost"], "vehicle_id"].tolist()
print("Ghost vehicles (declared but never moved):", flagged, "\n")
# 3. Spatial entropy of the free-floating distribution over time (higher = spread).
ent = gb.spatial_entropy(vehicles, grid_size_m=2000)
print("Spatial entropy per snapshot:")
print(
ent[["fetched_at", "n_vehicles", "shannon_entropy", "evenness"]]
.round(3)
.to_string(index=False)
)
if __name__ == "__main__":
main()