Skip to main content
Version: main

sdvplot.plotnine

The plotnine adapter: logo, wordmark, headshot and image geoms, axis logos, team color scales and reference lines.

NameWhat it is
add_binsA copy of the plot with hexagonal or square bins, filled by count or weight, as one geom_polygon layer.
add_headshotsA copy of the plot with each player's headshot at its (x, y).
add_logosA copy of the plot with each team's logo at its (x, y); the front door's plotnine adapter.
add_wordmarksA copy of the plot with each team's wordmark at its (x, y).
axis_logosA copy of the plot whose team axis shows logos or wordmarks (or whose player axis shows headshots), not text.
geom_from_pathAny image, by local path or URL, at (x, y): aes(x=..., y=..., path=...), plus height (fraction of the
geom_mean_linesReference lines at the mean of x0 (vertical) and/or y0 (horizontal), per panel: the port of ggpath's
geom_median_linesReference lines at the median of x0 (vertical) and/or y0 (horizontal), per panel: the port of ggpath's
geom_sdv_headshotsPlayer headshots at (x, y), as a plotnine layer.
geom_sdv_logosTeam logos at (x, y), as a plotnine layer.
geom_sdv_wordmarksTeam wordmarks at (x, y), as a plotnine layer: the same aesthetics and parameters as geom_sdv_logos.
scale_color_sdvA discrete color scale that maps each team value (any id system) to its team color.
scale_colour_sdvA discrete color scale that maps each team value (any id system) to its team color.
scale_fill_sdvA discrete fill scale that maps each team value (any id system) to its team color.
team_tiersA tier list as a ggplot: each team's logo in its tier's row, tier 1 on top, on a dark (sdvplotR) or light theme.
title_imageA plot title with an image (a team logo, or any image) beside it, added to a ggplot with +.

add_bins​

add_bins(
target: plotnine.ggplot.ggplot,
x: Any,
y: Any,
*,
shape: Literal['hex', 'square'] = 'hex',
radius: float | None = None,
side: float | None = None,
equal_area: bool = False,
weights: Any = None,
origin: tuple[float, float] = (0.0, 0.0),
value: Literal['count', 'weight'] = 'count',
fill: float | None = None,
min_count: int = 1,
alpha: float = 1.0,
color: str = 'white',
size: float = 0.25,
) -> plotnine.ggplot.ggplot

A copy of the plot with hexagonal or square bins, filled by count or weight, as one geom_polygon layer.

The cells are sdvplot.binner's, in data units, so they match every other adapter's (and sdvplot-js's). The layer's data has one row per vertex: x, y, bin_id ("x,y", its group), bin_x, bin_y (the centre), count and weight; fill maps value, so add a fill scale (scale_fill_cmap("Blues")) to color it. Linking: plotnine draws static images, so there is none; sdvplot.bin_ids keys a table to the cells.

Arguments​

NameTypeDescription
targetplotnine.ggplot.ggplotA plotnine ggplot.
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.
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.
alphafloatThe cells' opacity, 0 to 1.
colorstrThe cell outline color (default "white").
sizefloatThe cell outline width (default 0.25).

Returns​

ggplot — A new plot with the bins layer; target is unchanged.

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: (a TypeError) If target is not a plotnine ggplot.
  • ValueError: If x, y and weights differ in length.

Example​

import pandas as pd
from plotnine import aes, geom_point, ggplot, scale_fill_cmap
from sdvplot.plotnine import add_bins

# three Brooklyn shots of 2025-26, legacy tenths of a foot (sportsdataverse-data nba_stats_shots)
shots = pd.DataFrame({"x": [0, -1, -44], "y": [0, 7, 252]})
p = ggplot(shots, aes("x", "y")) + geom_point()
p = add_bins(p, shots["x"], shots["y"], shape="square", side=15) + scale_fill_cmap("Blues")

See also​

add_headshots​

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

A copy of the plot with each player's headshot at its (x, y).

Arguments​

NameTypeDescription
targetplotnine.ggplot.ggplotA plotnine ggplot.
xAnyThe points' x positions (read by position).
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 panel height, in (0, 1].
alphafloatOpacity, 0 to 1.
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​

ggplot — A new plot with a geom_sdv_headshots layer.

Raises​

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

Example​

import pandas as pd
import sdvplot
from plotnine import aes, geom_point, ggplot

df = pd.DataFrame({"epa": [0.2, 0.15], "sr": [0.48, 0.47]})
p = ggplot(df, aes("epa", "sr")) + geom_point()
p2 = sdvplot.add_headshots(p, [0.2], [0.48], ["3139477"], league="nfl")

See also​

add_logos​

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

A copy of the plot with each team's logo at its (x, y); the front door's plotnine adapter.

Arguments​

NameTypeDescription
targetplotnine.ggplot.ggplotA plotnine ggplot.
xAnyThe points' x positions (read by position).
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 panel height, in (0, 1].
alphafloatOpacity, 0 to 1.
variantstr"default", "dark", or a named variant from marks().
id_systemstrThe id system of teams; "auto" tries each in order.

Returns​

ggplot — A new plot with a geom_sdv_logos layer; target is unchanged.

Raises​

  • ValueError: If the inputs differ in length.
  • UnsupportedTargetError: (a TypeError) If target is not a plotnine ggplot.
  • InputError: (a ValueError) If height or alpha is out of range, or season is not a year (or a list whose length does not match the teams); when the plot is drawn, if league, id_system or variant is unknown, or a season is not a year or is outside the seasons sdvplot knows for the league.
  • OfflineError: When the plot is drawn, if the logo manifest or 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, or one PIL cannot decode).
  • UnsafeDownloadError: (an OSError) When the plot is drawn, if a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) When the plot is drawn, if the manifest's sha256 or extension for a mark would put the file outside the cache directory.
  • OptionalDependencyError: When the plot is drawn, if a mark is an SVG and the svg extra is not installed.

Example​

import pandas as pd
import sdvplot
from plotnine import aes, geom_point, ggplot

df = pd.DataFrame({"epa": [0.2, 0.15], "sr": [0.48, 0.47]})
p = ggplot(df, aes("epa", "sr")) + geom_point()
p2 = sdvplot.add_logos(p, [0.2], [0.48], ["KC"], league="nfl")

See also​

add_wordmarks​

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

A copy of the plot with each team's wordmark at its (x, y).

Arguments​

NameTypeDescription
targetplotnine.ggplot.ggplotA plotnine ggplot.
xAnyThe points' x positions (read by position).
yAnyThe points' y positions, the same length as x.
teamsAnyThe team for each point.
leaguestrThe SDV league key, e.g. "nfl".
seasonAnyOne season, or one per point, to pick each team's wordmark for that era.
heightfloatThe wordmark height as a fraction of the panel height, in (0, 1].
alphafloatOpacity, 0 to 1.
variantstr"default", "dark", or a named variant from marks().
id_systemstrThe id system of teams.

Returns​

ggplot — A new plot with a geom_sdv_wordmarks layer.

Raises​

  • ValueError: If the inputs differ in length.
  • UnsupportedTargetError: (a TypeError) If target is not a plotnine ggplot.
  • InputError: (a ValueError) If height or alpha is out of range, or season is not a year (or a list whose length does not match the teams); when the plot is drawn, if league, id_system or variant is unknown, or a season is not a year or is outside the seasons sdvplot knows for the league.
  • OfflineError: When the plot is drawn, if the logo manifest or 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, or one PIL cannot decode).
  • UnsafeDownloadError: (an OSError) When the plot is drawn, if a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) When the plot is drawn, if the manifest's sha256 or extension for a mark would put the file outside the cache directory.
  • OptionalDependencyError: When the plot is drawn, if a mark is an SVG and the svg extra is not installed.

Example​

import pandas as pd
import sdvplot
from plotnine import aes, geom_point, ggplot

df = pd.DataFrame({"epa": [0.2, 0.15], "sr": [0.48, 0.47]})
p = ggplot(df, aes("epa", "sr")) + geom_point()
p2 = sdvplot.add_wordmarks(p, [0.2], [0.48], ["KC"], league="nfl")

See also​

axis_logos​

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

A copy of the plot whose team axis shows logos or wordmarks (or whose player axis shows headshots), not text.

Arguments​

NameTypeDescription
targetplotnine.ggplot.ggplotA plotnine ggplot whose axis is a discrete team axis.
axisstr"x" or "y".
leaguestrThe SDV league key, e.g. "nfl".
seasonAnyOne season for every label.
heightfloatThe image height as a fraction of the panel 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.
id_systemstrThe id system of the labels.

Returns​

ggplot — A new plot; labels that are not teams stay as text, with one SdvplotWarning when drawn.

Raises​

  • ValueError: If axis is not "x"/"y".
  • UnsupportedTargetError: (a TypeError) If target is not a plotnine ggplot.
  • InputError: (a ValueError) If height is out of range or mark_type is not "logo", "wordmark" or "headshot"; when the plot is drawn, if league, id_system or variant is unknown, or a season is not a year or is outside the seasons sdvplot knows for the league.
  • OfflineError: When the plot is drawn, if the logo manifest or 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, or one PIL cannot decode).
  • UnsafeDownloadError: (an OSError) When the plot is drawn, if a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) When the plot is drawn, if the manifest's sha256 or extension for a mark would put the file outside the cache directory.
  • OptionalDependencyError: When the plot is drawn, if a mark is an SVG and the svg extra is not installed.

Example​

import pandas as pd
import sdvplot
from plotnine import aes, geom_col, ggplot

df = pd.DataFrame({"team": ["KC", "BUF", "BAL"], "epa": [0.2, 0.15, 0.1]})
p = ggplot(df, aes("team", "epa")) + geom_col()
p2 = sdvplot.axis_logos(p, "x", league="nfl")

# player headshots as the labels (ESPN athlete ids)
qb = pd.DataFrame({"player": ["3139477", "3918298"], "epa": [0.31, 0.27]})
p3 = sdvplot.axis_logos(ggplot(qb, aes("player", "epa")) + geom_col(), "x", league="nfl",
mark_type="headshot")

See also​

geom_from_path​

geom_from_path(
mapping: Any = None,
data: Any = None,
**kwargs: Any,
) -> None

Any image, by local path or URL, at (x, y): aes(x=..., y=..., path=...), plus height (fraction of the

panel height, default 0.1) and alpha. The port of ggpath's geom_from_path(), sized like the logo geoms.

Arguments​

NameDescription
mappingaes(x=..., y=..., path=...); path holds a local file path, file:// URI or https URL per row (http is refused).
dataThe layer's data (pandas or polars), when not the plot's.
**kwargsheight in (0, 1], alpha in [0, 1], and plotnine's layer arguments (inherit_aes, ...).

Returns​

geom — A plotnine layer to add with +. Images that cannot be read (a missing file, a file that is not an image, a failed download) are skipped with one SdvplotWarning when the plot is drawn; SVG is not read.

Raises​

  • InputError: (a ValueError) If height or alpha is out of range (when the layer is built). An image that cannot be read or downloaded is skipped with a warning when the plot is drawn, not raised.

Example​

import pandas as pd
from plotnine import aes, ggplot
from sdvplot.plotnine import geom_from_path

df = pd.DataFrame({"x": [1, 2], "y": [1, 2], "img": ["a.png", "https://www.python.org/static/favicon.ico"]})
p = ggplot(df, aes("x", "y", path="img")) + geom_from_path(height=0.15)

See also​

geom_mean_lines​

geom_mean_lines(
mapping: Any = None,
data: Any = None,
**kwargs: Any,
) -> None

Reference lines at the mean of x0 (vertical) and/or y0 (horizontal), per panel: the port of ggpath's

geom_mean_lines().

Arguments​

NameDescription
mappingaes(x0=..., y0=...), at least one of them (x0 alone draws only the vertical line).
dataThe layer's data (pandas or polars), when not the plot's.
**kwargscolor (default "red"), size (line width, default 0.5), linetype (default "dashed"), alpha, na_rm and plotnine's layer arguments. With na_rm=False (the default) a panel whose values include a missing one draws no line on that axis, with a PlotnineWarning, as ggpath does; na_rm=True ignores the missing values.

Returns​

geom — A plotnine layer to add with +; each facet panel gets its own reference value.

Raises​

  • ValueError: When the plot is drawn, if neither x0 nor y0 is mapped.

Example​

import pandas as pd
from plotnine import aes, geom_point, ggplot
from sdvplot.plotnine import geom_mean_lines

df = pd.DataFrame({"epa": [0.2, 0.15, 0.05], "success_rate": [0.48, 0.47, 0.44]})
p = (ggplot(df, aes("epa", "success_rate", x0="epa", y0="success_rate"))
+ geom_point() + geom_mean_lines(color="grey"))

See also​

geom_median_lines​

geom_median_lines(
mapping: Any = None,
data: Any = None,
**kwargs: Any,
) -> None

Reference lines at the median of x0 (vertical) and/or y0 (horizontal), per panel: the port of ggpath's

geom_median_lines().

Arguments​

NameDescription
mappingaes(x0=..., y0=...), at least one of them.
dataThe layer's data (pandas or polars), when not the plot's.
**kwargscolor (default "red"), size (default 0.5), linetype (default "dashed"), alpha, na_rm (as geom_mean_lines) and plotnine's layer arguments.

Returns​

geom — A plotnine layer to add with +; each facet panel gets its own reference value.

Raises​

  • ValueError: When the plot is drawn, if neither x0 nor y0 is mapped.

Example​

import pandas as pd
from plotnine import aes, geom_point, ggplot
from sdvplot.plotnine import geom_median_lines

df = pd.DataFrame({"epa": [0.2, 0.15, 0.05], "success_rate": [0.48, 0.47, 0.44]})
p = ggplot(df, aes("epa", "success_rate", x0="epa", y0="success_rate")) + geom_point() + geom_median_lines()

See also​

geom_sdv_headshots​

geom_sdv_headshots(
mapping: Any = None,
data: Any = None,
**kwargs: Any,
) -> None

Player headshots at (x, y), as a plotnine layer.

Arguments​

NameDescription
mappingaes(x=..., y=..., player_id=...).
dataThe layer's data (pandas or polars), when not the plot's.
**kwargsleague (required, e.g. "nfl"), height (a fraction of the panel height, in (0, 1], default 0.1), alpha (0 to 1), id_system ("espn", "gsis", "league" or a provider, as in headshot_url) and plotnine's layer arguments (inherit_aes, ...).

Returns​

geom — A plotnine layer to add with +. Marks that cannot be placed (an unknown team, a missing mark) are skipped with one SdvplotWarning when the plot is drawn.

Raises​

  • TypeError: If league is missing.
  • InputError: (a ValueError) If height or alpha is out of range (when the layer is built); when the plot is drawn, if league has no ESPN headshots or id_system is not valid for it.
  • OfflineError: When the plot is drawn, if a headshot, or with id_system="gsis" the nflverse player table, is neither cached nor downloadable (a DownloadError, also an OSError, for an HTTP error status).
  • UnsafeDownloadError: (an OSError) When the plot is drawn, if a download is refused: larger than the byte cap, past the deadline, or redirected away from https.

Example​

import pandas as pd
from plotnine import aes, ggplot
from sdvplot.plotnine import geom_sdv_headshots

df = pd.DataFrame({"x": [0.3, 0.7], "y": [0.4, 0.6], "espn_id": ["3139477", "3918298"]})
p = ggplot(df, aes("x", "y", player_id="espn_id")) + geom_sdv_headshots(league="nfl", height=0.15)

See also​

geom_sdv_logos​

geom_sdv_logos(
mapping: Any = None,
data: Any = None,
**kwargs: Any,
) -> None

Team logos at (x, y), as a plotnine layer.

For a season per row, map it instead of passing season=: aes(..., season="season") (a season= parameter wins over the mapping).

Arguments​

NameDescription
mappingaes(x=..., y=..., team=...), plus optional season.
dataThe layer's data (pandas or polars), when not the plot's.
**kwargsleague (required, e.g. "nfl"), season, height (a fraction of the panel height, in (0, 1], default 0.1), alpha (0 to 1), variant ("default", "dark" or a named variant), id_system and plotnine's layer arguments (inherit_aes, ...).

Returns​

geom — A plotnine layer to add with +. Marks that cannot be placed (an unknown team, a missing mark) are skipped with one SdvplotWarning when the plot is drawn.

Raises​

  • TypeError: If league is missing.
  • InputError: (a ValueError) If height or alpha is out of range (when the layer is built); when the plot is drawn, if league, id_system or variant is unknown, or a season is not a year or is outside the seasons sdvplot knows for the league.
  • OfflineError: When the plot is drawn, if the logo manifest or 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, or one PIL cannot decode).
  • UnsafeDownloadError: (an OSError) When the plot is drawn, if a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) When the plot is drawn, if the manifest's sha256 or extension for a mark would put the file outside the cache directory.
  • OptionalDependencyError: When the plot is drawn, if a mark is an SVG and the svg extra is not installed.

Example​

import pandas as pd
from plotnine import aes, ggplot
from sdvplot.plotnine import geom_sdv_logos

df = pd.DataFrame({"team": ["KC", "BUF"], "epa": [0.2, 0.15], "sr": [0.48, 0.47]})
p = ggplot(df, aes("epa", "sr", team="team")) + geom_sdv_logos(league="nfl", height=0.12)

See also​

geom_sdv_wordmarks​

geom_sdv_wordmarks(
mapping: Any = None,
data: Any = None,
**kwargs: Any,
) -> None

Team wordmarks at (x, y), as a plotnine layer: the same aesthetics and parameters as geom_sdv_logos.

Arguments​

NameDescription
mappingaes(x=..., y=..., team=...), plus optional season.
dataThe layer's data (pandas or polars), when not the plot's.
**kwargsleague (required, e.g. "nfl"), season, height (a fraction of the panel height, in (0, 1], default 0.1), alpha (0 to 1), variant ("default", "dark" or a named variant), id_system and plotnine's layer arguments (inherit_aes, ...).

Returns​

geom — A plotnine layer to add with +. Marks that cannot be placed (an unknown team, a missing mark) are skipped with one SdvplotWarning when the plot is drawn.

Raises​

  • TypeError: If league is missing.
  • InputError: (a ValueError) If height or alpha is out of range (when the layer is built); when the plot is drawn, if league, id_system or variant is unknown, or a season is not a year or is outside the seasons sdvplot knows for the league.
  • OfflineError: When the plot is drawn, if the logo manifest or 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, or one PIL cannot decode).
  • UnsafeDownloadError: (an OSError) When the plot is drawn, if a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) When the plot is drawn, if the manifest's sha256 or extension for a mark would put the file outside the cache directory.
  • OptionalDependencyError: When the plot is drawn, if a mark is an SVG and the svg extra is not installed.

Example​

import pandas as pd
from plotnine import aes, ggplot
from sdvplot.plotnine import geom_sdv_wordmarks

df = pd.DataFrame({"team": ["KC", "BUF"], "epa": [0.2, 0.15], "sr": [0.48, 0.47]})
p = ggplot(df, aes("epa", "sr", team="team")) + geom_sdv_wordmarks(league="nfl", height=0.08)

See also​

scale_color_sdv​

scale_color_sdv(
league: str,
*,
which: Literal['primary', 'secondary'] = 'primary',
season: Any = None,
id_system: Literal['auto', 'team_id', 'espn', 'espn_abbr', 'nhl', 'nflverse', 'mlbstats', 'nba_api', 'hockeytech', 'ncaa', 'pff', 'cricinfo', 'cfbd', 'bref', 'sportsipy', 'fangraphs', 'yahoo', 'kenpom', 'torvik', 'sdvplotr', 'name', 'nhl_id', 'fox', 'cbs', 'sports247', 'on3'] = 'auto',
strict: bool = False,
na_value: str = 'grey',
alpha: float | None = None,
**kwargs: Any,
) -> Any

A discrete color scale that maps each team value (any id system) to its team color.

Arguments​

NameTypeDescription
leaguestrThe SDV league key, e.g. "nfl".
whichLiteral['primary', 'secondary']"primary" or "secondary".
seasonAnyOne season for every value.
id_systemLiteral['auto', 'team_id', 'espn', 'espn_abbr', 'nhl', 'nflverse', 'mlbstats', 'nba_api', 'hockeytech', 'ncaa', 'pff', 'cricinfo', 'cfbd', 'bref', 'sportsipy', 'fangraphs', 'yahoo', 'kenpom', 'torvik', 'sdvplotr', 'name', 'nhl_id', 'fox', 'cbs', 'sports247', 'on3']The id system of the team values: "auto" (the default) tries them in order; pass "nhl_id" for NHL stats ids, which "auto" never tries.
strictboolRaise UnresolvedTeamError when the plot is drawn and a value does not resolve, instead of drawing it in na_value with one SdvplotWarning.
na_valuestrThe color of values that are not teams; drawn as given, alpha does not fade it.
alphafloat | NoneAn opacity in [0, 1] applied to the team colors (sdvplotR's alpha, scales::alpha()); None (the default) leaves them opaque.
**kwargsAnyPassed to plotnine's scale_color_manual (name, breaks, guide, ...).

Returns​

scale — A plotnine color scale.

Raises​

  • InputError: (a ValueError) If which is not "primary" or "secondary" or alpha is not in [0, 1]; when the plot is drawn, if league or id_system is unknown or season is not a year or is outside the seasons sdvplot knows for the league.
  • UnresolvedTeamError: (a ValueError) With strict=True, when the plot is drawn and a value does not resolve.

Example​

import pandas as pd
from plotnine import aes, geom_point, ggplot
from sdvplot.plotnine import scale_color_sdv

df = pd.DataFrame({"team": ["KC", "BUF"], "epa": [0.2, 0.15], "sr": [0.48, 0.47]})
p = ggplot(df, aes("epa", "sr", color="team")) + geom_point() + scale_color_sdv("nfl")

See also​

scale_colour_sdv​

scale_colour_sdv(
league: str,
*,
which: Literal['primary', 'secondary'] = 'primary',
season: Any = None,
id_system: Literal['auto', 'team_id', 'espn', 'espn_abbr', 'nhl', 'nflverse', 'mlbstats', 'nba_api', 'hockeytech', 'ncaa', 'pff', 'cricinfo', 'cfbd', 'bref', 'sportsipy', 'fangraphs', 'yahoo', 'kenpom', 'torvik', 'sdvplotr', 'name', 'nhl_id', 'fox', 'cbs', 'sports247', 'on3'] = 'auto',
strict: bool = False,
na_value: str = 'grey',
alpha: float | None = None,
**kwargs: Any,
) -> Any

A discrete color scale that maps each team value (any id system) to its team color.

Arguments​

NameTypeDescription
leaguestrThe SDV league key, e.g. "nfl".
whichLiteral['primary', 'secondary']"primary" or "secondary".
seasonAnyOne season for every value.
id_systemLiteral['auto', 'team_id', 'espn', 'espn_abbr', 'nhl', 'nflverse', 'mlbstats', 'nba_api', 'hockeytech', 'ncaa', 'pff', 'cricinfo', 'cfbd', 'bref', 'sportsipy', 'fangraphs', 'yahoo', 'kenpom', 'torvik', 'sdvplotr', 'name', 'nhl_id', 'fox', 'cbs', 'sports247', 'on3']The id system of the team values: "auto" (the default) tries them in order; pass "nhl_id" for NHL stats ids, which "auto" never tries.
strictboolRaise UnresolvedTeamError when the plot is drawn and a value does not resolve, instead of drawing it in na_value with one SdvplotWarning.
na_valuestrThe color of values that are not teams; drawn as given, alpha does not fade it.
alphafloat | NoneAn opacity in [0, 1] applied to the team colors (sdvplotR's alpha, scales::alpha()); None (the default) leaves them opaque.
**kwargsAnyPassed to plotnine's scale_color_manual (name, breaks, guide, ...).

Returns​

scale — A plotnine color scale.

Raises​

  • InputError: (a ValueError) If which is not "primary" or "secondary" or alpha is not in [0, 1]; when the plot is drawn, if league or id_system is unknown or season is not a year or is outside the seasons sdvplot knows for the league.
  • UnresolvedTeamError: (a ValueError) With strict=True, when the plot is drawn and a value does not resolve.

Example​

import pandas as pd
from plotnine import aes, geom_point, ggplot
from sdvplot.plotnine import scale_color_sdv

df = pd.DataFrame({"team": ["KC", "BUF"], "epa": [0.2, 0.15], "sr": [0.48, 0.47]})
p = ggplot(df, aes("epa", "sr", color="team")) + geom_point() + scale_color_sdv("nfl")

See also​

scale_fill_sdv​

scale_fill_sdv(
league: str,
*,
which: Literal['primary', 'secondary'] = 'primary',
season: Any = None,
id_system: Literal['auto', 'team_id', 'espn', 'espn_abbr', 'nhl', 'nflverse', 'mlbstats', 'nba_api', 'hockeytech', 'ncaa', 'pff', 'cricinfo', 'cfbd', 'bref', 'sportsipy', 'fangraphs', 'yahoo', 'kenpom', 'torvik', 'sdvplotr', 'name', 'nhl_id', 'fox', 'cbs', 'sports247', 'on3'] = 'auto',
strict: bool = False,
na_value: str = 'grey',
alpha: float | None = None,
**kwargs: Any,
) -> Any

A discrete fill scale that maps each team value (any id system) to its team color.

Arguments​

NameTypeDescription
leaguestrThe SDV league key, e.g. "nfl".
whichLiteral['primary', 'secondary']"primary" or "secondary".
seasonAnyOne season for every value.
id_systemLiteral['auto', 'team_id', 'espn', 'espn_abbr', 'nhl', 'nflverse', 'mlbstats', 'nba_api', 'hockeytech', 'ncaa', 'pff', 'cricinfo', 'cfbd', 'bref', 'sportsipy', 'fangraphs', 'yahoo', 'kenpom', 'torvik', 'sdvplotr', 'name', 'nhl_id', 'fox', 'cbs', 'sports247', 'on3']The id system of the team values: "auto" (the default) tries them in order; pass "nhl_id" for NHL stats ids, which "auto" never tries.
strictboolRaise UnresolvedTeamError when the plot is drawn and a value does not resolve, instead of drawing it in na_value with one SdvplotWarning.
na_valuestrThe color of values that are not teams; drawn as given, alpha does not fade it.
alphafloat | NoneAn opacity in [0, 1] applied to the team colors (sdvplotR's alpha, scales::alpha()); None (the default) leaves them opaque.
**kwargsAnyPassed to plotnine's scale_fill_manual.

Returns​

scale — A plotnine fill scale.

Raises​

  • InputError: (a ValueError) If which is not "primary" or "secondary" or alpha is not in [0, 1]; when the plot is drawn, if league or id_system is unknown or season is not a year or is outside the seasons sdvplot knows for the league.
  • UnresolvedTeamError: (a ValueError) With strict=True, when the plot is drawn and a value does not resolve.

Example​

import pandas as pd
from plotnine import aes, geom_col, ggplot
from sdvplot.plotnine import scale_fill_sdv

df = pd.DataFrame({"team": ["KC", "BUF"], "epa": [0.2, 0.15]})
p = ggplot(df, aes("team", "epa", fill="team")) + geom_col() + scale_fill_sdv("nfl")

See also​

team_tiers​

team_tiers(
data: Any,
league: str,
*,
title: str | None = None,
subtitle: str | None = 'created with the #sdvplot Tiermaker',
caption: str | None = None,
tier_desc: dict[Any, str] | None = None,
presort: bool = False,
alpha: float = 0.8,
height: float | None = None,
no_line_below_tier: Any = None,
devel: bool = False,
theme: Literal['dark', 'light'] = 'dark',
variant: str = 'auto',
) -> plotnine.ggplot.ggplot

A tier list as a ggplot: each team's logo in its tier's row, tier 1 on top, on a dark (sdvplotR) or light theme.

Arguments​

NameTypeDescription
dataAnyA pandas or polars DataFrame with tier_no (1 is the top tier) and team (any id system resolve() understands), and optionally tier_rank, the position within the tier; without it, teams keep their order in data.
leaguestrThe SDV league key, e.g. "nfl".
titlestr | NoneThe title; None gives "{LEAGUE} Team Tiers", "" none.
subtitlestr | NoneThe subtitle; None or "" for none.
captionstr | NoneThe caption; None for none.
tier_descdict[Any, str] | NoneEach tier's label, keyed by tier number; None gives sdvplotR's (1 "Elite" ... 5 "What are they doing?"). Labels wrap at 15 characters; a tier without one gets none.
presortboolSort teams alphabetically within each tier (ignores tier_rank).
alphafloatLogo opacity, 0 to 1.
heightfloat | NoneLogo height as a fraction of the panel height; None gives 0.1, about the largest height at which 32 logos in 5 tiers (7, 7, 6, 6, 6) neither overlap nor leave the panel at the default 6.4 x 4.8 in figure.
no_line_below_tierAnyA tier number, or several, with no separator line below.
develboolDraw each team as text instead of its logo (fast, and needs no download).
themeLiteral['dark', 'light']"dark" (sdvplotR's: a near-black background) or "light" (white).
variantstrThe logo variant: "auto" (the default) draws the archive's "dark" variant, a mark made for dark backgrounds, on the dark theme and "default" on the light one; a team with no dark mark draws its default one, with no warning. Any other value ("default", "dark" or a named variant from marks()) is drawn on either theme, as geom_sdv_logos draws it: variant="default" keeps the default logos on the dark theme, as sdvplotR and sdvplot 0.1.0 draw them.

Returns​

ggplot — The plot; a team that does not resolve is skipped with one SdvplotWarning, keeping its slot.

Raises​

  • TypeError: If data is not a DataFrame, or tier_no/tier_rank hold non-numbers.
  • InputError: (a ValueError) If height/alpha is out of range, or league is unknown; unless devel=True, when the plot is drawn, if variant is a name no mark in the archive has.
  • ValueError: If data lacks tier_no or team, has no row with a tier, or theme is not "dark" or "light".
  • OfflineError: Unless devel=True, when the plot is drawn, if the logo manifest or a logo is neither cached nor downloadable (a DownloadError, also an OSError, for an HTTP error status; an IntegrityError for a file that does not match the manifest's sha256, or one PIL cannot decode).
  • UnsafeDownloadError: (an OSError) Unless devel=True, when the plot is drawn, if a download is refused.
  • UnsafeCachePathError: (a ValueError) Unless devel=True, when the plot is drawn, if the manifest's sha256 or extension for a logo would put the file outside the cache directory.
  • OptionalDependencyError: Unless devel=True, when the plot is drawn, if a logo is an SVG and the svg extra is not installed.

Example​

import pandas as pd
from sdvplot.plotnine import team_tiers

df = pd.DataFrame({"tier_no": [1, 1, 2, 3], "team": ["KC", "BUF", "BAL", "NYJ"]})
p = team_tiers(df, "nfl", caption="data: nflverse")

# Draft it as text first:
p = team_tiers(df, "nfl", devel=True)

# A white background:
p = team_tiers(df, "cfb", theme="light")

# The default logos on the dark background, as sdvplotR draws them:
p = team_tiers(df, "nfl", variant="default")

See also​

title_image​

title_image(
image: Any,
title: str = '',
*,
league: str | None = None,
season: Any = None,
side: str = 'left',
height: float = 15,
) -> Any

A plot title with an image (a team logo, or any image) beside it, added to a ggplot with +.

The pair follows the theme's plot_title alignment, like the image inside sdvplotR's title: plotnine centres a lone title and left-aligns one with a subtitle.

Arguments​

NameTypeDescription
imageAnyA team, in any id system resolve() understands, when league is given; otherwise an image URL (https; http is refused) or a local file path.
titlestrThe title text; it replaces labs(title=...), so add title_image after any labs.
leaguestr | NoneThe SDV league key, e.g. "nfl"; None reads image as a URL or path.
seasonAnyOne season, to pick the team's logo for that era.
sidestr"left" or "right" of the title text.
heightfloatThe image height in points (1/72 inch). The title keeps its own line height, so an image much taller than the text needs room: a plot_title margin in theme().

Returns​

object — An object to add to a ggplot; the image is loaded now, and an unknown team, or an image by URL or path that cannot be read, gives one SdvplotWarning now (the title is drawn without the image). A second title_image added to the same plot replaces the first.

Raises​

  • TypeError: If league is given and image is not one team.
  • InputError: (a ValueError) If height is not a number of points of at least 1, or league is given and it is unknown or season is not a year or is outside the seasons sdvplot knows for the league.
  • ValueError: If side is not "left"/"right".
  • OfflineError: If league is given and the team's logo (or the logo manifest) 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, or one PIL cannot decode). An image by URL or path that cannot be read is skipped with a warning instead.
  • UnsafeDownloadError: (an OSError) If league is given and a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) If league is given and the manifest's sha256 or extension for the logo would put the file outside the cache directory.
  • OptionalDependencyError: If league is given, the logo is an SVG and the svg extra is not installed.

Example​

import pandas as pd
from plotnine import aes, geom_point, ggplot
from sdvplot.plotnine import title_image

df = pd.DataFrame({"epa": [0.2, 0.15], "sr": [0.48, 0.47]})
p = ggplot(df, aes("epa", "sr")) + geom_point() + title_image("KC", "Chiefs", league="nfl", height=20)

See also​