Skip to main content
Version: 0.1.1

sdvplot.plotly

The Plotly adapter: logos, wordmarks, headshots and axis logos as layout images on a Plotly Figure.

NameWhat it is
add_headshotsDraw each player's headshot centred on its (x, y) point of a Plotly figure.
add_logosDraw each team's logo centred on its (x, y) point of a Plotly figure, as layout images.
add_wordmarksDraw each team's wordmark centred on its (x, y) point of a Plotly figure.
axis_logosReplace a category axis' team labels with the teams' logos (or wordmarks), or a player axis' with headshots.

add_headshots​

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

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

Arguments​

NameTypeDescription
targetAnyA plotly.graph_objects.Figure.
xAnyThe points' x positions in the axis' own 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 plot area's height, in (0, 1].
alphafloatOpacity, 0 to 1.
xrefstrThe x axis to place on.
yrefstrThe y axis to place on.
layerstr"above" or "below" the traces.
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 the images 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 an axis is not supported (see add_logos).
  • UnsupportedTargetError: (a TypeError) If target is not a Plotly 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​

import plotly.graph_objects as go
import sdvplot

fig = go.Figure(go.Scatter(x=[0.3, 0.7], y=[0.5, 0.5], mode="markers"))
sdvplot.add_headshots(fig, [0.3], [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',
xref: str = 'x',
yref: str = 'y',
layer: str = 'above',
embed: bool = False,
id_system: str = 'auto',
) -> Any

Draw each team's logo centred on its (x, y) point of a Plotly figure, as layout images.

Call it after adding the traces: an axis range that is not set is worked out from the scatter and bar traces (stacked bars included) and the new points, with half a logo of room at each end (Plotly clips images at the plot edge), and pinned, because a data-placed image is sized in axis units. The logos then zoom with the data. Linear and category axes are supported (a category is placed at its index).

Arguments​

NameTypeDescription
targetAnyA plotly.graph_objects.Figure (or FigureWidget).
xAnyThe points' x positions in the axis' own values (numbers, or category names).
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 plot area's height, in (0, 1].
alphafloatOpacity, 0 to 1.
variantstr"default", "dark", or a named variant from marks().
xrefstrThe x axis to place on ("x", "x2", ...), for subplots.
yrefstrThe y axis to place on ("y", "y2", ...).
layerstr"above" or "below" the traces.
embedboolInline each image as a data URI (HTML that renders offline, and static export with kaleido) instead of linking its URL.
id_systemstrThe id system of teams; "auto" tries each in order.

Returns​

object — target itself, with the images added (like Plotly's own add_* methods).

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, xref/yref does not name an x/y axis, an axis is a log or date axis, or the range must be worked out from a trace type other than scatter or bar, stacked scatter traces (stackgroup), or bars with a base, barnorm or stacked offsetgroup (set the range first).
  • UnsupportedTargetError: (a TypeError) If target is not a Plotly 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​

import plotly.graph_objects as go
import sdvplot

fig = go.Figure(go.Scatter(x=[10, 20], y=[-3, -7], mode="markers"))
sdvplot.add_logos(fig, [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',
xref: str = 'x',
yref: str = 'y',
layer: str = 'above',
embed: bool = False,
id_system: str = 'auto',
) -> Any

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

Arguments​

NameTypeDescription
targetAnyA plotly.graph_objects.Figure.
xAnyThe points' x positions in the axis' own 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 plot area's height, in (0, 1].
alphafloatOpacity, 0 to 1.
variantstr"default", "dark", or a named variant from marks().
xrefstrThe x axis to place on.
yrefstrThe y axis to place on.
layerstr"above" or "below" the traces.
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 the images 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 an axis is not supported (see add_logos).
  • UnsupportedTargetError: (a TypeError) If target is not a Plotly 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​

import plotly.graph_objects as go
import sdvplot

fig = go.Figure(go.Bar(x=["KC", "BUF"], y=[12, 10]))
sdvplot.add_wordmarks(fig, ["KC", "BUF"], [12, 10], ["KC", "BUF"], league="nfl", height=0.08)

See also​

axis_logos​

axis_logos(
target: Any,
axis: str,
*,
league: str,
season: Any = None,
height: float = 0.1,
variant: str = 'default',
mark_type: Literal['logo', 'wordmark', 'headshot'] = 'logo',
embed: bool = False,
id_system: str = 'auto',
) -> Any

Replace a category axis' team labels with the teams' logos (or wordmarks), or a player axis' with headshots.

The images sit in paper coordinates just outside the plot (under the x axis, left of the y axis), height of the plot area tall; labels that are not teams stay as text, with one SdvplotWarning. The bottom (left) margin grows to make room. Call it after adding the traces, so the axis has its categories.

Arguments​

NameTypeDescription
targetAnyA plotly.graph_objects.Figure whose axis is a category axis. Player ids look numeric to Plotly (and to this inference): for a headshot axis give the axis type="category".
axisstr"x" or "y" (the first x or y axis).
leaguestrThe SDV league key, e.g. "nfl".
seasonAnyOne season for every label.
heightfloatThe image height as a fraction of the plot area's height, in (0, 1].
variantstr"default", "dark", or a named variant from marks().
mark_typeLiteral['logo', 'wordmark', 'headshot']"logo", "wordmark" or "headshot". With "headshot" the labels are player ids (id_system "espn", "gsis" or "league" as in headshot_url, "auto" meaning "espn"; season is ignored), drawn at their own aspect.
embedboolInline each image as a data URI instead of linking its URL.
id_systemstrThe id system of the labels; "auto" tries each in order.

Returns​

object — target itself, with the images added and the resolved labels blanked.

Raises​

  • InputError: (a ValueError) If height is out of range, league, id_system, mark_type or variant is unknown, or season is not a year or is outside the seasons sdvplot knows for the league.
  • ValueError: If axis is not "x"/"y", or the axis is not a category axis.
  • UnsupportedTargetError: (a TypeError) If target is not a Plotly 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​

import plotly.graph_objects as go
import sdvplot

fig = go.Figure(go.Bar(x=["KC", "BUF", "BAL"], y=[12, 10, 9]))
sdvplot.axis_logos(fig, "x", league="nfl", height=0.1)

See also​