floodlight.transforms.permutation

floodlight.transforms.permutation.assign_roles(xy, reference=None, n_iter=1)

Assigns consistent roles to players across frames using the Hungarian algorithm. [1]

For each frame, player positions are matched to reference positions by minimizing the total Euclidean distance. The resulting XY object has columns reordered so that column i consistently represents role i across all frames.

Parameters:

• xy (XY) – Spatiotemporal data with shape (T, 2*N).

• reference (np.ndarray, optional) – Reference positions of shape (N, 2) used as the assignment target. If None (default), the mean position of each player column across all frames is used.

• n_iter (int, optional) – Number of assignment iterations. After each iteration the reference is recomputed as the column-wise mean of the assigned data. More iterations can improve convergence for longer sequences. Defaults to 1, which is sufficient for short sequences as proposed in [1].

Returns:

xy_assigned – New XY object with columns reordered per frame so that column i consistently represents role i. Same shape, framerate, and direction as input.

Return type:

XY

Notes

Players with NaN positions in a given frame are excluded from the assignment. Their corresponding role slots in the output are filled with NaN. Reference positions that are NaN are likewise excluded from the cost matrix, so the assignment operates only on valid data.

References

[1] (1,2)

Bialkowski, A., Lucey, P., Carr, P., Yue, Y., Sridharan, S., & Matthews, I. (2014). Identifying team style in soccer using formations learned from spatiotemporal tracking data. In IEEE International Conference on Data Mining Workshop (pp. 9-14).