Skip to content
View UnravelSports's full-sized avatar

Block or report UnravelSports

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Please don't include any personal information such as legal names or email addresses. Maximum 100 characters, markdown supported. This note will be visible to only you.
Report abuse

Contact GitHub support about this user’s behavior. Learn more about reporting abuse.

Report abuse
UnravelSports/README.md

unravelsports logo

Powered by PySport Powered by PySport tl;dr legal

πŸŒ€ 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.

πŸŒ€ Features

Convert

⚽ Soccer positional tracking data into Graphs to train graph neural networks by leveraging the powerful Kloppy data conversion standard for

  • Metrica
  • Sportec
  • Tracab (CyronHego)
  • SecondSpectrum
  • SkillCorner
  • StatsPerform

🏈 BigDataBowl American football positional tracking data into Graphs to train graph neural networks by leveraging Polars.

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.

βŒ› 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.

πŸŒ€ 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}

πŸŒ€ 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.15.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.

πŸŒ€ Contributing

All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome.

An overview on how to contribute can be found in the contributing guide.

πŸŒ€ 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.1.0},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/unravelsports/unravelsports}
}

πŸ“Ž Sahasrabudhe, A., & Bekkers, J. (2023). A graph neural network deep-dive into successful counterattacks. MIT Sloan Sports Analytics Conference.

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}
}

and let me know on

alt_text alt_text

πŸŒ€ 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.

Pinned Loading

  1. rs-football-3d rs-football-3d Public

    UnravelSports repository to display Football/Soccer tracking data in 3D using Rust & Bevy

    Rust 21 2

  2. ussf_ssac_23_soccer_gnn ussf_ssac_23_soccer_gnn Public

    Forked from USSoccerFederation/ussf_ssac_23_soccer_gnn

    U.S. Soccer Federation 2023 MIT Sloan Sports Analytics Conference Graph Neural Network soccer research repository

    Jupyter Notebook 1

  3. unravelsports unravelsports Public

    The unravelsports package aims to aid researchers, analysts and enthusiasts by providing intermediary steps in the complex process of turning raw sports data into meaningful information and actiona…

    Python 47 1