[version-image]: https://img.shields.io/pypi/v/floodlight?color=006666
[version-url]: https://pypi.org/project/floodlight/
[python-image]: https://img.shields.io/pypi/pyversions/floodlight?color=006666
[python-url]: https://pypi.org/project/floodlight/
[docs-image]: https://readthedocs.org/projects/floodlight/badge/?version=latest
[docs-url]: https://floodlight.readthedocs.io/en/latest/?badge=latest
[tutorial-url]: https://floodlight.readthedocs.io/en/latest/guides/getting_started.html
[build-image]: https://github.com/floodlight-sports/floodlight/actions/workflows/build.yaml/badge.svg
[build-url]: https://github.com/floodlight-sports/floodlight/actions/workflows/build.yaml
[lint-image]: https://github.com/floodlight-sports/floodlight/actions/workflows/linting.yaml/badge.svg
[lint-url]: https://github.com/floodlight-sports/floodlight/actions/workflows/linting.yaml
[black-image]: https://img.shields.io/badge/code%20style-black-000000.svg
[black-url]: https://github.com/psf/black
[contrib-image]: https://img.shields.io/badge/contributions-welcome-006666
[contrib-url]: https://github.com/floodlight-sports/floodlight/blob/main/CONTRIBUTING.md
[arxiv-image]: https://img.shields.io/badge/arXiv-2206.02562-b31b1b.svg
[arxiv-url]: https://arxiv.org/abs/2206.02562
[joss-image]: https://joss.theoj.org/papers/10.21105/joss.04588/status.svg
[joss-url]: https://doi.org/10.21105/joss.04588
[codecov-image]: https://codecov.io/gh/floodlight-sports/floodlight/branch/develop/graph/badge.svg?token=RLY582UBC6
[codecov-url]: https://codecov.io/gh/floodlight-sports/floodlight
# floodlight
[![Latest Version][version-image]][version-url]
[![Python Version][python-image]][python-url]
[![Documentation Status][docs-image]][docs-url]
[![Build Status][build-image]][build-url]
[![Linting Status][lint-image]][lint-url]
[![Codecov][codecov-image]][codecov-url]
[![DOI][joss-image]][joss-url]
## 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, integrate, and process tracking and event data, codes and other match-related
information from major data providers. This package provides 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](#quick-demo)
* [Features](#features)
* [Installation](#installation)
* [Documentation](#documentation)
* [How to contribute](#contributing)
----------------------------------------------------------------------------------------
### 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()
>>> home_team_data, away_team_data, ball_data = dataset.get()
>>> home_team_data = butterworth_lowpass(home_team_data)
>>> model = MetabolicPowerModel()
>>> model.fit(home_team_data)
>>> metabolic_power = model.cumulative_metabolic_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][tutorial-url] 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
```
### Documentation
You can find all documentation [here][docs-url].
### Contributing
[![Contributions][contrib-image]][contrib-url]
[![Code style: black][black-image]][black-url]
Check out [Contributing.md][contrib-url] 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.
### Citing
If you've used *floodlight* in your scientific work, please cite the [corresponding paper][joss-url].
```
@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}
}
```
### 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.
### About
This project has been kindly supported by the [Institute of Exercise Training and Sport
Informatics](https://www.dshs-koeln.de/en/institut-fuer-trainingswissenschaft-und-sportinformatik/) at the German Sport
University Cologne under supervision of Prof. Daniel Memmert.
### Related Projects
- [matplotsoccer](https://github.com/TomDecroos/matplotsoccer)
- [kloppy](https://github.com/PySport/kloppy)
- [codeball](https://github.com/metrica-sports/codeball)
Raw data
{
"_id": null,
"home_page": "https://github.com/floodlight-sports/floodlight",
"name": "floodlight",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": "sports analytics, sports data analysis, tracking data",
"author": "draabe",
"author_email": "draabx@posteo.org",
"download_url": "https://files.pythonhosted.org/packages/d4/75/3ea90bde94ea8b75d24ab6194b4bbf2469b92f980a38b9d8482327cf3178/floodlight-0.5.0.tar.gz",
"platform": null,
"description": "[version-image]: https://img.shields.io/pypi/v/floodlight?color=006666\n[version-url]: https://pypi.org/project/floodlight/\n[python-image]: https://img.shields.io/pypi/pyversions/floodlight?color=006666\n[python-url]: https://pypi.org/project/floodlight/\n[docs-image]: https://readthedocs.org/projects/floodlight/badge/?version=latest\n[docs-url]: https://floodlight.readthedocs.io/en/latest/?badge=latest\n[tutorial-url]: https://floodlight.readthedocs.io/en/latest/guides/getting_started.html\n[build-image]: https://github.com/floodlight-sports/floodlight/actions/workflows/build.yaml/badge.svg\n[build-url]: https://github.com/floodlight-sports/floodlight/actions/workflows/build.yaml\n[lint-image]: https://github.com/floodlight-sports/floodlight/actions/workflows/linting.yaml/badge.svg\n[lint-url]: https://github.com/floodlight-sports/floodlight/actions/workflows/linting.yaml\n[black-image]: https://img.shields.io/badge/code%20style-black-000000.svg\n[black-url]: https://github.com/psf/black\n[contrib-image]: https://img.shields.io/badge/contributions-welcome-006666\n[contrib-url]: https://github.com/floodlight-sports/floodlight/blob/main/CONTRIBUTING.md\n[arxiv-image]: https://img.shields.io/badge/arXiv-2206.02562-b31b1b.svg\n[arxiv-url]: https://arxiv.org/abs/2206.02562\n[joss-image]: https://joss.theoj.org/papers/10.21105/joss.04588/status.svg\n[joss-url]: https://doi.org/10.21105/joss.04588\n[codecov-image]: https://codecov.io/gh/floodlight-sports/floodlight/branch/develop/graph/badge.svg?token=RLY582UBC6\n[codecov-url]: https://codecov.io/gh/floodlight-sports/floodlight\n\n\n# floodlight\n\n[![Latest Version][version-image]][version-url]\n[![Python Version][python-image]][python-url]\n[![Documentation Status][docs-image]][docs-url]\n[![Build Status][build-image]][build-url]\n[![Linting Status][lint-image]][lint-url]\n[![Codecov][codecov-image]][codecov-url]\n[![DOI][joss-image]][joss-url]\n\n## A high-level, data-driven sports analytics framework\n\n**floodlight** is a Python package for streamlined analysis of sports data. It is\ndesigned with a clear focus on scientific computing and built upon popular libraries\nsuch as *numpy* or *pandas*.\n\nLoad, integrate, and process tracking and event data, codes and other match-related\ninformation from major data providers. This package provides a set of standardized\ndata objects to structure and handle sports data, together with a suite of common\nprocessing operations such as transforms or data manipulation methods.\n\nAll implementations run completely provider- and sports-independent, while maintaining\na maximum of flexibility to incorporate as many data flavours as possible. A high-level\ninterface allows easy access to all standard routines, so that you can stop worrying\nabout data wrangling and start focussing on the analysis instead!\n\n----------------------------------------------------------------------------------------\n\n* [Quick Demo](#quick-demo)\n* [Features](#features)\n* [Installation](#installation)\n* [Documentation](#documentation)\n* [How to contribute](#contributing)\n\n----------------------------------------------------------------------------------------\n\n### Quick Demo\n\n**floodlight** simplifies sports data loading, processing and advanced performance\nanalyses. Check out the example below, where querying a public data sample, filtering\nthe data and computing the expended metabolic work of the active home team players is\ndone in a few lines of code:\n\n```\n>>> from floodlight.io.datasets import EIGDDataset\n>>> from floodlight.transforms.filter import butterworth_lowpass\n>>> from floodlight.models.kinetics import MetabolicPowerModel\n\n>>> dataset = EIGDDataset()\n>>> home_team_data, away_team_data, ball_data = dataset.get()\n\n>>> home_team_data = butterworth_lowpass(home_team_data)\n\n>>> model = MetabolicPowerModel()\n>>> model.fit(home_team_data)\n>>> metabolic_power = model.cumulative_metabolic_power()\n\n>>> print(metabolic_power[-1, 0:7])\n\n[1669.18781115 1536.22481121 1461.03243489 1488.61249785 773.09264071\n 1645.01702421 746.94057676]\n```\n\nTo find out more, see the full set of features below or get started quickly with\n[one of our many tutorials][tutorial-url] from the official documentation!\n\n\n### Features\n\nWe provide core data structures for team sports data, parsing functionality for major\ndata providers, access points to public data sets, data filtering, plotting routines and\nmany computational models from the literature. The feature set is constantly expanding,\nand if you want to add more just open an issue!\n\n#### Data-level Objects\n\n- Tracking data\n- Event data\n- Pitch information\n- Teamsheets with player information\n- Codes such as ball possession information\n- Properties such as distances or advanced computations\n\n#### Parser\n\n- **Tracab/ChyronHego**: Tracking data, Teamsheets, Codes\n- **DFL/STS**: Tracking data, Event data, Teamsheets, Codes\n- **Kinexon**: Tracking data\n- **Opta**: Event data (F24 feeds)\n- **Second Spectrum**: Tracking data, Event data\n- **Skillcorner**: Tracking data from the Skillcorner Open Dataset (*new*)\n- **Sportradar**: Event data\n- **StatsPerform**: Tracking data, Event data (with URL access)\n- **StatsBomb**: Event data\n\n#### Datasets\n\n- EIGD-H (Handball tracking data)\n- IDSSE (Football tracking and event data) (*new*)\n- StatsBomb OpenData (Football event data)\n\n#### Manipulation and Plotting\n\n- Spatial transformations for all data structures\n- Lowpass-filter tracking data\n- Slicing, selection and sequencing methods\n- Plot pitches, player positions and model overlays\n\n#### Models and Metrics\n\n- Approximate Entropy\n- Centroids\n- Distances, Velocities & Accelerations\n- Metabolic Power & Equivalent Distances\n- Voronoi Space Control\n\n### Installation\n\nThe package can be installed easily via pip:\n\n```\npip install floodlight\n```\n\n\n### Documentation\n\nYou can find all documentation [here][docs-url].\n\n\n\n### Contributing\n\n[![Contributions][contrib-image]][contrib-url]\n[![Code style: black][black-image]][black-url]\n\n\nCheck out [Contributing.md][contrib-url] for a quick rundown of what you need to\nknow to get started. We also provide an extended, beginner-friendly guide on how to\nstart contributing in our documentation.\n\n\n\n### Citing\n\nIf you've used *floodlight* in your scientific work, please cite the [corresponding paper][joss-url].\n\n```\n@article{Raabe2022,\n doi = {10.21105/joss.04588},\n url = {https://doi.org/10.21105/joss.04588},\n year = {2022},\n publisher = {The Open Journal},\n volume = {7},\n number = {76},\n pages = {4588},\n author = {Dominik Raabe and Henrik Biermann and Manuel Bassek and Martin Wohlan and Rumena Komitova\n and Robert Rein and Tobias Kuppens Groot and Daniel Memmert},\n title = {floodlight - A high-level, data-driven sports analytics framework},\n journal = {Journal of Open Source Software}\n}\n```\n\n\n\n### Why\n\nWhy do we need another package that introduces its own data structures and ways of dealing with certain problems?\nAnd what's the purpose of trying to integrate all different data sources and fit them into a single framework?\nEspecially since there already exist packages that aim to solve certain parts of that pipeline?\n\nOur answer is - although we love those packages out there - that we did not find a solution that did fit our needs.\nAvailable packages are either tightly connected to a certain data format/provider, adapt to the subtleties of a\nparticular sport, or solve *one* particular problem. This still left us with the essential problem of adapting to\ndifferent interfaces.\n\nWe felt that as long as there is no underlying, high-level framework, each and every use case again and again needs its\nown implementation. At last, we found ourselves refactoring the same code - and there are certain data processing or\nplotting routines that are required in *almost every* project - over and over again just to fit the particular data\nstructures we're dealing with at that time.\n\n\n### About\n\nThis project has been kindly supported by the [Institute of Exercise Training and Sport\nInformatics](https://www.dshs-koeln.de/en/institut-fuer-trainingswissenschaft-und-sportinformatik/) at the German Sport\nUniversity Cologne under supervision of Prof. Daniel Memmert.\n\n\n\n### Related Projects\n\n- [matplotsoccer](https://github.com/TomDecroos/matplotsoccer)\n- [kloppy](https://github.com/PySport/kloppy)\n- [codeball](https://github.com/metrica-sports/codeball)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A high-level framework for sports data analysis",
"version": "0.5.0",
"project_urls": {
"Documentation": "https://floodlight.readthedocs.io/en/latest/",
"Homepage": "https://github.com/floodlight-sports/floodlight",
"Repository": "https://github.com/floodlight-sports/floodlight"
},
"split_keywords": [
"sports analytics",
" sports data analysis",
" tracking data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c6a3a288be144ddf65f9a591a16deeea7d0d8c0836e30a3749f0f0a065eb87af",
"md5": "9f01535c2fb031fa0a2c309914612d2e",
"sha256": "ad0e30013f5a336d94996cfa2006c8ff376d77db573a8b37a4cea4f5b90464f0"
},
"downloads": -1,
"filename": "floodlight-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f01535c2fb031fa0a2c309914612d2e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 112579,
"upload_time": "2024-09-10T18:32:01",
"upload_time_iso_8601": "2024-09-10T18:32:01.879567Z",
"url": "https://files.pythonhosted.org/packages/c6/a3/a288be144ddf65f9a591a16deeea7d0d8c0836e30a3749f0f0a065eb87af/floodlight-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d4753ea90bde94ea8b75d24ab6194b4bbf2469b92f980a38b9d8482327cf3178",
"md5": "f79e9cb4ac1d60758bbe5312f3166d6e",
"sha256": "5f5f85cd93baa84cc7b0da0e6ff7360e9dc7ef85c82318b464fbf07779f5e716"
},
"downloads": -1,
"filename": "floodlight-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "f79e9cb4ac1d60758bbe5312f3166d6e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 92075,
"upload_time": "2024-09-10T18:32:03",
"upload_time_iso_8601": "2024-09-10T18:32:03.810862Z",
"url": "https://files.pythonhosted.org/packages/d4/75/3ea90bde94ea8b75d24ab6194b4bbf2469b92f980a38b9d8482327cf3178/floodlight-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-10 18:32:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "floodlight-sports",
"github_project": "floodlight",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "floodlight"
}
JSON
