Skip to content

outage_survival

outage_survival

outage_survival(episodes: DataFrame, *, by: str | None = None) -> DataFrame

Empirical survival function of outage durations: the time-to-recovery view.

From the stockout_episodes event table, the empirical survival :math:S(t) = \Pr(\text{duration} > t) of outage durations, optionally grouped, with the median and P90 time-to-recovery. Strictly empirical (Kaplan-Meier reduces to the ECDF without censoring). Episodes still open at the observation window's edge are right-censored in the data; they are not imputed, so read the longest durations as lower bounds.

Parameters:

Name Type Description Default
episodes DataFrame

Output of stockout_episodes (needs duration_minutes).

required
by str

A grouping column (e.g. "station_id" or "kind"); one survival curve per group.

None

Returns:

Type Description
DataFrame

[<by>,] duration_minutes, survival, at_risk, n_episodes, median_recovery, p90_recovery.

References

Kaplan and Meier (1958), used here as a descriptive empirical survival estimator.

See Also

station_outage_rates : How often outages occur. stockout_episodes : The episode table this consumes.

Examples:

>>> import pandas as pd
>>> episodes = pd.DataFrame({"duration_minutes": [10, 20, 20, 60]})
>>> float(outage_survival(episodes)["median_recovery"].iloc[0])
20.0
Source code in src/gbfs_toolkit/analytics/service.py
def outage_survival(episodes: pd.DataFrame, *, by: str | None = None) -> pd.DataFrame:
    """Empirical survival function of outage durations: the time-to-recovery view.

    From the [`stockout_episodes`][gbfs_toolkit.stockout_episodes] event table, the empirical survival
    :math:`S(t) = \\Pr(\\text{duration} > t)` of outage durations, optionally grouped, with the
    median and P90 time-to-recovery. Strictly empirical (Kaplan-Meier reduces to the ECDF without
    censoring). Episodes still open at the observation window's edge are right-censored in the data;
    they are not imputed, so read the longest durations as lower bounds.

    Parameters
    ----------
    episodes : pandas.DataFrame
        Output of [`stockout_episodes`][gbfs_toolkit.stockout_episodes] (needs ``duration_minutes``).
    by : str, optional
        A grouping column (e.g. ``"station_id"`` or ``"kind"``); one survival curve per group.

    Returns
    -------
    pandas.DataFrame
        ``[<by>,] duration_minutes, survival, at_risk, n_episodes, median_recovery, p90_recovery``.

    References
    ----------
    Kaplan and Meier (1958), used here as a descriptive empirical survival estimator.

    See Also
    --------
    [`station_outage_rates`][gbfs_toolkit.station_outage_rates] : How often outages occur.
    [`stockout_episodes`][gbfs_toolkit.stockout_episodes] : The episode table this consumes.

    Examples
    --------
    >>> import pandas as pd
    >>> episodes = pd.DataFrame({"duration_minutes": [10, 20, 20, 60]})
    >>> float(outage_survival(episodes)["median_recovery"].iloc[0])
    20.0
    """
    require_columns(episodes, ["duration_minutes"], what="outage_survival")

    def _curve(group: pd.DataFrame) -> pd.DataFrame:
        d = np.sort(pd.to_numeric(group["duration_minutes"], errors="coerce").dropna().to_numpy())
        if d.size == 0:
            return pd.DataFrame(
                columns=[
                    "duration_minutes",
                    "survival",
                    "at_risk",
                    "n_episodes",
                    "median_recovery",
                    "p90_recovery",
                ]
            )
        uniq = np.unique(d)
        return pd.DataFrame(
            {
                "duration_minutes": uniq,
                "survival": [float((d > t).mean()) for t in uniq],
                "at_risk": [int((d >= t).sum()) for t in uniq],
                "n_episodes": int(d.size),
                "median_recovery": float(np.median(d)),
                "p90_recovery": float(np.quantile(d, 0.9)),
            }
        )

    if by is None:
        return _curve(episodes).reset_index(drop=True)
    parts = []
    for value, group in episodes.groupby(by, sort=True):
        curve = _curve(group)
        curve.insert(0, by, value)
        parts.append(curve)
    if not parts:
        return _curve(episodes.iloc[:0])
    return pd.concat(parts, ignore_index=True)