Per-station ratio of total inflow to total outflow.
A ratio near 1 is a self-balancing station; a ratio well below 1 (mostly departures) marks a
morning-residential or hilltop station, and above 1 a sink. A compact descriptor of a station's
structural role in the urban topography.
Returns:
| Type |
Description |
DataFrame
|
system_id, station_id, inflow, outflow, asymmetry_ratio (= inflow / (outflow + eps)).
|
See Also
cumulative_imbalance : The cumulative view of the same flow.
rebalancing_tension : The system-level spatial tension.
calculate_net_flow : The observed flow this summarises.
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],
... })
>>> round(float(flow_asymmetry_ratio(panel)["asymmetry_ratio"].iloc[0]), 2)
0.67
Source code in src/gbfs_toolkit/analytics/dynamics.py
| def flow_asymmetry_ratio(panel: pd.DataFrame, *, eps: float = 1e-9) -> pd.DataFrame:
"""Per-station ratio of total inflow to total outflow.
A ratio near 1 is a self-balancing station; a ratio well below 1 (mostly departures) marks a
morning-residential or hilltop station, and above 1 a sink. A compact descriptor of a station's
structural role in the urban topography.
Returns
-------
pandas.DataFrame
``system_id, station_id, inflow, outflow, asymmetry_ratio`` (= ``inflow / (outflow + eps)``).
See Also
--------
[`cumulative_imbalance`][gbfs_toolkit.cumulative_imbalance] : The cumulative view of the same flow.
[`rebalancing_tension`][gbfs_toolkit.rebalancing_tension] : The system-level spatial tension.
[`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] : The observed flow this summarises.
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],
... })
>>> round(float(flow_asymmetry_ratio(panel)["asymmetry_ratio"].iloc[0]), 2)
0.67
"""
flow = calculate_net_flow(panel).dropna(subset=["net_flow"])
nf = flow["net_flow"]
work = flow.assign(_in=nf.clip(lower=0), _out=(-nf).clip(lower=0))
out = (
work.groupby(["system_id", "station_id"])
.agg(inflow=("_in", "sum"), outflow=("_out", "sum"))
.reset_index()
)
out["asymmetry_ratio"] = out["inflow"] / (out["outflow"] + eps)
return out
|