Skip to content

detect_ghost_vehicles

detect_ghost_vehicles

detect_ghost_vehicles(vehicle_panel: DataFrame, *, idle_days: float = 14.0, move_threshold_m: float = 50.0) -> DataFrame

Flag immobile ("ghost") vehicles from a longitudinal vehicle panel.

A unit advertised at (essentially) the same coordinates for a long stretch is almost certainly lost, broken, or abandoned, yet it inflates availability. Given a panel of free-floating vehicle snapshots over time, this measures each vehicle's displacement from its first observed position and flags those that never moved beyond move_threshold_m across a span of at least idle_days.

Parameters:

Name Type Description Default
vehicle_panel DataFrame

Long frame of vehicle snapshots with system_id, vehicle_id, lat, lon, fetched_at (e.g. concatenated to_canonical_vehicles outputs). Note GBFS 2.1+ rotates vehicle_id for privacy; ghost detection is only meaningful where the feed keeps stable ids.

required
idle_days float

Minimum observed span (first→last sighting) for a vehicle to qualify.

14
move_threshold_m float

Maximum great-circle displacement (metres) from the first position to count as immobile (absorbs GPS jitter).

50

Returns:

Type Description
DataFrame

Indexed by (system_id, vehicle_id): first_seen, last_seen, n_obs, observed_days, max_displacement_m, is_ghost.

See Also

vehicle_idle_time : The fleet-wide idle share over time. reconcile_fleet_state : The deduplicated fleet tally.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "system_id": "s", "vehicle_id": "v1",
...     "lat": [48.85, 48.85], "lon": [2.35, 2.35],
...     "fetched_at": pd.to_datetime(["2026-01-01T00:00Z", "2026-01-20T00:00Z"]),
... })
>>> bool(detect_ghost_vehicles(panel)["is_ghost"].iloc[0])
True
Source code in src/gbfs_toolkit/analytics/fleet.py
def detect_ghost_vehicles(
    vehicle_panel: pd.DataFrame,
    *,
    idle_days: float = 14.0,
    move_threshold_m: float = 50.0,
) -> pd.DataFrame:
    """Flag immobile ("ghost") vehicles from a longitudinal vehicle panel.

    A unit advertised at (essentially) the same coordinates for a long stretch is almost
    certainly lost, broken, or abandoned, yet it inflates availability. Given a panel of
    free-floating vehicle snapshots over time, this measures each vehicle's displacement from
    its first observed position and flags those that never moved beyond ``move_threshold_m``
    across a span of at least ``idle_days``.

    Parameters
    ----------
    vehicle_panel : pandas.DataFrame
        Long frame of vehicle snapshots with ``system_id, vehicle_id, lat, lon, fetched_at``
        (e.g. concatenated [`to_canonical_vehicles`][gbfs_toolkit.to_canonical_vehicles] outputs). Note GBFS 2.1+
        rotates ``vehicle_id`` for privacy; ghost detection is only meaningful where the feed
        keeps stable ids.
    idle_days : float, default 14
        Minimum observed span (first→last sighting) for a vehicle to qualify.
    move_threshold_m : float, default 50
        Maximum great-circle displacement (metres) from the first position to count as immobile
        (absorbs GPS jitter).

    Returns
    -------
    pandas.DataFrame
        Indexed by ``(system_id, vehicle_id)``: ``first_seen``, ``last_seen``, ``n_obs``,
        ``observed_days``, ``max_displacement_m``, ``is_ghost``.

    See Also
    --------
    [`vehicle_idle_time`][gbfs_toolkit.vehicle_idle_time] : The fleet-wide idle share over time.
    [`reconcile_fleet_state`][gbfs_toolkit.reconcile_fleet_state] : The deduplicated fleet tally.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "system_id": "s", "vehicle_id": "v1",
    ...     "lat": [48.85, 48.85], "lon": [2.35, 2.35],
    ...     "fetched_at": pd.to_datetime(["2026-01-01T00:00Z", "2026-01-20T00:00Z"]),
    ... })
    >>> bool(detect_ghost_vehicles(panel)["is_ghost"].iloc[0])
    True
    """
    df = panel_frame(vehicle_panel)
    require_columns(
        df, ["system_id", "vehicle_id", "lat", "lon", "fetched_at"], what="detect_ghost_vehicles"
    )
    df = df[["system_id", "vehicle_id", "lat", "lon", "fetched_at"]].copy()
    df["fetched_at"] = pd.to_datetime(df["fetched_at"], utc=True)
    df = df.sort_values(["system_id", "vehicle_id", "fetched_at"])

    keys = ["system_id", "vehicle_id"]
    first = (
        df.groupby(keys, sort=False)
        .first()[["lat", "lon"]]
        .rename(columns={"lat": "_lat0", "lon": "_lon0"})
    )
    m = df.merge(first, on=keys)
    m["_disp"] = haversine_m(m["lat"], m["lon"], m["_lat0"], m["_lon0"])

    g = m.groupby(keys, sort=False)
    out = g.agg(
        first_seen=("fetched_at", "min"),
        last_seen=("fetched_at", "max"),
        n_obs=("fetched_at", "size"),
        max_displacement_m=("_disp", "max"),
    )
    out["observed_days"] = (out["last_seen"] - out["first_seen"]).dt.total_seconds() / 86400
    out["max_displacement_m"] = out["max_displacement_m"].round(1)
    out["observed_days"] = out["observed_days"].round(2)
    out["is_ghost"] = (out["observed_days"] >= idle_days) & (
        out["max_displacement_m"] <= move_threshold_m
    )
    return out[
        ["first_seen", "last_seen", "n_obs", "observed_days", "max_displacement_m", "is_ghost"]
    ]