| =================================== |
| 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 |
|
|
