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)
|