<div align="center">
<img src="https://github.com/Alek050/databallpy/assets/49450063/56100e87-c680-4dc1-82e5-4aa8fdbc8a34" alt="Logo">
</div>
[version-image]: https://img.shields.io/pypi/v/databallpy?color=006666
[version-url]: https://pypi.org/project/databallpy/
[python-image]: https://img.shields.io/pypi/pyversions/databallpy?color=006666
[python-url]: https://pypi.org/project/databallpy/
[docs-image]: https://readthedocs.org/projects/databallpy/badge/?version=latest
[docs-url]: https://databallpy.readthedocs.io/en/latest/?badge=latest
[cicd-image]: https://github.com/Alek050/databallpy/actions/workflows/cicd_main.yml/badge.svg
[cicd-url]: https://github.com/Alek050/databallpy/actions/workflows/cicd_main.yml
[codecov-image]: https://codecov.io/gh/Alek050/databallpy/branch/develop/graph/badge.svg?token=MBI3380I0H
[codecov-url]: https://codecov.io/gh/Alek050/databallpy
[floodlight-url]:https://github.com/floodlight-sports/floodlight
[kloppy-url]:https://github.com/PySport/kloppy
[soccer-sync-url]: https://kwiatkowski.io/sync.soccer
[example-url]: https://databallpy.readthedocs.io/en/latest/example.html
[![Latest Version][version-image]][version-url]
[![Python Version][python-image]][python-url]
[![Documentation Status][docs-image]][docs-url]
[![CI/CD Status][cicd-image]][cicd-url]
[![Codecov][codecov-image]][codecov-url]
# DataBallPy
A package for loading, synchronizing, and analyzing your soccer event- and tracking data.
This package is developed to create a standardized way to analyse soccer matches using both event- and tracking data. Other packages, like [kloppy][kloppy-url] and [floodlight][floodlight-url], already standardize the import of data sources. The current package goes a step further in combining different data streams from the same match. In this case, the `Match` object combines information from the event and tracking data. The main feature is the smart synchronization of the tracking and event data. We utilize the Needleman-Wunch algorithm, inspired by [this article][soccer-sync-url], to align the tracking and even data, while ensuring the order of the events, something that is not done when only using (different) cost functions.
## V0.4.3 (15/1/2024)
- Added simple expected goals (xG) model
- Added anonimisation function
- Added pitch control model by Javier Fernandez (Wide Open Spaces paper)
- Fixed minor bugs
- Added logging possibilities
- Refactor of file structure and folder naming
## Planned changes
- Adding different filters to filter the tracking data
- Adding more features (if you have any ideas/requests, please open an issue!)
- Creating more databallpy events
- Adding expected passing and goals models
## Installation
```bash
$ pip install databallpy
```
## Usage
The package is centered around the `Match` object. A `Match` has tracking data, event data metadata about the match.
For a more elaborate example, see the [example file][example-url].
```console
$ from databallpy import get_match, get_open_match
$
$ match = get_match(
$ tracking_data_loc="../data/tracking_data.dat",
$ tracking_metadata_loc="../data/tracking_metadata.xml",
$ tracking_data_provider="tracab"
$ event_data_loc="../data/event_data_f24.xml",
$ event_metadata_loc="../data/event_metadata_f7.xml",
$ event_data_provider="opta",
$ )
$
$ # or to load an open metrica dataset of tracking and event data
$ match = get_open_match()
$
$ match.home_team_name # the team name of the home playing team
$ match.away_players # pandas dataframe with the names, ids, shirt numbers and positions of the away team
$ match.tracking_data # pandas dataframe with tracking data of the match
$ match.event_data # pandas dataframe with event data of the match
```
See [the documentation][docs-url] of the `Match` object and the [example usage][example-url] for more options. Note that this package is developed to combine event and tracking data, for now both datastreams are necessary to create a `Match` object.
## Synchronization of tracking and event data
Tracking and event data is often poorly synchronized. For instance, when taking the event data of Opta and tracking data of Tracab, you can sync the fist frame with the kick-off pass. Now you can sync the other events with the tracking data based on the time difference between the event and the kick off pass. If you do this, how get something like this:
<video width="640" height="480" controls>
<source src="https://raw.githubusercontent.com/Alek050/databallpy/main/docs/example_data/not_synced.mp4" type="video/mp4">
Your browser does not support the video tag.
</video>
https://user-images.githubusercontent.com/49450063/224564808-fa71735f-5510-464d-8499-9044227a02e8.mp4
As you can see, the timing (and placing) of the events do not correspond good with the tracking data locations, especially when events follow up quickly or around shots. Using the methodology of [this][soccer-synch-url] article, this package is able to synchronize tracking and event data using the Needleman-Wunsch algorithm.
After running the following command, the events are better synchronized to the tracking data:
```batch
$ match.synchronise_tracking_and_event_data()
```
<video width="640" height="480" controls>
<source src="https://raw.githubusercontent.com/Alek050/databallpy/main/docs/example_data/synced.mp4" type="video/mp4">
Your browser does not support the video tag.
</video>
https://user-images.githubusercontent.com/49450063/224564913-4091faf7-f6ef-4429-b132-7f93ce5e1d91.mp4
## Documentation
The official documentation can be found [here][docs-url].
## Providers
For now we limited providers. We are planning on adding more providers later on.
Event data providers:
- Opta
- Metrica
- Instat
Tracking data providers:
- Tracab
- Metrica
- Inmotio
## Contributing
Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
## Maintainers & owners
- [Alek050](https://github.com/Alek050/)
- [DaanGro](https://github.com/DaanGro/)
## Contributors
- [rdghe](https://github.com/rdghe/)
- [swopper050](https://github.com/Swopper050)
## License
`databallpy` was created by Alexander Oonk & Daan Grob. It is licensed under the terms of the MIT license.
## Similar projects
Although we think this package helps when starting to analyse soccer data, other packages may be better suited for your specific needs. Make sure to check out the following packages as well:
- [kloppy][kloppy-url]
- [floodlight][floodlight-url]
- [codeball](https://github.com/metrica-sports/codeball)
- [socceraction](https://github.com/ML-KULeuven/socceraction)
And for a more specific toturials on how to get started with soccer data"
- [Friends of Tracking](https://github.com/Friends-of-Tracking-Data-FoTD)
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/databallpy/",
"name": "databallpy",
"maintainer": "Alexander Oonk",
"docs_url": null,
"requires_python": ">=3.9,<3.13",
"maintainer_email": "alexanderoonk26@gmail.com",
"keywords": "soccer,football,tracking data,event data",
"author": "Alexander Oonk",
"author_email": "alexanderoonk26@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5b/95/b1b7c47d6b7b75adba6921fe6d3cd31818aabbfb6adeb0b038f4ab7b0ba4/databallpy-0.4.3.tar.gz",
"platform": null,
"description": "\n<div align=\"center\">\n <img src=\"https://github.com/Alek050/databallpy/assets/49450063/56100e87-c680-4dc1-82e5-4aa8fdbc8a34\" alt=\"Logo\">\n</div>\n\n[version-image]: https://img.shields.io/pypi/v/databallpy?color=006666\n[version-url]: https://pypi.org/project/databallpy/\n[python-image]: https://img.shields.io/pypi/pyversions/databallpy?color=006666\n[python-url]: https://pypi.org/project/databallpy/\n[docs-image]: https://readthedocs.org/projects/databallpy/badge/?version=latest\n[docs-url]: https://databallpy.readthedocs.io/en/latest/?badge=latest\n[cicd-image]: https://github.com/Alek050/databallpy/actions/workflows/cicd_main.yml/badge.svg\n[cicd-url]: https://github.com/Alek050/databallpy/actions/workflows/cicd_main.yml\n[codecov-image]: https://codecov.io/gh/Alek050/databallpy/branch/develop/graph/badge.svg?token=MBI3380I0H\n[codecov-url]: https://codecov.io/gh/Alek050/databallpy\n\n[floodlight-url]:https://github.com/floodlight-sports/floodlight\n[kloppy-url]:https://github.com/PySport/kloppy\n[soccer-sync-url]: https://kwiatkowski.io/sync.soccer\n[example-url]: https://databallpy.readthedocs.io/en/latest/example.html\n\n[![Latest Version][version-image]][version-url]\n[![Python Version][python-image]][python-url]\n[![Documentation Status][docs-image]][docs-url]\n[![CI/CD Status][cicd-image]][cicd-url]\n[![Codecov][codecov-image]][codecov-url]\n\n# DataBallPy\n\n\nA package for loading, synchronizing, and analyzing your soccer event- and tracking data.\n\nThis package is developed to create a standardized way to analyse soccer matches using both event- and tracking data. Other packages, like [kloppy][kloppy-url] and [floodlight][floodlight-url], already standardize the import of data sources. The current package goes a step further in combining different data streams from the same match. In this case, the `Match` object combines information from the event and tracking data. The main feature is the smart synchronization of the tracking and event data. We utilize the Needleman-Wunch algorithm, inspired by [this article][soccer-sync-url], to align the tracking and even data, while ensuring the order of the events, something that is not done when only using (different) cost functions.\n\n## V0.4.3 (15/1/2024)\n\n- Added simple expected goals (xG) model\n- Added anonimisation function\n- Added pitch control model by Javier Fernandez (Wide Open Spaces paper)\n- Fixed minor bugs\n- Added logging possibilities\n- Refactor of file structure and folder naming\n\n## Planned changes\n\n- Adding different filters to filter the tracking data\n- Adding more features (if you have any ideas/requests, please open an issue!)\n- Creating more databallpy events\n- Adding expected passing and goals models\n\n## Installation\n\n```bash\n$ pip install databallpy\n```\n\n## Usage\n\nThe package is centered around the `Match` object. A `Match` has tracking data, event data metadata about the match.\nFor a more elaborate example, see the [example file][example-url].\n\n```console\n$ from databallpy import get_match, get_open_match\n$\n$ match = get_match(\n$ tracking_data_loc=\"../data/tracking_data.dat\",\n$ tracking_metadata_loc=\"../data/tracking_metadata.xml\",\n$ tracking_data_provider=\"tracab\"\n$ event_data_loc=\"../data/event_data_f24.xml\",\n$ event_metadata_loc=\"../data/event_metadata_f7.xml\",\n$ event_data_provider=\"opta\",\n$ )\n$\n$ # or to load an open metrica dataset of tracking and event data\n$ match = get_open_match()\n$\n$ match.home_team_name # the team name of the home playing team\n$ match.away_players # pandas dataframe with the names, ids, shirt numbers and positions of the away team\n$ match.tracking_data # pandas dataframe with tracking data of the match\n$ match.event_data # pandas dataframe with event data of the match\n```\n\nSee [the documentation][docs-url] of the `Match` object and the [example usage][example-url] for more options. Note that this package is developed to combine event and tracking data, for now both datastreams are necessary to create a `Match` object.\n\n## Synchronization of tracking and event data\n\nTracking and event data is often poorly synchronized. For instance, when taking the event data of Opta and tracking data of Tracab, you can sync the fist frame with the kick-off pass. Now you can sync the other events with the tracking data based on the time difference between the event and the kick off pass. If you do this, how get something like this:\n\n<video width=\"640\" height=\"480\" controls>\n <source src=\"https://raw.githubusercontent.com/Alek050/databallpy/main/docs/example_data/not_synced.mp4\" type=\"video/mp4\">\n Your browser does not support the video tag.\n</video>\n\nhttps://user-images.githubusercontent.com/49450063/224564808-fa71735f-5510-464d-8499-9044227a02e8.mp4\n\n\nAs you can see, the timing (and placing) of the events do not correspond good with the tracking data locations, especially when events follow up quickly or around shots. Using the methodology of [this][soccer-synch-url] article, this package is able to synchronize tracking and event data using the Needleman-Wunsch algorithm. \n\nAfter running the following command, the events are better synchronized to the tracking data:\n\n```batch\n$ match.synchronise_tracking_and_event_data()\n```\n\n<video width=\"640\" height=\"480\" controls>\n <source src=\"https://raw.githubusercontent.com/Alek050/databallpy/main/docs/example_data/synced.mp4\" type=\"video/mp4\">\n Your browser does not support the video tag.\n</video>\n\n\nhttps://user-images.githubusercontent.com/49450063/224564913-4091faf7-f6ef-4429-b132-7f93ce5e1d91.mp4\n\n\n## Documentation\n\nThe official documentation can be found [here][docs-url].\n\n## Providers\n\nFor now we limited providers. We are planning on adding more providers later on.\n\nEvent data providers:\n- Opta\n- Metrica\n- Instat\n\nTracking data providers:\n- Tracab\n- Metrica\n- Inmotio\n\n## Contributing\n\nInterested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.\n\n## Maintainers & owners\n\n- [Alek050](https://github.com/Alek050/)\n- [DaanGro](https://github.com/DaanGro/)\n\n## Contributors\n\n- [rdghe](https://github.com/rdghe/)\n- [swopper050](https://github.com/Swopper050)\n\n## License\n\n`databallpy` was created by Alexander Oonk & Daan Grob. It is licensed under the terms of the MIT license.\n\n## Similar projects\n\nAlthough we think this package helps when starting to analyse soccer data, other packages may be better suited for your specific needs. Make sure to check out the following packages as well:\n- [kloppy][kloppy-url]\n- [floodlight][floodlight-url]\n- [codeball](https://github.com/metrica-sports/codeball)\n- [socceraction](https://github.com/ML-KULeuven/socceraction)\n\nAnd for a more specific toturials on how to get started with soccer data\"\n- [Friends of Tracking](https://github.com/Friends-of-Tracking-Data-FoTD)\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package for loading, preprocessing, vizualising and synchronizing soccere event and tracking data.",
"version": "0.4.3",
"project_urls": {
"Documentation": "https://github.com/Alek050/databallpy/tree/main/docs",
"Homepage": "https://pypi.org/project/databallpy/",
"Repository": "https://github.com/Alek050/databallpy"
},
"split_keywords": [
"soccer",
"football",
"tracking data",
"event data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dfe1e071ca9e73d15552f7f016f7178e9aa174144f9b10d8eef5f918c9cace01",
"md5": "37ce803312f370ed711839a7fba98db6",
"sha256": "fdd56653e64332fc7fa7dea3eb0e283279e71ebfc5e5407eb0b89db136db2342"
},
"downloads": -1,
"filename": "databallpy-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37ce803312f370ed711839a7fba98db6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<3.13",
"size": 118513,
"upload_time": "2024-01-15T19:33:13",
"upload_time_iso_8601": "2024-01-15T19:33:13.024190Z",
"url": "https://files.pythonhosted.org/packages/df/e1/e071ca9e73d15552f7f016f7178e9aa174144f9b10d8eef5f918c9cace01/databallpy-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5b95b1b7c47d6b7b75adba6921fe6d3cd31818aabbfb6adeb0b038f4ab7b0ba4",
"md5": "282f15449067adb9b5b70a470e20fed2",
"sha256": "ed488b755f2f1f85bb318ed09344d22cd0f9a7895940d6fe1652b2dab90c9f6c"
},
"downloads": -1,
"filename": "databallpy-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "282f15449067adb9b5b70a470e20fed2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<3.13",
"size": 94933,
"upload_time": "2024-01-15T19:33:14",
"upload_time_iso_8601": "2024-01-15T19:33:14.659716Z",
"url": "https://files.pythonhosted.org/packages/5b/95/b1b7c47d6b7b75adba6921fe6d3cd31818aabbfb6adeb0b038f4ab7b0ba4/databallpy-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-15 19:33:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Alek050",
"github_project": "databallpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "databallpy"
}
JSON
