In llefebure/nba-stats: NBA Data

The following vignettes summarises the most important functional use of rNBA package:

• Accessing all statistics from (http://stats.nba.com/)
• Plotting
• Using the Shiny Apps

Accessing all Statistics

One of the core functionalities of the rNBA package is data retrieval from http://stats.nba.com/. All of the data belongs to the NBA, so please abide by their Terms of Use when using and publishing any work resulting from the use of this package.

This package considers two classes of data sources: generic data and player tracking data. Generic data is a blanket term for most of the data that can be found on http://stats.nba.com/. This includes everything from player bio information to historic draft results. Player tracking data refers specifically to advanced player stats that are found under the Player Tracking tab on the webiste.

Retrieving Generic Data

The function for retrieving a generic data source is getGenericData. This function takes two arguments: a data source and a list of parameters for that data source. The available data sources can be explored with the searchEndpoints function, and the parameters for a specific data source are found with the getEndpointParams function.

For example, let's say that I am interested in getting some information on Kobe Bryant, so I want to see what sources of player data are available.

rNBA::searchEndpoints("player")

There are many sources of player data, but the "playercareerstats" one looks promising. Now I need to see what the required parameters for this source are.

rNBA::getEndpointParams("playercareerstats")

There are two parameters for this data source: PerMode and PlayerID. For now, let's just say that I want PerMode to be "PerGame" and that I know that Kobe Bryant's ID is 977 (see below for more information on this). Now I can make a call to getGenericData to get this data source.

player.career.stats <- rNBA::getGenericData(endpoint = "playercareerstats", 
                                            params = list(PerMode = "PerGame", PlayerID = 977))

What did getGenericData return? In this case, we got a list of 8 data frames with some data on Kobe Bryant. In general, getGenericData will return a list of data frames, except when the list would have only one element, in which case just a data frame is returned.

Parameter Formatting

Above, the values for the "PerMode" and "PlayerID" parameters seemed to come out of nowhere. First, consider the "PlayerID". This parameter (along with "TeamID") is very common, and it is a unique identifier. The getIDMappings function returns a mapping between player and team ID's and player and team names.

m <- rNBA::getIDMappings()

However, unless you need the full mapping, a more convenient way to search for an ID is with the searchIDMappings function. The PlayerID for Kobe Bryant, for example, can be found as shown below.

rNBA::searchIDMappings(player = "kobe")

For other parameters such as "PerMode", the meaning and appropriate values are sometimes self explanatory. However, often times they are not. See the wiki page on GitHub (user llefebure, repo "nba-stats") for a more complete guide on the meaning and format of parameters (repo may still be private at the time of this reading).

Retrieving Player Tracking Data

The process for retrieving player tracking data is more straightforward. There is a single function getPlayerTrackingData that takes as parameters the year from which to return data (2014 refers to 2014-15 season) and the type (valid types are "catchShootData", "defenseData", "drivesData", "passingData", "touchesData", "pullUpShootData", "reboundingData", "shootingData", or "speedData"). This function returns a list of data frames if multiple types are requested, and a single data frame if only one type is requested. Refer to http://stats.nba.com/ for the meaning of most of these stats.

drives <- rNBA::getPlayerTrackingData(year = 2015, "drivesData")

Plotting

This package allows the user to build custom shot charts. A shot chart is a scatterplot of the locations from which a player takes shots overlayed onto an outline of the court. They are a very powerful visualization tool to analyze the shooting preferences and efficiency of players. Raw shots data can be retrieved with getGenericData through the "shotchartdetail" endpoint. The package also includes an interactive app for building shot charts (see launchApp), although the functionality described here provides the building blocks for more customized charts.

Plotting the Court

This package provides two functions for assisting in plotting the lines of an NBA court: courtOutline and courtOutlinePlot. The first returns a data frame of coordinates of line segments that, when connected, draw the lines of an NBA court. One optional parameter specifies whether to get the coordinates of the full court or only half the court (default is half court).

half.court <- rNBA::courtOutline()
full.court <- rNBA::courtOutline(full = TRUE)
head(half.court)

Using base graphics, the lines can be plotted as follows.

examplePlotLines <- function(court) {
  plot(x = NULL, xlim = range(court$x), ylim = range(court$y), xaxt = "n", yaxt = "n", ann = FALSE)
  for (nm in unique(court$type)) {
     s <- court$type == nm
     points(x = court$x[s], y = court$y[s], type = "l", lty = court$ltype[s])
  } 
}
examplePlotLines(half.court)
examplePlotLines(full.court)

The second function, courtOutlinePlot, essentially produces the same plot as above except that it uses ggplot. This function would likely be preferable for almost all applications, as ggplot makes it easy to add layers. Again, one optional parameter specifies whether to plot the full court or only half the court (default is half court).

p.half <- rNBA::courtOutlinePlot()
p.full <- rNBA::courtOutlinePlot(full = TRUE)

p.half

Basic Shot Charts

The above functions can be used as a starting point for building a custom shot chart. Calling getGenericData with the "shotchartdetail" endpoint gets raw (x, y) coordinates of shots in the same coordinate axis as the above plots that can then be plotted directly on those plots. However, the package also includes a function shotChart that builds a basic complete shot chart for you. This function returns a list with two elements: the plot and the raw data from which the plot was built. With no arguments, this function will produce a default chart for Steph Curry using the stephCurryShots data that is attached to the package.

sc1 <- rNBA::shotChart()
sc1$plot

Arguments can be supplied to customize. See the Custom Shot Charts vignette or the documentation for shotChart for further information.

Using the Shiny Apps

The following vignette entails the working of the shiny apps included in the package:

• "draft" : This shiny app lets you explore the history of NBA drafts by colleges varying over years. For example: You can select "Stanford" and see in a histogram formulation which teams drafted Stanford players. Also, you can download the histogram as a plot.

• "shotcharts" : This shiny app lets you plot and download shot chart of a player with varying attributes including missed/not missed shot, in which quarter the shot was made etc. For example: You can choose "Stephen Curry" with outcome as an attribute which would plot the shots made and missed by Stephen Curry over the past twenty games.

Launching an app

Use launchApp() with the name of the App to start using the interface

rNBA::launchApp("draft")
rNBA::launchApp("shotcharts")

llefebure/nba-stats documentation built on May 21, 2019, 7:34 a.m.