floodlight.models.geometry

class floodlight.models.geometry.CentroidModel[source]

Computations based on the geometric center of all players, commonly referred to as a team’s centroid.

Upon calling the fit()-method, this model calculates a team’s centroid. The following calculations can subsequently be queried by calling the corresponding methods:

Notes

Team centroids are computed as the arithmetic mean of all player positions (based on numpy’s nanmean function). For a fixed point in time and \(N\) players with corresponding positions \(x_1, \dots, x_N \in \mathbb{R}^2\), the centroid is calculated as

\[C = \frac{1}{N} \sum_i^N x_i.\]

Examples

>>> import numpy as np
>>> from floodlight import XY
>>> from floodlight.models.geometry import CentroidModel
>>> xy = XY(np.array(((1, 1, 2, -2), (1.5, np.nan, np.nan, -0))))
>>> cm = CentroidModel()
>>> cm.fit(xy)
>>> cm.centroid()
XY(xy=array([[ 1.5, -0.5],
   [ 1.5,  0. ]]), framerate=None, direction=None)
>>> cm.stretch_index(xy)
TeamProperty(property=array([1.5811388, nan]), name='stretch_index', framerate=None)
>>> cm.stretch_index(xy, axis='x')
TeamProperty(property=array([0.5, 0.]), name='stretch_index', framerate=None)

References

1

Sampaio, J., & Maçãs, V. (2012). Measuring tactical behaviour in football. International Journal of Sports Medicine, 33(05), 395-401.

2

Bourbousson, J., Sève, C., & McGarry, T. (2010). Space–time coordination dynamics in basketball: Part 2. The interaction between the two teams. Journal of Sports Sciences, 28(3), 349-358.

centroid()[source]

Returns the team centroid positions as computed by the fit method.

Returns

centroid – An XY object of shape (T, 2), where T is the total number of frames. The two columns contain the centroids’ x- and y-coordinates, respectively.

Return type

XY

centroid_distance(xy, axis=None)[source]

Calculates the Euclidean distance of each player to the fitted centroids.

Parameters
  • xy (XY) – Player spatiotemporal data for which the distances to the fitted centroids are calculated.

  • axis ({None, ‘x’, ‘y’}, optional) – Optional argument that restricts distance calculation to either the x- or y-dimension of the data. If set to None (default), distances are calculated in both dimensions.

Returns

centroid_distance – A PlayerProperty object of shape (T, N), where T is the total number of frames. Each column contains the distances to the team centroid of the player with corresponding xID.

Return type

PlayerProperty

fit(xy, exclude_xIDs=None)[source]

Fit the model to the given data and calculate team centroids.

Parameters
  • xy (XY) – Player spatiotemporal data for which the centroid is calculated.

  • exclude_xIDs (list, optional) – A list of xIDs to be excluded from computation. This can be useful if one would like, for example, to exclude goalkeepers from analysis.

stretch_index(xy, axis=None)[source]

Calculates the Stretch Index, i.e., the mean distance of all players to the team centroid.

Parameters
  • xy (XY) – Player spatiotemporal data for which the stretch index is calculated.

  • axis ({None, ‘x’, ‘y’}, optional) – Optional argument that restricts stretch index calculation to either the x- or y-dimension of the data. If set to None (default), the stretch index is calculated in both dimensions.

Returns

stretch_index – A TeamProperty object of shape (T, 1), where T is the total number of frames. Each entry contains the stretch index of that particular frame.

Return type

TeamProperty