Football data analysis operates across multiple coordinate systems that are not directly interchangeable. For example, a StatsBomb event export measures x from 0 to 120 and y from 0 to 80, while a Wyscout export uses a 0 to 100 scale for both axes. The same pass plotted in each system will appear in a different location unless coordinates are transformed.
By David Findlay, Founder of KiqIQ.
Quick Answer: mplsoccer is an open-source Python library for football pitch visualisation and analysis, created by Andrew Rowlinson and distributed under the MIT licence. It supports multiple pitch coordinate systems including StatsBomb, Opta, Tracab, and Wyscout, and provides a Standardizer utility to convert event and tracking data between formats. It is installed via pip and supports modern Python versions.
Definition: mplsoccer is a Python library built on Matplotlib that renders football pitch visualisations and provides chart types specific to football analysis. It abstracts pitch geometry, coordinate transformation, and figure setup so analysts can plot events, heatmaps, and tactical shapes directly from raw data without manually managing axis scaling or pitch dimensions.
Key point: mplsoccer provides a built-in coordinate transformation layer via its Standardizer class, allowing analysts to convert event data between different provider formats before plotting. Without this step, visualisations can appear correct but represent incorrect spatial positions.
Pitch Coordinate Systems in Football Data
mplsoccer supports a range of pitch coordinate systems used by different data providers. These systems differ in scale, origin point, and axis orientation:
- StatsBomb: 120 by 80 grid, origin at top-left, y-axis inverted relative to some systems
- Opta: 0 to 100 scale on both axes, origin bottom-left
- Wyscout: 0 to 100 scale with different directional conventions to Opta
- Tracab: centred coordinate system used in tracking data
- Metrica Sports: normalised tracking data coordinates
- Second Spectrum: tracking data format used in broadcast analysis
- SkillCorner: optical tracking coordinate system
- Impect: event data provider format
- UEFA: coordinate system used in UEFA data contexts
- Custom: user-defined pitch dimensions
Because of these differences, analysts must transform coordinates before comparing or overlaying datasets from multiple providers.
Core Classes
The primary class in mplsoccer is Pitch, which generates a football pitch as a Matplotlib axes object. VerticalPitch provides the same functionality in portrait orientation, commonly used for half-pitch or tactical views.
The Radar class creates radar charts for player comparison. The PyPizza class provides a circular alternative commonly used in football analytics to display percentile-based player metrics.
Plotting Methods
mplsoccer includes football-specific plotting methods:
- Scatter: event locations such as shots or passes
- Arrows: directional actions such as passes or carries
- Heatmap: spatial density of events
- Hexbin: alternative density visualisation
- Comet lines: trajectories with directional fade
- Sonar: angular distributions of events
StatsBomb Open Data Integration
mplsoccer includes utilities to load StatsBomb open data into Pandas DataFrames. This simplifies working with nested JSON structures and allows analysts to focus on visualisation and analysis rather than data wrangling.
The available open data includes events, lineups, and 360 freeze-frame data across multiple competitions.
Installation and Requirements
Install via pip:
pip install mplsoccer
Or via conda:
conda install -c conda-forge mplsoccer
mplsoccer supports modern Python versions. Dependencies include Matplotlib, NumPy, and Pandas. It is distributed under the MIT licence, allowing both personal and commercial use.
The KiqIQ Angle
The coordinate fragmentation problem in football data is structural rather than cosmetic. Analysts working across multiple providers must handle different spatial reference systems. Without conversion, plots from different datasets cannot be reliably compared.
mplsoccer addresses this by providing a consistent interface and a coordinate transformation utility. However, analysts must still understand the underlying data. Using the wrong pitch type without conversion can produce visually correct but analytically incorrect results.
Frequently Asked Questions
What is mplsoccer?
mplsoccer is an open-source Python library for football pitch visualisation built on Matplotlib. It supports multiple pitch coordinate systems and includes tools for plotting and data transformation.
How do I install mplsoccer?
Install via pip or conda using the commands above.
What pitch types does mplsoccer support?
mplsoccer supports multiple coordinate systems including StatsBomb, Opta, Wyscout, and tracking data formats. The Standardizer class enables conversion between them.
Can mplsoccer load StatsBomb data?
Yes. It includes utilities for loading StatsBomb open data into Pandas DataFrames.
Is mplsoccer free to use commercially?
Yes. It is distributed under the MIT licence.
What chart types does mplsoccer support?
It supports scatter, arrows, heatmaps, hexbin plots, radar charts, and pizza charts for football data visualisation.
Sources
- mplsoccer Official Documentation
- mplsoccer on PyPI
- mplsoccer GitHub Repository
- StatsBomb Open Data Repository
“`