Reproducibility | Bus Check

Quick Start

git clone https://github.com/sbahamon/bus-check
cd bus-check
uv sync
uv pip install -e .
uv run --no-sync jupyter lab

Requires Python 3.11+ and uv (Astral's package manager).

What You'll Need

Python 3.11+ and uv (Astral's package manager)
Internet access — notebooks fetch data live from Chicago's public data portal
No API keys — ridership data is public. A CTA API key is only needed if you want to run your own headway data collection (a Cloudflare Worker handles this automatically for the live site).
~10 minutes to run all 8 notebooks (most time is API data fetching)

The Critical Gotcha

Always pair uv pip install -e . with uv run --no-sync.

Plain uv run (without --no-sync) re-syncs the virtual environment and drops the editable install. This causes ModuleNotFoundError: No module named 'bus_check'.

The safe pattern is always:

uv pip install -e . && uv run --no-sync jupyter ...

If you see ModuleNotFoundError, just run uv pip install -e . again.

Running the Notebooks

All 8 notebooks are independent — they each fetch data live from public APIs. No chaining required.

#	Notebook	Data Source	Key Output
01	Ridership Exploration 20-route YoY comparison + pooled DiD	SODA API	YoY changes, pooled DiD estimate
02	Headway Exploration GTFS scheduled vs. observed headways	GTFS + Cloudflare D1	Headway adherence rates
03	Phases 1–3 Only Excludes Phase 4 (no post-data)	SODA API	Filtered YoY comparison
04	Without Route #79 Sensitivity test excluding outlier	SODA API	Robustness check
05	Ridership Share FN share of total CTA ridership	SODA API	Share trend lines
06	DiD by Phase Phase-level DiD with bootstrap CIs	SODA API	P1 +428, P2 +514, P3 +1,142
07	Staggered DiD Callaway-Sant'Anna estimator	SODA API	ATT estimate
08	Regression DiD OLS with fixed effects + placebo	SODA API	Regression DiD, placebo test

Execute one notebook

uv pip install -e . && uv run --no-sync jupyter execute notebooks/01_ridership_exploration.ipynb --inplace

Execute all at once

for nb in notebooks/0{1..8}_*.ipynb; do
  echo "Running $nb..."
  uv pip install -e . && uv run --no-sync jupyter execute "$nb" --inplace
done

Verifying the Results

Run the test suite to confirm all components work correctly:

uv run pytest   # 163 tests should pass

Then compare notebook outputs against the key numbers on the main page:

Phase 1 DiD: +428 rides/day (+5.9%), 95% CI [+42, +799]
Phase 2 DiD: +514 rides/day (+4.2%), 95% CI [+163, +832]
Phase 3 DiD: +1,142 rides/day (+10.4%), 95% CI [+213, +2,492]
J14 Jeffery Jump YoY: +26.1%
13 of 16 Phase 1–3 routes gained riders YoY
Placebo test p-value: 0.925 (no pre-trends)

Data Sources

Ridership

Chicago Data Portal SODA API (dataset jyb9-n7fm). Public, no authentication required. Daily boardings by route from January 2023 through November 30, 2025.

Schedules (GTFS)

CTA GTFS static feed. Downloaded automatically by notebook 02 for scheduled headway computation.

Bus Tracker (optional)

CTA Bus Tracker API. Requires a CTA API key. Only needed for the real-time headway collector, not for ridership analysis.

Headway Data Caveat

The headway analysis (notebook 02) depends on real-time vehicle position data collected by a Cloudflare Worker that polls the CTA Bus Tracker API every 5 minutes during service hours and stores positions in Cloudflare D1. A fresh clone won't have this data. Your options:

Skip notebook 02's observed headway section (scheduled headways still work from GTFS)
Run the local collector yourself:

uv run python -m bus_check.collector.headway_collector

This requires a CTA_API_KEY in your .env file. See .env.example for the template. The local collector writes to data/headway.db (SQLite). For the live site, a Cloudflare Worker (worker/) handles collection automatically.

Known Limitations for Reproducibility

SODA data is live — results may change if Chicago updates the dataset
As of February 2026, ridership data goes through November 30, 2025
Phase launch dates are confirmed — config.py uses March 23, June 15, August 17, and December 21
Headway data is not included in the repo — observed headway data is collected by a Cloudflare Worker into D1 (for the live site) or by a local collector into SQLite (for local reproduction)

Project Structure

src/bus_check/config.py — all route/phase/date constants
src/bus_check/data/ — API clients (ridership, GTFS, Bus Tracker, D1)
src/bus_check/analysis/ — statistical models (ridership DiD, headway metrics)
notebooks/ — the 8 analysis notebooks
worker/ — Cloudflare Worker for automated headway data collection
tests/ — 163 tests validating all components

For AI Coding Assistants

Using Claude Code, Cursor, Copilot, or another AI coding assistant? See REPRODUCING.md in the repo root for a machine-readable reproduction guide written in direct, imperative language that agents parse well.