Skip to content

station_outage_rates

station_outage_rates

station_outage_rates(panel: DataFrame) -> DataFrame

Per-station fraction of time empty (stockout) and full (saturation).

The most basic service-quality statistic, the kind reported as "station X is empty 24% of the time". A pure boolean count over the observed snapshots.

Returns:

Type Description
DataFrame

system_id, station_id, stockout_rate, saturation_rate, n_obs (rates in [0, 1]).

See Also

service_reliability_index : Time-of-day service probabilities. outage_survival : Duration of the outages this counts. censored_time_ratio : The same censoring as a single ratio.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "system_id": "s", "station_id": "a",
...     "num_bikes_available": [0, 0, 5, 5], "num_docks_available": [10, 10, 5, 0],
... })
>>> out = station_outage_rates(panel)
>>> float(out["stockout_rate"].iloc[0]), float(out["saturation_rate"].iloc[0])
(0.5, 0.25)
Source code in src/gbfs_toolkit/analytics/service.py
def station_outage_rates(panel: pd.DataFrame) -> pd.DataFrame:
    """Per-station fraction of time empty (stockout) and full (saturation).

    The most basic service-quality statistic, the kind reported as "station X is empty 24% of the
    time". A pure boolean count over the observed snapshots.

    Returns
    -------
    pandas.DataFrame
        ``system_id, station_id, stockout_rate, saturation_rate, n_obs`` (rates in ``[0, 1]``).

    See Also
    --------
    [`service_reliability_index`][gbfs_toolkit.service_reliability_index] : Time-of-day service probabilities.
    [`outage_survival`][gbfs_toolkit.outage_survival] : Duration of the outages this counts.
    [`censored_time_ratio`][gbfs_toolkit.censored_time_ratio] : The same censoring as a single ratio.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "system_id": "s", "station_id": "a",
    ...     "num_bikes_available": [0, 0, 5, 5], "num_docks_available": [10, 10, 5, 0],
    ... })
    >>> out = station_outage_rates(panel)
    >>> float(out["stockout_rate"].iloc[0]), float(out["saturation_rate"].iloc[0])
    (0.5, 0.25)
    """
    df = panel_frame(panel)
    require_columns(
        df,
        ["system_id", "station_id", "num_bikes_available", "num_docks_available"],
        what="station_outage_rates",
    )
    bikes = pd.to_numeric(df["num_bikes_available"], errors="coerce")
    docks = pd.to_numeric(df["num_docks_available"], errors="coerce")
    work = pd.DataFrame(
        {
            "system_id": df["system_id"].to_numpy(),
            "station_id": df["station_id"].to_numpy(),
            "_empty": (bikes == 0).to_numpy(),
            "_full": (docks == 0).to_numpy(),
        }
    )
    return (
        work.groupby(["system_id", "station_id"])
        .agg(
            stockout_rate=("_empty", "mean"),
            saturation_rate=("_full", "mean"),
            n_obs=("_empty", "size"),
        )
        .reset_index()
    )