floodlight.metrics.trajectory_clustering

floodlight.metrics.trajectory_clustering.formation_similarity(xy, template, exclude_xIDs=None, role_assignment=True, n_iter=1, delta=0.3333333333333333)

Computes formation similarity (FSIM) between observed player positions and a formation template via template matching. [1]

The algorithm classifies a team’s formation by comparing role-resolved average positions against an idealized formation template.

Parameters:

• xy (XY) – Spatiotemporal tracking data for one team, shape (T, 2*N).

• template (np.ndarray) – Template position array of shape (M, 2) representing an idealized formation.

• exclude_xIDs (list, optional) – A list of player indices (xIDs) to exclude from the analysis. Excluded players are removed from centroid computation and from the formation comparison. This is typically used to exclude goalkeepers.

• role_assignment (bool, optional) – If True (default), role assignment via the Hungarian algorithm is applied before averaging. Set to False to skip this step, e.g. when the input data has already been role-assigned externally.

• n_iter (int, optional) – Number of role assignment iterations. Only used when role_assignment is True. Defaults to 1.

• delta (float, optional) – Similarity decay parameter controlling how quickly similarity drops with distance between role positions. Motivated by a coarse 3x3 pitch partitioning where roles one zone apart should have near-zero similarity. Defaults to 1/3 according to [1].

Returns:

fsim – Formation similarity score in [0, 1].

Return type:

float

Notes

The pipeline proceeds as follows:

1. Per-frame centroid subtraction to obtain center-relative positions.

2. Role assignment (optional, default=True) [2] via Hungarian algorithm using mean positions as reference (one iteration per default, as proposed in [1]).

3. Averaging role-resolved positions across frames to obtain a single formation snapshot of shape (N, 2).

4. Independent min-max normalization of query and template to [0, 1] per axis, ensuring scale and compactness invariance.

5. Computation of an N x N similarity matrix using \(m_{i,j} = \max(1 - \|\tilde{r}_i - \tilde{r}_j\|^2 / \delta, \; 0)\), optimal one-to-one assignment via the Hungarian algorithm, and averaging matched similarities to obtain the FSIM score.

References

[1] (1,2,3)

Müller-Budack, E., Theiner, J., Rigoll, G., & Ewerth, R. (2019). Does 4-4-2 exist? An analytics approach to understand and classify football team formations in single match situations. In Proceedings of the 2nd International Workshop on Multimedia Content Analysis in Sports (pp. 25-33).

[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).