<div align="center">
<img src="https://socceraction.readthedocs.io/en/latest/_static/logo_white.png" height="200">
<p>
<b>Convert soccer event stream data to the SPADL format<br/>and value on-the-ball player actions</b>
</p>
<br/>
[](https://pypi.org/project/socceraction)
[](https://pypi.org/project/socceraction)
[](https://pypistats.org/packages/socceraction)
[](https://en.wikipedia.org/wiki/MIT_License)
[](https://github.com/ML-KULeuven/socceraction/actions?workflow=CI)
[](https://socceraction.readthedocs.io)
[](https://codecov.io/gh/ML-KULeuven/socceraction)
<br/>
<br/>
</div>
Socceraction is a Python package for objectively quantifying the impact of the individual actions performed by soccer players using event stream data. The general idea is to assign a value to each on-the-ball action based on the action's impact on the game outcome, while accounting for the context in which the action happened. The video below gives a quick two-minute introduction to action values.
<div align="center">
https://user-images.githubusercontent.com/2175271/136857714-1d2c8706-7f2f-449d-818f-0e67fbb75400.mp4
</div>
## Features
Socceraction contains the following components:
- A set of API clients for **loading event stream data** from StatsBomb, Opta, Wyscout, Stats Perform and WhoScored as Pandas DataFrames using a unified data model. [Read more »](https://socceraction.readthedocs.io/en/latest/documentation/data/index.html)
- Converters for each of these provider's proprietary data format to the **SPADL** and **atomic-SPADL** formats, which are unified and expressive languages for on-the-ball player actions. [Read more »](https://socceraction.readthedocs.io/en/latest/documentation/spadl/index.html)
- An implementation of the **Expected Threat (xT)** possession value framework. [Read more »](https://socceraction.readthedocs.io/en/latest/documentation/valuing_actions/xT.html)
- An implementation of the **VAEP** and **Atomic-VAEP** possession value frameworks. [Read more »](https://socceraction.readthedocs.io/en/latest/documentation/valuing_actions/vaep.html)
## Installation / Getting started
The recommended way to install `socceraction` is to simply use pip. The latest version officially supports Python 3.9 - 3.11.
```sh
$ pip install socceraction
```
The folder [`public-notebooks`](https://github.com/ML-KULeuven/socceraction/tree/master/public-notebooks) provides a demo of the full pipeline from raw StatsBomb event stream data to action values and player ratings. More detailed installation/usage instructions can be found in the [Documentation](https://socceraction.readthedocs.io/en/latest/).
## Contributing
All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. However, be aware that socceraction is not actively developed. It's primary use is to enable reproducibility of our research. If you believe there is a feature missing, feel free to raise a feature request, but please do be aware that the overwhelming likelihood is that your feature request will not be accepted.
To learn more on how to contribute, see the [Contributor Guide](https://socceraction.readthedocs.io/en/latest/development/developer_guide.html).
## Research
If you make use of this package in your research, please consider citing the following papers:
- Tom Decroos, Lotte Bransen, Jan Van Haaren, and Jesse Davis. **Actions speak louder than goals: Valuing player actions in soccer.** In Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining, pp. 1851-1861. 2019. <br/>[ [pdf](http://doi.acm.org/10.1145/3292500.3330758) | [bibtex](https://github.com/ML-KULeuven/socceraction/blob/master/docs/_static/decroos19.bibtex) ]
- Maaike Van Roy, Pieter Robberechts, Tom Decroos, and Jesse Davis. **Valuing on-the-ball actions in soccer: a critical comparison of XT and VAEP.** In Proceedings of the AAAI-20 Workshop on Artifical Intelligence in Team Sports. AI in Team Sports Organising Committee, 2020. <br/>[ [pdf](https://limo.libis.be/primo-explore/fulldisplay?docid=LIRIAS2913207&context=L&vid=KULeuven&search_scope=ALL_CONTENT&tab=all_content_tab&lang=en_US) | [bibtex](https://github.com/ML-KULeuven/socceraction/blob/master/docs/_static/vanroy20.bibtex) ]
The Expected Threat (xT) framework was originally introduced by Karun Singh on his [blog](https://karun.in/blog/expected-threat.html) in 2019.
## License
Distributed under the terms of the [MIT license](https://opensource.org/licenses/MIT),
socceraction is free and open source software. Although not strictly required, we appreciate it if you include a link to this repo or cite our research in your work if you make use of socceraction.
Raw data
{
"_id": null,
"home_page": "https://github.com/ML-KULeuven/socceraction",
"name": "socceraction",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<3.12",
"maintainer_email": "",
"keywords": "soccer,football,sports analytics",
"author": "Tom Decroos",
"author_email": "tom.decroos.be@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c0/10/d80efb6494a0bd195977adfff3cf2a190e3a6f1799be2c8230b71d6d48f8/socceraction-1.5.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\t<img src=\"https://socceraction.readthedocs.io/en/latest/_static/logo_white.png\" height=\"200\">\n\t<p>\n\t<b>Convert soccer event stream data to the SPADL format<br/>and value on-the-ball player actions</b>\n\t</p>\n\t<br/>\n\n[](https://pypi.org/project/socceraction)\n[](https://pypi.org/project/socceraction)\n[](https://pypistats.org/packages/socceraction)\n[](https://en.wikipedia.org/wiki/MIT_License)\n\n[](https://github.com/ML-KULeuven/socceraction/actions?workflow=CI)\n[](https://socceraction.readthedocs.io)\n[](https://codecov.io/gh/ML-KULeuven/socceraction)\n\n<br/>\n<br/>\n</div>\n\nSocceraction is a Python package for objectively quantifying the impact of the individual actions performed by soccer players using event stream data. The general idea is to assign a value to each on-the-ball action based on the action's impact on the game outcome, while accounting for the context in which the action happened. The video below gives a quick two-minute introduction to action values.\n\n<div align=\"center\">\n\nhttps://user-images.githubusercontent.com/2175271/136857714-1d2c8706-7f2f-449d-818f-0e67fbb75400.mp4\n\n</div>\n\n## Features\n\nSocceraction contains the following components:\n\n- A set of API clients for **loading event stream data** from StatsBomb, Opta, Wyscout, Stats Perform and WhoScored as Pandas DataFrames using a unified data model. [Read more \u00bb](https://socceraction.readthedocs.io/en/latest/documentation/data/index.html)\n- Converters for each of these provider's proprietary data format to the **SPADL** and **atomic-SPADL** formats, which are unified and expressive languages for on-the-ball player actions. [Read more \u00bb](https://socceraction.readthedocs.io/en/latest/documentation/spadl/index.html)\n- An implementation of the **Expected Threat (xT)** possession value framework. [Read more \u00bb](https://socceraction.readthedocs.io/en/latest/documentation/valuing_actions/xT.html)\n- An implementation of the **VAEP** and **Atomic-VAEP** possession value frameworks. [Read more \u00bb](https://socceraction.readthedocs.io/en/latest/documentation/valuing_actions/vaep.html)\n\n## Installation / Getting started\n\nThe recommended way to install `socceraction` is to simply use pip. The latest version officially supports Python 3.9 - 3.11.\n\n```sh\n$ pip install socceraction\n```\n\nThe folder [`public-notebooks`](https://github.com/ML-KULeuven/socceraction/tree/master/public-notebooks) provides a demo of the full pipeline from raw StatsBomb event stream data to action values and player ratings. More detailed installation/usage instructions can be found in the [Documentation](https://socceraction.readthedocs.io/en/latest/).\n\n## Contributing\n\nAll contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. However, be aware that socceraction is not actively developed. It's primary use is to enable reproducibility of our research. If you believe there is a feature missing, feel free to raise a feature request, but please do be aware that the overwhelming likelihood is that your feature request will not be accepted.\nTo learn more on how to contribute, see the [Contributor Guide](https://socceraction.readthedocs.io/en/latest/development/developer_guide.html).\n\n## Research\n\nIf you make use of this package in your research, please consider citing the following papers:\n\n- Tom Decroos, Lotte Bransen, Jan Van Haaren, and Jesse Davis. **Actions speak louder than goals: Valuing player actions in soccer.** In Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining, pp. 1851-1861. 2019. <br/>[ [pdf](http://doi.acm.org/10.1145/3292500.3330758) | [bibtex](https://github.com/ML-KULeuven/socceraction/blob/master/docs/_static/decroos19.bibtex) ]\n\n- Maaike Van Roy, Pieter Robberechts, Tom Decroos, and Jesse Davis. **Valuing on-the-ball actions in soccer: a critical comparison of XT and VAEP.** In Proceedings of the AAAI-20 Workshop on Artifical Intelligence in Team Sports. AI in Team Sports Organising Committee, 2020. <br/>[ [pdf](https://limo.libis.be/primo-explore/fulldisplay?docid=LIRIAS2913207&context=L&vid=KULeuven&search_scope=ALL_CONTENT&tab=all_content_tab&lang=en_US) | [bibtex](https://github.com/ML-KULeuven/socceraction/blob/master/docs/_static/vanroy20.bibtex) ]\n\nThe Expected Threat (xT) framework was originally introduced by Karun Singh on his [blog](https://karun.in/blog/expected-threat.html) in 2019.\n\n## License\n\nDistributed under the terms of the [MIT license](https://opensource.org/licenses/MIT),\nsocceraction is free and open source software. Although not strictly required, we appreciate it if you include a link to this repo or cite our research in your work if you make use of socceraction.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert soccer event stream data to the SPADL format and value on-the-ball player actions",
"version": "1.5.1",
"project_urls": {
"Documentation": "https://socceraction.readthedocs.io",
"Homepage": "https://github.com/ML-KULeuven/socceraction",
"Repository": "https://github.com/ML-KULeuven/socceraction"
},
"split_keywords": [
"soccer",
"football",
"sports analytics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8aa01207a1549c8f6261b98dfd262297c7159d37b263dae471d9925b90baf1c1",
"md5": "4f3dfaa3e07b9c7b42d85942a669b433",
"sha256": "be2dc5d72cdc563df6c947fc139e90b37aca3cde868c69cb8c84fe24952e6dfa"
},
"downloads": -1,
"filename": "socceraction-1.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4f3dfaa3e07b9c7b42d85942a669b433",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<3.12",
"size": 92863,
"upload_time": "2024-03-07T17:27:09",
"upload_time_iso_8601": "2024-03-07T17:27:09.528671Z",
"url": "https://files.pythonhosted.org/packages/8a/a0/1207a1549c8f6261b98dfd262297c7159d37b263dae471d9925b90baf1c1/socceraction-1.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c010d80efb6494a0bd195977adfff3cf2a190e3a6f1799be2c8230b71d6d48f8",
"md5": "4b8704a57fd6207bc519e2626ea78c03",
"sha256": "6a8cb127b51502802fb25bf7d36ddbea7d6e6919d42f373911dc074d95b5b691"
},
"downloads": -1,
"filename": "socceraction-1.5.1.tar.gz",
"has_sig": false,
"md5_digest": "4b8704a57fd6207bc519e2626ea78c03",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<3.12",
"size": 71930,
"upload_time": "2024-03-07T17:27:11",
"upload_time_iso_8601": "2024-03-07T17:27:11.734037Z",
"url": "https://files.pythonhosted.org/packages/c0/10/d80efb6494a0bd195977adfff3cf2a190e3a6f1799be2c8230b71d6d48f8/socceraction-1.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-07 17:27:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ML-KULeuven",
"github_project": "socceraction",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "socceraction"
}
JSON
