Per-observation docking saturation tension: typical inflow over free docks.
A descriptive resilience indicator for return capacity. Each station's typical inflow (its
mean positive net flow per poll) is divided by the docks free right now: a station that usually
gains many bikes but has few open docks is under pressure to saturate. This describes the
current tension; it does not forecast future demand.
Returns:
| Type |
Description |
DataFrame
|
The calculate_net_flow frame plus expected_inflow (mean positive net flow per
station) and docking_pressure (= expected_inflow / num_docks_available, NaN when
no docks are free).
|
See Also
station_outage_rates : Saturation rate behind the pressure.
service_reliability_index : Dock-availability probabilities.
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"]),
... "num_bikes_available": [5, 8], "num_docks_available": [10, 7],
... })
>>> round(float(docking_pressure(panel)["docking_pressure"].iloc[0]), 1)
0.3
Source code in src/gbfs_toolkit/analytics/service.py
| def docking_pressure(panel: pd.DataFrame) -> pd.DataFrame:
"""Per-observation docking saturation tension: typical inflow over free docks.
A descriptive resilience indicator for return capacity. Each station's typical inflow (its
mean positive net flow per poll) is divided by the docks free right now: a station that usually
gains many bikes but has few open docks is under pressure to saturate. This describes the
current tension; it does not forecast future demand.
Returns
-------
pandas.DataFrame
The [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] frame plus ``expected_inflow`` (mean positive net flow per
station) and ``docking_pressure`` (= ``expected_inflow / num_docks_available``, ``NaN`` when
no docks are free).
See Also
--------
[`station_outage_rates`][gbfs_toolkit.station_outage_rates] : Saturation rate behind the pressure.
[`service_reliability_index`][gbfs_toolkit.service_reliability_index] : Dock-availability probabilities.
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"]),
... "num_bikes_available": [5, 8], "num_docks_available": [10, 7],
... })
>>> round(float(docking_pressure(panel)["docking_pressure"].iloc[0]), 1)
0.3
"""
flow = calculate_net_flow(panel)
require_columns(flow, ["num_docks_available"], what="docking_pressure")
positives = flow["net_flow"].where(flow["net_flow"] > 0)
expected = positives.groupby([flow["system_id"], flow["station_id"]]).transform("mean")
docks = pd.to_numeric(flow["num_docks_available"], errors="coerce")
flow["expected_inflow"] = expected.fillna(0.0)
flow["docking_pressure"] = flow["expected_inflow"] / docks.where(docks > 0)
return flow
|