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
|