Skip to content

turnover

turnover

turnover(panel: DataFrame, *, freq: str = '1D', normalize: str | None = None) -> DataFrame

Per-station activity proxy: summed absolute net flow per period.

A cheap, model-free measure of how busy a station is. It is a lower bound: by the aliasing argument in calculate_net_flow, trips that cancel within a polling interval are invisible. Use it for relative comparison (which stations / days are busier), not as a trip count.

Parameters:

Name Type Description Default
freq str

Aggregation bin (a pandas offset alias).

"1D"
normalize (None, 'capacity')

If "capacity", divide each station's turnover by its capacity (requires a capacity column in panel); comparable across stations of different sizes.

None

Returns:

Type Description
DataFrame

system_id, station_id, period, turnover (Σ |net_flow| over each freq bin).

See Also

calculate_net_flow : The per-interval flow this sums. flow_balance : Signed instead of absolute flow.

Source code in src/gbfs_toolkit/io/timeseries.py
def turnover(
    panel: pd.DataFrame, *, freq: str = "1D", normalize: str | None = None
) -> pd.DataFrame:
    """Per-station activity proxy: summed absolute net flow per period.

    A cheap, model-free measure of how busy a station is. It is a **lower bound**: by the
    aliasing argument in [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow], trips that cancel within a polling interval
    are invisible. Use it for relative comparison (which stations / days are busier), not as a
    trip count.

    Parameters
    ----------
    freq : str, default "1D"
        Aggregation bin (a pandas offset alias).
    normalize : {None, "capacity"}
        If ``"capacity"``, divide each station's turnover by its capacity (requires a
        ``capacity`` column in ``panel``); comparable across stations of different sizes.

    Returns
    -------
    pandas.DataFrame
        ``system_id, station_id, period, turnover`` (Σ ``|net_flow|`` over each ``freq`` bin).

    See Also
    --------
    [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] : The per-interval flow this sums.
    [`flow_balance`][gbfs_toolkit.flow_balance] : Signed instead of absolute flow.
    """
    flow = calculate_net_flow(panel).dropna(subset=["net_flow"])
    if flow.empty:
        return pd.DataFrame(columns=["system_id", "station_id", "period", "turnover"])
    flow = flow.assign(
        period=pd.to_datetime(flow["fetched_at"]).dt.floor(freq), activity=flow["net_flow"].abs()
    )
    out = (
        flow.groupby(["system_id", "station_id", "period"])["activity"]
        .sum()
        .rename("turnover")
        .reset_index()
    )
    if normalize == "capacity":
        require_columns(flow, ["capacity"], what='turnover(normalize="capacity")')
        caps = flow.groupby(["system_id", "station_id"])["capacity"].first()
        out = out.merge(caps.rename("capacity"), on=["system_id", "station_id"])
        out["turnover"] = out["turnover"] / out["capacity"].where(out["capacity"] > 0)
        out = out.drop(columns="capacity")
    return out