Per-station temporal peaking: the Gini of activity across time-of-day bins.
Distributes each station's activity (turnover :math:\sum|\Delta|) across the day's freq
bins and takes the Gini of that distribution: 1 means all activity in one peak bin, 0
means uniform. The temporal analogue of the spatial dynamic_gini_index, for sizing
peak-hour infrastructure and rebalancing windows. Convert to local time first for local hours.
Returns:
| Type |
Description |
DataFrame
|
system_id, station_id, temporal_gini, peak_share, peak_bin (peak_bin is minutes
since midnight of the busiest bin).
|
See Also
dynamic_gini_index : The spatial analogue of this peaking.
diurnal_summary_stats : The diurnal curve being concentrated.
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-01T08:30Z", "2026-01-01T18:00Z"]),
... "num_bikes_available": [5, 10, 9],
... })
>>> set(temporal_concentration(panel).columns) >= {"temporal_gini", "peak_share", "peak_bin"}
True
Source code in src/gbfs_toolkit/analytics/temporal.py
| def temporal_concentration(panel: pd.DataFrame, *, freq: str = "1h") -> pd.DataFrame:
"""Per-station temporal peaking: the Gini of activity across time-of-day bins.
Distributes each station's activity (turnover :math:`\\sum|\\Delta|`) across the day's ``freq``
bins and takes the Gini of that distribution: ``1`` means all activity in one peak bin, ``0``
means uniform. The temporal analogue of the spatial [`dynamic_gini_index`][gbfs_toolkit.dynamic_gini_index], for sizing
peak-hour infrastructure and rebalancing windows. Convert to local time first for local hours.
Returns
-------
pandas.DataFrame
``system_id, station_id, temporal_gini, peak_share, peak_bin`` (``peak_bin`` is minutes
since midnight of the busiest bin).
See Also
--------
[`dynamic_gini_index`][gbfs_toolkit.dynamic_gini_index] : The spatial analogue of this peaking.
[`diurnal_summary_stats`][gbfs_toolkit.diurnal_summary_stats] : The diurnal curve being concentrated.
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-01T08:30Z", "2026-01-01T18:00Z"]),
... "num_bikes_available": [5, 10, 9],
... })
>>> set(temporal_concentration(panel).columns) >= {"temporal_gini", "peak_share", "peak_bin"}
True
"""
flow = calculate_net_flow(panel).dropna(subset=["net_flow"])
if flow.empty:
return pd.DataFrame(
columns=["system_id", "station_id", "temporal_gini", "peak_share", "peak_bin"]
)
tod = time_of_day_minutes(flow["fetched_at"], freq).astype("int64")
by_bin = (
flow.assign(activity=flow["net_flow"].abs(), _tod=tod)
.groupby(["system_id", "station_id", "_tod"])["activity"]
.sum()
)
rows = []
for (sysid, stid), series in by_bin.groupby(level=["system_id", "station_id"]):
vals = series.to_numpy()
total = vals.sum()
bins = series.index.get_level_values("_tod").to_numpy()
rows.append(
{
"system_id": sysid,
"station_id": stid,
"temporal_gini": gini(vals),
"peak_share": float(vals.max() / total) if total > 0 else np.nan,
"peak_bin": int(bins[np.argmax(vals)]) if total > 0 else -1,
}
)
return pd.DataFrame(rows)
|