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
|