Guide_to_Version_0-2-0.Rmd

---
title: "Guide to function argument changes in Version 0.2.0"
author: "Ryo Nakagawara"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Guide to function argument changes in Version 0.2.0}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
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](https://abhiamishra.github.io/ggshakeR/articles/Guide_to_Pitch_Plots.html)
* [Guide to Creating Pizza Plots](https://abhiamishra.github.io/ggshakeR/articles/Guide_to_PizzaPlots.html)
* [Guide to Expected Threat](https://abhiamishra.github.io/ggshakeR/articles/Guide_to_Exp_Threat.html)

```{r setup}
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.

```{r example-bad}
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'](http://adv-r.had.co.nz/Functions.html#function-arguments). 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()`

```{r}
calculate_threat(data, type)
```

- `data`: changed from `event_data`
- `type`: changed from `dataType`

## `plot_heatmap()`

```{r}
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()`

```{r}
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()`

```{r}
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()`

```{r}
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()`

```{r}
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()`

```{r}
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()`

```{r}
plot_sonar(data, data_type, title)
```

* `data`: changed from `sonarData`

## `plot_trendline()`

```{r}
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()`

```{r}
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.

```{r}
## 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.