Skip to content

diurnal_summary_stats

diurnal_summary_stats

diurnal_summary_stats(panel: DataFrame, *, value_col: str = 'num_bikes_available', time_col: str = 'fetched_at') -> DataFrame

Hour-of-day summary of a quantity: mean, median and robust P5/P95 bands.

The aggregation behind the classic diurnal usage curve with its uncertainty ribbon. Provided once so studies do not re-derive groupby(hour).agg(...) with ad-hoc, outlier-sensitive percentiles. Convert the panel to local time first for local-hour semantics.

Returns:

Type Description
DataFrame

hour (0 to 23) with mean, median, p05, p95, n.

See Also

diurnal_bimodality : Commuter-vs-recreational scalar. temporal_autocorrelation : Rhythm regularity at fixed lags.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "fetched_at": pd.to_datetime(
...         ["2026-01-01T08:00Z", "2026-01-02T08:00Z", "2026-01-01T18:00Z"]),
...     "num_bikes_available": [4, 6, 10],
... })
>>> float(diurnal_summary_stats(panel).set_index("hour").loc[8, "mean"])
5.0
Source code in src/gbfs_toolkit/analytics/temporal.py
def diurnal_summary_stats(
    panel: pd.DataFrame, *, value_col: str = "num_bikes_available", time_col: str = "fetched_at"
) -> pd.DataFrame:
    """Hour-of-day summary of a quantity: mean, median and robust P5/P95 bands.

    The aggregation behind the classic diurnal usage curve with its uncertainty ribbon. Provided
    once so studies do not re-derive ``groupby(hour).agg(...)`` with ad-hoc, outlier-sensitive
    percentiles. Convert the panel to local time first for local-hour semantics.

    Returns
    -------
    pandas.DataFrame
        ``hour`` (0 to 23) with ``mean, median, p05, p95, n``.

    See Also
    --------
    [`diurnal_bimodality`][gbfs_toolkit.diurnal_bimodality] : Commuter-vs-recreational scalar.
    [`temporal_autocorrelation`][gbfs_toolkit.temporal_autocorrelation] : Rhythm regularity at fixed lags.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "fetched_at": pd.to_datetime(
    ...         ["2026-01-01T08:00Z", "2026-01-02T08:00Z", "2026-01-01T18:00Z"]),
    ...     "num_bikes_available": [4, 6, 10],
    ... })
    >>> float(diurnal_summary_stats(panel).set_index("hour").loc[8, "mean"])
    5.0
    """
    df = panel_frame(panel)
    require_columns(df, [value_col, time_col], what="diurnal_summary_stats")
    work = pd.DataFrame(
        {
            "hour": pd.to_datetime(df[time_col]).dt.hour.to_numpy(),
            "_v": pd.to_numeric(df[value_col], errors="coerce").to_numpy(),
        }
    )
    g = work.groupby("hour")["_v"]
    out = g.agg(["mean", "median", "size"]).rename(columns={"size": "n"})
    out["p05"] = g.quantile(0.05)
    out["p95"] = g.quantile(0.95)
    return out.reset_index()[["hour", "mean", "median", "p05", "p95", "n"]]