Skip to content

fleet_turnover_proxy

fleet_turnover_proxy

fleet_turnover_proxy(panel: DataFrame, *, freq: str = '1D') -> DataFrame

System-level turnover proxy: half the summed absolute flow per fleet vehicle, per period.

The headline operational metric, "how many times is a vehicle used per day". Without trip (OD) data the summed absolute change in station availability is the best mathematical approximation of usage. It is a strict lower bound: by the aliasing argument in calculate_net_flow, trips that cancel within a polling interval are invisible.

Returns:

Type Description
DataFrame

system_id, period, activity, fleet_size, turnover_proxy (one row per system and period).

See Also

cumulative_imbalance : Per-station drift behind the activity. calculate_net_flow : The observed flow this aggregates.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "system_id": "s", "station_id": "a",
...     "fetched_at": pd.to_datetime(
...         ["2026-01-01T08:00Z", "2026-01-01T09:00Z", "2026-01-01T10:00Z"]),
...     "num_bikes_available": [10, 7, 9],
... })
>>> round(float(fleet_turnover_proxy(panel)["turnover_proxy"].iloc[0]), 3)
0.25
Source code in src/gbfs_toolkit/analytics/dynamics.py
def fleet_turnover_proxy(panel: pd.DataFrame, *, freq: str = "1D") -> pd.DataFrame:
    """System-level turnover proxy: half the summed absolute flow per fleet vehicle, per period.

    The headline operational metric, "how many times is a vehicle used per day". Without trip (OD)
    data the summed absolute change in station availability is the best mathematical approximation
    of usage. It is a strict **lower bound**: by the aliasing argument in
    [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow], trips that cancel within a polling interval are invisible.

    Returns
    -------
    pandas.DataFrame
        ``system_id, period, activity, fleet_size, turnover_proxy`` (one row per system and period).

    See Also
    --------
    [`cumulative_imbalance`][gbfs_toolkit.cumulative_imbalance] : Per-station drift behind the activity.
    [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] : The observed flow this aggregates.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "system_id": "s", "station_id": "a",
    ...     "fetched_at": pd.to_datetime(
    ...         ["2026-01-01T08:00Z", "2026-01-01T09:00Z", "2026-01-01T10:00Z"]),
    ...     "num_bikes_available": [10, 7, 9],
    ... })
    >>> round(float(fleet_turnover_proxy(panel)["turnover_proxy"].iloc[0]), 3)
    0.25
    """
    flow = calculate_net_flow(panel)
    require_columns(flow, ["num_bikes_available", "fetched_at"], what="fleet_turnover_proxy")
    flow = flow.assign(period=pd.to_datetime(flow["fetched_at"]).dt.floor(freq))
    activity = (
        flow.assign(_a=flow["net_flow"].abs()).groupby(["system_id", "period"])["_a"].sum().div(2.0)
    )
    bikes_per_snapshot = flow.groupby(["system_id", "period", "fetched_at"])[
        "num_bikes_available"
    ].sum()
    fleet = bikes_per_snapshot.groupby(level=["system_id", "period"]).max()
    out = pd.concat([activity.rename("activity"), fleet.rename("fleet_size")], axis=1).reset_index()
    out["turnover_proxy"] = out["activity"] / out["fleet_size"].where(out["fleet_size"] > 0)
    return out