def availability_stats(panel: pd.DataFrame, *, time_col: str = "fetched_at") -> pd.DataFrame:
"""Per-station longitudinal statistics from an availability panel.
Complements [`diurnal_profiles`][gbfs_toolkit.diurnal_profiles] (which yields the curves) with
comparable scalars per station: central tendency, time spent empty/full, volatility, and
the diurnal amplitude / peak hour of occupancy.
Parameters
----------
panel : pandas.DataFrame
A panel from [`build_availability_panel`][gbfs_toolkit.build_availability_panel] (MultiIndexed) or a flat
frame with ``system_id, station_id, num_bikes_available, num_docks_available`` and a
time column. Hour-of-day uses ``time_col`` **as stored**; pass a panel built with
``target_tz`` for local-time peaks.
Returns
-------
pandas.DataFrame
Indexed by ``(system_id, station_id)``: ``n_obs``, ``mean_bikes``, ``median_bikes``,
``occupancy_mean``, ``pct_time_empty``, ``pct_time_full``, ``volatility``,
``diurnal_amplitude``, ``peak_hour``.
See Also
--------
[`diurnal_profiles`][gbfs_toolkit.diurnal_profiles] : The per-station diurnal curves.
[`diurnal_summary_stats`][gbfs_toolkit.diurnal_summary_stats] : System-wide hourly summary.
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-01T18:00Z"]),
... "num_bikes_available": [0, 10], "num_docks_available": [10, 0],
... })
>>> float(availability_stats(panel)["pct_time_empty"].iloc[0])
0.5
"""
df = panel_frame(panel)
bikes, docks = num(df, "num_bikes_available"), num(df, "num_docks_available")
denom = bikes + docks
work = pd.DataFrame(
{
"system_id": df["system_id"],
"station_id": df["station_id"],
"bikes": bikes,
"occ": (bikes / denom).where(denom > 0),
"empty": bikes <= 0,
"full": docks <= 0,
"hour": pd.to_datetime(df[time_col]).dt.hour,
}
)
g = work.groupby(["system_id", "station_id"], sort=False)
res = pd.DataFrame(
{
"n_obs": g.size(),
"mean_bikes": g["bikes"].mean(),
"median_bikes": g["bikes"].median(),
"occupancy_mean": g["occ"].mean(),
"pct_time_empty": g["empty"].mean(),
"pct_time_full": g["full"].mean(),
"volatility": g["bikes"].std(),
}
)
hourly = work.groupby(["system_id", "station_id", "hour"])["occ"].mean().dropna()
if len(hourly):
by_station = hourly.groupby(level=[0, 1])
res["diurnal_amplitude"] = by_station.max() - by_station.min()
res["peak_hour"] = by_station.idxmax().map(lambda t: t[2])
else:
res["diurnal_amplitude"] = np.nan
res["peak_hour"] = np.nan
return res