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"]]
|