Skip to content

flow_balance

flow_balance

flow_balance(panel: DataFrame) -> DataFrame

Per-station inflow / outflow split and source↔sink balance.

Splits calculate_net_flow into bikes gained (inflow = Σ positive Δ) and lost (outflow = Σ |negative Δ|), with balance = outflow / inflow: >1 ⇒ a net source (more departures than arrivals, a morning residential origin), <1 ⇒ a net sink (destination). Like turnover, these are lower bounds (intra-interval trips cancel).

Returns:

Type Description
DataFrame

Indexed by (system_id, station_id): inflow, outflow, net, balance.

See Also

calculate_net_flow : The per-interval flow this nets. turnover : Absolute instead of signed flow.

Source code in src/gbfs_toolkit/io/timeseries.py
def flow_balance(panel: pd.DataFrame) -> pd.DataFrame:
    """Per-station inflow / outflow split and source↔sink balance.

    Splits [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] into bikes gained (``inflow`` = Σ positive Δ) and lost
    (``outflow`` = Σ |negative Δ|), with ``balance = outflow / inflow``: ``>1`` ⇒ a net
    *source* (more departures than arrivals, a morning residential origin), ``<1`` ⇒ a net
    *sink* (destination). Like turnover, these are lower bounds (intra-interval trips cancel).

    Returns
    -------
    pandas.DataFrame
        Indexed by ``(system_id, station_id)``: ``inflow``, ``outflow``, ``net``, ``balance``.

    See Also
    --------
    [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] : The per-interval flow this nets.
    [`turnover`][gbfs_toolkit.turnover] : Absolute instead of signed flow.
    """
    flow = calculate_net_flow(panel).dropna(subset=["net_flow"])
    keys = ["system_id", "station_id"]
    if flow.empty:
        return pd.DataFrame(
            columns=["inflow", "outflow", "net", "balance"],
            index=pd.MultiIndex.from_arrays([[], []], names=keys),
        )
    f = flow["net_flow"]
    work = flow[keys].assign(_in=f.clip(lower=0), _out=(-f).clip(lower=0))
    out = work.groupby(keys).agg(inflow=("_in", "sum"), outflow=("_out", "sum"))
    out["net"] = out["inflow"] - out["outflow"]
    out["balance"] = (out["outflow"] / out["inflow"].where(out["inflow"] > 0)).round(3)
    return out