Guide to function argument changes in Version 0.2.0

Along side the new functionality in the v0.2.0 update, there have been a lot of changes made to existing {ggshakeR} functions as well. This is regarding the consistency and standardization of argument names in the package.

For guides on new functions please see:

library(ggshakeR)

The problem that really kicked off these changes was the fact that as I was looking through the package’s code base, I found that we had functions with arguments using snake_case in some functions, others using camelCase, and worst of all some functions that used both snake_case AND camelCase in the argument names.

plot_passflow(pass_data, dataType, bin_size) # !!!   (╯°□°）╯︵ ┻━┻

After some discussion with the other authors (Abhishek & Harsh), I have standardized everything to snake_case as well as making a number of other changes to argument names for the sake of consistency. This does mean some pain in the short-term, but please do know these changes are done with user experience in mind in the long-term by lessening the cognitive load for using the functions in the package. Some argument names are longer now, but this shouldn’t be an issue as in RStudio you can simply press Tab while typing to auto-complete longer argument names (other modern IDEs should have a similar feature as well). An exception (hopefully a rare one as we go forward) is binwidth as this is essentially an argument that is being passed on to some underlying ggplot2 function calls and we wanted to preserve the same argument name for familiarity’s sake.

The type arguments have also been rejigged so that the first type argument will always be the type related to the function. So for example each plot_*() function’s type argument will specify the plot type, then other arguments for the type of other things will have their own prefix such as data_type and so on. Another QOL change was to make the data argument be standardized across all functions so you don’t have to figure out whether it’s event_data or pass_data or sonarData or even simply data… it’s all just data now.

Some arguments have changed their order in the functions, to learn about why function order is important, check out Function arguments section in ‘Advanced R’. The functions in {ggshakeR} follows R function conventions by having the data argument come first, then usually a type argument, then the rest in an order we think makes sense.

Listed below are the changes made for version 0.2.0 to previously existing functions:

`calculate_threat()`

calculate_threat(data, type)

data: changed from event_data
type: changed from dataType

`plot_heatmap()`

plot_heatmap(data, type, data_type, binwidth, theme)

data: changed from event_data
type: specifically refers to the plot type while data_type (below) allows you to specify the data type (StatsBomb, Opta, etc.)
data_type: changed from dataType
binwidth: changed from bin, now the same argument name as the underlying call to geom_bin2d()
theme: moved to be the last argument

`plot_pass()`

plot_pass(data, 
          type, progressive_pass, 
          cross, shot, switch, outcome, 
          theme)

data: changed from pass_data
progressive_pass: changed from prog
type: changed from plot_type, specifically refers to plot type as it is a plot_*() function
data_type: changed from dataType

`plot_passflow()`

plot_passflow(data, data_type, binwidth)

data: changed from pass_data
data_type: moved to come after the data argument
binwidth: changed from bin_size, now the same argument name as the underlying call to geom_bin2d()

`plot_pizza()`

plot_pizza(data, type, template, 
           color_possession, color_attack, color_defense, color_compare,
           player_1, player_2, 
           season, season_player_1, season_player_2, 
           theme)

color_possession: changed from color_poss
color_attack: changed from color_att
color_defense: changed from color_def

`plot_scatter()`

plot_scatter(data, x, y, label,
             set_size_num, set_size_var,
             set_color_num, set_color_var,
             title, title_size,
             subtitle, subtitle_size,
             caption, caption_size,
             theme)

x: changed from scatter_x
y: changed from scatter_y
label: changed from scatter_label
title: changed from scatter_title
subtitle: changed from scatter_subtitle
subtitle_size: changed from subt_size
caption: changed from scatter_cap
caption_size: changed from cap_size
theme: moved to the very end of the argument order

`plot_shot()`

plot_shot(data, type, bins, highlight_goals, average_location)

bins: changed from bin_size, now the same argument name as the underlying call to geom_hex()
average_location: changed from avg_loc

`plot_sonar()`

plot_sonar(data, data_type, title)

data: changed from sonarData

`plot_trendline()`

plot_trendline(data, team, color_xg, color_xga, rolling_average, theme)

color_xg: changed from colour_xg
color_xga: changed from colour_xga
rolling_average: changed from roll_avg

`plot_timeline()`

plot_timeline(data, match_year, 
              team_home, team_away,
              color_home, color_away, theme)

color_home: changed from home_color
color_away: changed from away_color

Installing previous versions of the package

For those who are not ready to fully commit to these changes (because you have a large script with {ggshakeR} functions or whatever) but have accidentally installed the new version, fear not as you can go back and install a prior version of the package.

## Install previous 0.1.2 version
devtools::install_github("abhiamishra/ggshakeR@0.1.2")

Do note that the changes listed in this vignette are permanent and will be the standard going forward. So please take the time to read this vignette and the documentation carefully so that you can transition over to the new argument syntax and make use of the new functionality that version 0.2.0 (and beyond!) provides.

Ryo Nakagawara

2023-08-18