Skip to content

service_reliability_index

service_reliability_index

service_reliability_index(panel: DataFrame, *, freq: str = '1h', min_bikes: int = 1, min_docks: int = 1) -> DataFrame

Empirical level-of-service probability per station and time-of-day.

For each station and each time-of-day bucket (width freq), the fraction of observations with at least min_bikes bikes, with at least min_docks docks, and with both at once. This is the service view a mode-shift study needs ("can a user find a bike and a dock at 08:00?"), which an availability mean hides.

Parameters:

Name Type Description Default
panel DataFrame

From build_availability_panel (MultiIndexed) or a flat frame with system_id, station_id, fetched_at, num_bikes_available, num_docks_available. Convert to local time (build_availability_panel(target_tz=...)) first, so the buckets are local hours.

required
freq str

Fixed time-of-day bucket width (a pandas offset alias such as "1h" or "30min").

"1h"
min_bikes int

Availability thresholds for "service available".

1
min_docks int

Availability thresholds for "service available".

1

Returns:

Type Description
DataFrame

system_id, station_id, time_of_day (a Timedelta since local midnight), prob_bikes_avail, prob_docks_avail, prob_full_service, n_obs.

References

Vogel, Greiser and Mattfeld (2011), Understanding bike-sharing systems using data mining.

See Also

station_outage_rates : Time-share empty/full per station. censored_time_ratio : Share of demand lost to saturation. capacity_utilization : Normalise availability by capacity first.

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-08T08:00Z"]),
...     "num_bikes_available": [5, 0], "num_docks_available": [5, 10],
... })
>>> float(service_reliability_index(panel)["prob_bikes_avail"].iloc[0])
0.5
Source code in src/gbfs_toolkit/analytics/service.py
def service_reliability_index(
    panel: pd.DataFrame,
    *,
    freq: str = "1h",
    min_bikes: int = 1,
    min_docks: int = 1,
) -> pd.DataFrame:
    """Empirical level-of-service probability per station and time-of-day.

    For each station and each time-of-day bucket (width ``freq``), the fraction of observations
    with at least ``min_bikes`` bikes, with at least ``min_docks`` docks, and with both at once.
    This is the service view a mode-shift study needs ("can a user find a bike *and* a dock at
    08:00?"), which an availability mean hides.

    Parameters
    ----------
    panel : pandas.DataFrame
        From [`build_availability_panel`][gbfs_toolkit.build_availability_panel] (MultiIndexed) or a flat frame with
        ``system_id, station_id, fetched_at, num_bikes_available, num_docks_available``.
        Convert to local time (``build_availability_panel(target_tz=...)``) first, so the buckets
        are local hours.
    freq : str, default "1h"
        Fixed time-of-day bucket width (a pandas offset alias such as ``"1h"`` or ``"30min"``).
    min_bikes, min_docks : int
        Availability thresholds for "service available".

    Returns
    -------
    pandas.DataFrame
        ``system_id, station_id, time_of_day`` (a ``Timedelta`` since local midnight),
        ``prob_bikes_avail, prob_docks_avail, prob_full_service, n_obs``.

    References
    ----------
    Vogel, Greiser and Mattfeld (2011), Understanding bike-sharing systems using data mining.

    See Also
    --------
    [`station_outage_rates`][gbfs_toolkit.station_outage_rates] : Time-share empty/full per station.
    [`censored_time_ratio`][gbfs_toolkit.censored_time_ratio] : Share of demand lost to saturation.
    [`capacity_utilization`][gbfs_toolkit.capacity_utilization] : Normalise availability by capacity first.

    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-08T08:00Z"]),
    ...     "num_bikes_available": [5, 0], "num_docks_available": [5, 10],
    ... })
    >>> float(service_reliability_index(panel)["prob_bikes_avail"].iloc[0])
    0.5
    """
    df = panel_frame(panel)
    require_columns(
        df,
        ["system_id", "station_id", "fetched_at", "num_bikes_available", "num_docks_available"],
        what="service_reliability_index",
    )
    bucket = time_of_day_minutes(df["fetched_at"], freq)
    bikes_ok = pd.to_numeric(df["num_bikes_available"], errors="coerce") >= min_bikes
    docks_ok = pd.to_numeric(df["num_docks_available"], errors="coerce") >= min_docks
    work = pd.DataFrame(
        {
            "system_id": df["system_id"].to_numpy(),
            "station_id": df["station_id"].to_numpy(),
            "time_of_day": pd.to_timedelta(bucket, unit="m"),
            "_bikes": bikes_ok.to_numpy(),
            "_docks": docks_ok.to_numpy(),
        }
    )
    work["_full"] = work["_bikes"] & work["_docks"]
    out = (
        work.groupby(["system_id", "station_id", "time_of_day"])
        .agg(
            prob_bikes_avail=("_bikes", "mean"),
            prob_docks_avail=("_docks", "mean"),
            prob_full_service=("_full", "mean"),
            n_obs=("_full", "size"),
        )
        .reset_index()
    )
    return out