mplsoccer.utils module

Python module containing helper functions for mplsoccer.

mplsoccer.utils.add_image(image, fig, left, bottom, width=None, height=None, **kwargs)[source]

Adds an image to a figure using fig.add_axes and ax.imshow

If downsampling an image ‘hamming’ interpolation is recommended

Parameters:

  • image (array-like or PIL image) – The image data.

  • fig (matplotlib.figure.Figure) – The figure on which to add the image.

  • left, bottom (float) – The dimensions left, bottom of the new axes. All quantities are in fractions of figure width and height. This positions the image axis in the figure left% in from the figure side and bottom% in from the figure bottom.

  • width, height (float, default None) – The width, height of the new axes. All quantities are in fractions of figure width and height. For best results use only one of these so the image is scaled appropriately.

  • **kwargs (All other keyword arguments are passed on to matplotlib.axes.Axes.imshow.)

Return type:

matplotlib.axes.Axes

Examples

>>> import matplotlib.pyplot as plt
>>> from PIL import Image
>>> from mplsoccer import add_image
>>> from urllib.request import urlopen
>>> fig, ax = plt.subplots()
>>> image_url = 'https://upload.wikimedia.org/wikipedia/commons/b/b8/Messi_vs_Nigeria_2018.jpg'
>>> image = urlopen(image_url)
>>> image = Image.open(image)
>>> ax_image = add_image(image, fig, left=0.1, bottom=0.2, width=0.4, height=0.4)
mplsoccer.utils.validate_ax(ax)[source]

Error message when ax is missing.

mplsoccer.utils.set_visible(ax, spine_bottom=False, spine_top=False, spine_left=False, spine_right=False, grid=False, tick=False, label=False)[source]

Helper method to set the visibility of matplotlib spines, grid and ticks/ labels. By default, sets all to invisible.

Parameters:

  • ax (matplotlib.axes.Axes) – The axis to set visibility on.

  • spine_bottom, spine_top, spine_left, spine_right (bool, default False) – Whether to show the spines.

  • grid (bool, default False) – Whether to show the grid lines.

  • tick (bool, deafult False) – Whether to draw the ticks.

  • label (bool, default False) – Whether to draw the tick labels.

class mplsoccer.utils.Standardizer(pitch_from, pitch_to, length_from=None, width_from=None, length_to=None, width_to=None)[source]

Bases: object

Convert from one set of coordinates to another.

Parameters:

  • pitch_from, pitch_to (str, default ‘statsbomb’) – The pitch to convert the coordinates from (pitch_from) and to (pitch_to). The supported pitch types are: ‘opta’, ‘statsbomb’, ‘tracab’, ‘wyscout’, ‘uefa’, ‘metricasports’, ‘custom’, ‘skillcorner’ and ‘secondspectrum’.

  • length_from, length_to (float, default None) – The pitch length in meters. Only used for the ‘tracab’ and ‘metricasports’, ‘skillcorner’, ‘secondspectrum’ and ‘custom’ pitch_type.

  • width_from, width_to (float, default None) – The pitch width in meters. Only used for the ‘tracab’ and ‘metricasports’, ‘skillcorner’, ‘secondspectrum’ and ‘custom’ pitch_type

Examples

>>> from mplsoccer import Standardizer
>>> standard = Standardizer(pitch_from='statsbomb', pitch_to='custom',                                 length_to=105, width_to=68)
>>> x = [20, 30]
>>> y = [50, 80]
>>> x_std, y_std = standard.transform(x, y)

Methods

transform(x, y[, reverse])

Transform the coordinates.
transform(x, y, reverse=False)[source]

Transform the coordinates.

Parameters:

  • x, y (array-like or scalar.) – Commonly, these parameters are 1D arrays.

  • reverse (bool, default False) – If reverse=True then reverse the transform. Therefore, the coordinates are converted from pitch_to to pitch_from.

Returns:

x_standardized, y_standardized – The coordinates standardized in pitch_to coordinates (or pitch_from if reverse=True).

Return type:

np.array 1d

class mplsoccer.utils.FontManager(url='https://raw.githubusercontent.com/google/fonts/main/apache/roboto/Roboto%5Bwdth,wght%5D.ttf')[source]

Bases: object

Utility to load fun fonts from https://fonts.google.com/ for matplotlib. Find a nice font at https://fonts.google.com/, and then get its corresponding URL from https://github.com/google/fonts/.

The FontManager is taken from the ridge_map package by Colin Carroll (@colindcarroll).

Parameters:

url (str, default is the url for Roboto-Regular.ttf) – Can really be any .ttf file, but probably looks like ‘https://github.com/google/fonts/blob/main/ofl/cinzel/static/Cinzel-Regular.ttf?raw=true’ Note 1: make sure the ?raw=true is at the end. Note 2: urls like ‘https://raw.githubusercontent.com/google/fonts/main/ofl/cinzel/static/Cinzel-Regular.ttf’

allow Cross-Origin Resource Sharing, and work in browser environments based on PyOdide (e.g. JupyterLite). Those urls don’t need the ?raw=true at the end

Examples

>>> from mplsoccer import FontManager
>>> import matplotlib.pyplot as plt
>>> font_url = 'https://raw.githubusercontent.com/google/fonts/main/ofl/abel/Abel-Regular.ttf'
>>> fm = FontManager(url=font_url)
>>> fig, ax = plt.subplots()
>>> ax.text(x=0.5, y=0.5, s="Good content.", fontproperties=fm.prop, size=30)
Attributes:
prop

Get matplotlib.font_manager.FontProperties object that sets the custom font.

property prop

Get matplotlib.font_manager.FontProperties object that sets the custom font.

mplsoccer.utils.set_labels(ax, label_value, label_axis)[source]

Function to set label for a given axis.

Args:

ax (axes.Axes): axis object. label_value (list): ticklabel values. label_axis (str): axis name, ‘x’ or ‘y’

Returns:

list: label names