Per-station cumulative net flow (drift) since each period's start.
The running sum of the observed net_flow reveals structural sources and sinks: a station
whose drift trends steadily negative over a day is being drained faster than it refills. By
default the drift resets at each period boundary (reset="1D"); pass reset=None for a
single running total over the whole panel.
This is a descriptive reconstruction of the observed inventory change. It does not attribute
the change to rebalancing versus organic demand, which is not identifiable from
station-aggregate counts (see calculate_net_flow and the methodology).
Returns:
See Also
calculate_net_flow : The per-interval flow this accumulates.
flow_asymmetry_ratio : In/out balance of the same flow.
fleet_turnover_proxy : System-level turnover from the same flow.
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],
... })
>>> cumulative_imbalance(panel)["cumulative_drift"].tolist()
[0.0, -3.0, -1.0]
Source code in src/gbfs_toolkit/analytics/dynamics.py
| def cumulative_imbalance(panel: pd.DataFrame, *, reset: str | None = "1D") -> pd.DataFrame:
"""Per-station cumulative net flow (drift) since each period's start.
The running sum of the observed ``net_flow`` reveals structural sources and sinks: a station
whose drift trends steadily negative over a day is being drained faster than it refills. By
default the drift resets at each period boundary (``reset="1D"``); pass ``reset=None`` for a
single running total over the whole panel.
This is a descriptive reconstruction of the *observed* inventory change. It does not attribute
the change to rebalancing versus organic demand, which is not identifiable from
station-aggregate counts (see [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] and the methodology).
Returns
-------
pandas.DataFrame
The [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] frame plus a ``cumulative_drift`` column.
See Also
--------
[`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] : The per-interval flow this accumulates.
[`flow_asymmetry_ratio`][gbfs_toolkit.flow_asymmetry_ratio] : In/out balance of the same flow.
[`fleet_turnover_proxy`][gbfs_toolkit.fleet_turnover_proxy] : System-level turnover from the same flow.
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],
... })
>>> cumulative_imbalance(panel)["cumulative_drift"].tolist()
[0.0, -3.0, -1.0]
"""
flow = calculate_net_flow(panel).sort_values(["system_id", "station_id", "fetched_at"])
filled = flow["net_flow"].fillna(0.0)
groupers = [flow["system_id"], flow["station_id"]]
if reset:
groupers.append(pd.to_datetime(flow["fetched_at"]).dt.floor(reset))
flow["cumulative_drift"] = filled.groupby(groupers).cumsum()
return flow.reset_index(drop=True)
|