Skip to content

flag_rate_ci

flag_rate_ci

flag_rate_ci(verdict: DataFrame, *, seed: int = 42, n_boot: int = 10000, alpha: float = 0.05) -> DataFrame

System-level flag rate per class with a cluster-bootstrap confidence interval.

Collapses the per-station verdict of audit_static to per-system (flagged iff any station of the system is flagged), then resamples systems with replacement to bound the rate, accounting for within-system correlation. Seeded, so the interval is reproducible.

Parameters:

Name Type Description Default
verdict DataFrame

Output of audit_static (must carry system_id and A1 … A7).

required
seed int

Seed for the bootstrap resampling.

42
n_boot int

Number of bootstrap resamples.

10000
alpha float

Two-sided level; the interval is the central 1 - alpha.

0.05

Returns:

Type Description
DataFrame

Columns class, systems_flagged, rate, ci_lo, ci_hi (rates as fractions).

See Also

audit_static : Produces the per-station verdict this summarises. audit_sensitivity : The complementary threshold-robustness analysis.

Examples:

>>> import pandas as pd
>>> verdict = pd.DataFrame({
...     "system_id": ["a", "b", "c", "d"],
...     "A1": 0, "A2": 0, "A3": 0, "A4": 0, "A5": 0, "A6": 0,
...     "A7": [1, 1, 0, 0],
... })
>>> float(flag_rate_ci(verdict, n_boot=500).set_index("class").loc["A7", "rate"])
0.5
Source code in src/gbfs_toolkit/audit/static.py
def flag_rate_ci(
    verdict: pd.DataFrame,
    *,
    seed: int = 42,
    n_boot: int = 10_000,
    alpha: float = 0.05,
) -> pd.DataFrame:
    """System-level flag rate per class with a cluster-bootstrap confidence interval.

    Collapses the per-station verdict of [`audit_static`][gbfs_toolkit.audit_static] to per-system
    (flagged iff any station of the system is flagged), then resamples *systems*
    with replacement to bound the rate, accounting for within-system correlation.
    Seeded, so the interval is reproducible.

    Parameters
    ----------
    verdict : pandas.DataFrame
        Output of [`audit_static`][gbfs_toolkit.audit_static] (must carry ``system_id`` and ``A1 … A7``).
    seed : int, default 42
        Seed for the bootstrap resampling.
    n_boot : int, default 10000
        Number of bootstrap resamples.
    alpha : float, default 0.05
        Two-sided level; the interval is the central ``1 - alpha``.

    Returns
    -------
    pandas.DataFrame
        Columns ``class, systems_flagged, rate, ci_lo, ci_hi`` (rates as fractions).

    See Also
    --------
    [`audit_static`][gbfs_toolkit.audit_static] : Produces the per-station ``verdict`` this summarises.
    [`audit_sensitivity`][gbfs_toolkit.audit_sensitivity] : The complementary threshold-robustness analysis.

    Examples
    --------
    >>> import pandas as pd
    >>> verdict = pd.DataFrame({
    ...     "system_id": ["a", "b", "c", "d"],
    ...     "A1": 0, "A2": 0, "A3": 0, "A4": 0, "A5": 0, "A6": 0,
    ...     "A7": [1, 1, 0, 0],
    ... })
    >>> float(flag_rate_ci(verdict, n_boot=500).set_index("class").loc["A7", "rate"])
    0.5
    """
    sysf = verdict.groupby("system_id")[list(AUDIT_FLAGS)].max().astype(int)
    n = len(sysf)
    rng = np.random.default_rng(seed)
    resample = rng.integers(0, n, size=(n_boot, n)) if n else None
    rows = []
    for k in AUDIT_FLAGS:
        x = sysf[k].to_numpy()
        if n:
            boot = x[resample].mean(axis=1)
            lo, hi = np.percentile(boot, [100 * alpha / 2, 100 * (1 - alpha / 2)])
            rate = float(x.mean())
        else:
            lo = hi = rate = float("nan")
        rows.append(
            {
                "class": k,
                "systems_flagged": int(x.sum()),
                "rate": round(rate, 4),
                "ci_lo": round(float(lo), 4),
                "ci_hi": round(float(hi), 4),
            }
        )
    return pd.DataFrame(rows)