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:Centroid 1 –>
centroid()
Centroid Distance –>
centroid_distance()
Stretch Index 2 –>
stretch_index()
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
- 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
- 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
- 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