Welcome to NBAGrapher’s documentation!

NBA Grapher is a small utility tool that automates the process of scraping data from basketball-reference and uses matplotlib to create frequenty used graphs.

The tool was initially built with sportsreference for simple scatter plots. Since then, the scraping has been switched to a slightly modified version of basketball_reference_scraper, which allows greater flexibility for choosing between Per game, per minute and per possession statistics as well as filtering between playoffs and the regular season.

To maintain backward compatibility, the original functions based on sportsreference are present in the current version, however radar charts and shot charts require basketball_reference_scraper.

Graphical functions

For the stats supported by each function see List of Sportsreference stats

Scatter plots

These are simple 2d plots that shows a player or a team’s progression through seasons or games within a season

nbagrapher.grappher.plot_player_season(players, stat, start_year=0, end_year=3000, xlabel='Year', ylabel=None, scatter=True, return_type='img', cum=False)

Uses sportsreference

Plots the graphs for seasons of a player or a list of players by seasons. Stats are from the regular season collected at the end of the season.

Parameters:
  • players (String or list of strings) – Basketball-reference id of a player
  • stat (String) – The statistical attribute of the player to plot
  • start_year (Integer) – Starting year from which to plot
  • end_year (Integer) – Ending year until which to plot
  • xlabel (String) – The label on the x-axis on the returned plot
  • ylabel (String) – The label on the x-axis on the returned plot
  • scatter (Bool) – Whether on not to include a dot for each data point in the graph
  • return_type ("img": png image, "fig":Matplotlib figure and axes,"show": calls the matplotlib show function (appropriate for jupyter notebooks), "html": base64 image useful for rendering in html pages) – Various methods by which the graph can be returned
  • cum (Bool) – Whether results are cumulative or not
nbagrapher.grappher.plot_player_game(players, season, stat, start_date=datetime.date(1900, 1, 1), end_date=datetime.date(3000, 1, 1), only_month=False, xlabel='Time', ylabel=None, scatter=True, return_type='img', cum=False)

Uses Sportsreference Plots the graphs of players according to their performance in particular games.

Parameters:
  • players (String or list of strings) – Basketball-reference id of a player or list of players
  • season (Either in dashed form (2018-19) or single form (2019 means the season 2018-19)) – The season in which the games are played
  • stat (String) – The statistical attribute of the player to plot
  • start_date (datetime.date format) – The date from which the data is plotted
  • end_date (datetime.date format) – The date untill which data is plotted
  • only_month (Bool) – Wheter or not the ticks on the x-axis only contain months. (Recommended when plotting dates extending across dates more than a couple of months)
  • xlabel (String) – The label on the x-axis on the returned plot
  • ylabel (String) – The label on the x-axis on the returned plot
  • scatter (Bool) – Wheter on not to include a dot for each data point in the graph
  • return_type ("img": png image, "fig":Matplotlib figure and axes,"show": calls the matplotlib show function (appropriate for jupyter notebooks), "html": base64 image useful for rendering in html pages) – Various methods by which the graph can be returned
  • cum (Bool) – Wheter results are cumulative or not
nbagrapher.grappher.plot_team_season(teams, stat, start_season, end_season, opp=False, xlabel='Year', ylabel=None, scatter=True, return_type='img', cum=False)
Uses Sportsreference
Plots the graph of a team or a list of teams by seasons. Stats are from the regular season collected at the end of the season.
Parameters:
  • teams (String or list of strings) – Basketball-reference id for team
  • stat (String) – The statistical attribute of the player to plot
  • start_season (Integer) – Starting season from which to plot
  • end_season (Integer) – Last season until which to plot
  • opp (Bool) – Whether the stat is for the opponent
  • xlabel (String) – The label on the x-axis on the returned plot
  • ylabel (String) – The label on the y-axis on the returned plot
  • scatter (Bool) – Whether on not to include a dot for each data point in the graph
  • return_type ("img": png image, "fig":Matplotlib figure and axes,"show": calls the matplotlib show function (appropriate for jupyter notebooks), "html": base64 image useful for rendering in html pages) – Various methods by which the graph can be returned
  • cum (Bool) – Whether results are cumulative or not
nbagrapher.grappher.plot_team_game(teams, stat, season, start_date, end_date, opp=False, xlabel='Time', ylabel=None, only_month=False, scatter=True, return_type='img', cum=False)

Uses Sportsreference

Parameters:
  • teams (String or list of strings) – Basketball-reference id for team
  • stat (String) – The statistical attribute of the player to plot
  • season (Either in dashed form (2018-19) or single form (2019 means the season 2018-19)) – The season in which the games are played
  • start_date (datetime.date format) – The date from which the data is plotted
  • end_date (datetime.date format) – The date untill which data is plotted
  • opp (Bool) – Whether the stat is for the opponent
  • xlabel (String) – The label on the x-axis on the returned plot
  • ylabel (String) – The label on the Y-axis on the returned plot
  • scatter (Bool) – Whether on not to include a dot for each data point in the graph
  • return_type ("img": png image, "fig":Matplotlib figure and axes,"show": calls the matplotlib show function (appropriate for jupyter notebooks), "html": base64 image useful for rendering in html pages) – Various methods by which the graph can be returned
  • cum (Bool) – Whether results are cumulative or not
nbagrapher.grappher.player_season(players, stat, stat_type='PER_GAME', players_label=None, playoffs=False, start_year=0, end_year=3000, xlabel='Year', ylabel=None, scatter=True, return_type='img', cum=False)

Uses Basketball_reference_scraper

Plots the graphs for seasons of a player or a list of players by seasons. Can specify whether to use the regular season only or regular season+playoffs

Parameters:
  • players (String or list of strings) – Basketball-reference id of a player or list of players
  • stat (String) – Statisitc to use
  • stat_type ("PER_GAME", "PER_MINUTE","PER_POSS","ADVANCED" :param stat:) – Type of statistic. PER_GAME by default
  • start_year (Integer) – Starting year from which to plot
  • end_year – Ending year until which to plot

:type end_year:Integer :param xlabel:The label on the x-axis on the returned plot :type xlabel: String :param ylabel:The label on the x-axis on the returned plot :type ylabel:String :param scatter:Whether on not to include a dot for each data point in the graph :type scatter:Boolean :param return_type:Various methods by which the graph can be returned :type return_type:”img”: png image, “fig”:Matplotlib figure and axes,”show”: calls the matplotlib show function (appropriate for jupyter notebooks), “html”: base64 image useful for rendering in html pages) :param cum:Whether results are cumulative or not :type cum:Boolean

Shot Charts

Mapping of shots on a 2d plot of a basketball court.

nbagrapher.grappher.player_shot_chart_season(player, season, playoffs=False, fig_type='scatter', hex_C='makes', hex_binsize=(30, 30), hex_minshots=10, return_type='img', figsize=(5, 4))

Uses basketball_reference_scraper Create a shot chart for a player from a particular season

Parameters:
  • player (String) – Basketball-reference id of a player
  • season (Integer) – Season to get the shots from
  • playoffs (Boolean) – Wheter or not to include the playoffs
  • fig_type ("scatter","hex") – Scatter plots every shot event as point. Hex creates bins of a certain size and counts the shots inside the point.
  • hex_C ("makes","miss","fg%","fg%_adj") – The statistic that gives magnitude to the hexbins. Makes and misses simply count makes and misses in each hexbin. fg% is the field goal percentage in each bin. fg%_adj is similar to TS%, it accounts for 3 pointers being more valuable than 2 pointers
  • hex_binsize (Tuple, (Integer,Integer)) – Number of hexbins in x and y directions. A greater value of hexbins means that each bins becomes smaller
  • hex_minshots (Integer) – Minimum shots needed to count a hexbin. Prevents bins with a small shot sample from diluting the data. Default is 10
  • figsize (Tuple containing size in inches) – Size of the matplotlib figure
  • return_type ("img": png image, "fig":Matplotlib figure and axes,"show": calls the matplotlib show function (appropriate for jupyter notebooks), "html": base64 image useful for rendering in html pages) – Various methods by which the graph can be returned

Radar Charts

Displaying multiple stats of one or multiple players.

nbagrapher.grappher.player_season_radar(players, season, player_labels=None, template='splits', playoffs=False, stat_type=None, stats=None, range=None, figsize=(8, 6), return_type='img')

Create a radar chart for a season of one or multiple players. You can customize the stats to include in the radar chart.

Parameters:
  • players (String or list of strings) – Basketball-reference id of a player
  • season (Integer) – Season to gets stat from
  • player_labels (List of strings) – Player labels to show in the legend, None to use Basketball-reference id
  • template ("splits","shooting","advanced","advanced_metrics") – Pre-defined statistics chosen on the based of templates.
  • playoffs (Boolean) – Include the playoffs or not
  • stat_type ("PER_GAME", "PER_MINUTE","PER_POSS","ADVANCED") – Type of statistic. Do not need to specify if using a template, however if needed according to context you can. For instance splits can be used with PER_GAME, PER_POSS or PER_MINUTE
  • stats (List of strings) – If the stats you need are not defined by a template, you can use stats to get a new radar chart
  • range (List of integers, eg [(0,10),(5,20)..]) – Range on the radar chart. By default, the lower range is the 10th percentile and upper range is 90th percentile of the stat in the 2019 NBA Season
  • figsize (Tuple containing size in inches) – Size of the matplotlib figure
  • return_type ("img": png image, "fig":Matplotlib figure and axes,"show": calls the matplotlib show function (appropriate for jupyter notebooks), "html": base64 image useful for rendering in html pages) – Various methods by which the graph can be returned

List of Sportsreference stats

Each of the function has a varying degree of statistical measurements available to it. Some measures that are available on the per-season basis are applicable on game-to-game basic. This document outlines the possible stats by each of the function. Each of the following stats should be provided to the function as a string.

plot_player_season()

All attributes available from the sportsreference.NBA.Player and sportsreference.NBA.AbstractPlayer. Details can be found in these pages.

  • and_ones
  • assist_percentage
  • assists
  • block_percentage
  • blocking_fouls
  • blocks
  • box_plus_minus
  • center_percentage
  • defensive_box_plus_minus
  • defensive_rebound_percentage
  • defensive_rebounds
  • defensive_win_shares
  • dunks
  • effective_field_goal_percentage
  • field_goal_attempts
  • field_goal_perc_sixteen_foot_plus_two_pointers
  • field_goal_perc_ten_to_sixteen_feet
  • field_goal_perc_three_to_ten_feet
  • field_goal_perc_zero_to_three_feet
  • field_goal_percentage
  • field_goals
  • free_throw_attempt_rate
  • free_throw_attempts
  • free_throw_percentage
  • free_throws
  • games_played
  • games_started
  • half_court_heaves
  • half_court_heaves_made
  • height
  • lost_ball_turnovers
  • minutes_played
  • nationality
  • net_plus_minus
  • offensive_box_plus_minus
  • offensive_fouls
  • offensive_rebound_percentage
  • offensive_rebounds
  • offensive_win_shares
  • on_court_plus_minus
  • other_turnovers
  • passing_turnovers
  • percentage_field_goals_as_dunks
  • percentage_of_three_pointers_from_corner
  • percentage_shots_three_pointers
  • percentage_shots_two_pointers
  • percentage_sixteen_foot_plus_two_pointers
  • percentage_ten_to_sixteen_footers
  • percentage_three_to_ten_footers
  • percentage_zero_to_three_footers
  • personal_fouls
  • player_efficiency_rating
  • player_id
  • point_guard_percentage
  • points
  • points_generated_by_assists
  • position
  • power_forward_percentage
  • salary
  • shooting_distance
  • shooting_fouls
  • shooting_fouls_drawn
  • shooting_guard_percentage
  • shots_blocked
  • small_forward_percentage
  • steal_percentage
  • steals
  • take_fouls
  • team_abbreviation
  • three_point_attempt_rate
  • three_point_attempts
  • three_point_percentage
  • three_point_shot_percentage_from_corner
  • three_pointers
  • three_pointers_assisted_percentage
  • total_rebound_percentage
  • total_rebounds
  • true_shooting_percentage
  • turnover_percentage
  • turnovers
  • two_point_attempts
  • two_point_percentage
  • two_pointers
  • two_pointers_assisted_percentage
  • usage_percentage
  • value_over_replacement_player
  • weight
  • win_shares
  • win_shares_per_48_minutes

plot_player_game()

All attributes available from the sportsreference.NBA.AbstractPlayer and sportsreference.NBA.BoxScorePlayer

  • assist_percentage
  • assists
  • block_percentage
  • blocks
  • box_plus_minus
  • defensive_rating
  • defensive_rebound_percentage
  • defensive_rebounds
  • effective_field_goal_percentage
  • field_goal_attempts
  • field_goal_percentage
  • field_goals
  • free_throw_attempt_rate
  • free_throw_attempts
  • free_throw_percentage
  • free_throws
  • minutes_played
  • offensive_rating
  • offensive_rebound_percentage
  • offensive_rebounds
  • personal_fouls
  • points
  • steal_percentage
  • steals
  • three_point_attempt_rate
  • three_point_attempts
  • three_point_percentage
  • three_pointers
  • total_rebound_percentage
  • total_rebounds
  • true_shooting_percentage
  • turnover_percentage
  • turnovers
  • two_point_attempts
  • two_point_percentage
  • two_pointers
  • usage_percentage

plot_team_season()

All attributes from sportsreference.NBA.teams.Teams. The attributes starting with “opp” refer to the value of the stat but for the opposing team. While these attributes can be used as well, if opposition stat is required it is recommend to use the opp=True parameter in the function.

  • abbreviation
  • assists
  • blocks
  • defensive_rebounds
  • field_goal_attempts
  • field_goal_percentage
  • field_goals
  • free_throw_attempts
  • free_throw_percentage
  • free_throws
  • games_played
  • minutes_played
  • name
  • offensive_rebounds
  • personal_fouls
  • points
  • rank
  • steals
  • three_point_field_goal_attempts
  • three_point_field_goal_percentage
  • three_point_field_goals
  • total_rebounds
  • turnovers
  • two_point_field_goal_attempts
  • two_point_field_goal_percentage
  • two_point_field_goals

plot_team_game()

  • assist_percentage
  • assists
  • block_percentage
  • blocks
  • defensive_rating
  • defensive_rebound_percentage
  • defensive_rebounds
  • effective_field_goal_percentage
  • field_goal_attempts
  • field_goal_percentage
  • field_goals
  • free_throw_attempt_rate
  • free_throw_attempts
  • free_throw_percentage
  • free_throws
  • losses
  • minutes_played
  • offensive_rating
  • offensive_rebound_percentage
  • offensive_rebounds
  • personal_fouls
  • points
  • steal_percentage
  • steals
  • three_point_attempt_rate
  • three_point_field_goal_attempts
  • three_point_field_goal_percentage
  • three_point_field_goals
  • total_rebound_percentage
  • total_rebounds
  • true_shooting_percentage
  • turnover_percentage
  • turnovers
  • two_point_field_goal_attempts
  • two_point_field_goal_percentage
  • two_point_field_goals
  • wins

List of basketball_reference_scraper stats

The variables in this section is the same as the one on a players basketball-reference page. For details, see the glossary in any player’s basketball-reference page. Example

PER_GAME

  • G
  • GS
  • MP
  • FG
  • FGA
  • FG%
  • 3P
  • 3PA
  • 3P%
  • 2P
  • 2PA
  • 2P%
  • eFG%
  • FT
  • FTA
  • FT%
  • ORB
  • DRB
  • TRB
  • AST
  • STL
  • BLK
  • TOV
  • PF
  • PTS

PER_MINUTE

  • G
  • GS
  • MP
  • FG
  • FGA
  • FG%
  • 3P
  • 3PA
  • 3P%
  • 2P
  • 2PA
  • 2P%
  • FT
  • FTA
  • FT%
  • ORB
  • DRB
  • TRB
  • AST
  • STL
  • BLK
  • TOV
  • PF
  • PTS

PER_POSS

  • G
  • GS
  • MP
  • FG
  • FGA
  • FG%
  • 3P
  • 3PA
  • 3P%
  • 2P
  • 2PA
  • 2P%
  • FT
  • FTA
  • FT%
  • ORB
  • DRB
  • TRB
  • AST
  • STL
  • BLK
  • TOV
  • PF
  • PTS
  • ORtg
  • DRtg

ADVANCED

  • G
  • MP
  • PER
  • TS%
  • 3PAr
  • FTr
  • ORB%
  • DRB%
  • TRB%
  • AST%
  • STL%
  • BLK%
  • TOV%
  • USG%
  • OWS
  • DWS
  • WS
  • WS/48
  • OBPM
  • DBPM
  • BPM
  • VORP

Radar Chart Templates

The stats that are included in each template for the radar chart. For details, see the glossary in any player’s basketball-reference page. Example

splits: [“MP”,”FG”,”FG%”,”STL”,”TOV”,”AST”,”TRB”,”PTS”]

shooting: [“3P”,”3P%”,”2P”,”2P%”,”eFG%”,”FT”,”FT%”]

advanced: [“PER”,”WS/48”,”VORP”,”TS%”,”BPM”]

advanced_metrics: [“3PAr”,”FTr”,”TRB%”,”AST%”,”STL%”,”BLK%”,”TOV%”,”USG%”]

Indices and tables