Penalty Blog

penaltyblog: Football Data & Modelling Made Easy

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.

Features

• 🔄 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 🚀

Installation

pip install penaltyblog

Agent Support

If 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.

🚀 Quick Start - Try it Now!

Run these examples directly in your browser (no installation required):

Documentation

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

Why Penaltyblog?

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.

Community & Contributions

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:

• Open an Issue here
• Get in touch here