A local Python application that estimates each driver's chance of winning an F1 Grand Prix before the race and updates predictions as lap data arrives. A Streamlit dashboard displays probabilities and race state.
FastF1 / OpenF1 → ingestion → SQLite raw tables → feature engineering
↓
SQLite features
↓
field-choice win models
↓
SQLite predictions
↓
Streamlit + Plotly
The prediction pipeline and dashboard run independently and share a SQLite database. WAL mode supports concurrent reads and writes; prediction replacements use transactions.
| Layer | Tools |
|---|---|
| Runtime | Python 3.11+, setuptools |
| Data sources | FastF1 for years through 2022; OpenF1 for 2023 onward |
| HTTP and retries | HTTPX, Tenacity |
| Storage | SQLite, SQLAlchemy |
| Feature engineering | pandas, NumPy |
| Models | Field-choice model (conditional logit, fitted with SciPy); XGBoost kept as an evaluation challenger |
| Model artifacts and normalization | joblib, SciPy |
| Live scheduling | APScheduler |
| Dashboard | Streamlit, Plotly |
| Tests | pytest |
Run commands from the repository root:
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.lock # exact versions the model artifacts were built with
python -m pip install -e '.[dev]'The local database and downloaded data cache are excluded from Git. Backfill historical sessions to create the database and features:
python scripts/backfill.py --years 2022 2023 2024
python scripts/check_backfill.pyDownloads require network access and can take time. To rebuild features separately:
python scripts/build_features.pyTrain both models with 2024 held out for validation:
python scripts/train.py --model prerace
python scripts/train.py --model inrace
python scripts/evaluate.py # walk-forward: served model vs baselines and an XGBoost challengerModel artifacts live in data/models/, each with a .meta.json recording what it was trained on. evaluate.py writes a timestamped report to data/eval/. Retrain them in your environment if serialized artifacts are incompatible with installed dependency versions.
Start the prediction pipeline:
python -m f1_prediction.pipelineIn a second terminal, activate the environment and launch the dashboard:
source .venv/bin/activate
streamlit run src/f1_prediction/dashboard.pyThe dashboard binds to localhost. The pipeline selects the latest race session in the database, computes pre-race predictions if needed, and polls every 30 seconds. New lap arrivals trigger in-race inference. The dashboard's in-race view refreshes every 15 seconds.
Before running against a current race, ingest its available sessions and build its features. Live API availability and access requirements depend on the data provider.
- Pre-race: qualifying delta to pole, FP2/FP3 pace, circuit win rate, championship position, grid position, and driver experience.
- In-race: gap to leader, tyre age, pit-stop count, position, intervals ahead/behind, pit-stop delta, lap number, laps remaining, and five tyre-compound indicators.
Training and inference share feature definitions in src/f1_prediction/inference/features.py. Each model predicts a binary winner probability per driver. The application then applies softmax within each race or race/lap group and stores the resulting distribution.
Softmax is applied to already calibrated probabilities, which compresses the displayed distribution and changes its calibration. A sum of one does not establish predictive accuracy. Training and validation scripts report Brier score and log loss for the raw classifier probabilities separately.
Calibration folds are not explicitly grouped by race; race-aware calibration is an area for improvement. Live inference rebuilds the session's in-race features and predicts only the latest available lap, so polling can skip intermediate lap predictions. Historical replay calls inference directly because the live poller checks the actual session time window.
pytest -m 'not slow'Tests cover ingestion, features, training, prediction storage, polling, and historical replay. Tests marked slow can require FastF1 cache/network access.
For replay options, run:
python scripts/replay_race.py --helpIn-place replay temporarily clears and rebuilds a race's raw rows. Use a scratch database copy with --db when experimenting; the normal dashboard continues to use data/f1.db.
src/f1_prediction/
ingest/ Data clients, loaders, and normalization
db/ Schema, connections, queries, and inserts
features/ Historical and lap-level feature computation
inference/ Shared feature contracts and prediction storage
live/ Polling and session-window checks
dashboard_lib/ Dashboard queries and charts
pipeline.py Poll-and-infer orchestration
dashboard.py Streamlit application
scripts/ Backfill, feature building, training, validation, replay
tests/ Test suite and sample API fixtures
data/models/ Serialized models
Implementation dependencies are declared in pyproject.toml. Older planning documents may describe technologies that differ from the implemented stack.