File size: 6,626 Bytes
d6ea71e |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 |
.. _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; or the value `fail`, if this was
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
|