Skip to content

reconcile_fleet_state

reconcile_fleet_state

reconcile_fleet_state(station_status: DataFrame | None = None, vehicles: DataFrame | None = None) -> Series

Reconcile docked and free-floating feeds into one labelled fleet tally.

Pass either or both canonical frames. Vehicles carrying a station_id are treated as parked at a station (already represented in station_status) and are not added to the deployed total, so the two feeds don't double-count; that overlap is reported as docked_in_vehicle_feed / double_count_avoided for transparency.

Returns:

Type Description
pandas.Series (``Int64``) with:

available_in_stations: Σ num_bikes_available (docked, rentable). free_floating_available / _reserved / _disabled: vehicles not at a station, split by state. docked_in_vehicle_feed: vehicles that are at a station (overlap with the station counts). total_deployed: physically on the street: stations + all free-floating (available + reserved + disabled), overlap excluded. total_rentable: available in stations + available free-floating. double_count_avoided: vehicles that a naive sum would have double-counted (non-zero only when both feeds are given).

See Also

detect_ghost_vehicles : Find immobile units in the fleet. vehicle_idle_time : Track the idle share over time.

Examples:

>>> import pandas as pd
>>> stations = pd.DataFrame({"station_id": ["a"], "num_bikes_available": [8]})
>>> vehicles = pd.DataFrame({"vehicle_id": ["v1", "v2"], "station_id": [None, "a"]})
>>> tally = reconcile_fleet_state(stations, vehicles)
>>> int(tally["total_rentable"]), int(tally["double_count_avoided"])
(9, 1)
Source code in src/gbfs_toolkit/analytics/fleet.py
def reconcile_fleet_state(
    station_status: pd.DataFrame | None = None,
    vehicles: pd.DataFrame | None = None,
) -> pd.Series:
    """Reconcile docked and free-floating feeds into one labelled fleet tally.

    Pass either or both canonical frames. Vehicles carrying a ``station_id`` are treated as
    parked at a station (already represented in ``station_status``) and are **not** added to
    the deployed total, so the two feeds don't double-count; that overlap is reported as
    ``docked_in_vehicle_feed`` / ``double_count_avoided`` for transparency.

    Returns
    -------
    pandas.Series (``Int64``) with:
        ``available_in_stations``: Σ ``num_bikes_available`` (docked, rentable).
        ``free_floating_available`` / ``_reserved`` / ``_disabled``: vehicles **not** at a
        station, split by state.
        ``docked_in_vehicle_feed``: vehicles that *are* at a station (overlap with the
        station counts).
        ``total_deployed``: physically on the street: stations + all free-floating
        (available + reserved + disabled), overlap excluded.
        ``total_rentable``: available in stations + available free-floating.
        ``double_count_avoided``: vehicles that a naive sum would have double-counted
        (non-zero only when both feeds are given).

    See Also
    --------
    [`detect_ghost_vehicles`][gbfs_toolkit.detect_ghost_vehicles] : Find immobile units in the fleet.
    [`vehicle_idle_time`][gbfs_toolkit.vehicle_idle_time] : Track the idle share over time.

    Examples
    --------
    >>> import pandas as pd
    >>> stations = pd.DataFrame({"station_id": ["a"], "num_bikes_available": [8]})
    >>> vehicles = pd.DataFrame({"vehicle_id": ["v1", "v2"], "station_id": [None, "a"]})
    >>> tally = reconcile_fleet_state(stations, vehicles)
    >>> int(tally["total_rentable"]), int(tally["double_count_avoided"])
    (9, 1)
    """
    out: dict[str, int] = {}

    in_stations = 0
    if station_status is not None and len(station_status):
        in_stations = int(
            pd.to_numeric(station_status["num_bikes_available"], errors="coerce").fillna(0).sum()
        )
    out["available_in_stations"] = in_stations

    ff_available = ff_reserved = ff_disabled = docked_in_vehicle_feed = 0
    if vehicles is not None and len(vehicles):
        at_station = (
            vehicles["station_id"].notna()
            if "station_id" in vehicles.columns
            else pd.Series(False, index=vehicles.index)
        )
        disabled = _bool_col(vehicles, "is_disabled")
        reserved = _bool_col(vehicles, "is_reserved")
        free = ~at_station
        docked_in_vehicle_feed = int(at_station.sum())
        ff_disabled = int((free & disabled).sum())
        ff_reserved = int((free & ~disabled & reserved).sum())
        ff_available = int((free & ~disabled & ~reserved).sum())

    out["free_floating_available"] = ff_available
    out["free_floating_reserved"] = ff_reserved
    out["free_floating_disabled"] = ff_disabled
    out["docked_in_vehicle_feed"] = docked_in_vehicle_feed
    out["total_deployed"] = in_stations + ff_available + ff_reserved + ff_disabled
    out["total_rentable"] = in_stations + ff_available
    both = station_status is not None and vehicles is not None
    out["double_count_avoided"] = docked_in_vehicle_feed if both else 0

    return pd.Series(out, dtype="Int64")