unravelsports 1.1.0

A project to analyze sports event and tracking data

🌀 pip install unravelsports

🌀 What is it?

The unravelsports package aims to aid researchers, analysts and enthusiasts by providing intermediary steps in the complex process of converting raw sports data into meaningful information and actionable insights.

This package currently supports:

• ⚽ 🏈 Polars DataFrame Conversion
• ⚽ 🏈 Graph Neural Network Training, Graph Conversion and Prediction [🔗 Bekkers & Sahasrabudhe (2023)]
• ⚽ Pressing Intensity [🔗 Bekkers (2024)]
• ⚽ Formation and Position Identification (EFPI) [🔗 Bekkers (2025)]

🌀 Features

Polars DataFrames

⚽🏈 Convert Tracking Data into Polars DataFrames for rapid data conversion and data processing.

⚽ For soccer we rely on Kloppy and as such we support Sportec, SkillCorner, PFF / GradientSports, Metrica, StatsPerform, Tracab (CyronHego), SecondSpectrum, HawkEye and Signality tracking data.

from unravel.soccer import KloppyPolarsDataset

from kloppy import sportec

kloppy_dataset = sportec.load_open_tracking_data()
kloppy_polars_dataset = KloppyPolarsDataset(
    kloppy_dataset=kloppy_dataset
)

	period_id	timestamp	frame_id	ball_state	id	x	y	z	team_id	position_name	game_id	vx	vy	vz	v	ax	ay	az	a	ball_owning_team_id	is_ball_carrier
0	1	0 days 00:00:00	10000	alive	DFL-OBJ-00008F	-20.67	-4.56	0	DFL-CLU-000005	RCB	DFL-MAT-J03WPY	0.393	-0.214	0	0.447	0	0	0	0	DFL-CLU-00000P	False
1	1	0 days 00:00:00	10000	alive	DFL-OBJ-0000EJ	-8.86	-0.94	0	DFL-CLU-000005	UNK	DFL-MAT-J03WPY	-0.009	0.018	0	0.02	0	0	0	0	DFL-CLU-00000P	False
2	1	0 days 00:00:00	10000	alive	DFL-OBJ-0000F8	-2.12	9.85	0	DFL-CLU-00000P	RM	DFL-MAT-J03WPY	0	0	0	0	0	0	0	0	DFL-CLU-00000P	False
3	1	0 days 00:00:00	10000	alive	DFL-OBJ-0000NZ	0.57	23.23	0	DFL-CLU-00000P	RB	DFL-MAT-J03WPY	0.179	-0.134	0	0.223	0	0	0	0	DFL-CLU-00000P	False
4	1	0 days 00:00:00	10000	alive	DFL-OBJ-0001HW	-46.26	0.08	0	DFL-CLU-000005	GK	DFL-MAT-J03WPY	0.357	0.071	0	0.364	0	0	0	0	DFL-CLU-00000P	False

🏈 For American Football we use BigDataBowl Data directly.

from unravel.american_football import BigDataBowlDataset

bdb = BigDataBowlDataset(
    tracking_file_path="week1.csv",
    players_file_path="players.csv",
    plays_file_path="plays.csv",
)

Graph Neural Networks

⚽🏈 Convert Polars Dataframes into Graphs to train graph neural networks. These Graphs can be used with Spektral - a flexible framework for training graph neural networks. unravelsports allows you to randomize and split data into train, test and validation sets along matches, sequences or possessions to avoid leakage and improve model quality. And finally, train, validate and test your (custom) Graph model(s) and easily predict on new data.

from unravel.soccer import SoccerGraphConverter

converter = SoccerGraphConverter(
    dataset=kloppy_polars_dataset,
    self_loop_ball=True,
    adjacency_matrix_connect_type="ball",
    adjacency_matrix_type="split_by_team",
    label_type="binary",
    defending_team_node_value=0.1,
    non_potential_receiver_node_value=0.1,
    random_seed=False,
    pad=False,
    verbose=False,
)

---

⚽ Pressing Intensity

Compute Pressing Intensity for a whole game (or segment) of Soccer tracking data.

See Pressing Intensity Jupyter Notebook for an example how to create mp4 videos.

from unravel.soccer import PressingIntensity

import polars as pl

model = PressingIntensity(
    dataset=kloppy_polars_dataset
)
model.fit(
    start_time = pl.duration(minutes=1, seconds=53),
    end_time = pl.duration(minutes=2, seconds=32),
    period_id = 1,
    method="teams",
    ball_method="max",
    orient="home_away",
    speed_threshold=2.0,
) 

---

⚽ Formation and Position Identification

Compute Elastic Formation and Position Identification, EFPI for individual frames, possessions, periods or specific time intervals for Soccer.

For more information on all possibilities for "every" check out Polars Documentation.

from unravel.soccer import EFPI

model = EFPI(dataset=kloppy_polars_dataset)
model.fit(
    # Default 65 formations , or specify a subset (e.g. ["442" , "433"])
    formations=None,
    # specific time intervals (e.g. 1m, 1m14s, 2m30s etc.), or specify "possession", "period" or "frame".
    every="5m",
    substitutions="drop",
    change_threshold=0.1,
    change_after_possession=True,
)

⌛ More to come soon...!

🌀 Quick Start

📖 ⚽ The Quick Start Jupyter Notebook explains how to convert any positional tracking data from Kloppy to Spektral GNN in a few easy steps while walking you through the most important features and documentation.

📖 ⚽ The Graph Converter Tutorial Jupyter Notebook gives an in-depth walkthrough.

📖 🏈 The BigDataBowl Converter Tutorial Jupyter Notebook gives an guide on how to convert the BigDataBowl data into Graphs.

📖 ⚽ The Pressing Intensity Tutorial Jupyter Notebook gives a description on how to create Pressing Intensity videos.

🌀 Documentation

For now, follow the Graph Converter Tutorial and check the Graph FAQ, more documentation will follow!

Additional reading:

📖 A Graph Neural Network Deep-dive into Successful Counterattacks {A. Sahasrabudhe & J. Bekkers, 2023}

🎤 Cutting Edge Football Analytics: using polars, keras and spektral (PyData London, 2025)

🌀 Installation

The easiest way to get started is:

pip install unravelsports

⚠️ Due to compatibility issues unravelsports currently only works on Python 3.11 with:

spektral==1.20.0 
tensorflow==2.14.0 
keras==2.14.0
kloppy==3.17.0
polars==1.2.1

These dependencies come pre-installed with the package. It is advised to create a virtual environment.

This package is tested on the latest versions of Ubuntu, MacOS and Windows.

🌀 Licenses

This project is licensed under the Mozilla Public License Version 2.0 (MPL), which requires that you include a copy of the license and provide attribution to the original authors. Any modifications you make to the MPL-licensed files must be documented, and the source code for those modifications must be made open-source under the same license.

🌀 Citation

If you use this repository for any educational purposes, research, project etc., please reference both:

📎 The unravelsports package.

BibTex

@software{unravelsports2024repository,
  author = {Bekkers, Joris},
  title = {unravelsports},
  version = {0.3.0},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/unravelsports/unravelsports}
}

📎 Bekkers, J., & Sahasrabudhe, A. (2024). A Graph Neural Network deep-dive into successful counterattacks. arXiv preprint arXiv:2411.17450.

BibTex

@inproceedings{sahasrabudhe2023graph,
  title={A Graph Neural Network deep-dive into successful counterattacks},
  author={Sahasrabudhe, Amod and Bekkers, Joris},
  booktitle={17th Annual MIT Sloan Sports Analytics Conference. Boston, MA, USA: MIT},
  pages={15},
  year={2023}
}

📎 Bekkers, J. (2024). Pressing Intensity: An Intuitive Measure for Pressing in Soccer. arXiv preprint arXiv:2501.04712.

BibTex

@article{bekkers2024pressing,
  title={Pressing Intensity: An Intuitive Measure for Pressing in Soccer},
  author={Bekkers, Joris},
  journal={arXiv preprint arXiv:2501.04712},
  year={2024}
}

📎 Bekkers, J. (2025). EFPI: Elastic Formation and Position Identification in Football (Soccer) using Template Matching and Linear Assignment. arXiv preprint arXiv:2506.23843.

BibTex

@article{bekkers2025efpi,
  title={EFPI: Elastic Formation and Position Identification in Football (Soccer) using Template Matching and Linear Assignment},
  author={Bekkers, Joris},
  journal={arXiv preprint arXiv:2506.23843},
  year={2025}
}

🌀 Social Media