Skip to content

temporal_concentration

temporal_concentration

temporal_concentration(panel: DataFrame, *, freq: str = '1h') -> 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, 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)