Skip to content

calculate_net_flow

calculate_net_flow

calculate_net_flow(panel: DataFrame) -> DataFrame

Period-over-period change in available bikes per station.

Adds net_flow: the Δ in num_bikes_available vs the previous poll of the same station. net_flow is NaN across polls where last_reported did not change (the feed re-served an identical observation), so you don't read spurious zero-flows.

This intentionally reports the observed flow only, not its cause. Attributing a flow to rebalancing vs. organic demand is not identifiable from availability counts alone: a station spike can be a van drop or a burst of returns, and system-wide mass conservation cannot separate an internal van move from coincident organic trips. Apply your own, explicitly-stated heuristic downstream rather than trusting a built-in label.

.. warning:: Aliasing (the polling Nyquist limit). net_flow is the net change between two polls, so any activity that cancels within a polling interval is invisible: a bike rented and returned to the same station between snapshots yields Δ=0. Treat the summed absolute flow as a lower bound on true activity, and poll well below the timescale of the dynamics you want to measure.

Accepts a panel from build_availability_panel (MultiIndexed) or a flat frame; returns a flat frame with system_id, station_id, fetched_at columns.

See Also

build_availability_panel : The panel this consumes. turnover : Aggregate absolute flow. flow_balance : Net source/sink balance.

Source code in src/gbfs_toolkit/io/timeseries.py
def calculate_net_flow(panel: pd.DataFrame) -> pd.DataFrame:
    """Period-over-period change in available bikes per station.

    Adds ``net_flow``: the Δ in ``num_bikes_available`` vs the previous poll of the same
    station. ``net_flow`` is ``NaN`` across polls where ``last_reported`` did not change (the
    feed re-served an identical observation), so you don't read spurious zero-flows.

    This intentionally reports the **observed flow only**, not its cause. Attributing a flow to
    rebalancing vs. organic demand is not identifiable from availability counts alone: a
    station spike can be a van drop *or* a burst of returns, and system-wide mass conservation
    cannot separate an internal van move from coincident organic trips. Apply your own,
    explicitly-stated heuristic downstream rather than trusting a built-in label.

    .. warning::
       **Aliasing (the polling Nyquist limit).** ``net_flow`` is the *net* change between two
       polls, so any activity that cancels within a polling interval is invisible: a bike
       rented and returned to the same station between snapshots yields Δ=0. Treat the summed
       absolute flow as a **lower bound** on true activity, and poll well below the timescale
       of the dynamics you want to measure.

    Accepts a panel from [`build_availability_panel`][gbfs_toolkit.build_availability_panel] (MultiIndexed) or a flat frame;
    returns a flat frame with ``system_id, station_id, fetched_at`` columns.

    See Also
    --------
    [`build_availability_panel`][gbfs_toolkit.build_availability_panel] : The panel this consumes.
    [`turnover`][gbfs_toolkit.turnover] : Aggregate absolute flow.
    [`flow_balance`][gbfs_toolkit.flow_balance] : Net source/sink balance.
    """
    df = panel_frame(panel)
    require_columns(
        df,
        ["system_id", "station_id", "fetched_at", "num_bikes_available"],
        what="calculate_net_flow",
    )
    df = df.sort_values(["system_id", "station_id", "fetched_at"])
    grp = df.groupby(["system_id", "station_id"], sort=False)

    df["net_flow"] = grp["num_bikes_available"].diff()
    if "last_reported" in df:
        unchanged = grp["last_reported"].diff().eq(pd.Timedelta(0))
        df.loc[unchanged, "net_flow"] = np.nan
    return df.reset_index(drop=True)