Skip to main content

Convert soccer event stream data to the SPADL format and value on-the-ball player actions

Project description

Convert soccer event stream data to the SPADL format
and value on-the-ball player actions


PyPi Python Version: 3.7.1+ Downloads License: MIT

Build Status Read the Docs Code coverage



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.

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 »
  • 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 »
  • An implementation of the Expected Threat (xT) possession value framework. Read more »
  • An implementation of the VAEP and Atomic-VAEP possession value frameworks. Read more »

Installation / Getting started

The recommended way to install socceraction is to simply use pip. The latest version officially supports Python 3.9 - 3.12.

$ pip install socceraction

The folder 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.

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.

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.
    [ pdf | 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.
    [ pdf | bibtex ]

The Expected Threat (xT) framework was originally introduced by Karun Singh on his blog in 2019.

License

Distributed under the terms of the MIT license, 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

socceraction-1.5.3.tar.gz (72.1 kB view details)

Uploaded Source

Built Distribution

socceraction-1.5.3-py3-none-any.whl (93.1 kB view details)

Uploaded Python 3

File details

Details for the file socceraction-1.5.3.tar.gz.

File metadata

  • Download URL: socceraction-1.5.3.tar.gz
  • Upload date:
  • Size: 72.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.12.5

File hashes

Hashes for socceraction-1.5.3.tar.gz
Algorithm Hash digest
SHA256 8e22e7437a9168cc44f2d2619ebe1095e3b3d175b35c84c5a9b6635bf07470a8
MD5 3c83291cce173148757ecdaf26804fdf
BLAKE2b-256 d6ef7699091682c7c38749bc2e0a7a2ec6e192c50e62a614e809a460aff79546

See more details on using hashes here.

File details

Details for the file socceraction-1.5.3-py3-none-any.whl.

File metadata

  • Download URL: socceraction-1.5.3-py3-none-any.whl
  • Upload date:
  • Size: 93.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.12.5

File hashes

Hashes for socceraction-1.5.3-py3-none-any.whl
Algorithm Hash digest
SHA256 43abbafab03d103440bdd4e2abb95d71b0715f588fb43ff7e57e2d8edd51f3ad
MD5 381e0c9d0e2733e0a4cf284279a51ea3
BLAKE2b-256 c94588ef58854e2f44f4533fcff4873d16a6cb770e94744b29e75b9cdb429bb2

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page