Rigorous & comparative analysis¶
The two analyses a reviewer leans on hardest: showing the audit's verdicts are not knife-edge, and turning the clean stations into defensible research metrics. Both parts are self-contained (bundled data plus small synthetic frames, no network) and run in CI.
Part 1 — Audit robustness and uncertainty¶
Report the A1–A7 audit the way a careful study should: not just the verdict, but evidence that it survives the threshold choices.
- Verdict and capacity convention
(
audit_static,capacity_convention). - Threshold robustness with
audit_sensitivity— the Jaccard overlap of the flagged set across a grid, so you can claim a stability plateau. - Seeded cluster-bootstrap intervals on every flag rate with
flag_rate_ci. - Spatial hotspots controlled for multiple testing:
local_morans_iwithfdr=True(Benjamini–Hochberg).
"""A rigorous, reproducible audit: verdict, robustness, uncertainty, hotspots.
Self-contained (uses the bundled ``load_example`` dataset and small synthetic
frames, no network), so it runs anywhere:
python 05_rigorous_audit.py
It walks the audit the way a careful study would report it: the A1-A7 verdict and
the capacity convention, then a threshold-sensitivity sweep and a bootstrap
confidence interval to show the conclusions are not knife-edge, then spatial
hotspots with a false-discovery-rate correction.
"""
import numpy as np
import pandas as pd
import gbfs_toolkit as gb
def main() -> None:
info, _status = gb.load_example()
# 1. The verdict and the capacity-field convention of the (single) system.
verdict = gb.audit_static(info)
print("Flagged stations:", int(verdict["flagged"].sum()), "/", len(verdict))
print("Capacity convention:", gb.capacity_convention(info).to_dict(), "\n")
# 2. Robustness: a synthetic 25-station system that publishes 60% NaN capacity
# trips A7; the sweep shows the flagged set is stable across thresholds.
synth = pd.DataFrame(
{
"system_id": "demo",
"station_id": [str(i) for i in range(25)],
"station_type": "docked_bike",
"capacity": [np.nan] * 15 + [12.0] * 10,
"lat": 48.85 + 0.001 * np.arange(25),
"lon": 2.35 + 0.001 * np.arange(25),
}
)
sweep = gb.audit_sensitivity(synth, {"a7_tau": [0.4, 0.5, 0.6, 0.7]}, a7_scope="all")
a7 = sweep[sweep["class"] == "A7"]
print("A7 robustness to its threshold (Jaccard vs baseline):")
print(a7[["value", "systems_flagged", "jaccard_vs_baseline"]].to_string(index=False), "\n")
# 3. Uncertainty: a cluster-bootstrap CI on the system-level flag rates (seeded).
many = pd.concat(
[
synth.assign(system_id=f"s{k}", capacity=[np.nan] * (12 + k) + [10.0] * (13 - k))
for k in range(8)
],
ignore_index=True,
)
ci = gb.flag_rate_ci(gb.audit_static(many, a7_scope="all"), seed=42)
print("Flag-rate 95% bootstrap CIs:")
print(
ci[ci["systems_flagged"] > 0][["class", "rate", "ci_lo", "ci_hi"]].to_string(index=False),
"\n",
)
# 4. Spatial hotspots with FDR control (no naive per-station alpha).
lisa = gb.local_morans_i(info, "capacity", permutations=499, seed=0, fdr=True)
print("LISA cluster types (FDR-controlled):", lisa["cluster_type"].value_counts().to_dict())
if __name__ == "__main__":
main()
Part 2 — Equity, accessibility and rebalancing¶
Three downstream questions, and the signature rebalancing metric.
- Equity with
theil_index(between/within-zone) andpalma_ratio. - Accessibility under distance decay with
two_step_fca(E2SFCA). - Spatial fragmentation of the live fleet with
rebalancing_tension(Wasserstein earth-mover distance, purely descriptive), pluscensored_time_ratioand an honest interval for autocorrelated series (block_bootstrap_ci,effective_sample_size).
"""Equity, accessibility and the signature rebalancing-tension metric.
Self-contained (bundled ``load_example`` plus small synthetic frames, no network):
python 06_equity_rebalancing.py
Three research angles a transport-geography study would want: how unequally the
supply is shared (Theil decomposition, Palma ratio), how reachable it is under
distance decay (E2SFCA), and how spatially fragmented the live fleet is at each
moment (the Wasserstein rebalancing tension), plus the observability loss from
saturation and an honest interval for an autocorrelated series.
"""
import numpy as np
import pandas as pd
import gbfs_toolkit as gb
def main() -> None:
info, _status = gb.load_example()
# 1. Equity of a skewed capacity distribution (40 small periphery + 10 big
# centre stations): Theil splits inequality into between/within-zone, Palma
# measures the extremes. (Needs more than a handful of stations to be meaningful.)
rng = np.random.default_rng(0)
caps = np.concatenate([rng.integers(2, 8, 40), rng.integers(20, 40, 10)])
zones = ["periphery"] * 40 + ["centre"] * 10
print("Theil decomposition:", gb.theil_index(caps, groups=zones).round(3).to_dict())
print("Palma ratio (top10/bottom40):", round(gb.palma_ratio(caps), 2), "\n")
# 2. Accessibility under distance decay (E2SFCA): demand points are BYOD.
demand = pd.DataFrame(
{"lat": [48.853, 48.857], "lon": [2.349, 2.354], "population": [1200, 800]}
)
access = gb.two_step_fca(info, demand, max_distance_m=800, decay="gaussian")
print("E2SFCA accessibility per demand point:", access.round(6).to_list(), "\n")
# 3. A synthetic 3-station, 3-timestamp panel for the dynamic metrics.
times = pd.date_range("2026-06-01T08:00Z", periods=3, freq="5min")
panel = pd.DataFrame(
[
{
"station_id": s,
"lat": la,
"lon": lo,
"fetched_at": t,
"num_bikes_available": b,
"num_docks_available": 20 - b,
}
for s, la, lo in [("a", 48.85, 2.35), ("b", 48.95, 2.35), ("c", 48.85, 2.55)]
for t, b in zip(
times, {"a": [20, 10, 0], "b": [0, 5, 12], "c": [4, 6, 8]}[s], strict=True
)
]
)
tension = gb.rebalancing_tension(panel)
print("Rebalancing tension (bike-km) per timestamp:")
print(tension.round(2).to_string(), "\n")
print("Censored time ratio:", gb.censored_time_ratio(panel).round(3).to_dict(), "\n")
# 4. Honest uncertainty for an autocorrelated availability series.
series = pd.Series(np.sin(np.linspace(0, 12, 200)) * 5 + 10)
print("Effective sample size:", round(gb.effective_sample_size(series), 1), "of 200")
print("Block-bootstrap mean CI:", gb.block_bootstrap_ci(series, seed=42).round(2).to_dict())
if __name__ == "__main__":
main()