Skip to content

availability_stats

availability_stats

availability_stats(panel: DataFrame, *, time_col: str = 'fetched_at') -> DataFrame

Per-station longitudinal statistics from an availability panel.

Complements 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:

Name Type Description Default
panel DataFrame

A panel from 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.

required

Returns:

Type Description
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 : The per-station diurnal curves. 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
Source code in src/gbfs_toolkit/analytics/temporal.py
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