repository·master·Indexed 41 days ago
https://github.com/martineastwood/penaltyblogA high-performance Python package optimized with Cython for football (soccer) analytics. Version 1.12.2 provides tools for data scraping (Understat, Club Elo, FPL), streaming JSON processing via MatchFlow, and statistical modelling including Poisson, Bivariate Poisson, and Dixon-Coles models. It includes capabilities for team ratings (Elo, Massey, Colley, Pi), betting probability estimation, arbitrage hedging, and publication-ready pitch visualizations.
MatchFlow is used to explore and analyze StatsBomb event data through end-to-end workflows. The typical pattern involves three stages:
Flow object to filter, group, or aggregate events.penaltyblog is a high-performance Python package optimized with Cython for football (soccer) analytics. Key capabilities include:
The penaltyblog library provides utility functions to evaluate the performance of football (soccer) model predictions. Key metrics available include:
For a deep dive into selecting the right metrics for football analytics, refer to the external guide: https://pena.lt/y/2025/05/01/better-metrics-for-football-forecasts-moving-beyond-the-ranked-probability-score/
The betting submodule in penaltyblog provides a suite of tools designed for professional betting workflows. It includes utilities for:
MatchFlow is a sub-package within penaltyblog designed for football data processing and modeling. The API is organized into several functional modules:
penaltyblog.matchflow.flow handles the execution flow, while penaltyblog.matchflow.executor manages how processes are run.penaltyblog.matchflow.steps contains specialized modules for different stages of a data pipeline:steps.source: For ingesting data.steps.transform: For modifying data.steps.group: For grouping data.steps.utils: Utility functions for steps.penaltyblog.matchflow.predicates and penaltyblog.matchflow.predicates_helpers provide logical conditions for data filtering or evaluation.penaltyblog.matchflow.group handles data grouping operations.penaltyblog.matchflow.optimizer provides performance improvements, and penaltyblog.matchflow.helpers contains general utility functions.penaltyblog.matchflow.plotting is used for generating visual representations of data.penaltyblog.matchflow.contrib.statsbomb provides specific support/contributions for StatsBomb data formats.The penaltyblog library provides statistical models designed to predict football (soccer) match outcomes. These models generate probability estimates for several betting markets, including:
For deep theoretical understanding and foundational research papers related to these models, refer to the documentation available at http://www.pena.lt/y/blog.html.
The Ranked Probability Score (RPS) is a metric for evaluating probabilistic predictions of ordinal outcomes (where outcomes have a natural order, such as Win > Draw > Loss).
Key Characteristics:
Flow is a stream-first, nested-data engine designed specifically for irregular, event-based JSON (like football event data). Unlike pandas, which requires data to be flattened into rigid tables (DataFrames) for processing, Flow treats nested JSON as a first-class citizen.
Key Differences:
pandas requires premature normalization (flattening), which can lead to key collisions and loss of hierarchy. Flow embraces nesting, allowing you to work with the natural hierarchy of the data (e.g., a match containing events, which contain players).pandas.json_normalize() can be brittle when dealing with inconsistent schemas, mixed types, or optional nesting (like variable-length freeze frames). Flow is schema-flexible and can handle different provider formats (Opta, StatsBomb, Wyscout) without overfitting.Flow allows you to query, filter, and transform nested records directly, deferring flattening until the very end of your pipeline (e.g., when exporting to a BI tool or performing vectorized operations).When to use which:
Flow is a lightweight, lazy query engine designed for processing deeply nested football data (like event data, freeze frames, or tracking points) without requiring early normalization or flattening.
Unlike a dataframe, Flow acts as a pipeline builder. It constructs an internal execution plan of transformations and only processes the data when an action is explicitly requested. This allows you to work with nested JSON structures using natural field access (e.g., "player.name") and chainable operations.
The penaltyblog package provides a suite of Cython-optimized statistical models for predicting football match scores. All models share a consistent API, allowing you to swap between them easily for benchmarking or fine-tuning.
| Model | Best Used For |
|---|---|
| Poisson | General forecasting (simple, efficient baseline) |
| Dixon & Coles | Low-scoring leagues (corrects low-score bias) |
| Bivariate Poisson | High-scoring leagues (models score correlation) |
| Zero-Inflated Poisson | Defensive teams (improves accuracy for goalless matches) |
| Negative Binomial | High-scoring, volatile leagues (handles overdispersion) |
| Weibull + Copula | Complex goal patterns (flexible distribution & correlation) |
| Bayesian | Small datasets, understanding uncertainty (captures parameter uncertainty) |
| Hierarchical Bayesian | Sparse data, multi-league (learns league-wide priors) |
MatchFlow is a stream-first query engine designed for irregular, event-based football data (such as nested JSON from StatsBomb or Opta). Unlike a DataFrame, MatchFlow is built to handle deeply nested structures without requiring early flattening.
Key characteristics:
.collect(), .to_pandas(), or .to_jsonl()..filter(), .assign(), .select(), and .group_by()."age > 30 and team == @team_name").The optimizer is safe-by-default and uses a conservative approach to ensure that user-defined logic remains correct. It makes no assumptions about commutativity, determinism, or purity of user functions.
Structural plan steps that are generally safe to reorder include:
select()drop()limit()filter() (when independent)sort()group_by()The optimizer will not reorder these steps because they may contain side effects or depend on execution order:
map()assign()filter() with non-trivial predicatesWhile the optimizer avoids reordering unsafe steps, it performs syntactic fusion. This means consecutive map(), assign(), or filter() steps may be combined into a single step for efficiency, but their relative order is strictly preserved.