Skip to main content
Version: main

sdvplot.bokeh

The Bokeh adapter: logos, wordmarks and headshots as one image_url glyph per call on a Bokeh figure.

NameWhat it is
add_binsDraw hexagonal or square bins, colored by count or weight, as one patches glyph on a Bokeh figure.
add_headshotsDraw each player's headshot centred on its (x, y) point of a Bokeh figure.
add_logosDraw each team's logo centred on its (x, y) point of a Bokeh figure.
add_wordmarksDraw each team's wordmark centred on its (x, y) point of a Bokeh figure.
axis_logosNot supported on Bokeh: Bokeh glyphs cannot sit outside the plot frame at a fixed pixel offset.

add_bins​

add_bins(
target: Any,
x: Any,
y: Any,
*,
shape: Literal['hex', 'square'] = 'hex',
radius: float | None = None,
side: float | None = None,
equal_area: bool = False,
ids: Any = None,
weights: Any = None,
origin: tuple[float, float] = (0.0, 0.0),
value: Literal['count', 'weight'] = 'count',
fill: float | None = None,
min_count: int = 1,
palette: Any = 'Viridis256',
alpha: float = 1.0,
link: Any = None,
) -> Any

Draw hexagonal or square bins, colored by count or weight, as one patches glyph on a Bokeh figure.

The cells are sdvplot.binner's, in data units. The glyph (named "sdvplot_bins") has its own ColumnDataSource, one row per cell: xs/ys (the polygon), x/y (the centre), count, weight, bin_id ("x,y", as sdvplot-js stamps data-sdv-id), point_ids (the ids of its points) and rows (their row numbers); a linear_cmap on value (count or weight) colors it.

Linking: pass the points' ColumnDataSource (row i is the point at x[i], y[i]) as link, and two CustomJS callbacks tie the selections in the browser, with no server: selecting cells (with a tap or box_select tool on the figure) selects their points, and selecting points (in any glyph or DataTable on that source) selects the cells holding them. A selection already consistent both ways is left as it is.

Arguments​

NameTypeDescription
targetAnyA bokeh.plotting figure.
xAnyThe points' x values, in data units.
yAnyThe points' y values.
shapeLiteral['hex', 'square']"hex" (the default) or "square".
radiusfloat | NoneThe hexagon's circumradius, in data units; for squares, with equal_area=True.
sidefloat | NoneThe square's side (shape="square").
equal_areaboolSquares of a radius-radius hexagon's area.
idsAnyOptional link ids, one per point (default the row number); see sdvplot.hexbin.
weightsAnyOptional non-negative weights, one per point (see sdvplot.hexbin): each bin's weight.
origintuple[float, float]The point a cell centre falls on (default (0.0, 0.0)): a hoop-centred lattice, origin = the basket's coordinates.
valueLiteral['count', 'weight']What the fill encodes: "count" (the default, the points in each cell) or "weight" (the sum of their weights).
fillfloat | NoneThe drawn cell's size as a fraction of the lattice cell, in (0, 1]: default 0.88 for squares (a gap, so they do not touch edge to edge) and 1.0 for hexagons (the tiled hexbin look).
min_countintCells with fewer points are not drawn (default 1, every cell). min_count=2 suits shot charts: single attempts are not drawn. sdvplot.hexbin / squarebin still return every cell.
paletteAnyA Bokeh palette name or list of colors (default "Viridis256"), fewest to most points.
alphafloatThe cells' fill opacity, 0 to 1.
linkAnyOptional ColumnDataSource of the same points, in the same order, to link selections with.

Returns​

figure — target, with the glyph added.

Raises​

  • InputError: If the lattice options are not valid (see sdvplot.binner), value is not "count" or "weight", fill is not in (0, 1], min_count is not a whole number >= 1, or alpha is outside [0, 1].
  • UnsupportedTargetError: If target is not a bokeh.plotting figure.
  • TypeError: If link is not a ColumnDataSource.
  • ValueError: If x, y and ids differ in length, or link does not hold one row per point.

Example​

from bokeh.models import ColumnDataSource
from bokeh.plotting import figure
from sdvplot.bokeh import add_bins

# three Brooklyn shots of 2025-26, legacy tenths of a foot (sportsdataverse-data nba_stats_shots)
shots = ColumnDataSource({"x": [0, -1, -44], "y": [0, 7, 252]})
p = figure(tools="tap,box_select,reset", frame_height=300)
p.scatter("x", "y", source=shots)
add_bins(p, shots.data["x"], shots.data["y"], shape="square", side=15, alpha=0.6, link=shots)

See also​

add_headshots​

add_headshots(
target: Any,
x: Any,
y: Any,
players: Any,
*,
league: str,
height: float = 0.1,
alpha: float = 1,
embed: bool = False,
id_system: str = 'espn',
) -> Any

Draw each player's headshot centred on its (x, y) point of a Bokeh figure.

Arguments​

NameTypeDescription
targetAnyA bokeh.plotting.figure.
xAnyThe points' x positions, in the figure's x values.
yAnyThe points' y positions, the same length as x.
playersAnyThe player id for each point.
leaguestrThe SDV league key, e.g. "nfl".
heightfloatThe headshot height as a fraction of the reference height (see add_logos), in (0, 1].
alphafloatOpacity, 0 to 1.
embedboolInline each image as a data URI instead of linking its URL.
id_systemstr"espn" (ESPN athlete ids), "gsis" (NFL) or "league" (the league's own player id: nfl gsis, NBA and WNBA Stats ids, MLBAM, NHL), as in headshot_url.

Returns​

object — target itself, with one renderer named sdvplot_headshot added.

Raises​

  • InputError: (a ValueError) If height or alpha is out of range, league has no ESPN headshots, or id_system is not valid for league.
  • ValueError: If the inputs differ in length, or the figure has no pixel height (neither frame_height nor height is set).
  • UnsupportedTargetError: (a TypeError) If target is not a Bokeh figure.
  • OfflineError: If the nflverse player table (id_system="gsis"), or with embed=True a headshot, is neither cached nor downloadable (a DownloadError, also an OSError, for an HTTP error status).
  • UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or redirected away from https.

Example​

from bokeh.plotting import figure
import sdvplot

p = figure(frame_height=300)
sdvplot.add_headshots(p, [0.5], [0.5], ["3139477"], league="nfl", height=0.2)

See also​

add_logos​

add_logos(
target: Any,
x: Any,
y: Any,
teams: Any,
*,
league: str,
season: Any = None,
height: float = 0.1,
alpha: float = 1,
variant: str = 'default',
embed: bool = False,
id_system: str = 'auto',
) -> Any

Draw each team's logo centred on its (x, y) point of a Bokeh figure.

The logos are sized in screen pixels, so they keep their size when the user zooms. height is a fraction of the figure's frame_height (the plot area) when it is set, else of its height (the whole canvas, a little taller than the plot area): set frame_height for the same sizing as the other libraries.

Arguments​

NameTypeDescription
targetAnyA bokeh.plotting.figure.
xAnyThe points' x positions, in the figure's x values (numbers, factors or datetimes).
yAnyThe points' y positions, the same length as x.
teamsAnyThe team for each point, in any id system resolve() understands.
leaguestrThe SDV league key, e.g. "nfl".
seasonAnyOne season, or one per point, to pick each team's mark for that era.
heightfloatThe logo height as a fraction of the reference height, in (0, 1].
alphafloatOpacity, 0 to 1.
variantstr"default", "dark", or a named variant from marks().
embedboolInline each image as a data URI (HTML that renders offline) instead of linking its URL.
id_systemstrThe id system of teams; "auto" tries each in order.

Returns​

object — target itself, with one image_url renderer named sdvplot_logo added.

Raises​

  • InputError: (a ValueError) If height or alpha is out of range, league, id_system or variant is unknown, or season is not a year or is outside the seasons sdvplot knows for the league.
  • ValueError: If the inputs differ in length, or the figure has no pixel height (neither frame_height nor height is set).
  • UnsupportedTargetError: (a TypeError) If target is not a Bokeh figure.
  • OfflineError: If the logo manifest, or with embed=True a mark's image, is neither cached nor downloadable (a DownloadError, also an OSError, when the CDN answers with an error status; an IntegrityError when it sends a file that does not match the manifest's sha256).
  • UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) If embed=True and the manifest's sha256 or extension for a mark would put the file outside the cache directory.

Example​

from bokeh.plotting import figure
import sdvplot

p = figure(frame_width=400, frame_height=300)
p.scatter([10, 20], [-3, -7])
sdvplot.add_logos(p, [10, 20], [-3, -7], ["KC", "BUF"], league="nfl", height=0.15)

See also​

add_wordmarks​

add_wordmarks(
target: Any,
x: Any,
y: Any,
teams: Any,
*,
league: str,
season: Any = None,
height: float = 0.1,
alpha: float = 1,
variant: str = 'default',
embed: bool = False,
id_system: str = 'auto',
) -> Any

Draw each team's wordmark centred on its (x, y) point of a Bokeh figure.

Arguments​

NameTypeDescription
targetAnyA bokeh.plotting.figure.
xAnyThe points' x positions, in the figure's x values.
yAnyThe points' y positions, the same length as x.
teamsAnyThe team for each point, in any id system resolve() understands.
leaguestrThe SDV league key, e.g. "nfl".
seasonAnyOne season, or one per point.
heightfloatThe wordmark height as a fraction of the reference height (see add_logos), in (0, 1].
alphafloatOpacity, 0 to 1.
variantstr"default", "dark", or a named variant from marks().
embedboolInline each image as a data URI instead of linking its URL.
id_systemstrThe id system of teams; "auto" tries each in order.

Returns​

object — target itself, with one renderer named sdvplot_wordmark added.

Raises​

  • InputError: (a ValueError) If height or alpha is out of range, league, id_system or variant is unknown, or season is not a year or is outside the seasons sdvplot knows for the league.
  • ValueError: If the inputs differ in length, or the figure has no pixel height (neither frame_height nor height is set).
  • UnsupportedTargetError: (a TypeError) If target is not a Bokeh figure.
  • OfflineError: If the logo manifest, or with embed=True a mark's image, is neither cached nor downloadable (a DownloadError, also an OSError, when the CDN answers with an error status; an IntegrityError when it sends a file that does not match the manifest's sha256).
  • UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) If embed=True and the manifest's sha256 or extension for a mark would put the file outside the cache directory.

Example​

from bokeh.plotting import figure
import sdvplot

p = figure(x_range=["KC", "BUF"], frame_height=300)
p.vbar(x=["KC", "BUF"], top=[12, 10], width=0.8)
sdvplot.add_wordmarks(p, ["KC", "BUF"], [12, 10], ["KC", "BUF"], league="nfl", height=0.06)

See also​

axis_logos​

axis_logos(target: Any, axis: str, **kwargs: Any) -> Any

Not supported on Bokeh: Bokeh glyphs cannot sit outside the plot frame at a fixed pixel offset.

Arguments​

NameTypeDescription
targetAnyA Bokeh figure.
axisstr"x" or "y".
**kwargsAnyIgnored.

Returns​

object — Never returns.

Raises​

  • UnsupportedTargetError: (a TypeError) Always. Draw the logos inside the plot with add_logos at a y below the bars, or use the matplotlib, Plotly or Altair adapter for axis logos.

Example​

from bokeh.plotting import figure
import sdvplot

try:
sdvplot.axis_logos(figure(), "x", league="nfl")
except TypeError:
pass # raised: Bokeh has no axis logos yet

See also​