|
|
Quickstart |
|
|
=========== |
|
|
|
|
|
Eager to get started valuing some soccer actions? This page gives a quick |
|
|
introduction on how to get started. |
|
|
|
|
|
Installation |
|
|
------------ |
|
|
|
|
|
First, make sure that socceraction is installed: |
|
|
|
|
|
.. code-block:: console |
|
|
|
|
|
$ pip install socceraction[statsbomb] |
|
|
|
|
|
For detailed instructions and other installation options, check out our |
|
|
detailed :doc:`installation instructions <install>`. |
|
|
|
|
|
Loading event stream data |
|
|
------------------------- |
|
|
|
|
|
First of all, you will need some data. Luckily, both `StatsBomb <https://github.com/statsbomb/open-data>`_ and |
|
|
`Wyscout <https://www.nature.com/articles/s41597-019-0247-7>`_ provide a small freely available dataset. |
|
|
The :ref:`data module<api-data>` of socceraction makes it trivial to load these datasets as |
|
|
`Pandas DataFrames <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html>`__. |
|
|
In this short introduction, we will work with Statsbomb's dataset of the 2018 World Cup. |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
import pandas as pd |
|
|
from socceraction.data.statsbomb import StatsBombLoader |
|
|
|
|
|
# Set up the StatsBomb data loader |
|
|
SBL = StatsBombLoader() |
|
|
|
|
|
# View all available competitions |
|
|
df_competitions = SBL.competitions() |
|
|
|
|
|
# Create a dataframe with all games from the 2018 World Cup |
|
|
df_games = SBL.games(competition_id=43, season_id=3).set_index("game_id") |
|
|
|
|
|
|
|
|
.. note:: |
|
|
Keep in mind that by using the public StatsBomb data you are agreeing to their `user agreement <https://github.com/statsbomb/open-data/blob/master/LICENSE.pdf>`__. |
|
|
|
|
|
For each game, you can then retrieve a dataframe containing the teams, all |
|
|
players that participated, and all events that were recorded in that game. |
|
|
Specifically, we'll load the data from the third place play-off game between |
|
|
England and Belgium. |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
game_id = 8657 |
|
|
df_teams = SBL.teams(game_id) |
|
|
df_players = SBL.players(game_id) |
|
|
df_events = SBL.events(game_id) |
|
|
|
|
|
|
|
|
Converting to SPADL actions |
|
|
--------------------------- |
|
|
|
|
|
The event stream format is not well-suited for data analysis: some of the |
|
|
recorded information is irrelevant for valuing actions, each vendor uses their |
|
|
own custom format and definitions, and the events are stored as unstructured |
|
|
JSON objects. Therefore, socceraction uses the :doc:`SPADL format |
|
|
<spadl/index>` for describing actions on the pitch. With the code below, you |
|
|
can convert the events to SPADL actions. |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
import socceraction.spadl as spadl |
|
|
|
|
|
home_team_id = df_games.at[game_id, "home_team_id"] |
|
|
df_actions = spadl.statsbomb.convert_to_actions(df_events, home_team_id) |
|
|
|
|
|
With the `matplotsoccer package <https://github.com/TomDecroos/matplotsoccer>`_, you can try plotting some of these |
|
|
actions: |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
import matplotsoccer as mps |
|
|
|
|
|
# Select relevant actions |
|
|
df_actions_goal = df_actions.loc[2196:2200] |
|
|
# Replace result, actiontype and bodypart IDs by their corresponding name |
|
|
df_actions_goal = spadl.add_names(df_actions_goal) |
|
|
# Add team and player names |
|
|
df_actions_goal = df_actions_goal.merge(df_teams).merge(df_players) |
|
|
# Create the plot |
|
|
mps.actions( |
|
|
location=df_actions_goal[["start_x", "start_y", "end_x", "end_y"]], |
|
|
action_type=df_actions_goal.type_name, |
|
|
team=df_actions_goal.team_name, |
|
|
result=df_actions_goal.result_name == "success", |
|
|
label=df_actions_goal[["time_seconds", "type_name", "player_name", "team_name"]], |
|
|
labeltitle=["time", "actiontype", "player", "team"], |
|
|
zoom=False |
|
|
) |
|
|
|
|
|
.. figure:: spadl/eden_hazard_goal_spadl.png |
|
|
:align: center |
|
|
|
|
|
|
|
|
Valuing actions |
|
|
--------------- |
|
|
|
|
|
We can now assign a numeric value to each of these individual actions that |
|
|
quantifies how much the action contributed towards winning the game. |
|
|
Socceraction implements three frameworks for doing this: xT, VAEP and |
|
|
Atomic-Vaep. In this quickstart guide, we will focus on the xT framework. |
|
|
|
|
|
The expected threat or xT model overlays a :math:`M \times N` grid on the |
|
|
pitch in order to divide it into zones. Each zone :math:`z` is |
|
|
then assigned a value :math:`xT(z)` that reflects how threatening teams are at |
|
|
that location, in terms of scoring. An example grid is visualized below. |
|
|
|
|
|
.. image:: valuing_actions/default_xt_grid.png |
|
|
:width: 600 |
|
|
:align: center |
|
|
|
|
|
The code below allows you to load |
|
|
league-wide xT values from the 2017-18 Premier League season (the 12x8 grid |
|
|
shown above). Instructions on how to train your own model can be found in the |
|
|
:doc:`detailed documentation about xT <valuing_actions/xT>`. |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
import socceraction.xthreat as xthreat |
|
|
|
|
|
url_grid = "https://karun.in/blog/data/open_xt_12x8_v1.json" |
|
|
xT_model = xthreat.load_model(url_grid) |
|
|
|
|
|
|
|
|
|
|
|
Subsequently, the model can be used to value actions that successfully move |
|
|
the ball between two zones by computing the difference between the threat |
|
|
value on the start and end location of each action. The xT framework does not |
|
|
assign a value to failed actions, shots and defensive actions such as tackles. |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
df_actions_ltr = spadl.play_left_to_right(df_actions, home_team_id) |
|
|
df_actions["xT_value"] = xT_model.rate(df_actions_ltr) |
|
|
|
|
|
|
|
|
.. image:: valuing_actions/eden_hazard_goal_xt.png |
|
|
:align: center |
|
|
|
|
|
|
|
|
----------------------- |
|
|
|
|
|
Ready for more? Check out the detailed documentation about the |
|
|
:doc:`data representation <spadl/index>` and |
|
|
:doc:`action value frameworks <valuing_actions/index>`. |
|
|
|
