Skip to content

flow_asymmetry_ratio

flow_asymmetry_ratio

flow_asymmetry_ratio(panel: DataFrame, *, eps: float = 1e-09) -> 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:

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