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.inset_axes(x, y, width=None, height=None, aspect=None, polar=False, vertical=False, ax=None, **kwargs)[source]

A function to create an inset axes.

Parameters:

x, y (float) – The x/y coordinate of the center of the inset axes.
width (float, default None) – The width of the inset axes in the x data coordinates.
height (float, default None) – The height of the inset axes in the y data coordinates.
aspect (float or str (‘pitch’), default None) – You can specify a combination of height and aspect or width and aspect. This will make the axes visually have the given aspect ratio (width/height). For example, if you want an inset axes to appear square set aspect = 1. For polar plots, this is defaulted to 1.
polar (bool, default False) – Whether the inset axes if a polar projection.
vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.
ax (matplotlib.axes.Axes, default None) – The axis to plot on.
**kwargs (All other keyword arguments are passed on to the inset_axes.)

Returns:

ax

Return type:

matplotlib.axes.Axes

Examples

>>> from mplsoccer import inset_axes
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> inset_ax = inset_axes(0.5, 0.5, height=0.2, aspect=1, ax=ax)

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/googlefonts/roboto/main/src/hinted/Roboto-Regular.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

mplsoccer.utils.get_aspect(ax)[source]

Get the aspect ratio of an axes. From Stackoverflow post by askewchan: https://stackoverflow.com/questions/41597177/get-aspect-ratio-of-axes

Parameters:: ax (matplotlib.axes.Axes, default None)
Return type:: float

mplsoccer.utils.copy_doc(func)[source]: Decorator to copy a docstring to a new function/method. Inspired by estnani’s answer: https://stackoverflow.com/questions/4056983/how-do-i-programmatically-set-the-docstring

mplsoccer.utils.inset_image(x, y, image, width=None, height=None, vertical=False, ax=None, **kwargs)[source]

Adds an image as an inset_axes.

Parameters:

x, y (float)
image (array-like or PIL image) – The image data.
width, height (float, default None) – The width, height of the inset_axes for plotting the image. By default in the data coordinates.
vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.
ax (matplotlib.axes.Axes, default None) – The axis to plot on.
**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 urllib.request import urlopen
>>> from mplsoccer import inset_image
>>> 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 = inset_image(0.5, 0.5, image, width=0.2, ax=ax)