penaltyblog is a production-ready Python package designed for football (soccer) analytics, providing powerful tools from pena.lt/y/blog for data analysis, outcome modelling, and betting insights. Optimized with Cython, penaltyblog delivers high-performance modelling to power faster, efficient predictions.
- 🔄 Streamline JSON Workflows with MatchFlow: Process nested football data using a lazy, streaming pipeline built for JSON. Filter, select, flatten, join, group, and summarize large datasets without loading everything into memory.
- 🔌 Connect to Professional APIs: Seamlessly stream and filter data directly from industry leaders, like StatsBomb and Opta. Query matches, events, and stats using lazy loading without handling massive JSON dumps.
- 📊 Model Matches Efficiently: High-performance implementations of Poisson, Bivariate Poisson, Dixon-Coles, and other advanced statistical models, optimized with Cython for rapid analysis.
- 🧠 Advanced Bayesian Modelling: Full posterior distributions for match outcomes using MCMC sampling. Includes Hierarchical Bayesian models to automatically learn league-wide variances and handle parameter uncertainty.
- ⚽ Scrape Data: Collect match statistics from sources like Understat, Club Elo, and Fantasy Premier League.
- 💰 Bet Smarter: Precisely estimate probabilities for Asian handicaps, over/under totals, match outcomes, and more.
- 🏆 Rank Teams: Evaluate team strengths with sophisticated methods including Elo, Massey, Colley, and Pi ratings.
- 📈 Decode Bookmaker Odds: Accurately extract implied probabilities by removing bookmaker margins (overrounds).
- 🎯 Fantasy Football Optimisation: Mathematically optimize your fantasy football squad to maximize performance.
- 🎨 Visualize with Style: Create publication-ready pitch visualizations and data flow diagrams with customizable themes, supporting multiple data providers and flexible layouts.
Take your football analytics and betting strategy to the next level with penaltyblog 🚀
pip install penaltyblogIf you are using a coding agent such as Claude Code, Cursor, or Copilot, the repository includes a skill file at .claude/skills/penaltyblog/SKILL.md that gives your agent full context about the penaltyblog API. The file is self-contained and covers all public modules — no additional files are needed.
Run these examples directly in your browser (no installation required):
| Example | Description | Colab |
|---|---|---|
| Predict Soccer Match Results | Build a match prediction model from scratch |  |
| Process Soccer Data the Easy Way | Lazy processing of football data using Matchflow | |
| Calculate Massey Ratings | Calculate teams' attack and defense strengths | |
| Use Pi Ratings | Like Elo ratings, but better | |
| Create Interactive Charts | Create your own interactive football vizualisations | |
| Work Directly With Statsbomb Data | Connect directly to Statsbomb's API, including their free open data sets | |
| Calculate Implied Probabilities | Calculate implied probabilities from bookmaker's odds | |
| Calculate Expected Threat (xT) | Calculate xT from event data | |
Learn more about how to utilize penaltyblog by exploring the official documentation and detailed examples:
- Processing football event data with MatchFlow
- Scraping football data
- Predicting football matches and betting markets
- Estimating implied odds from bookmaker prices
- Calculating Massey, Colley, Pi, and Elo ratings
- Calculating metrics such as Ranked Probability Scores
Unlike many football analytics resources that are academic, one-off, or hard to scale, penaltyblog is designed from the ground up to be production-ready, performance-optimized, and practically useful.
It combines advanced statistical models (including Bayesian and Hierarchical Bayesian variants), efficient implementations (via Cython), and real-world workflows, from scraping public data to modelling outcomes and optimising fantasy teams.
The project is maintained by Martin Eastwood, a data scientist focused on the intersection of high-performance computing and sports analytics. penaltyblog aims to provide the community with a robust, audited foundation for advanced modeling.
I am always interested in seeing how penaltyblog is being applied in research and industry. If you have feedback, bug reports, or want to collaborate on new features, feel free to: