Skip to content

audit_static

audit_static

audit_static(stations: DataFrame, *, a7_scope: str = 'docked', a4_sigma: float = A4_SIGMA, a5_area_km2: float = A5_BBOX_MAX_KM2, a6_tau: float = A6_RATE_THRESHOLD, a7_tau: float = A7_RATE_THRESHOLD, n_min: int | None = None) -> DataFrame

Run the A1–A7 semantic audit on a canonical station-information frame.

All policy thresholds are exposed so the audit can be swept for sensitivity analysis (see audit_sensitivity); every default equals the published gbfs-audit-catalogue value, so calling with no keywords reproduces the released verdicts exactly.

Parameters:

Name Type Description Default
stations DataFrame

Canonical station inventory; requires system_id, station_id, station_type, capacity, lat, lon.

required
a7_scope ('docked', 'all')

Scope of the A7 null-capacity rule. "docked" (default) counts only physical docked stations, so dockless systems are not flagged spuriously. "all" counts every station, reproducing the original gbfs-audit-catalogue verdicts.

"docked"
a4_sigma float

Multiplier of the robust (MAD-rescaled) scale in the A4 nearest-neighbour outlier rule.

``3.0``
a5_area_km2 float

Bounding-box area (km²) above which a system trips the A5 out-of-perimeter rule.

``50000``
a6_tau float

Minimum share of zero-capacity docked stations for the A6 rule.

``0.01``
a7_tau float

Minimum share of null-capacity stations for the A7 rule.

``0.50``
n_min int

Override the minimum system size (number of stations) for the system-level rules A2/A6/A7. None (default) keeps the published value of 20.

None

Returns:

Type Description
DataFrame

One row per input station with boolean columns A1 … A7, a flagged column (any rule fired) and a human-readable reason (comma-separated rule names).

See Also

audit_dynamic : The companion D1-D3 audit of live availability payloads. audit_frames : Run static and dynamic audits together on canonical frames. drop_flagged : Keep only the stations that pass this audit, in one call. audit_sensitivity : Sweep these thresholds to test conclusion robustness. flag_rate_ci : Bootstrap a confidence interval on each class's flag rate.

Examples:

>>> import pandas as pd
>>> stations = pd.DataFrame({
...     "system_id": "s", "station_id": ["a", "b"],
...     "station_type": ["docked_bike", "carsharing"],
...     "capacity": [20, 5], "lat": [48.85, 48.86], "lon": [2.35, 2.36],
... })
>>> audit_static(stations)[["station_id", "A1", "flagged"]]
  station_id     A1  flagged
0          a  False    False
1          b   True     True
Source code in src/gbfs_toolkit/audit/static.py
def audit_static(
    stations: pd.DataFrame,
    *,
    a7_scope: str = "docked",
    a4_sigma: float = A4_SIGMA,
    a5_area_km2: float = A5_BBOX_MAX_KM2,
    a6_tau: float = A6_RATE_THRESHOLD,
    a7_tau: float = A7_RATE_THRESHOLD,
    n_min: int | None = None,
) -> pd.DataFrame:
    """Run the A1–A7 semantic audit on a canonical station-information frame.

    All policy thresholds are exposed so the audit can be swept for sensitivity
    analysis (see [`audit_sensitivity`][gbfs_toolkit.audit_sensitivity]); every default equals
    the published ``gbfs-audit-catalogue`` value, so calling with no keywords
    reproduces the released verdicts exactly.

    Parameters
    ----------
    stations : pandas.DataFrame
        Canonical station inventory; requires
        ``system_id, station_id, station_type, capacity, lat, lon``.
    a7_scope : {"docked", "all"}, default "docked"
        Scope of the A7 null-capacity rule. ``"docked"`` (default) counts only physical
        docked stations, so dockless systems are not flagged spuriously. ``"all"`` counts
        every station, reproducing the original ``gbfs-audit-catalogue`` verdicts.
    a4_sigma : float, default ``3.0``
        Multiplier of the robust (MAD-rescaled) scale in the A4 nearest-neighbour
        outlier rule.
    a5_area_km2 : float, default ``50000``
        Bounding-box area (km²) above which a system trips the A5 out-of-perimeter rule.
    a6_tau : float, default ``0.01``
        Minimum share of zero-capacity docked stations for the A6 rule.
    a7_tau : float, default ``0.50``
        Minimum share of null-capacity stations for the A7 rule.
    n_min : int, optional
        Override the minimum system size (number of stations) for the system-level
        rules A2/A6/A7. ``None`` (default) keeps the published value of ``20``.

    Returns
    -------
    pandas.DataFrame
        One row per input station with boolean columns ``A1 … A7``, a
        ``flagged`` column (any rule fired) and a human-readable ``reason``
        (comma-separated rule names).

    See Also
    --------
    [`audit_dynamic`][gbfs_toolkit.audit_dynamic] : The companion D1-D3 audit of live availability payloads.
    [`audit_frames`][gbfs_toolkit.audit_frames] : Run static and dynamic audits together on canonical frames.
    [`drop_flagged`][gbfs_toolkit.drop_flagged] : Keep only the stations that pass this audit, in one call.
    [`audit_sensitivity`][gbfs_toolkit.audit_sensitivity] : Sweep these thresholds to test conclusion robustness.
    [`flag_rate_ci`][gbfs_toolkit.flag_rate_ci] : Bootstrap a confidence interval on each class's flag rate.

    Examples
    --------
    >>> import pandas as pd
    >>> stations = pd.DataFrame({
    ...     "system_id": "s", "station_id": ["a", "b"],
    ...     "station_type": ["docked_bike", "carsharing"],
    ...     "capacity": [20, 5], "lat": [48.85, 48.86], "lon": [2.35, 2.36],
    ... })
    >>> audit_static(stations)[["station_id", "A1", "flagged"]]  # doctest: +NORMALIZE_WHITESPACE
      station_id     A1  flagged
    0          a  False    False
    1          b   True     True
    """
    require_columns(stations, _REQUIRED, what="audit_static")
    df = stations.reset_index(drop=True)
    projected = project_meters(
        df["lat"].to_numpy(dtype="float64"), df["lon"].to_numpy(dtype="float64")
    )
    a2_min = A2_MIN_STATIONS if n_min is None else n_min
    a6_min = A6_MIN_STATIONS if n_min is None else n_min
    a7_min = A7_MIN_STATIONS if n_min is None else n_min

    out = pd.DataFrame({"system_id": df["system_id"], "station_id": df["station_id"]})
    out["A1"] = (df["station_type"] == "carsharing").to_numpy()
    out["A2"] = _flag_a2(df, min_stations=a2_min).to_numpy()
    out["A3"] = (df["station_type"] == "free_floating").to_numpy()
    out["A4"] = _flag_a4(df, projected, a4_sigma=a4_sigma)
    out["A5"] = _flag_a5(df, area_km2=a5_area_km2)
    out["A6"] = _flag_a6(df, tau=a6_tau, min_stations=a6_min).to_numpy()
    out["A7"] = _flag_a7(df, scope=a7_scope, tau=a7_tau, min_stations=a7_min).to_numpy()

    flags = out[list(AUDIT_FLAGS)].to_numpy()
    out["flagged"] = flags.any(axis=1)
    out["reason"] = [
        ", ".join(RULES[f]["name"] for f, fired in zip(AUDIT_FLAGS, row, strict=True) if fired)
        for row in flags
    ]
    return out