Skip to content

cumulative_imbalance

cumulative_imbalance

cumulative_imbalance(panel: DataFrame, *, reset: str | None = '1D') -> 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 and the methodology).

Returns:

Type Description
DataFrame

The calculate_net_flow frame plus a cumulative_drift column.

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)