floodlight - A high-level, data-driven sports analytics framework

floodlight - A high-level, data-driven sports analytics framework - Published in JOSS (2022)

https://github.com/floodlight-sports/floodlight

Science Score: 93.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 7 DOI reference(s) in README and JOSS metadata
✓
Academic publication links
Links to: arxiv.org, joss.theoj.org
○
Committers with academic emails
○
Institutional organization owner
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

python sports-analytics sports-stats

Scientific Fields

Mathematics Computer Science - 84% confidence

Last synced: 6 months ago · JSON representation

Repository

Python package for streamlined analysis of sports data.

Basic Info

Host: GitHub
Owner: floodlight-sports
License: mit
Language: Python
Default Branch: main
Homepage: https://floodlight.readthedocs.io/en/latest/index.html
Size: 4.33 MB

Statistics

Stars: 92
Watchers: 5
Forks: 17
Open Issues: 20
Releases: 4

Topics

python sports-analytics sports-stats

Created over 4 years ago · Last pushed 7 months ago

Metadata Files

Readme Changelog Contributing License

floodlight

A high-level, data-driven sports analytics framework

floodlight is a Python package for streamlined analysis of sports data. It is designed with a clear focus on scientific computing and built upon popular libraries such as numpy or pandas.

Load, process, and model tracking and event data, codes and other match-related information from over ten major data providers or public datasets. This package provides a range of popular analyses and methods such as space control models, metabolic power, approximate entropy out of the box. Under the hood, the package comes with a set of standardized data objects to structure and handle sports data, together with a suite of common processing operations such as transforms or data manipulation methods.

All implementations run completely provider- and sports-independent, while maintaining a maximum of flexibility to incorporate as many data flavours as possible. A high-level interface allows easy access to all standard routines, so that you can stop worrying about data wrangling and start focussing on the analysis instead!

Quick Demo
Features
Installation
Documentation
How to contribute

Quick Demo

floodlight simplifies sports data loading, processing and advanced performance analyses. Check out the example below, where querying a public data sample, filtering the data and computing the expended metabolic work of the active home team players is done in a few lines of code:

```

from floodlight.io.datasets import EIGDDataset from floodlight.transforms.filter import butterworth_lowpass from floodlight.models.kinetics import MetabolicPowerModel

dataset = EIGDDataset() hometeamdata, awayteamdata, ball_data = dataset.get()

hometeamdata = butterworthlowpass(hometeam_data)

model = MetabolicPowerModel() model.fit(hometeamdata) metabolicpower = model.cumulativemetabolic_power()

print(metabolic_power[-1, 0:7])

[1669.18781115 1536.22481121 1461.03243489 1488.61249785 773.09264071 1645.01702421 746.94057676] ```

To find out more, see the full set of features below or get started quickly with one of our many tutorials from the official documentation!

Features

We provide core data structures for team sports data, parsing functionality for major data providers, access points to public data sets, data filtering, plotting routines and many computational models from the literature. The feature set is constantly expanding, and if you want to add more just open an issue!

Data-level Objects

Tracking data
Event data
Pitch information
Teamsheets with player information
Codes such as ball possession information
Properties such as distances or advanced computations

Parser

Tracab/ChyronHego: Tracking data, Teamsheets, Codes
DFL/STS: Tracking data, Event data, Teamsheets, Codes
Kinexon: Tracking data
Opta: Event data (F24 feeds)
Second Spectrum: Tracking data, Event data
Skillcorner: Tracking data from the Skillcorner Open Dataset (new)
Sportradar: Event data
StatsPerform: Tracking data, Event data (with URL access)
StatsBomb: Event data

Datasets

EIGD-H (Handball tracking data)
IDSSE (Football tracking and event data) (new)
StatsBomb OpenData (Football event data)

Manipulation and Plotting

Spatial transformations for all data structures
Lowpass-filter tracking data
Slicing, selection and sequencing methods
Plot pitches, player positions and model overlays

Models and Metrics

Approximate Entropy
Centroids
Distances, Velocities & Accelerations
Metabolic Power & Equivalent Distances
Voronoi Space Control

Installation

The package can be installed easily via pip:

pip install floodlight

Citing

If you've used floodlight in your scientific work, please cite the corresponding paper.

@article{Raabe2022, doi = {10.21105/joss.04588}, url = {https://doi.org/10.21105/joss.04588}, year = {2022}, publisher = {The Open Journal}, volume = {7}, number = {76}, pages = {4588}, author = {Dominik Raabe and Henrik Biermann and Manuel Bassek and Martin Wohlan and Rumena Komitova and Robert Rein and Tobias Kuppens Groot and Daniel Memmert}, title = {floodlight - A high-level, data-driven sports analytics framework}, journal = {Journal of Open Source Software} }

Documentation

You can find all documentation here.

Contributing

Check out Contributing.md for a quick rundown of what you need to know to get started. We also provide an extended, beginner-friendly guide on how to start contributing in our documentation.

Why

Why do we need another package that introduces its own data structures and ways of dealing with certain problems? And what's the purpose of trying to integrate all different data sources and fit them into a single framework? Especially since there already exist packages that aim to solve certain parts of that pipeline?

Our answer is - although we love those packages out there - that we did not find a solution that did fit our needs. Available packages are either tightly connected to a certain data format/provider, adapt to the subtleties of a particular sport, or solve one particular problem. This still left us with the essential problem of adapting to different interfaces.

We felt that as long as there is no underlying, high-level framework, each and every use case again and again needs its own implementation. At last, we found ourselves refactoring the same code - and there are certain data processing or plotting routines that are required in almost every project - over and over again just to fit the particular data structures we're dealing with at that time.

Acknowledgements

This project has received funding by the BMBF (Bundesministerium für Bildung und Forschung, 01IS20021A) and the DFG (Deutsche Forschungsgemeinschaft, ME 2678/43-1) and has been kindly supported by the Institute of Exercise Training and Sport Informatics at the German Sport University Cologne.

Owner

Name: floodlight-sports
Login: floodlight-sports
Kind: organization

Repositories: 1
Profile: https://github.com/floodlight-sports

JOSS Publication

floodlight - A high-level, data-driven sports analytics framework

Published

August 26, 2022

DOI

10.21105/joss.04588

Volume 7, Issue 76, Page 4588