---
title: "Retrieving player data from the NHL API"
author: "Jozef Hajnala"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Retrieving player data from the NHL API}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

# High-level players APIs

The high-level APIs intend to provide convenient functionality used by most users. Each function from the players API returns a data frame with the requested data processed to serve common purposes.

Note that while some of the showcased examples use the `dplyr` package to manipulate the data, the `nhlapi` package itself does not import it and the user is free to use whichever methods to manipulate the data.

```{r}
library(nhlapi)
```

## Players information

The first endpoint retrieves information on players based on provided player names or ids. This information includes data such as names, nationalities, birth dates, etc.

One or more names of one or more ids can be provided to the function, data on each valid player name or id will be returned as one row of the resulting data frame:

Example with player names, note that they are not case sensitive:

```{r}
# Get information on players by name
nhl_players(c("joe sakic", "PETER forsberg"))
```

With player ids:

```{r}
playerIds <- c(8451101, 8458554)
nhl_players(playerIds = playerIds)
```

Invalid or erring requests will not return any rows, the errors will be reported:

```{r}
nhl_players(c("made up player", "Joe Sakic"))

nhl_players(playerIds = c("made up player", 8451101))
```

The functions are designed is such a way that they allow working with the `%>%` operator if the user desires to do so:

```{r}
# Requires `dplyr` attached using library("dplyr")
nhl_players(playerIds = playerIds) %>%
  select(fullName, nationality, shootsCatches, primaryPosition.code)
```


## Players' season statistics

The second endpoint is used to retrieve players' statistics per seasons. The function `nhl_players_seasons()` accepts multiple `playerNames` or  `playerIds` and multiple `seasons`. The proper API URLs will be constructed and a flat data frame returned:

```{r}
# Get a specific season statistics using player names
nhl_players_seasons(
  c("Joe SAKIC", "Peter Forsberg"),
  seasons = 1996:1998
)
```

It also accepts a `playoff` argument in case the users wants playoff statistics returned and not regular season:

```{r}
# Get a specific season playoff statistics
nhl_players_seasons(
  c("Joe SAKIC", "Peter Forsberg"),
  seasons = 1996,
  playoffs = TRUE
)
```

Player ids can also be used instead of player names:

```{r}
# Get a specific season playoff statistics
nhl_players_seasons(
  playerIds = c(8451101, 8458554),
  seasons = 1996,
  playoffs = TRUE
)
```


A simple wrapper `nhl_players_allseasons()` is also provided to get the statistics for all the seasons for the specified players:

```{r}
# Get all season statistics for players
nhl_players_allseasons(playerIds = c(8451101, 8458554))
```

# Combining the endpoints

The package outputs are designed in such a way that they support easy data manipulation and exploration. For instance, using the popular `dplyr` package:

```{r}
# Requires `dplyr` attached using library
playerNames <- c("Joe Sakic", "Peter Forsberg")

result <- nhl_players(playerNames) %>%
  left_join(
    nhl_players_allseasons(playerNames),
    by = c("id" = "playerId")
  ) %>%
  filter(league.name == "National Hockey League") %>%
  select(fullName, seasonStart, stat.points)

head(result)
```

# Plotting the data

The `nhlapi` package itself does not contain plotting functionality, the output of user-facing functions are however designed to be data frames adhering to principles that make plotting with popular packages very natural.

For instance, using the `ggplot2` package to plot the amount of points gathered by multiple players over the seasons:

```{r}
# Requires `ggplot2` attached using library
ggplot(result) +
  geom_line(aes(seasonStart, stat.points, colour = fullName))
```

Or using the `highcharter` package to create an interactive version of the same chart:

```{r}
# Requires `highcharter` attached using library
result %>%
  hchart("line", hcaes(seasonStart, stat.points, group = fullName)) %>%
  hc_add_theme(hc_theme_google())
```