-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathREADME.Rmd
373 lines (305 loc) · 12.6 KB
/
README.Rmd
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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
---
output: github_document
editor_options:
markdown:
wrap: 72
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
cache = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%",
dpi = 600
)
```
# sportyR <img src="https://raw.githubusercontent.com/sportsdataverse/sportyR/main/logos/sportyr-logo-hex.png" align="right" width="120"/>
<!-- badges: start -->
[](https://CRAN.R-project.org/package=sportyR)
[](https://CRAN.R-project.org/package=sportyR)
[](https://github.com/sportsdataverse/sportyR/)
[](https://github.com/sportsdataverse/sportyR/actions/workflows/R-CMD-check.yaml)
[](https://codecov.io/gh/sportsdataverse/sportyR)
[](https://github.com/sportsdataverse/sportyR/)
[](https://twitter.com/sportyR_pkg)
[](https://twitter.com/sportsdataverse)
<!-- badges: end -->
As the field of sports analytics evolve, there's a growing need for
methods to both track and visualize players throughout the game. This
package aims to make this easy regardless of sport needed to be plotted.
This repository contains code necessary to draw scale versions of playing surfaces to visualize play-by-play data for baseball, basketball, curling, football, hockey, soccer, and tennis in **R**. For the **Python** version of this package, click [here](https://github.com/sportsdataverse/sportypy).
## Installation
The most recent release of `sportyR` is available on
[CRAN](https://cran.r-project.org/web/packages/sportyR/index.html), and
it can be installed directly via:
```{r readme-install-package-cran, eval = FALSE}
# Install released version from CRAN
install.packages("sportyR")
```
The development version of `sportyR` can be installed from
[GitHub](https://github.com/sportsdataverse/sportyR) with:
```{r readme-install-package-github, eval = FALSE}
# Install development version from GitHub
devtools::install_github("sportsdataverse/sportyR")
```
Once the library is installed, be sure to load it into the working
environment.
```{r readme-load-sportyR}
# Required to use package
library(sportyR)
```
## Plotting Functions {#plotting-functions}
All plotting functions in this library are named as `geom_{sport}()`,
and take the following arguments:
- `league`: the league code for the sport. In all functions, this will
***NOT*** have a default value. The supplied league is
**case-insensitive**. Future iterations of this package may allow
the full league name to be supplied if desired (e.g.
`league = 'National Basketball Associaton'` instead of
`league = 'NBA'`), but this feature is not currently available.
- `display_range`: This automatically "zooms" in on the area of the
plot you're interested in. Valid ranges here vary by sport, but can
be found by calling `?geom_{sport}` and reading about the display
ranges
- `x_trans` and `y_trans`: By default, the origin of the coordinate
system *always* lies at the center of the plot. For example,
`(0, 0)` on a basketball court lies along the division line and on
the line that connects the center of each basket. If you want to
shift the origin (and therefore the entire plot), use `x_trans` and
`y_trans` to do so
- `{surface_type}_updates`: A list of updates to the parameters that
define the surface. I'll demo how to use this to change a hockey
rink in a different vignette, but I'll call this out here
- `color_updates`: A list that contains updates to the features'
colors on the plot. These are named by what the feature is, using
`snake_case` to specify the names. To get the list of color names
you can change, try running `cani_color_league_features()` with your
desired league
- `rotation`: An angle (in degrees) that you'd like to rotate the plot
by, where +\theta is counterclockwise
- `xlims` and `ylims`: Any limits you'd like to put on the plot in the
x and y direction. These will overwrite anything set by the
`display_range` parameter
- `{surface}_units`: If your data is in units that are different than
how the rule book of the league specifies the units (e.g. you've got
NHL data in inches, but the rule book describes the rink in feet),
change this parameter to match the units you've got your data in.
You're welcome to change the units of the data as well, but this is
provided for convenience
## TV View and Display Ranges
### TV View
All of the `geom_{sport}()` functions, by default, will draw the surface
in what can be considered "TV view", or the way that the surface would
typically be displayed on a television broadcast. This typically means
the action moves from left to right across the screen (a basketball game
that has the baskets on the left and right end of the court). As
mentioned above, it is possible to change this to be in any orientation
through the `rotation` parameter to each `geom_{sport}()` function.
There are a few exceptions to this:
- `geom_baseball()` is displayed from the high-home view by default,
as baseball coordinates typically have the `+y` axis extending from
the back tip of home plate towards center field
- `geom_tennis()` is displayed with the court diagrammed from the
perspective of the chair umpire
### Display Ranges
Related to the idea of custom displays of the plot is the concept of the
`display_range` parameter in the `geom_{sport}()` function. This is
unique to each sport, but globally supported across the package. This
parameter allows the specification of a designated region of the surface
to display. As an example, if you're trying to limit the analysis of NFL
data to being inside of the red zone, you may want to do something
similar to the following:
```{r readme-display-range-demo, dev = "png"}
# Display only the red zone of the football field
geom_football("nfl", display_range = "red zone")
```
Another use case would be to make the data you're viewing easier to see. Say you wanted to look at curling data, but only cared about stone positions in the house (and not the path as to how the stones got there). You might do this:
```{r readme-display-range-curling-demo, dev = "png"}
# Display only the house on a curling sheet
geom_curling("wcf", display_range = "house")
```
## Plot Units
Each plot function has a standardized unit of measure in which the plot
is created, and is standardized by the primary units specified in their
respective rule books. They are as follows (and any explanation is in
parentheses):
```{r readme-plot-units-table, echo = FALSE}
units_df <- data.frame(
sport = c(
rep("Baseball", 6),
rep("Basketball", 6),
rep("Curling", 1),
rep("Football", 7),
rep("Hockey", 10),
rep("Lacrosse", 7),
rep("Soccer", 5),
rep("Tennis", 6),
rep("Volleyball", 3)
),
league = c(
# Baseball
"Little League",
"MiLB",
"MLB",
"NCAA",
"NFHS (High School)",
"Pony",
# Basketball
"FIBA",
"NBA",
"NBA G League",
"NCAA",
"NFHS",
"WNBA",
# Curling
"WCF (World Curling Federation)",
# Football
"CFL",
"NCAA",
"NFHS11 (High School, 11 players)",
"NFHS6 (High School, 6 players)",
"NFHS8 (High School, 8 players)",
"NFHS9 (High School, 9 players)",
"NFL",
# Hockey
"AHL",
"ECHL",
"IIHF",
"NCAA",
"NHL",
"NWHL",
"OHL",
"PHF",
"QMJHL",
"USHL",
# Lacrosse
"NCAAM",
"NCAAW",
"NLL",
"PLL",
"USA Men's",
"USA Women's",
"World Lacrosse",
# Soccer
"EPL",
"FIFA",
"MLS",
"NCAA",
"NWSL",
# Tennis
"ATP",
"ITA",
"ITF",
"NCAA",
"USTA",
"WTA",
# Volleyball
"FIVB",
"NCAA",
"USA Volleyball"
),
primary_unit = c(
rep("`ft`", 6),
rep("`m`", 1),
rep("`ft`", 5),
rep("`ft`", 1),
rep("`yd`", 7),
rep("`ft`", 2),
rep("`m`", 1),
rep("`ft`", 7),
rep("`yd`", 1),
rep("`m`", 1),
rep("`ft`", 1),
rep("`yd`", 2),
rep("`m`", 1),
rep("`ft`", 1),
rep("`m`", 2),
rep("`yd`", 3),
rep("`ft`", 6),
rep("`m`", 3)
)
)
names(units_df) <- c("Sport", "League", "Primary Plotting Unit")
knitr::kable(units_df, align = "c")
```
However, since the data that is supplied may come in various units of
measure, the plots are able to be generated in the data's units. This is
done via the `unit` argument in `geom_{sport}()`. The features
themselves will look visually identical, but the underlying coordinate
grid will change.
Additionally, the `convert_units()` function can be called on a data
frame to convert from the data's arguments to the plot's. For example,
if soccer data is given in yards, but is desirable to be plotted in
meters, calling
`convert_units(tracking_data, 'yd', 'm', conversion_columns = c('x', 'y'))`
will convert the x and y coordinates from yards to meters.
As mentioned [above](#plotting-functions), the `geom_{sport}()` family
of functions allow for rotations of surfaces via the `rotation`
argument. To make this easy, `sportyR` also allows for the rotation of
data frames' coordinates ***so long as they contain an*** `x` ***and***
`y` ***column*** via the `rotate_coords()` function. Reflection is also
possible through `reflect()`.
## Surface Examples
Most playing surfaces are standard in size, so they can be rendered via
a call to the proper `geom_{sport}()` function like so:
```{r readme-mlb-example}
# Draw a basic MLB infield plot
geom_baseball("mlb", display_range = "infield")
```
```{r readme-fifa-example}
# Create a 100m by 75m FIFA pitch
geom_soccer(
"fifa",
pitch_updates = list(
pitch_length = 100,
pitch_width = 75
)
)
```
It's also possible to plot partial surfaces and rotated surfaces:
```{r readme-nhl-example}
# Draw half of a rotated NBA court
geom_basketball("nba", display_range = "offense", rotation = 270)
```
## License
This package is released under the [GPL 3.0
License](https://github.com/sportsdataverse/sportyR/blob/master/LICENSE.md).
## Contributions
### League Office
The package maintainers and functional engineers
- [Ross Drucker](https://github.com/rossdrucker) - `sportyR`
Commissioner
### General Managers
Contribute by adding a new sport and become its general manager. Current
general managers (and their sports) are:
- [Ross Drucker](https://github.com/rossdrucker) - Baseball
- [Ross Drucker](https://github.com/rossdrucker) - Basketball
- [Ross Drucker](https://github.com/rossdrucker) - Curling
- [Ross Drucker](https://github.com/rossdrucker) - Football
- [Ross Drucker](https://github.com/rossdrucker) - Hockey
- [Ross Drucker](https://github.com/rossdrucker) - Soccer
- [Ross Drucker](https://github.com/rossdrucker) - Tennis
- [Ross Drucker](https://github.com/rossdrucker) - Volleyball
### Coaching Staffs
Notice something for a sport that already exists, but isn't quite right?
Join that sport's coaching staff!
### Scout Team
By regularly reporting issues, making very slight modifications, fixing
typos, or just helping others navigate their own issues, you're able to
join the Scout Team!
### Acknowledgements
Much of the underling code structure in `sportyR`, beginning with
`v2.0.0`, was influenced by [The
Bucketless](https://github.com/the-bucketless)'s work on the
[hockey_rink](https://github.com/the-bucketless/hockey_rink) package for
Python.
### `sportyR`tist
The `sportyR` logo was created by Lindsey Kelso. Check her out on
[Instagram](http://Instagram.com/kelsokreationsbylindsey) or her [online
shop](http://kelsokreationsbylindsey.bigcartel.com)!