| =================================== | |
| A Soccer Action Valuation Toolkit | |
| =================================== | |
| `socceraction` is a Python package for objectively quantifying the value of | |
| the individual actions performed by soccer players using event stream data. It | |
| contains the following components: | |
| - A set of API clients for **loading event stream data** from | |
| `StatsBomb <https://statsbomb.com/>`__, `Wyscout <https://wyscout.com/>`__ | |
| and `Opta <https://www.statsperform.com/opta/>`__. | |
| - 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. | |
| - An implementation of the **Expected Threat (xT)** possession value framework. | |
| - An implementation of the **VAEP** and **Atomic-VAEP** possession value frameworks. | |
| .. image:: actions_bra-bel.png | |
| :width: 600 | |
| :align: center | |
| .. toctree:: | |
| :hidden: | |
| :caption: Documentation | |
| documentation/intro | |
| documentation/install | |
| documentation/data/index | |
| documentation/spadl/index | |
| documentation/valuing_actions/index | |
| documentation/faq | |
| .. toctree:: | |
| :hidden: | |
| :caption: API reference | |
| api/data | |
| api/spadl_regular | |
| api/xthreat | |
| api/vaep | |
| api/spadl_atomic | |
| api/atomic_vaep | |
| .. toctree:: | |
| :hidden: | |
| :caption: Development | |
| Changelog <https://github.com/ML-KULeuven/socceraction/releases> | |
| development/developer_guide | |
| First steps | |
| =========== | |
| Are you new to soccer event stream data and possession value frameworks? Check | |
| out our `interactive explainer <https://dtai.cs.kuleuven.be/sports/vaep>`__ | |
| and watch Lotte Bransen's and Jan Van Haaren's `presentation in Friends of | |
| Tracking <https://www.youtube.com/watch?v=w0LX-2UgyXU>`__. Once familiar with | |
| the basic concepts, you can move on to the :doc:`quickstart guide | |
| <documentation/intro>` or continue with the hands-on video tutorials of the | |
| Friends of Tracking series: | |
| - Valuing actions in soccer (`video <https://www.youtube.com/watch?v=xyyZLs_N1F0>`__, `slides <https://drive.google.com/open?id=1t-jPgQFjZ7K4HRduaZWexUOMOmc1XR9H1jVWwaZYsOU>`__) | |
| This presentation expands on the content of the introductory presentation | |
| by discussing the technicalities behind the VAEP framework for valuing | |
| actions of soccer players as well as the content of the hands-on video | |
| tutorials in more depth. | |
| - Tutorial 1: Run pipeline (`video <https://www.youtube.com/watch?v=0ol_eLLEQ64>`__, `notebook <https://github.com/SciSports-Labs/fot-valuing-actions/blob/master/notebooks/tutorial1-run-pipeline.ipynb>`__, `notebook on Google Colab <https://colab.research.google.com/github/SciSports-Labs/fot-valuing-actions/blob/master/notebooks/tutorial1-run-pipeline.ipynb>`__) | |
| This tutorial demonstrates the entire pipeline of ingesting the raw Wyscout | |
| match event data to producing ratings for soccer players. This tutorial | |
| touches upon the following four topics: downloading and preprocessing the | |
| data, valuing game states, valuing actions and rating players. | |
| - Tutorial 2: Generate features (`video <https://www.youtube.com/watch?v=Ep9wXQgAFaE>`__, `notebook <https://github.com/SciSports-Labs/fot-valuing-actions/blob/master/notebooks/tutorial2-generate-features.ipynb>`__, `notebook on Google Colab <https://colab.research.google.com/github/SciSports-Labs/fot-valuing-actions/blob/master/notebooks/tutorial2-generate-features.ipynb>`__) | |
| This tutorial demonstrates the process of generating features and labels. This | |
| tutorial touches upon the following three topics: exploring the data in the | |
| SPADL representation, constructing features to represent actions and | |
| constructing features to represent game states. | |
| - Tutorial 3: Learn models (`video <https://www.youtube.com/watch?v=WlORqYIb-Gg>`__, `notebook <https://github.com/SciSports-Labs/fot-valuing-actions/blob/master/notebooks/tutorial3-learn-models.ipynb>`__, `notebook on Google Colab <https://colab.research.google.com/github/SciSports-Labs/fot-valuing-actions/blob/master/notebooks/tutorial3-learn-models.ipynb>`__) | |
| This tutorial demonstrates the process of splitting the dataset into | |
| a training set and a test set, learning baseline models using conservative | |
| hyperparameters for the learning algorithm, optimizing the hyperparameters for | |
| the learning algorithm and learning the final models. | |
| - Tutorial 4: Analyze models and results (`video <https://www.youtube.com/watch?v=w9G0z3eGCj8>`__, `notebook <https://github.com/SciSports-Labs/fot-valuing-actions/blob/master/notebooks/tutorial4-analyze-models-and-results.ipynb>`__, `notebook on Google Colab <https://colab.research.google.com/github/SciSports-Labs/fot-valuing-actions/blob/master/notebooks/tutorial4-analyze-models-and-results.ipynb>`__) | |
| This tutorial demonstrates the process of analyzing the importance of | |
| the features that are included in the trained machine learning models, | |
| analyzing the predictions for specific game states, and analyzing the | |
| resulting player ratings. | |
| .. note:: | |
| The video tutorials are based on version 0.2.0 of the socceraction library. | |
| If a more recent version of the library is installed, the code may need to | |
| be adapted. | |
| Getting help | |
| ============ | |
| Having trouble? We'd like to help! | |
| * Try the :doc:`FAQ <documentation/faq>` -- it's got answers to many common questions. | |
| * Looking for specific information? Try the :ref:`genindex` or :ref:`modindex`. | |
| * Report bugs in our `ticket tracker`_. | |
| .. _ticket tracker: https://github.com/ML-KULeuven/socceraction/issues | |
| Contributing | |
| ============ | |
| Learn about the development process itself and about how you can contribute in our :doc:`developer guide <development/developer_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`__] | |
| __ http://doi.acm.org/10.1145/3292500.3330758 | |
| __ https://raw.githubusercontent.com/ML-KULeuven/socceraction/master/docs/_static/decroos19.bibtex | |
| __ https://limo.libis.be/primo-explore/fulldisplay?docid=LIRIAS2913207&context=L&vid=KULeuven&search_scope=ALL_CONTENT&tab=all_content_tab&lang=en_US | |
| __ https://raw.githubusercontent.com/ML-KULeuven/socceraction/master/docs/_static/vanroy20.bibtex | |