| | .. _SPADL: |
| |
|
| | SPADL |
| | ===== |
| |
|
| | Definitions |
| | ----------- |
| |
|
| | SPADL (*Soccer Player Action Description Language*) represents a game as |
| | a sequence of on-the-ball actions :math:`[a_1, a_2, . . . , a_m]`, where |
| | :math:`m` is the total number of actions that happened in the game. Each |
| | action is a tuple of the same twelve attributes: |
| |
|
| | .. list-table:: |
| | :widths: 20 80 |
| | :header-rows: 1 |
| |
|
| | * - Attribute |
| | - Description |
| | * - game_id |
| | - the ID of the game in which the action was performed |
| | * - period_id |
| | - the ID of the game period in which the action was performed |
| | * - seconds |
| | - the action's start time |
| | * - player |
| | - the player who performed the action |
| | * - team |
| | - the player's team |
| | * - start_x |
| | - the x location where the action started |
| | * - start_y |
| | - the y location where the action started |
| | * - end_x |
| | - the x location where the action ended |
| | * - end_y |
| | - the y location where the action ended |
| | * - action_type |
| | - the type of the action (e.g., pass, shot, dribble) |
| | * - result |
| | - the result of the action (e.g., success or fail) |
| | * - bodypart |
| | - the player's body part used for the action |
| |
|
| |
|
| | Start and End Locations |
| | SPADL uses a standardized coordinate system with the origin on the bottom |
| | left of the pitch, and a uniform field of 105m x 68m. For direction of play, |
| | SPADL uses the "home team attacks to the right" convention, but this can be |
| | converted conveniently with the :func:`~socceraction.spadl.play_left_to_right` |
| | function such that the lower x-coordinates represent the own half of the team |
| | performing the action. |
| |
|
| | .. image:: spadl_coordinates.png |
| | :width: 500 |
| | :align: center |
| |
|
| |
|
| | Action Type |
| | The action type attribute can have 22 possible values. These are `pass`, |
| | `cross`, `throw-in`, `crossed free kick`, `short free kick`, `crossed |
| | corner`, `short corner`, `take-on`, `foul`, `tackle`, `interception`, |
| | `shot`, `penalty shot`, `free kick` `shot`, `keeper save`, `keeper claim`, |
| | `keeper punch`, `keeper pick-up`, `clearance`, `bad touch`, `dribble` and |
| | `goal kick`. A detailed definition of each action type is available |
| | :doc:`here <SPADL_definitions>`. |
| | Result |
| | The result attribute can either have the value `success`, to indicate that |
| | an action achieved it’s intended result |
| | not the case. An example of a successful action is a pass which reaches |
| | a teammate. An example of an unsuccessful action is a pass which goes over |
| | the sideline. Some action types can have special results. These are |
| | `offside` (for passes, corners and free-kicks), `own goal` (for shots), and |
| | `yellow card` and `red card` (for fouls). |
| | Body Part |
| | The body part attribute can have 4 possible values. These are `foot`, `head`, |
| | `other` and `none`. For Wyscout, which does not distinguish between the |
| | head and other body parts a special body part `head/other` is used. |
| |
|
| | All actions, except for some dribbles, are derived from an event in the |
| | original event stream data. They can be linked back to the original data by |
| | the `original_event_id` attribute. Synthetic dribbles are added to fill gaps |
| | between two events. These synthetic dribbles do not have an |
| | `original_event_id`. |
| |
|
| | Example |
| | ------- |
| |
|
| | Socceraction currently implements converters for |
| | :mod:`StatsBomb <socceraction.spadl.statsbomb>`, |
| | :mod:`Wyscout <socceraction.spadl.wyscout>`, and |
| | :mod:`Opta <socceraction.spadl.opta>` |
| | event stream data. We'll use StatsBomb data to illustrate the API, but the API |
| | of the other converters is identical. |
| | |
| | First, we load the event stream data of the third place play-off in the 2018 |
| | FIFA World Cup between Belgium and England. |
| |
|
| | .. code-block:: python |
| |
|
| | from socceraction.data.statsbomb import StatsBombLoader |
| |
|
| | SBL = StatsBombLoader() |
| | df_events = SBL.events(game_id=8657) |
| |
|
| | These events can now be converted to SPADL using the :func:`~socceraction.spadl.statsbomb.convert_to_actions` |
| | function of the StatsBomb converter. |
| |
|
| | .. code-block:: python |
| |
|
| | import socceraction.spadl as spadl |
| |
|
| | df_actions = spadl.statsbomb.convert_to_actions(df_events, home_team_id=777) |
| |
|
| | The obtained dataframe represents the body part, result, action type, players |
| | and teams with numeric IDs. The code below adds their corresponding names. |
| |
|
| | .. code-block:: python |
| |
|
| | df_actions = ( |
| | spadl |
| | .add_names(df_actions) # add actiontype and result names |
| | .merge(SBL.teams(game_id=8657)) # add team names |
| | .merge(SBL.players(game_id=8657)) # add player names |
| | ) |
| |
|
| | Below are the five actions in the SPADL format leading up to Belgium's |
| | second goal. |
| |
|
| | +---------+-----------+---------+---------+-----------+----------+----------+--------+--------+------------+---------+----------+ |
| | | game_id | period_id | seconds | team | player | start\_x | start\_y | end\_x | end\_y | actiontype | result | bodypart | |
| | +=========+===========+=========+=========+===========+==========+==========+========+========+============+=========+==========+ |
| | | 8657 | 2 | 2179 | Belgium | Witsel | 37.1 | 44.8 | 53.8 | 48.2 | pass | success | foot | |
| | +---------+-----------+---------+---------+-----------+----------+----------+--------+--------+------------+---------+----------+ |
| | | 8657 | 2 | 2181 | Belgium | De Bruyne | 53.8 | 48.2 | 70.6 | 42.2 | dribble | success | foot | |
| | +---------+-----------+---------+---------+-----------+----------+----------+--------+--------+------------+---------+----------+ |
| | | 8657 | 2 | 2184 | Belgium | De Bruyne | 70.6 | 42.2 | 87.4 | 49.1 | pass | success | foot | |
| | +---------+-----------+---------+---------+-----------+----------+----------+--------+--------+------------+---------+----------+ |
| | | 8657 | 2 | 2185 | Belgium | Hazard | 87.4 | 49.1 | 97.9 | 38.7 | dribble | success | foot | |
| | +---------+-----------+---------+---------+-----------+----------+----------+--------+--------+------------+---------+----------+ |
| | | 8657 | 2 | 2187 | Belgium | Hazard | 97.9 | 38.7 | 105 | 37.4 | shot | success | foot | |
| | +---------+-----------+---------+---------+-----------+----------+----------+--------+--------+------------+---------+----------+ |
| |
|
| | Here is the same phase visualized using the ``matplotsoccer`` package |
| |
|
| | .. image:: eden_hazard_goal_spadl.png |
| | :align: center |
| |
|
| | .. seealso:: |
| |
|
| | This `notebook`__ gives an example of the complete pipeline to download public |
| | StatsBomb data and convert it to the SPADL format. |
| |
|
| | __ https://github.com/ML-KULeuven/socceraction/blob/master/public-notebooks/1-load-and-convert-statsbomb-data.ipynb |
| |
|
