penaltyblog 1.11.0

Football (soccer) Data & Modelling Made Easy

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):

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

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