Skip to content

coverage_report

coverage_report

coverage_report(panel: DataFrame, *, expected_freq: str = '5min', level: str = 'station') -> DataFrame

Longitudinal coverage: quantify missingness before you model.

Operators go offline and scrapers crash; calculate_net_flow / clustering silently assume continuity. With level="station" this reports how complete each station's series is, against the system-wide observation window (so a station that dropped out shows low uptime). With level="system" it returns one row per system, the summary a paper's "Data and methods" section needs: window, cadence, cadence jitter and overall yield.

Parameters:

Name Type Description Default
panel DataFrame

A panel from build_availability_panel (MultiIndexed) or a flat frame with system_id, station_id, fetched_at.

required
expected_freq str

Your intended polling cadence (a pandas offset alias).

"5min"
level ('station', 'system')

"station" returns the per-station coverage; "system" returns a per-system summary (median cadence, cadence jitter, yield).

"station"

Returns:

Type Description
DataFrame

For level="station", indexed by (system_id, station_id): expected_snapshots, actual_snapshots, uptime_pct, longest_gap_minutes. For level="system", indexed by system_id: global_start, global_end, n_stations, total_snapshots, median_cadence_s, cadence_jitter_s, station_hours_yield_pct.

See Also

audit_feed : The audit behind the report. generate_manifest : Manifest of an archived collection.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "system_id": "s", "station_id": ["a", "a", "b"],
...     "fetched_at": pd.to_datetime(
...         ["2026-01-01T00:00Z", "2026-01-01T00:05Z", "2026-01-01T00:00Z"]),
... })
>>> int(coverage_report(panel, level="system")["total_snapshots"].iloc[0])
2
Source code in src/gbfs_toolkit/io/timeseries.py
def coverage_report(
    panel: pd.DataFrame, *, expected_freq: str = "5min", level: str = "station"
) -> pd.DataFrame:
    """Longitudinal coverage: quantify missingness *before* you model.

    Operators go offline and scrapers crash; ``calculate_net_flow`` / clustering silently
    assume continuity. With ``level="station"`` this reports how complete each station's
    series is, against the system-wide observation window (so a station that dropped out
    shows low uptime). With ``level="system"`` it returns one row per system, the summary a
    paper's "Data and methods" section needs: window, cadence, cadence jitter and overall
    yield.

    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, fetched_at``.
    expected_freq : str, default "5min"
        Your intended polling cadence (a pandas offset alias).
    level : {"station", "system"}, default "station"
        ``"station"`` returns the per-station coverage; ``"system"`` returns a per-system
        summary (median cadence, cadence jitter, yield).

    Returns
    -------
    pandas.DataFrame
        For ``level="station"``, indexed by ``(system_id, station_id)``:
        ``expected_snapshots, actual_snapshots, uptime_pct, longest_gap_minutes``.
        For ``level="system"``, indexed by ``system_id``: ``global_start, global_end,
        n_stations, total_snapshots, median_cadence_s, cadence_jitter_s,
        station_hours_yield_pct``.

    See Also
    --------
    [`audit_feed`][gbfs_toolkit.audit_feed] : The audit behind the report.
    [`generate_manifest`][gbfs_toolkit.generate_manifest] : Manifest of an archived collection.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "system_id": "s", "station_id": ["a", "a", "b"],
    ...     "fetched_at": pd.to_datetime(
    ...         ["2026-01-01T00:00Z", "2026-01-01T00:05Z", "2026-01-01T00:00Z"]),
    ... })
    >>> int(coverage_report(panel, level="system")["total_snapshots"].iloc[0])
    2
    """
    if level not in ("station", "system"):
        raise ValueError(f"level must be 'station' or 'system', got {level!r}")
    df = panel_frame(panel)
    require_columns(df, ["system_id", "station_id", "fetched_at"], what="coverage_report")
    df = df[["system_id", "station_id", "fetched_at"]].copy()
    df["fetched_at"] = pd.to_datetime(df["fetched_at"])
    step = pd.Timedelta(expected_freq)

    if level == "system":
        rows = []
        for sid, sysdf in df.groupby("system_id", sort=False):
            t0, t1 = sysdf["fetched_at"].min(), sysdf["fetched_at"].max()
            snapshots = sysdf["fetched_at"].drop_duplicates().sort_values()
            deltas = snapshots.diff().dropna().dt.total_seconds()
            n_stations = int(sysdf["station_id"].nunique())
            expected = int((t1 - t0) / step) + 1 if t1 > t0 else 1
            actual_pairs = len(sysdf[["station_id", "fetched_at"]].drop_duplicates())
            denom = expected * n_stations
            median_dt = float(deltas.median()) if len(deltas) else float("nan")
            rows.append(
                {
                    "system_id": sid,
                    "global_start": t0,
                    "global_end": t1,
                    "n_stations": n_stations,
                    "total_snapshots": int(len(snapshots)),
                    "median_cadence_s": round(median_dt, 1),
                    "cadence_jitter_s": round(float((deltas - median_dt).abs().median()), 1)
                    if len(deltas)
                    else float("nan"),
                    "station_hours_yield_pct": round(min(1.0, actual_pairs / denom) * 100, 1)
                    if denom
                    else float("nan"),
                }
            )
        if not rows:
            return pd.DataFrame(
                columns=[
                    "global_start",
                    "global_end",
                    "n_stations",
                    "total_snapshots",
                    "median_cadence_s",
                    "cadence_jitter_s",
                    "station_hours_yield_pct",
                ],
                index=pd.Index([], name="system_id"),
            )
        return pd.DataFrame(rows).set_index("system_id")

    rows = []
    for sid, sysdf in df.groupby("system_id", sort=False):
        t0, t1 = sysdf["fetched_at"].min(), sysdf["fetched_at"].max()
        expected = int((t1 - t0) / step) + 1 if t1 > t0 else 1
        for stid, g in sysdf.groupby("station_id", sort=False):
            ts = g["fetched_at"].drop_duplicates().sort_values()
            actual = int(len(ts))
            gaps = ts.diff().dropna()
            longest = gaps.max().total_seconds() / 60 if len(gaps) else 0.0
            rows.append(
                {
                    "system_id": sid,
                    "station_id": stid,
                    "expected_snapshots": expected,
                    "actual_snapshots": actual,
                    "uptime_pct": round(min(1.0, actual / expected) * 100, 1),
                    "longest_gap_minutes": round(float(longest), 1),
                }
            )
    if not rows:
        return pd.DataFrame(
            columns=["expected_snapshots", "actual_snapshots", "uptime_pct", "longest_gap_minutes"],
            index=pd.MultiIndex.from_arrays([[], []], names=["system_id", "station_id"]),
        )
    return pd.DataFrame(rows).set_index(["system_id", "station_id"])