Skip to content

audit_sensitivity

audit_sensitivity

audit_sensitivity(stations: DataFrame, grids: dict[str, list], *, a7_scope: str = 'docked', **baseline: Any) -> DataFrame

One-at-a-time threshold sensitivity of the A1–A7 audit.

For each (parameter, value) in grids, re-run audit_static with that single threshold changed (the others held at their baseline) and report, per class, the number of flagged systems and the Jaccard overlap of the flagged-system set against the baseline audit. Deterministic (no sampling), so it is the reproducible backbone of a threshold-robustness analysis.

Parameters:

Name Type Description Default
stations DataFrame

Canonical station inventory (see audit_static).

required
grids dict[str, list]

Maps an audit_static threshold keyword (a4_sigma, a5_area_km2, a6_tau, a7_tau, n_min) to the values to sweep.

required
a7_scope ('docked', 'all')

Held fixed across the sweep.

"docked"
**baseline Any

Threshold keywords defining the baseline audit (defaults reproduce the published verdicts).

{}

Returns:

Type Description
DataFrame

Columns param, value, class, systems_flagged, jaccard_vs_baseline. jaccard_vs_baseline == 1.0 means the flagged-system set is unchanged; a value near 1 across a wide grid is evidence the conclusion sits on a stability plateau.

See Also

audit_static : The single audit this sweeps one threshold at a time. flag_rate_ci : The complementary sampling-based uncertainty on flag rates.

Examples:

>>> import pandas as pd
>>> stations = pd.DataFrame({
...     "system_id": "s", "station_id": [str(i) for i in range(20)],
...     "station_type": "docked_bike",
...     "capacity": [float("nan")] * 12 + [10.0] * 8,
...     "lat": 48.85, "lon": 2.35,
... })
>>> sens = audit_sensitivity(stations, {"a7_tau": [0.5, 0.7]}, a7_scope="all")
>>> sens[sens["class"] == "A7"]["systems_flagged"].tolist()
[1, 0]
Source code in src/gbfs_toolkit/audit/static.py
def audit_sensitivity(
    stations: pd.DataFrame,
    grids: dict[str, list],
    *,
    a7_scope: str = "docked",
    **baseline: Any,
) -> pd.DataFrame:
    """One-at-a-time threshold sensitivity of the A1–A7 audit.

    For each ``(parameter, value)`` in ``grids``, re-run [`audit_static`][gbfs_toolkit.audit_static] with
    that single threshold changed (the others held at their baseline) and report,
    per class, the number of flagged systems and the Jaccard overlap of the
    flagged-system set against the baseline audit. Deterministic (no sampling), so
    it is the reproducible backbone of a threshold-robustness analysis.

    Parameters
    ----------
    stations : pandas.DataFrame
        Canonical station inventory (see [`audit_static`][gbfs_toolkit.audit_static]).
    grids : dict[str, list]
        Maps an [`audit_static`][gbfs_toolkit.audit_static] threshold keyword (``a4_sigma``,
        ``a5_area_km2``, ``a6_tau``, ``a7_tau``, ``n_min``) to the values to sweep.
    a7_scope : {"docked", "all"}, default "docked"
        Held fixed across the sweep.
    **baseline
        Threshold keywords defining the baseline audit (defaults reproduce the
        published verdicts).

    Returns
    -------
    pandas.DataFrame
        Columns ``param, value, class, systems_flagged, jaccard_vs_baseline``.
        ``jaccard_vs_baseline == 1.0`` means the flagged-system set is unchanged;
        a value near 1 across a wide grid is evidence the conclusion sits on a
        stability plateau.

    See Also
    --------
    [`audit_static`][gbfs_toolkit.audit_static] : The single audit this sweeps one threshold at a time.
    [`flag_rate_ci`][gbfs_toolkit.flag_rate_ci] : The complementary sampling-based uncertainty on flag rates.

    Examples
    --------
    >>> import pandas as pd
    >>> stations = pd.DataFrame({
    ...     "system_id": "s", "station_id": [str(i) for i in range(20)],
    ...     "station_type": "docked_bike",
    ...     "capacity": [float("nan")] * 12 + [10.0] * 8,
    ...     "lat": 48.85, "lon": 2.35,
    ... })
    >>> sens = audit_sensitivity(stations, {"a7_tau": [0.5, 0.7]}, a7_scope="all")
    >>> sens[sens["class"] == "A7"]["systems_flagged"].tolist()
    [1, 0]
    """
    base = audit_static(stations, a7_scope=a7_scope, **baseline)
    base_sets = {k: set(base.loc[base[k], "system_id"]) for k in AUDIT_FLAGS}
    rows = []
    for param, values in grids.items():
        for value in values:
            res = audit_static(stations, a7_scope=a7_scope, **{**baseline, param: value})
            for k in AUDIT_FLAGS:
                flagged = set(res.loc[res[k], "system_id"])
                rows.append(
                    {
                        "param": param,
                        "value": value,
                        "class": k,
                        "systems_flagged": len(flagged),
                        "jaccard_vs_baseline": round(_jaccard(flagged, base_sets[k]), 4),
                    }
                )
    return pd.DataFrame(rows)