# mplsoccer.pitch module

Module containing: Pitch and VerticalPitch, which are used to plot pitches in mplsoccer

Bases: `BasePitchPlot`

Methods

 `annotate`(text, xy[, xytext, ax]) Utility wrapper around ax.annotate which automatically flips the xy and xytext coordinates if the pitch is vertical. `arrows`(xstart, ystart, xend, yend, *args[, ax]) Utility wrapper around matplotlib.axes.Axes.quiver. `bin_statistic`(x, y[, values, statistic, ...]) Calculates binned statistics using scipy.stats.binned_statistic_2d. `bin_statistic_positional`(x, y[, values, ...]) Calculates binned statistics for the Juego de posición (position game) concept. `calculate_angle_and_distance`(xstart, ystart, ...) Calculates the angle in radians counter-clockwise and the distance between a start and end location. `convexhull`(x, y) Get lines of Convex Hull for a set of coordinates `draw`([ax, figsize, nrows, ncols, ...]) Draws the specified soccer/ football pitch(es). `flow`(xstart, ystart, xend, yend[, bins, ...]) Create a flow map by binning the data into cells and calculating the average angles and distances. `goal_angle`(x, y[, ax, goal]) Plot a polygon with the angle to the goal using matplotlib.patches.Polygon. `grid`([figheight, nrows, ncols, grid_height, ...]) A helper to create a grid of pitches in a specified location `grid_dimensions`(figwidth, figheight, nrows, ...) A helper method to propose a grid_width and grid_height for grid based on the inputs. `heatmap`(stats[, ax]) Utility wrapper around matplotlib.axes.Axes.pcolormesh which automatically flips the x_grid and y_grid coordinates if the pitch is vertical. `heatmap_positional`(stats[, ax]) Plots several heatmaps for the different Juegos de posición areas. `hexbin`(x, y[, ax]) Utility wrapper around matplotlib.axes.Axes.hexbin, which automatically flips the x and y coordinates if the pitch is vertical and clips to the pitch boundaries. `jointgrid`([figheight, left, grid_width, ...]) Create a grid with a pitch at the center and (marginal) axes at the sides of the pitch. `kdeplot`(x, y[, ax]) Utility wrapper around seaborn.kdeplot, which automatically flips the x and y coordinates if the pitch is vertical and clips to the pitch boundaries. `label_heatmap`(stats[, str_format, ...]) Labels the heatmap(s) and automatically flips the coordinates if the pitch is vertical. `lines`(xstart, ystart, xend, yend[, color, ...]) Plots lines using matplotlib.collections.LineCollection. `plot`(x, y[, ax]) Utility wrapper around matplotlib.axes.Axes.plot, which automatically flips the x and y coordinates if the pitch is vertical. `polygon`(verts[, ax]) Plot polygons. `scatter`(x, y[, rotation_degrees, marker, ax]) Utility wrapper around matplotlib.axes.Axes.scatter, which automatically flips the x and y coordinates if the pitch is vertical. `triplot`(x, y[, ax]) Utility wrapper around matplotlib.axes.Axes.triplot `voronoi`(x, y, teams) Get Voronoi vertices for a set of coordinates.
annotate(text, xy, xytext=None, ax=None, **kwargs)

Utility wrapper around ax.annotate which automatically flips the xy and xytext coordinates if the pitch is vertical.

Annotate the point xy with text. See: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.annotate.html

Parameters:
• text (str) – The text of the annotation.

• xy ((float, float)) – The point (x, y) to annotate.

• xytext ((float, float), optional) – The position (x, y) to place the text at. If None, defaults to xy.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

annotation

Return type:

matplotlib.text.Annotation

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.annotate(text='center', xytext=(50, 50), xy=(60, 40), ha='center', va='center',                            ax=ax, arrowprops=dict(facecolor='black'))
```
arrows(xstart, ystart, xend, yend, *args, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.quiver. Quiver uses locations and direction vectors usually. Here these are instead calculated automatically from the start and endpoints of the arrow. The function also automatically flips the x and y coordinates if the pitch is vertical.

Plot a 2D field of arrows. See: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.quiver.html

Parameters:
• xstart, ystart, xend, yend (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the start and end coordinates of the lines.

• C (1D or 2D array-like, optional) – Numeric data that defines the arrow colors by colormapping via norm and cmap. This does not support explicit colors. If you want to set colors directly, use color instead. The size of C must match the number of arrow locations.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.

• width (float, default 4) – Arrow shaft width in points.

• headwidth (float, default 3) – Head width as a multiple of the arrow shaft width.

• headlength (float, default 5) – Head length as a multiple of the arrow shaft width.

• headaxislength (float, default: 4.5) – Head length at the shaft intersection. If this is equal to the headlength then the arrow will be a triangular shape. If greater than the headlength then the arrow will be wedge shaped. If less than the headlength the arrow will be swept back.

• color (color or color sequence, optional) – Explicit color(s) for the arrows. If C has been set, color has no effect.

• linewidth or linewidths or lw (float or sequence of floats) – Edgewidth of arrow.

• edgecolor or ec or edgecolors (color or sequence of colors or ‘face’)

• alpha (float or None) – Transparency of arrows.

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

Returns:

PolyCollection

Return type:

matplotlib.quiver.Quiver

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.arrows(20, 20, 45, 80, ax=ax)
```
```>>> from mplsoccer.quiver import arrows
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> arrows([0.1, 0.4], [0.1, 0.5], [0.9, 0.4], [0.8, 0.8], ax=ax)
>>> ax.set_xlim(0, 1)
>>> ax.set_ylim(0, 1)
```
bin_statistic(x, y, values=None, statistic='count', bins=(5, 4), normalize=False, standardized=False)

Calculates binned statistics using scipy.stats.binned_statistic_2d.

This method automatically sets the range, changes the scipy defaults, and outputs the grids and centers for plotting.

The default statistic has been changed to count instead of mean. The default bins have been set to (5,4).

Parameters:
• x, y, values (array-like or scalar.) – Commonly, these parameters are 1D arrays. If the statistic is ‘count’ then values are ignored.

• dim (mplsoccer pitch dimensions) – One of FixedDims, MetricasportsDims, VariableCenterDims, or CustomDims. Automatically populated when using Pitch/ VerticalPitch class

• statistic (string or callable, optional) – The statistic to compute (default is ‘count’). The following statistics are available: ‘count’ (default), ‘mean’, ‘std’, ‘median’, ‘sum’, ‘min’, ‘max’, ‘circmean’ or a user-defined function. See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.binned_statistic_2d.html

• bins (int or [int, int] or array_like or [array, array], optional) –

The bin specification.
• the number of bins for the two dimensions (nx = ny = bins),

• the number of bins in each dimension (nx, ny = bins),

• the bin edges for the two dimensions (x_edge = y_edge = bins),

• the bin edges in each dimension (x_edge, y_edge = bins). If the bin edges are specified, the number of bins will be, (nx = len(x_edge)-1, ny = len(y_edge)-1).

• normalize (bool, default False) – Whether to normalize the statistic by dividing by the total.

• standardized (bool, default False) – Whether the x, y values have been standardized to the ‘uefa’ pitch coordinates (105m x 68m)

Returns:

bin_statistic – The keys are ‘statistic’ (the calculated statistic), ‘x_grid’ and ‘y_grid (the bin’s edges), cx and cy (the bin centers) and ‘binnumber’ (the bin indices each point belongs to). ‘binnumber’ is a (2, N) array that represents the bin in which the observation falls if the observations falls outside the pitch the value is -1 for the dimension. The binnumber are zero indexed and start from the top and left handside of the pitch.

Return type:

dict.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic(x, y)
>>> pitch.heatmap(stats, edgecolors='black', cmap='hot', ax=ax)
```
bin_statistic_positional(x, y, values=None, positional='full', statistic='count', normalize=False)

Calculates binned statistics for the Juego de posición (position game) concept. It uses scipy.stats.binned_statistic_2d.

Parameters:
• x, y, values (array-like or scalar.) – Commonly, these parameters are 1D arrays. If the statistic is ‘count’ then values are ignored.

• dim (mplsoccer pitch dimensions) – One of FixedDims, MetricasportsDims, VariableCenterDims, or CustomDims. Automatically populated when using Pitch/ VerticalPitch class

• positional (str) – One of ‘full’, ‘horizontal’ or ‘vertical’ for the respective heatmaps.

• statistic (string or callable, optional) – The statistic to compute (default is ‘count’). The following statistics are available: ‘count’ (default), ‘mean’, ‘std’, ‘median’, ‘sum’, ‘min’, ‘max’, or a user-defined function. See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.binned_statistic_2d.html.

• normalize (bool, default False) – Whether to normalize the statistic by dividing by the total.

Returns:

bin_statistic – The dictionary keys are ‘statistic’ (the calculated statistic), ‘x_grid’ and ‘y_grid (the bin’s edges), and cx and cy (the bin centers).

Return type:

A list of dictionaries.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic_positional(x, y)
>>> pitch.heatmap_positional(stats, edgecolors='black', cmap='hot', ax=ax)
```
calculate_angle_and_distance(xstart, ystart, xend, yend, standardized=False, degrees=False)

Calculates the angle in radians counter-clockwise and the distance between a start and end location. Where the angle 0 is this way → (the straight line from left to right) in a horizontally orientated pitch and this way ↑ in a vertically orientated pitch. The angle goes from 0 to 2pi. To convert the angle to degrees clockwise use degrees=True.

Parameters:
• xstart, ystart, xend, yend (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the start and end coordinates to calculate the angle between.

• standardized (bool, default False) – Whether the x, y values have been standardized to the ‘uefa’ pitch coordinates (105m x 68m)

• degrees (bool, default False) – If False, the angle is returned in radians counter-clockwise in the range [0, 2pi] If True, the angle is returned in degrees clockwise in the range [0, 360].

Returns:

• angle (ndarray) – The default is an array of angles in radians counter-clockwise in the range [0, 2pi]. Where 0 is the straight line left to right in a horizontally orientated pitch and the straight line bottom to top in a vertically orientated pitch. If degrees = True, then the angle is returned in degrees clockwise in the range [0, 360]

• distance (ndarray) – Array of distances.

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> pitch.calculate_angle_and_distance(0, 40, 30, 20, degrees=True)
(array([326.30993247]), array([36.05551275]))
```
convexhull(x, y)

Get lines of Convex Hull for a set of coordinates

Parameters:

x, y (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the coordinates on the pitch.

Returns:

hull_vertices

Return type:

a numpy array of vertoces [1, num_vertices, [x, y]] of the Convex Hull.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=11)
>>> y = np.random.uniform(low=0, high=80, size=11)
>>> hull = pitch.convexhull(x, y)
>>> poly = pitch.polygon(hull, ax=ax, facecolor='cornflowerblue', alpha=0.3)
```
draw(ax=None, figsize=None, nrows=1, ncols=1, tight_layout=True, constrained_layout=False)

Draws the specified soccer/ football pitch(es). If an ax is specified the pitch is drawn on an existing axis.

Parameters:
• ax (matplotlib axis, default None) – A matplotlib.axes.Axes to draw the pitch on. If None is specified the pitch is plotted on a new figure.

• figsize (tuple of float, default Matplotlib figure size) – The figure size in inches by default uses rcParams[“figure.figsize”].

• nrows, ncols (int, default 1) – Number of rows/columns of the subplot grid.

• tight_layout (bool, default True) – Whether to use Matplotlib’s tight layout.

• constrained_layout (bool, default False) – Whether to use Matplotlib’s constrained layout.

Returns:

• If ax=None returns a matplotlib Figure and Axes.

• Else plotted on an existing axis and returns None.

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
```
```>>> from mplsoccer import Pitch
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> pitch = Pitch()
>>> pitch.draw(ax=ax)
```
flow(xstart, ystart, xend, yend, bins=(5, 4), arrow_type='same', arrow_length=5, color=None, ax=None, **kwargs)

Create a flow map by binning the data into cells and calculating the average angles and distances.

Parameters:
• xstart, ystart, xend, yend (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the start and end coordinates to calculate the angle between.

• bins (int or [int, int] or array_like or [array, array], optional) –

The bin specification for binning the data to calculate the angles/ distances.
• the number of bins for the two dimensions (nx = ny = bins),

• the number of bins in each dimension (nx, ny = bins),

• the bin edges for the two dimensions (x_edge = y_edge = bins),

• the bin edges in each dimension (x_edge, y_edge = bins). If the bin edges are specified, the number of bins will be, (nx = len(x_edge)-1, ny = len(y_edge)-1).

• arrow_type (str, default ‘same’) – The supported arrow types are: ‘same’, ‘scale’, and ‘average’. ‘same’ makes the arrows the same size (arrow_length). ‘scale’ scales the arrow length by the average distance in the cell (up to a max of arrow_length). ‘average’ makes the arrow size the average distance in the cell.

• arrow_length (float, default 5) – The arrow_length for the flow map. If the arrow_type=’same’, all the arrows will be arrow_length. If the arrow_type=’scale’, the arrows will be scaled by the average distance. If the arrow_type=’average’, the arrows_length is ignored This is automatically multipled by 100 if using a ‘tracab’ pitch (i.e. the default is 500).

• color (A matplotlib color, defaults to None.) – Defaults to None. In that case the marker color is determined by the cmap (default ‘viridis’). and the counts of the starting positions in each bin.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

PolyCollection

Return type:

matplotlib.quiver.Quiver

Examples

```>>> from mplsoccer import Pitch, Sbopen
>>> parser = Sbopen()
>>> df, related, freeze, tactics = parser.event(7478)
>>> team1, team2 = df.team_name.unique()
>>> mask_team1 = (df.type_name == 'Pass') & (df.team_name == team1)
>>> pitch = Pitch(line_zorder=2)
>>> fig, ax = pitch.draw()
>>> bs_heatmap = pitch.bin_statistic(df.x, df.y, statistic='count', bins=(6, 4))
>>> hm = pitch.heatmap(bs_heatmap, ax=ax, cmap='Blues')
```
goal_angle(x, y, ax=None, goal='right', **kwargs)

Plot a polygon with the angle to the goal using matplotlib.patches.Polygon. See: https://matplotlib.org/stable/api/collections_api.html. Valid Collection keyword arguments: edgecolors, facecolors, linewidths, antialiaseds, transOffset, norm, cmap

Parameters:
• x, y (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the coordinates on the pitch.

• goal (str default ‘right’.) – The goal to plot, either ‘left’ or ‘right’.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• **kwargs (All other keyword arguments are passed on to) – matplotlib.collections.PathCollection.

Returns:

Polygon

Return type:

matplotlib.patches.Polygon

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.goal_angle(100, 30, alpha=0.5, color='red', ax=ax)
```
grid(figheight=9, nrows=1, ncols=1, grid_height=0.715, grid_width=0.95, space=0.05, left=None, bottom=None, endnote_height=0.065, endnote_space=0.01, title_height=0.15, title_space=0.01, axis=True)

A helper to create a grid of pitches in a specified location

Parameters:
• figheight (float, default 9) – The figure height in inches.

• nrows, ncols (int, default 1) – Number of rows/columns of pitches in the grid.

• grid_height (float, default 0.715) – The height of the pitch grid in fractions of the figure height. The default is the grid height is 71.5% of the figure height.

• grid_width (float, default 0.95) – The width of the pitch grid in fractions of the figure width. The default is the grid is 95% of the figure width.

• space (float, default 0.05) – The total amount of the grid height reserved for spacing between the pitch axes. Expressed as a fraction of the grid_height. The default is 5% of the grid height. The spacing across the grid width is automatically calculated to maintain even spacing.

• left (float, default None) – The location of the left-hand side of the axes in fractions of the figure width. The default of None places the axes in the middle of the figure.

• bottom (float, default None) – The location of the bottom endnote axes in fractions of the figure height. The default of None places the axes in the middle of the figure. If the endnote_height=0 then the pitch grid is located at the bottom coordinate instead.

• endnote_height (float, default 0.065) – The height of the endnote axes in fractions of the figure height. The default is the endnote is 6.5% of the figure height. If endnote_height=0, then the endnote axes is not plotted.

• endnote_space (float, default 0.01) – The space between the pitch grid and endnote axis in fractions of the figure height. The default space is 1% of the figure height. If endnote_height=0, then the endnote_space is set to zero.

• title_height (float, default 0.15) – The height of the title axis in fractions of the figure height. The default is the title axis is 15% of the figure height. If title_height=0, then the title axes is not plotted.

• title_space (float, default 0.01) – The space between the pitch grid and title axis in fractions of the figure height. The default space is 1% of the figure height. If title_height=0, then the title_space is set to zero.

• axis (bool, default True) – Whether the endnote and title axes are ‘on’.

Returns:

• fig (matplotlib.figure.Figure)

• axs (dict[label, Axes]) – A dictionary mapping the labels to the Axes objects. The possible keys are ‘pitch’, ‘title’, and ‘endnote’.

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, axs = pitch.grid(nrows=3, ncols=3, grid_height=0.7, figheight=14)
```
grid_dimensions(figwidth, figheight, nrows, ncols, max_grid, space)

A helper method to propose a grid_width and grid_height for grid based on the inputs.

Parameters:
• figwidth, figheight (float) – The figure width/height in inches.

• nrows, ncols (int) – Number of rows/columns of pitches in the grid.

• max_grid (float) – The longest side of the grid in fractions of the figure width / height. Should be between zero and one.

• space (float) – The total amount of the grid height reserved for spacing between the pitch axes. Expressed as a fraction of the grid_height.

Returns:

grid_width, grid_height

Return type:

the suggested grid_width and grid_height

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> grid_width, grid_height = pitch.grid_dimensions(figwidth=16, figheight=9,                                                             nrows=1, ncols=1,                                                             max_grid=1,  space=0)
```
heatmap(stats, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.pcolormesh which automatically flips the x_grid and y_grid coordinates if the pitch is vertical.

Parameters:
• stats (dict.) – This should be calculated via bin_statistic(). The keys are ‘statistic’ (the calculated statistic), ‘x_grid’ and ‘y_grid (the bin’s edges), and cx and cy (the bin centers).

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.

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

Returns:

mesh

Return type:

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic(x, y)
>>> pitch.heatmap(stats, edgecolors='black', cmap='hot', ax=ax)
```
heatmap_positional(stats, ax=None, **kwargs)

Plots several heatmaps for the different Juegos de posición areas.

Parameters:
• stats (A list of dictionaries.) – This should be calculated via bin_statistic_positional(). The dictionary keys are ‘statistic’ (the calculated statistic), ‘x_grid’ and ‘y_grid (the bin’s edges), and cx and cy (the bin centers).

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.

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

Returns:

mesh

Return type:

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic_positional(x, y)
>>> pitch.heatmap_positional(stats, edgecolors='black', cmap='hot', ax=ax)
```
hexbin(x, y, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.hexbin, which automatically flips the x and y coordinates if the pitch is vertical and clips to the pitch boundaries.

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

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• mincnt (int > 0, default: 1) – If not None, only display cells with more than mincnt number of points in the cell.

• gridsize (int or (int, int), default: (17, 8) for Pitch/ (17, 17) for VerticalPitch) – If a single int, the number of hexagons in the x-direction. The number of hexagons in the y-direction is chosen such that the hexagons are approximately regular. Alternatively, if a tuple (nx, ny), the number of hexagons in the x-direction and the y-direction.

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

Returns:

polycollection

Return type:

matplotlib.collections.PolyCollection

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2)
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> pitch.hexbin(x, y, edgecolors='black', gridsize=(11, 5), cmap='Reds', ax=ax)
```
jointgrid(figheight=9, left=None, grid_width=0.95, bottom=None, endnote_height=0.065, endnote_space=0.01, grid_height=0.715, title_space=0.01, title_height=0.15, space=0, marginal=0.1, ax_left=True, ax_top=True, ax_right=True, ax_bottom=False, axis=True)

Create a grid with a pitch at the center and (marginal) axes at the sides of the pitch.

Parameters:
• figheight (float, default 9) – The figure height in inches.

• left (float, default None) – The location of the left-hand side of the grid in fractions of the figure width. The default of None places the axes in the middle of the figure.

• grid_width (float, default 0.95) – The width of the grid area in fractions of the figure width. The default is the grid is 80% of the figure width.

• bottom (float, default None) – The location of the bottom endnote axes in fractions of the figure height. The default of None places the axes in the middle of the figure. If the endnote_height=0 then the joint grid is located at the bottom coordinate instead.

• endnote_height (float, default 0.065) – The height of the endnote axes in fractions of the figure height. The default is the endnote is 6.5% of the figure height. If endnote_height=0, then the endnote axes is not plotted.

• endnote_space (float, default 0.01) – The space between the joint grid and endnote axis in fractions of the figure height. The default space is 1% of the figure height. If endnote_height=0, then the endnote_space is set to zero.

• grid_height (float, default 0.715) – The height of the joint grid area in fractions of the figure height. The default is the grid height is 70% of the figure height.

• title_space (float, default 0.01) – The space between the joint grid and title axis in fractions of the figure height. The default space is 1% of the figure height. If title_height=0, then the title_space is set to zero.

• title_height (float, default 0.15) – The height of the title axis in fractions of the figure height. The default is the title axis is 15% of the figure height. If title_height=0, then the title axes is not plotted.

• space (float, default 0.01) – The total amount of the grid height reserved for spacing between axes. Expressed as a fraction of the grid height. The default is 0.01% of the grid height. Note if space is zero, it will still look like there is space if the pitch has padding, e.g. pad_top=15.

• marginal (float, default 0.1) – The total amount of the grid height reserved for the marginal axes. Expressed as a fraction of the grid height. The default is 10% of the grid height.

• ax_left, ax_top, ax_right (bool, default True) – Whether to include a Matplotlib Axes on the left/top/right side of the pitch.

• ax_bottom (bool, default False) – Whether to include a Matplotlib Axes on the bottom side of the pitch.

• axis (bool, default True) – Whether the endnote, title, and the marginal axes are ‘on’.

Returns:

• fig (matplotlib.figure.Figure)

• axs (dict[label, Axes]) – A dictionary mapping the labels to the Axes objects. The possible keys are ‘left’, ‘right’, ‘bottom’, ‘top’ for the marginal axes, ‘pitch’, ‘title’ and ‘endnote’.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> import seaborn as sns
>>> pitch = Pitch()
>>> fig, axs = pitch.jointgrid(ax_left=False, ax_right=False,                                        ax_bottom=False, ax_top=True)
>>> x = np.random.uniform(low=0, high=120, size=100)
```
kdeplot(x, y, ax=None, **kwargs)

Utility wrapper around seaborn.kdeplot, which automatically flips the x and y coordinates if the pitch is vertical and clips to the pitch boundaries.

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

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• **kwargs (All other keyword arguments are passed on to seaborn.kdeplot.)

Returns:

contour

Return type:

matplotlib.contour.ContourSet

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2)
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> pitch.kdeplot(x, y, cmap='Reds', fill=True, levels=100, ax=ax)
```
label_heatmap(stats, str_format=None, exclude_zeros=False, ax=None, **kwargs)

Labels the heatmap(s) and automatically flips the coordinates if the pitch is vertical.

Parameters:
• stats (A dictionary or list of dictionaries.) – This should be calculated via bin_statistic_positional() or bin_statistic().

• str_format (str) – A format string passed to str_format.format() to format the labels.

• exclude_zeros (bool) – Whether to exclude zeros when labelling the heatmap.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

annotations

Return type:

A list of matplotlib.text.Annotation.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> import matplotlib.patheffects as path_effects
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic(x, y)
>>> pitch.heatmap(stats, edgecolors='black', cmap='hot', ax=ax)
>>> stats['statistic'] = stats['statistic'].astype(int)
>>> path_eff = [path_effects.Stroke(linewidth=0.5, foreground='#22312b')]
>>> text = pitch.label_heatmap(stats, color='white', ax=ax, fontsize=20, ha='center',                                        va='center', path_effects=path_eff)
```
lines(xstart, ystart, xend, yend, color=None, n_segments=100, comet=False, transparent=False, alpha_start=0.01, alpha_end=1, cmap=None, ax=None, **kwargs)

Plots lines using matplotlib.collections.LineCollection. This is a fast way to plot multiple lines without loops. Also enables lines that increase in width or opacity by splitting the line into n_segments of increasing width or opacity as the line progresses.

Parameters:
• xstart, ystart, xend, yend (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the start and end coordinates of the lines.

• color (A matplotlib color or sequence of colors, defaults to None.) – Defaults to None. In that case the marker color is determined by the value rcParams[‘lines.color’]

• n_segments (int, default 100) – If comet=True or transparent=True this is used to split the line into n_segments of increasing width/opacity.

• comet (bool default False) – Whether to plot the lines increasing in width.

• transparent (bool, default False) – Whether to plot the lines increasing in opacity.

• linewidth or lw (array-like or scalar, default 5.) – Multiple linewidths not supported for the comet or transparent lines.

• alpha_start (float, default 0.01) – The starting alpha value for transparent lines, between 0 (transparent) and 1 (opaque). If transparent = True the line will be drawn to linearly increase in opacity between alpha_start and alpha_end.

• alpha_end (float, default 1) – The ending alpha value for transparent lines, between 0 (transparent) and 1 (opaque). If transparent = True the line will be drawn to linearly increase in opacity between alpha_start and alpha_end.

• cmap (str, default None) – A matplotlib cmap (colormap) name

• vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.

• reverse_cmap (bool, default False) – Whether to reverse the cmap colors. If the pitch is horizontal and the y-axis is inverted then set this to True.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• **kwargs (All other keyword arguments are passed on to matplotlib.collections.LineCollection.)

Returns:

LineCollection

Return type:

matplotlib.collections.LineCollection

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.lines(20, 20, 45, 80, comet=True, transparent=True, ax=ax)
```
```>>> from mplsoccer.linecollection import lines
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> lines([0.1, 0.4], [0.1, 0.5], [0.9, 0.4], [0.8, 0.8], ax=ax)
```
plot(x, y, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.plot, which automatically flips the x and y coordinates if the pitch is vertical.

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

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

lines

Return type:

A list of Line2D objects representing the plotted data.

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.plot([30, 35, 20], [30, 19, 40], ax=ax)
```
polygon(verts, ax=None, **kwargs)

Plot polygons. Automatically flips the x and y vertices if the pitch is vertical.

Parameters:
• verts (verts is a sequence of (verts0, verts1, …)) – where verts_i is a numpy array of shape (number of vertices, 2).

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• **kwargs (All other keyword arguments are passed on to) – matplotlib.patches.Polygon

Return type:

list of matplotlib.patches.Polygon

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(label=True, axis=True)
>>> fig, ax = pitch.draw()
>>> shape1 = np.array([[50, 2], [80, 30], [40, 30], [40, 20]])
>>> shape2 = np.array([[70, 70], [60, 50], [40, 40]])
>>> verts = [shape1, shape2]
>>> pitch.polygon(verts, color='red', alpha=0.3, ax=ax)
```
scatter(x, y, rotation_degrees=None, marker=None, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.scatter, which automatically flips the x and y coordinates if the pitch is vertical. You can optionally use a football marker with marker=’football’ and rotate markers with rotation_degrees.

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

• rotation_degrees (array-like or scalar, default None.) – Rotates the marker in degrees, clockwise. 0 degrees is facing the direction of play. In a horizontal pitch, 0 degrees is this way →, in a vertical pitch, 0 degrees is this way ↑

• marker (MarkerStyle, optional) – The marker style. marker can be either an instance of the class or the text shorthand for a particular marker. Defaults to None, in which case it takes the value of rcParams[“scatter.marker”] (default: ‘o’) = ‘o’. If marker=’football’ plots a football shape with the pentagons the color of the edgecolors and hexagons the color of the ‘c’ argument; ‘linewidths’ also sets the linewidth of the football marker.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

paths – or a tuple of (paths, paths) if marker=’football’

Return type:

matplotlib.collections.PathCollection

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.scatter(30, 30, ax=ax)
```
```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.scatter(30, 30, rotation_degrees=45, marker=arrowhead_marker, ax=ax)
```
```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.scatter(30, 30, marker='football', ax=ax)
```
triplot(x, y, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.triplot

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

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

voronoi(x, y, teams)

Get Voronoi vertices for a set of coordinates. Uses a trick by Dan Nichol (@D4N__ on Twitter) where points are reflected in the pitch lines before calculating the Voronoi. This means that the Voronoi extends to the edges of the pitch. See: https://github.com/ProformAnalytics/tutorial_nbs/blob/master/notebooks/Voronoi%20Reflection%20Trick.ipynb

Players outside the pitch dimensions are assumed to be standing on the pitch edge. This means that their coordinates are clipped to the pitch edges before calculating the Voronoi.

Parameters:
• x, y (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the coordinates on the pitch.

• teams (array-like or scalar.) – This splits the results into the Voronoi vertices for each team. This can either have integer (1/0) values or boolean (True/False) values. team1 is where team==1 or team==True team2 is where team==0 or team==False

Returns:

• team1 (a 1d numpy array (length number of players in team 1) of 2d arrays) – Where the individual 2d arrays are coordinates of the Voronoi vertices.

• team2 (a 1d numpy array (length number of players in team 2) of 2d arrays) – Where the individual 2d arrays are coordinates of the Voronoi vertices.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=22)
>>> y = np.random.uniform(low=0, high=80, size=22)
>>> teams = np.array([0] * 11 + [1] * 11)
>>> pitch.scatter(x[teams == 0], y[teams == 0], color='red', ax=ax)
>>> pitch.scatter(x[teams == 1], y[teams == 1], color='blue', ax=ax)
>>> team1, team2 = pitch.voronoi(x, y, teams)
>>> team1_poly = pitch.polygon(team1, ax=ax, color='blue', alpha=0.3)
>>> team2_poly = pitch.polygon(team2, ax=ax, color='red', alpha=0.3)
```

Bases: `BasePitchPlot`

Methods

 `annotate`(text, xy[, xytext, ax]) Utility wrapper around ax.annotate which automatically flips the xy and xytext coordinates if the pitch is vertical. `arrows`(xstart, ystart, xend, yend, *args[, ax]) Utility wrapper around matplotlib.axes.Axes.quiver. `bin_statistic`(x, y[, values, statistic, ...]) Calculates binned statistics using scipy.stats.binned_statistic_2d. `bin_statistic_positional`(x, y[, values, ...]) Calculates binned statistics for the Juego de posición (position game) concept. `calculate_angle_and_distance`(xstart, ystart, ...) Calculates the angle in radians counter-clockwise and the distance between a start and end location. `convexhull`(x, y) Get lines of Convex Hull for a set of coordinates `draw`([ax, figsize, nrows, ncols, ...]) Draws the specified soccer/ football pitch(es). `flow`(xstart, ystart, xend, yend[, bins, ...]) Create a flow map by binning the data into cells and calculating the average angles and distances. `goal_angle`(x, y[, ax, goal]) Plot a polygon with the angle to the goal using matplotlib.patches.Polygon. `grid`([figheight, nrows, ncols, grid_height, ...]) A helper to create a grid of pitches in a specified location `grid_dimensions`(figwidth, figheight, nrows, ...) A helper method to propose a grid_width and grid_height for grid based on the inputs. `heatmap`(stats[, ax]) Utility wrapper around matplotlib.axes.Axes.pcolormesh which automatically flips the x_grid and y_grid coordinates if the pitch is vertical. `heatmap_positional`(stats[, ax]) Plots several heatmaps for the different Juegos de posición areas. `hexbin`(x, y[, ax]) Utility wrapper around matplotlib.axes.Axes.hexbin, which automatically flips the x and y coordinates if the pitch is vertical and clips to the pitch boundaries. `jointgrid`([figheight, left, grid_width, ...]) Create a grid with a pitch at the center and (marginal) axes at the sides of the pitch. `kdeplot`(x, y[, ax]) Utility wrapper around seaborn.kdeplot, which automatically flips the x and y coordinates if the pitch is vertical and clips to the pitch boundaries. `label_heatmap`(stats[, str_format, ...]) Labels the heatmap(s) and automatically flips the coordinates if the pitch is vertical. `lines`(xstart, ystart, xend, yend[, color, ...]) Plots lines using matplotlib.collections.LineCollection. `plot`(x, y[, ax]) Utility wrapper around matplotlib.axes.Axes.plot, which automatically flips the x and y coordinates if the pitch is vertical. `polygon`(verts[, ax]) Plot polygons. `scatter`(x, y[, rotation_degrees, marker, ax]) Utility wrapper around matplotlib.axes.Axes.scatter, which automatically flips the x and y coordinates if the pitch is vertical. `triplot`(x, y[, ax]) Utility wrapper around matplotlib.axes.Axes.triplot `voronoi`(x, y, teams) Get Voronoi vertices for a set of coordinates.
annotate(text, xy, xytext=None, ax=None, **kwargs)

Utility wrapper around ax.annotate which automatically flips the xy and xytext coordinates if the pitch is vertical.

Annotate the point xy with text. See: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.annotate.html

Parameters:
• text (str) – The text of the annotation.

• xy ((float, float)) – The point (x, y) to annotate.

• xytext ((float, float), optional) – The position (x, y) to place the text at. If None, defaults to xy.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

annotation

Return type:

matplotlib.text.Annotation

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.annotate(text='center', xytext=(50, 50), xy=(60, 40), ha='center', va='center',                            ax=ax, arrowprops=dict(facecolor='black'))
```
arrows(xstart, ystart, xend, yend, *args, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.quiver. Quiver uses locations and direction vectors usually. Here these are instead calculated automatically from the start and endpoints of the arrow. The function also automatically flips the x and y coordinates if the pitch is vertical.

Plot a 2D field of arrows. See: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.quiver.html

Parameters:
• xstart, ystart, xend, yend (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the start and end coordinates of the lines.

• C (1D or 2D array-like, optional) – Numeric data that defines the arrow colors by colormapping via norm and cmap. This does not support explicit colors. If you want to set colors directly, use color instead. The size of C must match the number of arrow locations.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.

• width (float, default 4) – Arrow shaft width in points.

• headwidth (float, default 3) – Head width as a multiple of the arrow shaft width.

• headlength (float, default 5) – Head length as a multiple of the arrow shaft width.

• headaxislength (float, default: 4.5) – Head length at the shaft intersection. If this is equal to the headlength then the arrow will be a triangular shape. If greater than the headlength then the arrow will be wedge shaped. If less than the headlength the arrow will be swept back.

• color (color or color sequence, optional) – Explicit color(s) for the arrows. If C has been set, color has no effect.

• linewidth or linewidths or lw (float or sequence of floats) – Edgewidth of arrow.

• edgecolor or ec or edgecolors (color or sequence of colors or ‘face’)

• alpha (float or None) – Transparency of arrows.

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

Returns:

PolyCollection

Return type:

matplotlib.quiver.Quiver

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.arrows(20, 20, 45, 80, ax=ax)
```
```>>> from mplsoccer.quiver import arrows
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> arrows([0.1, 0.4], [0.1, 0.5], [0.9, 0.4], [0.8, 0.8], ax=ax)
>>> ax.set_xlim(0, 1)
>>> ax.set_ylim(0, 1)
```
bin_statistic(x, y, values=None, statistic='count', bins=(5, 4), normalize=False, standardized=False)

Calculates binned statistics using scipy.stats.binned_statistic_2d.

This method automatically sets the range, changes the scipy defaults, and outputs the grids and centers for plotting.

The default statistic has been changed to count instead of mean. The default bins have been set to (5,4).

Parameters:
• x, y, values (array-like or scalar.) – Commonly, these parameters are 1D arrays. If the statistic is ‘count’ then values are ignored.

• dim (mplsoccer pitch dimensions) – One of FixedDims, MetricasportsDims, VariableCenterDims, or CustomDims. Automatically populated when using Pitch/ VerticalPitch class

• statistic (string or callable, optional) – The statistic to compute (default is ‘count’). The following statistics are available: ‘count’ (default), ‘mean’, ‘std’, ‘median’, ‘sum’, ‘min’, ‘max’, ‘circmean’ or a user-defined function. See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.binned_statistic_2d.html

• bins (int or [int, int] or array_like or [array, array], optional) –

The bin specification.
• the number of bins for the two dimensions (nx = ny = bins),

• the number of bins in each dimension (nx, ny = bins),

• the bin edges for the two dimensions (x_edge = y_edge = bins),

• the bin edges in each dimension (x_edge, y_edge = bins). If the bin edges are specified, the number of bins will be, (nx = len(x_edge)-1, ny = len(y_edge)-1).

• normalize (bool, default False) – Whether to normalize the statistic by dividing by the total.

• standardized (bool, default False) – Whether the x, y values have been standardized to the ‘uefa’ pitch coordinates (105m x 68m)

Returns:

bin_statistic – The keys are ‘statistic’ (the calculated statistic), ‘x_grid’ and ‘y_grid (the bin’s edges), cx and cy (the bin centers) and ‘binnumber’ (the bin indices each point belongs to). ‘binnumber’ is a (2, N) array that represents the bin in which the observation falls if the observations falls outside the pitch the value is -1 for the dimension. The binnumber are zero indexed and start from the top and left handside of the pitch.

Return type:

dict.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic(x, y)
>>> pitch.heatmap(stats, edgecolors='black', cmap='hot', ax=ax)
```
bin_statistic_positional(x, y, values=None, positional='full', statistic='count', normalize=False)

Calculates binned statistics for the Juego de posición (position game) concept. It uses scipy.stats.binned_statistic_2d.

Parameters:
• x, y, values (array-like or scalar.) – Commonly, these parameters are 1D arrays. If the statistic is ‘count’ then values are ignored.

• dim (mplsoccer pitch dimensions) – One of FixedDims, MetricasportsDims, VariableCenterDims, or CustomDims. Automatically populated when using Pitch/ VerticalPitch class

• positional (str) – One of ‘full’, ‘horizontal’ or ‘vertical’ for the respective heatmaps.

• statistic (string or callable, optional) – The statistic to compute (default is ‘count’). The following statistics are available: ‘count’ (default), ‘mean’, ‘std’, ‘median’, ‘sum’, ‘min’, ‘max’, or a user-defined function. See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.binned_statistic_2d.html.

• normalize (bool, default False) – Whether to normalize the statistic by dividing by the total.

Returns:

bin_statistic – The dictionary keys are ‘statistic’ (the calculated statistic), ‘x_grid’ and ‘y_grid (the bin’s edges), and cx and cy (the bin centers).

Return type:

A list of dictionaries.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic_positional(x, y)
>>> pitch.heatmap_positional(stats, edgecolors='black', cmap='hot', ax=ax)
```
calculate_angle_and_distance(xstart, ystart, xend, yend, standardized=False, degrees=False)

Calculates the angle in radians counter-clockwise and the distance between a start and end location. Where the angle 0 is this way → (the straight line from left to right) in a horizontally orientated pitch and this way ↑ in a vertically orientated pitch. The angle goes from 0 to 2pi. To convert the angle to degrees clockwise use degrees=True.

Parameters:
• xstart, ystart, xend, yend (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the start and end coordinates to calculate the angle between.

• standardized (bool, default False) – Whether the x, y values have been standardized to the ‘uefa’ pitch coordinates (105m x 68m)

• degrees (bool, default False) – If False, the angle is returned in radians counter-clockwise in the range [0, 2pi] If True, the angle is returned in degrees clockwise in the range [0, 360].

Returns:

• angle (ndarray) – The default is an array of angles in radians counter-clockwise in the range [0, 2pi]. Where 0 is the straight line left to right in a horizontally orientated pitch and the straight line bottom to top in a vertically orientated pitch. If degrees = True, then the angle is returned in degrees clockwise in the range [0, 360]

• distance (ndarray) – Array of distances.

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> pitch.calculate_angle_and_distance(0, 40, 30, 20, degrees=True)
(array([326.30993247]), array([36.05551275]))
```
convexhull(x, y)

Get lines of Convex Hull for a set of coordinates

Parameters:

x, y (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the coordinates on the pitch.

Returns:

hull_vertices

Return type:

a numpy array of vertoces [1, num_vertices, [x, y]] of the Convex Hull.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=11)
>>> y = np.random.uniform(low=0, high=80, size=11)
>>> hull = pitch.convexhull(x, y)
>>> poly = pitch.polygon(hull, ax=ax, facecolor='cornflowerblue', alpha=0.3)
```
draw(ax=None, figsize=None, nrows=1, ncols=1, tight_layout=True, constrained_layout=False)

Draws the specified soccer/ football pitch(es). If an ax is specified the pitch is drawn on an existing axis.

Parameters:
• ax (matplotlib axis, default None) – A matplotlib.axes.Axes to draw the pitch on. If None is specified the pitch is plotted on a new figure.

• figsize (tuple of float, default Matplotlib figure size) – The figure size in inches by default uses rcParams[“figure.figsize”].

• nrows, ncols (int, default 1) – Number of rows/columns of the subplot grid.

• tight_layout (bool, default True) – Whether to use Matplotlib’s tight layout.

• constrained_layout (bool, default False) – Whether to use Matplotlib’s constrained layout.

Returns:

• If ax=None returns a matplotlib Figure and Axes.

• Else plotted on an existing axis and returns None.

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
```
```>>> from mplsoccer import Pitch
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> pitch = Pitch()
>>> pitch.draw(ax=ax)
```
flow(xstart, ystart, xend, yend, bins=(5, 4), arrow_type='same', arrow_length=5, color=None, ax=None, **kwargs)

Create a flow map by binning the data into cells and calculating the average angles and distances.

Parameters:
• xstart, ystart, xend, yend (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the start and end coordinates to calculate the angle between.

• bins (int or [int, int] or array_like or [array, array], optional) –

The bin specification for binning the data to calculate the angles/ distances.
• the number of bins for the two dimensions (nx = ny = bins),

• the number of bins in each dimension (nx, ny = bins),

• the bin edges for the two dimensions (x_edge = y_edge = bins),

• the bin edges in each dimension (x_edge, y_edge = bins). If the bin edges are specified, the number of bins will be, (nx = len(x_edge)-1, ny = len(y_edge)-1).

• arrow_type (str, default ‘same’) – The supported arrow types are: ‘same’, ‘scale’, and ‘average’. ‘same’ makes the arrows the same size (arrow_length). ‘scale’ scales the arrow length by the average distance in the cell (up to a max of arrow_length). ‘average’ makes the arrow size the average distance in the cell.

• arrow_length (float, default 5) – The arrow_length for the flow map. If the arrow_type=’same’, all the arrows will be arrow_length. If the arrow_type=’scale’, the arrows will be scaled by the average distance. If the arrow_type=’average’, the arrows_length is ignored This is automatically multipled by 100 if using a ‘tracab’ pitch (i.e. the default is 500).

• color (A matplotlib color, defaults to None.) – Defaults to None. In that case the marker color is determined by the cmap (default ‘viridis’). and the counts of the starting positions in each bin.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

PolyCollection

Return type:

matplotlib.quiver.Quiver

Examples

```>>> from mplsoccer import Pitch, Sbopen
>>> parser = Sbopen()
>>> df, related, freeze, tactics = parser.event(7478)
>>> team1, team2 = df.team_name.unique()
>>> mask_team1 = (df.type_name == 'Pass') & (df.team_name == team1)
>>> pitch = Pitch(line_zorder=2)
>>> fig, ax = pitch.draw()
>>> bs_heatmap = pitch.bin_statistic(df.x, df.y, statistic='count', bins=(6, 4))
>>> hm = pitch.heatmap(bs_heatmap, ax=ax, cmap='Blues')
```
goal_angle(x, y, ax=None, goal='right', **kwargs)

Plot a polygon with the angle to the goal using matplotlib.patches.Polygon. See: https://matplotlib.org/stable/api/collections_api.html. Valid Collection keyword arguments: edgecolors, facecolors, linewidths, antialiaseds, transOffset, norm, cmap

Parameters:
• x, y (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the coordinates on the pitch.

• goal (str default ‘right’.) – The goal to plot, either ‘left’ or ‘right’.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• **kwargs (All other keyword arguments are passed on to) – matplotlib.collections.PathCollection.

Returns:

Polygon

Return type:

matplotlib.patches.Polygon

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.goal_angle(100, 30, alpha=0.5, color='red', ax=ax)
```
grid(figheight=9, nrows=1, ncols=1, grid_height=0.715, grid_width=0.95, space=0.05, left=None, bottom=None, endnote_height=0.065, endnote_space=0.01, title_height=0.15, title_space=0.01, axis=True)

A helper to create a grid of pitches in a specified location

Parameters:
• figheight (float, default 9) – The figure height in inches.

• nrows, ncols (int, default 1) – Number of rows/columns of pitches in the grid.

• grid_height (float, default 0.715) – The height of the pitch grid in fractions of the figure height. The default is the grid height is 71.5% of the figure height.

• grid_width (float, default 0.95) – The width of the pitch grid in fractions of the figure width. The default is the grid is 95% of the figure width.

• space (float, default 0.05) – The total amount of the grid height reserved for spacing between the pitch axes. Expressed as a fraction of the grid_height. The default is 5% of the grid height. The spacing across the grid width is automatically calculated to maintain even spacing.

• left (float, default None) – The location of the left-hand side of the axes in fractions of the figure width. The default of None places the axes in the middle of the figure.

• bottom (float, default None) – The location of the bottom endnote axes in fractions of the figure height. The default of None places the axes in the middle of the figure. If the endnote_height=0 then the pitch grid is located at the bottom coordinate instead.

• endnote_height (float, default 0.065) – The height of the endnote axes in fractions of the figure height. The default is the endnote is 6.5% of the figure height. If endnote_height=0, then the endnote axes is not plotted.

• endnote_space (float, default 0.01) – The space between the pitch grid and endnote axis in fractions of the figure height. The default space is 1% of the figure height. If endnote_height=0, then the endnote_space is set to zero.

• title_height (float, default 0.15) – The height of the title axis in fractions of the figure height. The default is the title axis is 15% of the figure height. If title_height=0, then the title axes is not plotted.

• title_space (float, default 0.01) – The space between the pitch grid and title axis in fractions of the figure height. The default space is 1% of the figure height. If title_height=0, then the title_space is set to zero.

• axis (bool, default True) – Whether the endnote and title axes are ‘on’.

Returns:

• fig (matplotlib.figure.Figure)

• axs (dict[label, Axes]) – A dictionary mapping the labels to the Axes objects. The possible keys are ‘pitch’, ‘title’, and ‘endnote’.

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, axs = pitch.grid(nrows=3, ncols=3, grid_height=0.7, figheight=14)
```
grid_dimensions(figwidth, figheight, nrows, ncols, max_grid, space)

A helper method to propose a grid_width and grid_height for grid based on the inputs.

Parameters:
• figwidth, figheight (float) – The figure width/height in inches.

• nrows, ncols (int) – Number of rows/columns of pitches in the grid.

• max_grid (float) – The longest side of the grid in fractions of the figure width / height. Should be between zero and one.

• space (float) – The total amount of the grid height reserved for spacing between the pitch axes. Expressed as a fraction of the grid_height.

Returns:

grid_width, grid_height

Return type:

the suggested grid_width and grid_height

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> grid_width, grid_height = pitch.grid_dimensions(figwidth=16, figheight=9,                                                             nrows=1, ncols=1,                                                             max_grid=1,  space=0)
```
heatmap(stats, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.pcolormesh which automatically flips the x_grid and y_grid coordinates if the pitch is vertical.

Parameters:
• stats (dict.) – This should be calculated via bin_statistic(). The keys are ‘statistic’ (the calculated statistic), ‘x_grid’ and ‘y_grid (the bin’s edges), and cx and cy (the bin centers).

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.

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

Returns:

mesh

Return type:

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic(x, y)
>>> pitch.heatmap(stats, edgecolors='black', cmap='hot', ax=ax)
```
heatmap_positional(stats, ax=None, **kwargs)

Plots several heatmaps for the different Juegos de posición areas.

Parameters:
• stats (A list of dictionaries.) – This should be calculated via bin_statistic_positional(). The dictionary keys are ‘statistic’ (the calculated statistic), ‘x_grid’ and ‘y_grid (the bin’s edges), and cx and cy (the bin centers).

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.

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

Returns:

mesh

Return type:

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic_positional(x, y)
>>> pitch.heatmap_positional(stats, edgecolors='black', cmap='hot', ax=ax)
```
hexbin(x, y, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.hexbin, which automatically flips the x and y coordinates if the pitch is vertical and clips to the pitch boundaries.

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

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• mincnt (int > 0, default: 1) – If not None, only display cells with more than mincnt number of points in the cell.

• gridsize (int or (int, int), default: (17, 8) for Pitch/ (17, 17) for VerticalPitch) – If a single int, the number of hexagons in the x-direction. The number of hexagons in the y-direction is chosen such that the hexagons are approximately regular. Alternatively, if a tuple (nx, ny), the number of hexagons in the x-direction and the y-direction.

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

Returns:

polycollection

Return type:

matplotlib.collections.PolyCollection

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2)
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> pitch.hexbin(x, y, edgecolors='black', gridsize=(11, 5), cmap='Reds', ax=ax)
```
jointgrid(figheight=9, left=None, grid_width=0.95, bottom=None, endnote_height=0.065, endnote_space=0.01, grid_height=0.715, title_space=0.01, title_height=0.15, space=0, marginal=0.1, ax_left=True, ax_top=True, ax_right=True, ax_bottom=False, axis=True)

Create a grid with a pitch at the center and (marginal) axes at the sides of the pitch.

Parameters:
• figheight (float, default 9) – The figure height in inches.

• left (float, default None) – The location of the left-hand side of the grid in fractions of the figure width. The default of None places the axes in the middle of the figure.

• grid_width (float, default 0.95) – The width of the grid area in fractions of the figure width. The default is the grid is 80% of the figure width.

• bottom (float, default None) – The location of the bottom endnote axes in fractions of the figure height. The default of None places the axes in the middle of the figure. If the endnote_height=0 then the joint grid is located at the bottom coordinate instead.

• endnote_height (float, default 0.065) – The height of the endnote axes in fractions of the figure height. The default is the endnote is 6.5% of the figure height. If endnote_height=0, then the endnote axes is not plotted.

• endnote_space (float, default 0.01) – The space between the joint grid and endnote axis in fractions of the figure height. The default space is 1% of the figure height. If endnote_height=0, then the endnote_space is set to zero.

• grid_height (float, default 0.715) – The height of the joint grid area in fractions of the figure height. The default is the grid height is 70% of the figure height.

• title_space (float, default 0.01) – The space between the joint grid and title axis in fractions of the figure height. The default space is 1% of the figure height. If title_height=0, then the title_space is set to zero.

• title_height (float, default 0.15) – The height of the title axis in fractions of the figure height. The default is the title axis is 15% of the figure height. If title_height=0, then the title axes is not plotted.

• space (float, default 0.01) – The total amount of the grid height reserved for spacing between axes. Expressed as a fraction of the grid height. The default is 0.01% of the grid height. Note if space is zero, it will still look like there is space if the pitch has padding, e.g. pad_top=15.

• marginal (float, default 0.1) – The total amount of the grid height reserved for the marginal axes. Expressed as a fraction of the grid height. The default is 10% of the grid height.

• ax_left, ax_top, ax_right (bool, default True) – Whether to include a Matplotlib Axes on the left/top/right side of the pitch.

• ax_bottom (bool, default False) – Whether to include a Matplotlib Axes on the bottom side of the pitch.

• axis (bool, default True) – Whether the endnote, title, and the marginal axes are ‘on’.

Returns:

• fig (matplotlib.figure.Figure)

• axs (dict[label, Axes]) – A dictionary mapping the labels to the Axes objects. The possible keys are ‘left’, ‘right’, ‘bottom’, ‘top’ for the marginal axes, ‘pitch’, ‘title’ and ‘endnote’.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> import seaborn as sns
>>> pitch = Pitch()
>>> fig, axs = pitch.jointgrid(ax_left=False, ax_right=False,                                        ax_bottom=False, ax_top=True)
>>> x = np.random.uniform(low=0, high=120, size=100)
```
kdeplot(x, y, ax=None, **kwargs)

Utility wrapper around seaborn.kdeplot, which automatically flips the x and y coordinates if the pitch is vertical and clips to the pitch boundaries.

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

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• **kwargs (All other keyword arguments are passed on to seaborn.kdeplot.)

Returns:

contour

Return type:

matplotlib.contour.ContourSet

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(line_zorder=2)
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> pitch.kdeplot(x, y, cmap='Reds', fill=True, levels=100, ax=ax)
```
label_heatmap(stats, str_format=None, exclude_zeros=False, ax=None, **kwargs)

Labels the heatmap(s) and automatically flips the coordinates if the pitch is vertical.

Parameters:
• stats (A dictionary or list of dictionaries.) – This should be calculated via bin_statistic_positional() or bin_statistic().

• str_format (str) – A format string passed to str_format.format() to format the labels.

• exclude_zeros (bool) – Whether to exclude zeros when labelling the heatmap.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

annotations

Return type:

A list of matplotlib.text.Annotation.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> import matplotlib.patheffects as path_effects
>>> pitch = Pitch(line_zorder=2, pitch_color='black')
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=100)
>>> y = np.random.uniform(low=0, high=80, size=100)
>>> stats = pitch.bin_statistic(x, y)
>>> pitch.heatmap(stats, edgecolors='black', cmap='hot', ax=ax)
>>> stats['statistic'] = stats['statistic'].astype(int)
>>> path_eff = [path_effects.Stroke(linewidth=0.5, foreground='#22312b')]
>>> text = pitch.label_heatmap(stats, color='white', ax=ax, fontsize=20, ha='center',                                        va='center', path_effects=path_eff)
```
lines(xstart, ystart, xend, yend, color=None, n_segments=100, comet=False, transparent=False, alpha_start=0.01, alpha_end=1, cmap=None, ax=None, **kwargs)

Plots lines using matplotlib.collections.LineCollection. This is a fast way to plot multiple lines without loops. Also enables lines that increase in width or opacity by splitting the line into n_segments of increasing width or opacity as the line progresses.

Parameters:
• xstart, ystart, xend, yend (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the start and end coordinates of the lines.

• color (A matplotlib color or sequence of colors, defaults to None.) – Defaults to None. In that case the marker color is determined by the value rcParams[‘lines.color’]

• n_segments (int, default 100) – If comet=True or transparent=True this is used to split the line into n_segments of increasing width/opacity.

• comet (bool default False) – Whether to plot the lines increasing in width.

• transparent (bool, default False) – Whether to plot the lines increasing in opacity.

• linewidth or lw (array-like or scalar, default 5.) – Multiple linewidths not supported for the comet or transparent lines.

• alpha_start (float, default 0.01) – The starting alpha value for transparent lines, between 0 (transparent) and 1 (opaque). If transparent = True the line will be drawn to linearly increase in opacity between alpha_start and alpha_end.

• alpha_end (float, default 1) – The ending alpha value for transparent lines, between 0 (transparent) and 1 (opaque). If transparent = True the line will be drawn to linearly increase in opacity between alpha_start and alpha_end.

• cmap (str, default None) – A matplotlib cmap (colormap) name

• vertical (bool, default False) – If the orientation is vertical (True), then the code switches the x and y coordinates.

• reverse_cmap (bool, default False) – Whether to reverse the cmap colors. If the pitch is horizontal and the y-axis is inverted then set this to True.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• **kwargs (All other keyword arguments are passed on to matplotlib.collections.LineCollection.)

Returns:

LineCollection

Return type:

matplotlib.collections.LineCollection

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.lines(20, 20, 45, 80, comet=True, transparent=True, ax=ax)
```
```>>> from mplsoccer.linecollection import lines
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> lines([0.1, 0.4], [0.1, 0.5], [0.9, 0.4], [0.8, 0.8], ax=ax)
```
plot(x, y, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.plot, which automatically flips the x and y coordinates if the pitch is vertical.

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

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

lines

Return type:

A list of Line2D objects representing the plotted data.

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.plot([30, 35, 20], [30, 19, 40], ax=ax)
```
polygon(verts, ax=None, **kwargs)

Plot polygons. Automatically flips the x and y vertices if the pitch is vertical.

Parameters:
• verts (verts is a sequence of (verts0, verts1, …)) – where verts_i is a numpy array of shape (number of vertices, 2).

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

• **kwargs (All other keyword arguments are passed on to) – matplotlib.patches.Polygon

Return type:

list of matplotlib.patches.Polygon

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch(label=True, axis=True)
>>> fig, ax = pitch.draw()
>>> shape1 = np.array([[50, 2], [80, 30], [40, 30], [40, 20]])
>>> shape2 = np.array([[70, 70], [60, 50], [40, 40]])
>>> verts = [shape1, shape2]
>>> pitch.polygon(verts, color='red', alpha=0.3, ax=ax)
```
scatter(x, y, rotation_degrees=None, marker=None, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.scatter, which automatically flips the x and y coordinates if the pitch is vertical. You can optionally use a football marker with marker=’football’ and rotate markers with rotation_degrees.

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

• rotation_degrees (array-like or scalar, default None.) – Rotates the marker in degrees, clockwise. 0 degrees is facing the direction of play. In a horizontal pitch, 0 degrees is this way →, in a vertical pitch, 0 degrees is this way ↑

• marker (MarkerStyle, optional) – The marker style. marker can be either an instance of the class or the text shorthand for a particular marker. Defaults to None, in which case it takes the value of rcParams[“scatter.marker”] (default: ‘o’) = ‘o’. If marker=’football’ plots a football shape with the pentagons the color of the edgecolors and hexagons the color of the ‘c’ argument; ‘linewidths’ also sets the linewidth of the football marker.

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

Returns:

paths – or a tuple of (paths, paths) if marker=’football’

Return type:

matplotlib.collections.PathCollection

Examples

```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.scatter(30, 30, ax=ax)
```
```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.scatter(30, 30, rotation_degrees=45, marker=arrowhead_marker, ax=ax)
```
```>>> from mplsoccer import Pitch
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> pitch.scatter(30, 30, marker='football', ax=ax)
```
triplot(x, y, ax=None, **kwargs)

Utility wrapper around matplotlib.axes.Axes.triplot

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

• ax (matplotlib.axes.Axes, default None) – The axis to plot on.

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

voronoi(x, y, teams)

Get Voronoi vertices for a set of coordinates. Uses a trick by Dan Nichol (@D4N__ on Twitter) where points are reflected in the pitch lines before calculating the Voronoi. This means that the Voronoi extends to the edges of the pitch. See: https://github.com/ProformAnalytics/tutorial_nbs/blob/master/notebooks/Voronoi%20Reflection%20Trick.ipynb

Players outside the pitch dimensions are assumed to be standing on the pitch edge. This means that their coordinates are clipped to the pitch edges before calculating the Voronoi.

Parameters:
• x, y (array-like or scalar.) – Commonly, these parameters are 1D arrays. These should be the coordinates on the pitch.

• teams (array-like or scalar.) – This splits the results into the Voronoi vertices for each team. This can either have integer (1/0) values or boolean (True/False) values. team1 is where team==1 or team==True team2 is where team==0 or team==False

Returns:

• team1 (a 1d numpy array (length number of players in team 1) of 2d arrays) – Where the individual 2d arrays are coordinates of the Voronoi vertices.

• team2 (a 1d numpy array (length number of players in team 2) of 2d arrays) – Where the individual 2d arrays are coordinates of the Voronoi vertices.

Examples

```>>> from mplsoccer import Pitch
>>> import numpy as np
>>> pitch = Pitch()
>>> fig, ax = pitch.draw()
>>> x = np.random.uniform(low=0, high=120, size=22)
>>> y = np.random.uniform(low=0, high=80, size=22)
>>> teams = np.array([0] * 11 + [1] * 11)
>>> pitch.scatter(x[teams == 0], y[teams == 0], color='red', ax=ax)
>>> pitch.scatter(x[teams == 1], y[teams == 1], color='blue', ax=ax)
>>> team1, team2 = pitch.voronoi(x, y, teams)
>>> team1_poly = pitch.polygon(team1, ax=ax, color='blue', alpha=0.3)
>>> team2_poly = pitch.polygon(team2, ax=ax, color='red', alpha=0.3)
```