DOCSEARCHbyAlgolia
Submit Docs

mplsoccer Documentation

repository·main·Indexed 19 days ago

https://github.com/andrewrowlinson/mplsoccer

A Python library for plotting soccer/football charts using Matplotlib and loading StatsBomb open-data. It provides tools for pitch plotting (including nine pitch types), radar charts, pizza plots, bumpy charts, and sonars. Key features include the Pitch class for visualizations, data overlays like heatmaps and quiver plots, and specialized interfaces for StatsBomb data via Sbopen, Sbapi, and Sblocal.

Tokens
21.5K
Snippets
60
Records
79
Agent score
62%

What's inside mplsoccer

  1. What can you do with mplsoccer?

    main

    The mplsoccer library provides tools for soccer analytics visualization, including:

    • Pitch Plotting: Nine different pitch types.
    • Chart Types: Radar charts, Nightingale/pizza charts, and bumpy charts (for time-series changes).
    • Data Overlays: Arrows, heatmaps, hexbins, scatter plots, and comet lines.
    • Data Handling: Loading StatsBomb open-data as tidy DataFrames and standardizing pitch coordinates into a single format.

  5. Install the mplsoccer environment via Conda

    main

    To run the examples provided in this repository, you can recreate the specific Anaconda environment used by the developers.

    1. Download or copy the contents of the environment.yml file from the repository into a new file named environment.yml.
    2. Open your Anaconda Prompt and navigate to the directory containing the file.
    3. Run the creation command and then activate the environment.
    conda env create -f environment.yml
conda activate mplsoccer

  6. Plot radar charts with mplsoccer

    main
    The mplsoccer library provides functionality to create radar charts (also known as spider charts) to visualize multi-dimensional data, commonly used in football analytics to compare player attributes or team statistics. You can find specific implementation patterns in the examples/radar/ directory of the repository.

  9. Calculate and plot sonar grids

    main

    Sonar plots (polar bar charts) visualize data distribution relative to an angle and distance.

    1. Calculate statistics: Use bin_statistic_sonar to create a dictionary containing the statistical data.
    2. Plot grid: Use sonar_grid to plot these statistics as a grid of polar charts across the pitch.
    3. Plot zones: Use sonar_zones to plot sonar charts centered within specific pitch zones.

    sonar_grid parameters include width and height (for inset size), exclude_zeros, exclude_nan, and exclude_outside to control which cells are rendered.

    from mplsoccer import Pitch
# ... (data loading/processing) ...

# 1. Calculate sonar statistics
angle, distance = pitch.calculate_angle_and_distance(df.x, df.y, df.end_x, df.end_y)
bs = pitch.bin_statistic_sonar(df.x, df.y, angle, bins=(6, 4, 4), center=True)

# 2. Plot the grid
fig, ax = pitch.draw(figsize=(8, 5.5))
pitch.sonar_grid(bs, width=10, fc='cornflowerblue', ec='black', ax=ax)

  10. How grid layouts and dimensions work

    main

    The mplsoccer.grid module uses a coordinate system based on fractions of the figure size (0.0 to 1.0) to position axes.

    1. Dimension Calculation: The internal _grid_dimensions function calculates the exact left, bottom, axwidth, and axheight for every axis in the grid, accounting for the requested space between rows and the ax_aspect.
    2. Layout Composition: The total vertical space is composed of endnote_height + endnote_space + grid_height + title_space + title_height. If this sum exceeds 1.0, a ValueError is raised.
    3. Padding: When using grid(), you can use left_pad and right_pad (fractions of figure width) to indent the title and endnote axes relative to the main grid axes.
    4. Automatic Centering: If left or bottom are not provided, the grid is automatically centered in the figure.

  11. Plot a StatsBomb pitch

    main

    Use the Pitch class to create a soccer pitch visualization. You can customize the pitch_color, line_color, and whether to use stripes via the stripe argument. The draw() method returns a Matplotlib fig and ax object.

    from mplsoccer import Pitch
import matplotlib.pyplot as plt

pitch = Pitch(pitch_color='grass', line_color='white', stripe=True)
fig, ax = pitch.draw()
plt.show()