In abhiamishra/ggshakeR: Analytics and Visualization Package for Soccer Data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)

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:

• Guide to Pitch Plots
• Guide to Creating Pizza Plots
• Guide to Expected Threat

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.

abhiamishra/ggshakeR documentation built on Aug. 19, 2023, 2 p.m.