Skip to content

docking_pressure

docking_pressure

docking_pressure(panel: DataFrame) -> 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:

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