-
Notifications
You must be signed in to change notification settings - Fork 17
/
Copy pathREADME.qmd
237 lines (140 loc) · 8.16 KB
/
README.qmd
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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
---
title: '{soccerAnimate}'
format:
gfm:
preview-mode: html
---
An R package to create 2D animations of soccer tracking data
<p align="center">
<img width="200" src="man/soccerAnimate.png">
</p>
## How to install it?
```
# install.packages("remotes")
remotes::install_github("Dato-Futbol/soccerAnimate")
```
In case you have a previous version and you would like to update the package, don't forget to add the argument `force = T`
## Changelog
The following additions were added for the last version of the package (*v1.1 at March 11th, 2024*)
* Visualization for team avg. positioning comparing ON/OFF ball possession
* Avg. positioning team stats:
- Last defender X pos. [m]
- Highest forward X pos. [m]
- Depth [m]
- Amplitude [m]
- Area [m2]
- Centroid X,Y
- Spread
#### v1.0 (April 28th, 2023)
* Player stats calculations:
- Minutes played and avg. speed
- Instant velocity per sample (magnitude and direction) which allow to calculate some game level stats and to show this info on the visualizations
- Total distances over the game and for different velocity ranges (you are able to choose between 2 kind of ranges)
- Number of sprints made by each player
* Player visualizations:
- A plot showing where a specific player made a specific action (e.g. sprints)
- Animation highlighting the player path on a specific time range
* General:
- Pitch dimension could be customized
## How to use it?
The package already has multiple functions to use, so it is usefulness to think about of them like a workflow for a either players or team level, as the following diagram shows:
<p align="center">
<img width="80%" src="man/mermaid-figure-1.png">
</p>
The functions allows you to do the following tasks:
### 1) To get and process the tracking data
The function **get_tidy_data()** reads, tidies and joins the rawdata of both the Home and Away teams.
Currently only data from the provider Metrica Sports is supported. Even though you can download the open tracking/event data following [this link](https://github.com/metrica-sports/sample-data), it is also possible to get the processed data directly using the function *get_tidy_data()* with the URLs of rawdata like the following example for the Game #2:
```
library(soccerAnimate)
home_team_file <- "https://raw.githubusercontent.com/metrica-sports/sample-data/master/data/Sample_Game_2/Sample_Game_2_RawTrackingData_Home_Team.csv"
away_team_file <- "https://raw.githubusercontent.com/metrica-sports/sample-data/master/data/Sample_Game_2/Sample_Game_2_RawTrackingData_Away_Team.csv"
td <- get_tidy_data(home_team_file, away_team_file)
```
If you have another data provider or format, contact me in order to explore how can I help you adapting the code.
I also could provide you some professional services related, even if you have tracking data from GPS devices. Check [this link](https://www.datofutbol.cl/services/tracking-data-applications/) for more details.
### 2) To get events information
The function **events_info()** gets events information from the eventing dataset (Period, Team, Event, start and end time, start and end frame, etc.). You could get info for either shots, goals, free kicks or corner kicks. One of the current main usefulness of this is to know at which times/frames specific events occurs, then you will create both static plots and animations for those times/frames.
```
event_path = "https://raw.githubusercontent.com/metrica-sports/sample-data/master/data/Sample_Game_2/Sample_Game_2_RawEventsData.csv"
ed <- readr::read_csv(event_path)
goals <- events_info(ed, events = "GOAL")
# all_events <- events_info(ed, events = c("SHOT", "GOAL", "FREE KICK", "CORNER KICK"))
```
{fig-align="center" width=80%}
## Team level
### 3) To create a 2D static plot
The function **soccer_plot()** creates a static plot of one specific and unique **frame**. It is useful to explore and pre visualize your data, aesthetic and method setting, before to create the animation (whose creation time will be longer). You are able to export this plots as PNG files.
```
soccer_plot(tidy_data = td, target_frame = 12212, export_png = T)
```
{fig-align="center" width=80%}
### 4) To create a 2D soccer animation
The function **soccer_animate()** creates 2D soccer animations using tracking data. You are able to set multiple arguments besides tidy tracking data, like the starting and the ending time to animate (in seconds, no frames!), geometric or spatial analysis method (options: "base", "convexhull", "voronoi", "delaunay"), aesthetics setting (colors of pitch fill and lines, teams colors, titles, etc.), and some output settings. Most of this arguments are enabled also for **soccer_plot()** function.
```
# Example A: "base"
soccer_animate(td, 480, 490, "base", export_gif = T)
```
{fig-align="center" width=80%}
```
# Example B "convexhull"
soccer_animate(td, 480, 490, "convexhull", export_gif = T, gif_name = "convexhull.gif")
```
{fig-align="center" width=80%}
```
# Example C: "voronoi"
soccer_animate(td, 2112, 2122, "voronoi", export_gif = T, gif_name = "voronoi.gif")
```
{fig-align="center" width=80%}
### 4) Team avg. postitioning and stats by ON/OFF ball possession states
With the function **soccer_plot_poss()** you can create a plot showing for each team the avg. position of players, its convex hull and position stats.
```
soccer_plot_poss(td, event_path, team = "Away", pitch_fill = "grey40",
on_ball_col = "white", off_ball_col = "#74a9cf")
```
{fig-align="center" width=80%}
## Player level
### 5) Player stats calculation and visualization:
With the function **players_stats()** you calculate for every player the minutes played, avg. speed, total distance and distance for different speed ranges.
Then you are able to visualize those stats with the function **players_stats_graph()** (Home team by default):
```
player_stats = players_stats(td)
players_stats_graph(player_stats, export_png = T)
```
{fig-align="center" width=80%}
{fig-align="center" width=80%}
### 6) To get players sprints information:
With the function **sprints_info()** you apply the needed data processing to get the number of sprints that every player for a chosen team (Home team by default) made. A sprint is considered when a player run a very high speed (higher than 7 [m/s]) for at least 1 second.
With this information you can observe a player ranking based on the number of sprints:
```
sprints = sprints_info(td)
library(dplyr)
player_sprints = sprints %>%
summarise(n_sprint = sum(start)) %>%
arrange(desc(n_sprint))
```
{fig-align="center" width=25%}
### 7) To create a player plot with specific actions:
With the function **player_plot()** you can create a plot showing where and when (labels show Time[s]) specific actions made by a player happened.
For example, the sprints made by the player 10 of the Home team:
```
player10_starts = sprints %>% filter(player == 10 & start == 1)
player10_ends = sprints %>% filter(player == 10 & end == 1)
player_plot(td, 10, player10_starts$n, player10_ends$n, export_png = T)
```
{fig-align="center" width=80%}
### 8) To create a player animation highlighting :
With the function **player_animate()** you are able to create a 2D animation for the specific time range when one specific player sprint happened.
```
player_animate(td, 10, player10_starts$n[1], player10_ends$n[1], export_gif = T)
```
{fig-align="center" width=80%}
## General considerations
* A soccer pitch of dimensions 105x68 meters was considered by default.
* Reverted coordinates for Period 2: Teams are always attacking in the same direction.
* Avg. positioning viz and stats consider the 11 players who played the highest amount of minutes
## Currently working on:
- target team ON possession vs opponent team OFF possession
- split stats and positioning by context: score, venue, game state, etc.
- add specific metric text annotations
- additional data providers