d3-shotchart

Basketball fans are paying attention to stats and advanced metrics more than ever. There exists few open source tools to help facilitate the display and distribution of the data fans care about. With d3-shotchart, you can easily build a visualization that enables fans to interact with NBA shot data (publicly available elsewhere).

Installing

If you use NPM, npm install d3-shotchart. Otherwise, download the latest release.

Dependencies

d3-shotchart depends on d3-tip and d3-hexbin Be sure to include these dependencies above d3-shotchart in your code.

Data Requirements

Minimum requirements

The bare minimum data requirements for the plugin to display data are:

1. x coordinate with a value betweeon 0-50
2. y coordinate with a value between 0-47

Example format:

[ 
  {
    "x": 19.5,
    "y": 28.45
  }
]

Tooltip requirements

To take full advantage of the tooltip functionality, your data should include a few other publicly available data points:

• "Action Type"
• "Shot Distance"

Example format:

[ 
  {
    "x": 19.5,
    "y": 28.45,
    "action_type": "Jump Shot",
    "shot_distance": 24,
  }
]

Demo

Here is an interactive visualization of Philadelphia 76ers data that takes advantage of most of d3-shotchart's configuration options.

Example usage

<div id="shot-chart"></div>
 
<script src="https://cdnjs.cloudflare.com/ajax/libs/d3/4.4.0/d3.min.js"></script> 
<script src="https://d3js.org/d3-hexbin.v0.2.min.js"></script> 
<script src="https://cdnjs.cloudflare.com/ajax/libs/d3-tip/0.7.1/d3-tip.min.js"></script>
<script src="d3-shotchart.js" ></script>
<script src="shots.js" ></script>
 
<script> 
    var courtSelection = d3.select("#shot-chart");
    var court = d3.court().width(600);
    var shots = d3.shots().shotRenderThreshold(1).displayToolTips(true).displayType("hexbin");
    courtSelection.call(court);
    courtSelection.datum(data).call(shots);
</script>

API Reference

# court()

Constructs a new default court generator.

# court.width([width])

If width is specified, sets the courth width to the specified number and returns the court generator. If width is not specified, returns the current court width accessor, which defaults to:

function width() {
  return 500;
}

Court height is always automatically generated as a function of court width. Default NBA half-court dimensions are 50 x 47 feet. As such, the height of the court is always equal to .94 * court width.

# shots()

Constructs a new default shots generator.

# shots.displayType([displayType])

displayType can only be one of two values:

1. "scatter"
2. "hexbin"

If displayType is specified, sets shot display type to the specified value and returns the shots generator. If displayType is not specified, returns the current shot displayType accessor, which defaults to:

function displayType() {
  return "scatter";
}

# shots.shotRenderThreshold([shotRenderThreshold])

shotRenderThreshold can be any integer greater than 0

If shotRenderThreshold is specified, sets the minimum number of shots required for a hexbin to display and returns the shots generator. If displayType is not specified, returns the current shot displayType accessor, which defaults to:

function shotRenderThreshold() {
  return 1;
}

# shots.displayToolTips([displayToolTips])

displayToolTips can only be set to true or false

If displayToolTips is specified, sets the tool tip display to the specified value and returns the shots generator. If displayToolTips is not specified, returns the current shot displayToolTips accessor, which defaults to:

function shotRenderThreshold() {
  return false;
}