sdvplot.plotly
The Plotly adapter: logos, wordmarks, headshots and axis logos as layout images on a Plotly Figure.
| Name | What it is |
|---|---|
| add_headshots | Draw each player's headshot centred on its (x, y) point of a Plotly figure. |
| add_logos | Draw each team's logo centred on its (x, y) point of a Plotly figure, as layout images. |
| add_wordmarks | Draw each team's wordmark centred on its (x, y) point of a Plotly figure. |
| axis_logos | Replace 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
| Name | Type | Description |
|---|---|---|
target | Any | A plotly.graph_objects.Figure. |
x | Any | The points' x positions in the axis' own values. |
y | Any | The points' y positions, the same length as x. |
players | Any | The player id for each point. |
league | str | The SDV league key, e.g. "nfl". |
height | float | The headshot height as a fraction of the plot area's height, in (0, 1]. |
alpha | float | Opacity, 0 to 1. |
xref | str | The x axis to place on. |
yref | str | The y axis to place on. |
layer | str | "above" or "below" the traces. |
embed | bool | Inline each image as a data URI instead of linking its URL. |
id_system | str | "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) Ifheightoralphais out of range,leaguehas no ESPN headshots, orid_systemis not valid forleague.ValueError: If the inputs differ in length, or an axis is not supported (seeadd_logos).UnsupportedTargetError: (a TypeError) Iftargetis not a PlotlyFigure.OfflineError: If the nflverse player table (id_system="gsis"), or withembed=Truea 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
| Name | Type | Description |
|---|---|---|
target | Any | A plotly.graph_objects.Figure (or FigureWidget). |
x | Any | The points' x positions in the axis' own values (numbers, or category names). |
y | Any | The points' y positions, the same length as x. |
teams | Any | The team for each point, in any id system resolve() understands. |
league | str | The SDV league key, e.g. "nfl". |
season | Any | One season, or one per point, to pick each team's mark for that era. |
height | float | The logo height as a fraction of the plot area's height, in (0, 1]. |
alpha | float | Opacity, 0 to 1. |
variant | str | "default", "dark", or a named variant from marks(). |
xref | str | The x axis to place on ("x", "x2", ...), for subplots. |
yref | str | The y axis to place on ("y", "y2", ...). |
layer | str | "above" or "below" the traces. |
embed | bool | Inline each image as a data URI (HTML that renders offline, and static export with kaleido) instead of linking its URL. |
id_system | str | The 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) Ifheightoralphais out of range,league,id_systemorvariantis unknown, orseasonis not a year or is outside the seasons sdvplot knows for the league.ValueError: If the inputs differ in length,xref/yrefdoes 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 abase,barnormor stackedoffsetgroup(set the range first).UnsupportedTargetError: (a TypeError) Iftargetis not a PlotlyFigure.OfflineError: If the logo manifest, or withembed=Truea 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) Ifembed=Trueand 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
| Name | Type | Description |
|---|---|---|
target | Any | A plotly.graph_objects.Figure. |
x | Any | The points' x positions in the axis' own values. |
y | Any | The points' y positions, the same length as x. |
teams | Any | The team for each point, in any id system resolve() understands. |
league | str | The SDV league key, e.g. "nfl". |
season | Any | One season, or one per point. |
height | float | The wordmark height as a fraction of the plot area's height, in (0, 1]. |
alpha | float | Opacity, 0 to 1. |
variant | str | "default", "dark", or a named variant from marks(). |
xref | str | The x axis to place on. |
yref | str | The y axis to place on. |
layer | str | "above" or "below" the traces. |
embed | bool | Inline each image as a data URI instead of linking its URL. |
id_system | str | The id system of teams; "auto" tries each in order. |
Returns
object — target itself, with the images added.
Raises
InputError: (a ValueError) Ifheightoralphais out of range,league,id_systemorvariantis unknown, orseasonis 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 (seeadd_logos).UnsupportedTargetError: (a TypeError) Iftargetis not a PlotlyFigure.OfflineError: If the logo manifest, or withembed=Truea 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) Ifembed=Trueand 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
| Name | Type | Description |
|---|---|---|
target | Any | A 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". |
axis | str | "x" or "y" (the first x or y axis). |
league | str | The SDV league key, e.g. "nfl". |
season | Any | One season for every label. |
height | float | The image height as a fraction of the plot area's height, in (0, 1]. |
variant | str | "default", "dark", or a named variant from marks(). |
mark_type | Literal['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. |
embed | bool | Inline each image as a data URI instead of linking its URL. |
id_system | str | The 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) Ifheightis out of range,league,id_system,mark_typeorvariantis unknown, orseasonis not a year or is outside the seasons sdvplot knows for the league.ValueError: Ifaxisis not "x"/"y", or the axis is not a category axis.UnsupportedTargetError: (a TypeError) Iftargetis not a PlotlyFigure.OfflineError: If the logo manifest, or withembed=Truea 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) Ifembed=Trueand 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)