A ready, end-to-end ML project that compares model-implied probabilities against bookmaker-implied probabilities for EPL matches. The focus is on calibration, evaluation, and risk-aware decision analysis, not guaranteed profit.
- Calibrated probabilistic modeling (isotonic regression)
- Time-aware evaluation to reduce leakage
- Market vs model edge analysis + backtests
- Live odds report + automated future predictions
- Streamlit demo designed for non-technical users
- Full ML pipeline: data → features → training → calibration → evaluation → app
- Risk-aware thinking: EV filters, capped Kelly sizing, Monte Carlo stress test
- Production signals: tests, CI, CLI wrapper, model card, reproducible scripts
.
├── data/ # Season CSVs and generated artifacts
├── models/ # Saved model artifacts (not committed)
├── notebooks/ # Exploration
├── src/ # Core pipeline and app
├── tests/ # Unit tests
├── MODEL_CARD.md # Model assumptions and limitations
├── CONTRIBUTING.md # Contribution guidelines
└── pyproject.toml # Tooling configuration
python -m pip install -r src/requirements.txt -r requirements-dev.txtTrain and predict (improved OOS pipeline):
python src/train_xgb_oos_improved.py
python src/predict_xgb_oos_improved.pyRun the dashboard:
streamlit run src/app.pyOptional CLI wrapper:
python src/cli.py train --variant xgb-oos-improved
python src/cli.py predict --variant xgb-oos-improved
python src/cli.py backtest --variant kelly-oosGenerate a recruiter-friendly report from a fresh CSV drop of odds:
python src/live_odds_report.py --input data/live_odds.csv --outdir reports/live_odds_demoOutputs:
reports/live_odds_demo/report.html(shareable report)reports/live_odds_demo/snapshot.png(dashboard-style image)reports/live_odds_demo/candidates.csv(filtered edges)
If your input CSV is missing Elo features, the script will compute them from
historical season files in data/.
Use free-tier APIs to build data/PL-future.csv automatically.
Set keys:
export ODDS_API_KEY="your-odds-api-key"
export FOOTBALL_DATA_API_KEY="your-football-data-key"Fetch:
python src/fetch_future_odds.py --out data/PL-future.csvThen run the Streamlit app to see upcoming predictions.
The dashboard reads data/PL-future.csv and shows future matches only with:
- Home win probability
- Edge vs market
- Simple “Candidate/Skip” label
Populate data/PL-future.csv using the API script above.
The live report includes practical risk filters:
- Minimum edge and expected value thresholds
- Maximum odds filter to avoid long-tail variance
- Kelly sizing with a hard cap
- Monte Carlo bankroll stress test to estimate drawdown risk
These are designed to prevent overexposure, not guarantee profit.
- Place season files in
data/asPL-YYYY-YYYY.csv. - The loader auto-detects common columns (team names, dates, results, odds).
- Sample prediction CSVs in
data/are included for dashboard demos.
Generate metrics, calibration plots, and backtest summaries:
python src/evaluate_predictions.py --pred data/predictions_xgb_oos_improved.csv --threshold 0.05Artifacts are written to data/ (calibration_home.png, sim_fixed.csv, sim_kelly.csv).
- Tests in
tests/and CI workflow in.github/workflows/ci.yml - Linting with
ruff - Model assumptions documented in
MODEL_CARD.md
- Python, pandas, scikit-learn, XGBoost
- Streamlit for the demo UI
- Matplotlib/Seaborn for plots
This project is for educational and analytical purposes only and does not provide betting advice.
MIT — see LICENSE.