Skip to content

spatial_outage_redundancy

spatial_outage_redundancy

spatial_outage_redundancy(panel: DataFrame, *, radius_m: float = 300.0, time_col: str = 'fetched_at', value_col: str = 'num_bikes_available') -> DataFrame

Separate a station's local stockouts from systemic neighbourhood failures.

A station at zero bikes is not a service failure if a station 100 m away is full: the user simply walks. The real rupture is spatial. For each station this reports the share of time it is empty (local_outage_ratio) and the share of time it is empty and every observed neighbour within radius_m is also empty (systemic_outage_ratio), the fraction of outages that no nearby station can absorb. A neighbour with no reading at that timestamp is treated as unknown (it neither creates nor masks a systemic flag), and a timestamp needs at least one observed neighbour to count. Repeated polls for the same station and timestamp are de-duplicated (last kept), not summed. Purely descriptive: it reads observed stock, it neither predicts demand nor reroutes anyone.

Parameters:

Name Type Description Default
panel DataFrame

Availability panel with station_id, lat, lon, time_col and value_col (available bikes). Coordinates are taken as each station's first observation.

required
radius_m float

Great-circle walking radius defining a station's substitutes.

300.0
time_col str

Timestamp and per-station available-bike column.

'fetched_at'
value_col str

Timestamp and per-station available-bike column.

'fetched_at'

Returns:

Type Description
DataFrame

station_id, local_outage_ratio, systemic_outage_ratio, n_neighbors, n_obs. A high local but low systemic ratio is a well-buffered station; the two being close marks a genuine neighbourhood desert.

See Also

station_outage_rates : The non-spatial stockout rate. two_step_fca : Demand-weighted spatial accessibility. coverage_stats : Areal coverage of the network.

Examples:

Station a is always empty, but only counts as a systemic outage when its 300 m neighbour b is empty too:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "station_id": ["a", "b", "a", "b"],
...     "lat": [48.8500, 48.8501, 48.8500, 48.8501],
...     "lon": [2.3500, 2.3501, 2.3500, 2.3501],
...     "fetched_at": pd.to_datetime(
...         ["2026-01-01T08:00Z", "2026-01-01T08:00Z",
...          "2026-01-01T09:00Z", "2026-01-01T09:00Z"]),
...     "num_bikes_available": [0, 5, 0, 0],
... })
>>> out = spatial_outage_redundancy(panel, radius_m=300).set_index("station_id")
>>> float(out.loc["a", "local_outage_ratio"]), float(out.loc["a", "systemic_outage_ratio"])
(1.0, 0.5)
Source code in src/gbfs_toolkit/spatial/analytics.py
def spatial_outage_redundancy(
    panel: pd.DataFrame,
    *,
    radius_m: float = 300.0,
    time_col: str = "fetched_at",
    value_col: str = "num_bikes_available",
) -> pd.DataFrame:
    """Separate a station's *local* stockouts from *systemic* neighbourhood failures.

    A station at zero bikes is not a service failure if a station 100 m away is full:
    the user simply walks. The real rupture is *spatial*. For each station this reports
    the share of time it is empty (``local_outage_ratio``) and the share of time it is
    empty **and** every *observed* neighbour within ``radius_m`` is also empty
    (``systemic_outage_ratio``), the fraction of outages that no nearby station can
    absorb. A neighbour with no reading at that timestamp is treated as unknown (it
    neither creates nor masks a systemic flag), and a timestamp needs at least one
    observed neighbour to count. Repeated polls for the same station and timestamp are
    de-duplicated (last kept), not summed. Purely descriptive: it reads observed stock,
    it neither predicts demand nor reroutes anyone.

    Parameters
    ----------
    panel : pandas.DataFrame
        Availability panel with ``station_id, lat, lon``, ``time_col`` and ``value_col``
        (available bikes). Coordinates are taken as each station's first observation.
    radius_m : float, default 300.0
        Great-circle walking radius defining a station's substitutes.
    time_col, value_col : str
        Timestamp and per-station available-bike column.

    Returns
    -------
    pandas.DataFrame
        ``station_id, local_outage_ratio, systemic_outage_ratio, n_neighbors, n_obs``.
        A high ``local`` but low ``systemic`` ratio is a well-buffered station; the two
        being close marks a genuine neighbourhood desert.

    See Also
    --------
    [`station_outage_rates`][gbfs_toolkit.station_outage_rates] : The non-spatial stockout rate.
    [`two_step_fca`][gbfs_toolkit.two_step_fca] : Demand-weighted spatial accessibility.
    [`coverage_stats`][gbfs_toolkit.coverage_stats] : Areal coverage of the network.

    Examples
    --------
    Station ``a`` is always empty, but only counts as a systemic outage when its
    300 m neighbour ``b`` is empty too:

    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "station_id": ["a", "b", "a", "b"],
    ...     "lat": [48.8500, 48.8501, 48.8500, 48.8501],
    ...     "lon": [2.3500, 2.3501, 2.3500, 2.3501],
    ...     "fetched_at": pd.to_datetime(
    ...         ["2026-01-01T08:00Z", "2026-01-01T08:00Z",
    ...          "2026-01-01T09:00Z", "2026-01-01T09:00Z"]),
    ...     "num_bikes_available": [0, 5, 0, 0],
    ... })
    >>> out = spatial_outage_redundancy(panel, radius_m=300).set_index("station_id")
    >>> float(out.loc["a", "local_outage_ratio"]), float(out.loc["a", "systemic_outage_ratio"])
    (1.0, 0.5)
    """
    require_columns(
        panel, ["station_id", "lat", "lon", time_col, value_col], what="spatial_outage_redundancy"
    )
    coords = panel.groupby("station_id")[["lat", "lon"]].first()
    stations = coords.index.to_numpy()
    pos = {s: i for i, s in enumerate(stations)}
    n_st = len(stations)
    tree = GeoKDTree(coords["lat"].to_numpy(), coords["lon"].to_numpy())
    neigh = tree.query_radius(coords["lat"].to_numpy(), coords["lon"].to_numpy(), radius_m=radius_m)

    # One cell per (station, timestamp). Deduplicate repeated polls deterministically
    # (independent of input row order): sort by value with NaN first, then keep the
    # highest reported count, rather than summing them (which would corrupt the
    # empty/occupied test) or keeping an order-dependent row.
    vals = num(panel, value_col)
    long = (
        pd.DataFrame(
            {
                "_s": panel["station_id"].map(pos).to_numpy(),
                "_t": panel[time_col].to_numpy(),
                "_v": vals.to_numpy(),
            }
        )
        .sort_values(["_s", "_t", "_v"], na_position="first")
        .drop_duplicates(["_s", "_t"], keep="last")
    )
    grid = long.pivot(index="_t", columns="_s", values="_v").reindex(columns=range(n_st))
    matrix = grid.to_numpy(dtype="float64")  # times x stations; NaN where unobserved
    empty = matrix == 0  # NaN (unobserved) compares False
    has_bike = matrix > 0  # NaN compares False, so unobserved is neither empty nor occupied

    rows = []
    for i, station in enumerate(stations):
        nb = neigh[i][neigh[i] < n_st]
        others = nb[nb != i]
        observed = ~np.isnan(matrix[:, i])
        n_obs = int(observed.sum())
        # Systemic outage: the station is empty AND no *observed* neighbour has a bike,
        # with at least one neighbour observed (an unobserved neighbour is unknown, not
        # empty, so it neither creates nor masks a systemic flag).
        if others.size:
            neighbour_observed = (~np.isnan(matrix[:, others])).any(axis=1)
            neighbour_has_bike = has_bike[:, others].any(axis=1)
            systemic = empty[:, i] & neighbour_observed & ~neighbour_has_bike
        else:
            systemic = np.zeros(matrix.shape[0], dtype=bool)
        rows.append(
            {
                "station_id": station,
                "local_outage_ratio": float(empty[observed, i].mean()) if n_obs else float("nan"),
                "systemic_outage_ratio": float(systemic[observed].mean())
                if n_obs
                else float("nan"),
                "n_neighbors": int(nb.size - 1),
                "n_obs": n_obs,
            }
        )
    return pd.DataFrame(rows)