This repository contains code to gather shot data from the NBA stats api and perform an empirical analysis of the allocative efficiency exploratory methods introduced in Chuckers: Measuring Lineup Shot Distribution Optimality Using Spatial Allocative Efficiency Models. Our code relies on the r package nbastatR to gather shot data and from the NBA stats api. The demo can be carried out by running the following scripts in order:
get_shot_data.R
retrieves the 2016-17 regular season shot data and play by play data from NBA stats.get_lineup_data.R
retrieves 2016-17 regular season lineup minutes for the top 250 lineups for each team and merges that data with the shot data.discrete_court_regions.R
defines a coarse discretization of the court for our empirical LPL demo. For more nuanced spatial surfaces, we recommend following the modeling procedure outlined in our paper.empirical_lpl_demo.R
calculates and produces plots for a specified lineup's ranks, rank correspondence, LPL, and PLC surfaces empirically using the court regions defined indicrete_court_regions.R
.
While we recommend that users read our paper to understand the full details for each metric shown in this demo, we've provided a list of high-level definitions for reference:
-
Rank Plots: Show ranks of FG% (Field Goal %) and FGA (Field Goal Attempts) for each region of the court for all 5 players of a given lineup code. FG% is calculated as the percentage of shots that player X made. FGA rate is the number of shot attempts per 36 minutes by player X
-
Rank Correspondence: Rank Correspondence is defined as
(Rank of FGA) - (Rank of FG%)
This measures how strongly each player's FG% rank matches their FGA rank. A Rank Correspondence bigger than 0 is labeled asunder-use
because player X is taking fewer shots than his FG% warrants. On the other hand, a Rank Correspondence smaller than 0 is labelled asover-use
because player X is taking more shots than his FG% warrants. -
Lineup Points Lost (LPL): LPL is defined as the difference in expected points between the actual distribution of shot attempts from a given lineup and the expected points had those same shots been taken according to the optimal redistribution. Specifically, for court region i
where j indexes the 5 players in the lineup. In theory, higher LPL values correspond to greater inefficiencies while lower LPL entail higher efficiency. The demo shows LPL per 36 minutes and LPL per shot. -
Player LPL Contribution (PLC): PLC is defined as each player's individual contribution to LPL, while maintaining the directionality of their contribution (i.e. whether their contribution is due to over-use or under-use). These plots in this section show PLC per 36 minutes and PLC per shot for the 5 players in a given lineup.