pientist / ballradar

[KDD 2023] Official implementation of "Ball Trajectory Inference from Multi-Agent Sports Contexts Using Set Transformer and Hierarchical Bi-LSTM".

Ball Radar

Source code for the paper Ball Trajectory Inference from Multi-Agent Sports Contexts Using Set Transformer and Hierarchical Bi-LSTM by Kim et al., KDD 2023.

Introduction

Ball Radar is a framework for ball trajectory inference from player trajectories in soccer matches. The main model has a hierarchical structure containing the Ball Possessor Classifier that predicts which player has the ball at each time step and the Ball Trajectory Regressor that predict the final ball trajectory conditioned on the players' possession probabilities. Each of the submodels deploys Set Transformers (Lee et al., 2019) to get permutation-invariant or equivariant representations of multi-agent contexts and a Bi-LSTM (or Bi-LSTMs) for sequential inference. Additionally, we perform rule-based postprocessing to make the model output more physically realistic. The following figure is an overview of the framework.

Installation and Setup

We have implemented the code using Python 3.10 and PyTorch 1.13.0.

After cloning the repository, you need to install the packages listed in requirements.txt.

$ pip install -r requirements.txt

Data Usage

For this study, we have used a mixed dataset including the following:

• Fitogether data: 15 matches of GPS tracking data combined with the corresponding event data provided by Fitogether.
• Metrica data: 3 matches of publicly available optical tracking and event data provided by Metrica Sports.

Unfortunately, we cannot share the Fitogether data because it is the company's internal information, but every process can be reproduced using Metrica data with little performance degradation. (See Table 5 of the paper.) We have attached the preprocessed version of the Metrica event data to data/metrica_events/ and uploaded that of the Metrica tracking data to my Google Drive. To execute the code, you should download the tracking data files from the drive and locate them in data/metrica_traces/.

For your reference, we have also attached the preprocessing code in datatools/metrica_data_processing.ipynb. That is, you can regenerate the preprocessed data files on your own by downloading the raw Metrica data from the original repository, locating the CSV files in data/metrica_traces/Sample_Game_X for each game, and executing datatools/metrica_data_processing.ipynb.

Running the Code

To train the model, you can run scripts/player_ball.sh using the following command on the terminal:

$ sh scripts/player_ball.sh

Also, you can train the other models that we introduced in Section 4.2 of the paper, by running scripts/direct_ball.sh, scripts/team_ball.sh, and so on. As a result, the model weights, hyperparameters, and the training log will be saved in saved/<trial_id>/.

To evaluate the model performance, please run model_eval.ipynb which can reproduce the results of Section 4.4 and Section 4.5.

Animating Match Scenes

For interpretability, we have implemented a tool named TraceAnimator for dynamically visualizing soccer match tracking data. It animates multiple types of trajectories, including true player and ball trajectories and the predicted trajectories generated from different steps. We have attached a sample 5-minute animation (img/metrica_match2_00.00-05.00.mp4) resulting from applying our model to a match in the Metrica dataset, respectively. Both animations include the following:

• player trajectories (red and blue circles with numbers inside)
• true ball trajectory (white circle)
• output of the ball trajectory regressor (orange star)
• predicted ball trajectory after the postprocessing (green star)

You can animate an arbitrary slice of Metrica data by importing the class TraceAnimator in datatools/trace_animator.py, making a class object, and executing the method run(). Please refer to model_eval.ipynb for the exact usage of this tool.

Citation

@inproceedings{Kim2023,
  author       = {Kim, Hyunsung and
                  Choi, Han-Jun and
                  Kim, Chang Jo and
                  Yoon, Jinsung and
                  Ko, Sang{-}Ki},
  title        = {Ball Trajectory Inference from Multi-Agent Sports Contexts
                  Using Set Transformer and Hierarchical {Bi-LSTM}},
  booktitle    = {The 29th {ACM} {SIGKDD} Conference on Knowledge Discovery and Data Mining},
  publisher    = {{ACM}},
  year         = {2023},
  location     = {Long Beach, CA, USA}
  isbn         = {979-8-4007-0103-0}
  url          = {https://doi.org/10.1145/3580305.3599779},
  doi          = {10.1145/3580305.3599779},
}