Skip to main content
Version: 0.1.1

sdvplot.altair

The Altair adapter: logos, wordmarks and headshots as a native Vega-Lite image layer.

NameWhat it is
add_headshotsLayer each player's headshot, centred on its (x, y) point, onto an Altair chart.
add_logosLayer each team's logo, centred on its (x, y) point, onto an Altair chart.
add_wordmarksLayer each team's wordmark, centred on its (x, y) point, onto an Altair chart.
axis_logosReplace a discrete axis' team labels with the teams' logos (or wordmarks), or a player axis' with headshots.
logo_layerA Vega-Lite image layer of team logos, to layer onto a chart: alt.layer(chart, logo_layer(...)).

add_headshots​

add_headshots(
chart: Any,
x: Any,
y: Any,
players: Any,
*,
league: str,
height: float = 0.1,
alpha: float = 1,
embed: bool = False,
id_system: str = 'espn',
) -> altair.vegalite.v6.api.LayerChart

Layer each player's headshot, centred on its (x, y) point, onto an Altair chart.

Arguments​

NameTypeDescription
chartAnyAn altair.Chart or LayerChart.
xAnyThe points' x positions, in the chart'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 chart height, 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​

altair.LayerChart — A new chart, chart plus the image layer.

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 chart cannot take a layer (see add_logos).
  • UnsupportedTargetError: (a TypeError) If chart is not an Altair Chart or LayerChart.
  • 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 altair as alt
import pandas as pd
import sdvplot

df = pd.DataFrame({"x": [0.3], "y": [0.5], "player": ["3139477"]})
chart = alt.Chart(df).mark_point().encode(x="x", y="y")
sdvplot.add_headshots(chart, df["x"], df["y"], df["player"], league="nfl", height=0.2)

See also​

add_logos​

add_logos(
chart: 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',
) -> altair.vegalite.v6.api.LayerChart

Layer each team's logo, centred on its (x, y) point, onto an Altair chart.

The image layer reuses the chart's x/y field names, types, time units and sort, so a nominal axis stays nominal, a logo on yearmonth(date) sits on its month, and the axis titles stay as they were. An aggregated or binned axis is not copied: aggregate or bin in the data first.

Arguments​

NameTypeDescription
chartAnyAn altair.Chart or LayerChart (facet, concat and repeat charts: pass one of their charts).
xAnyThe points' x positions, in the chart'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, to pick each team's mark for that era.
heightfloatThe logo height as a fraction of the chart height, 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​

altair.LayerChart — A new chart, chart plus the image layer (chart itself is unchanged).

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, the chart is a facet, concat or repeat chart, its height is not a positive number of pixels where it must be, its x or y encoding aggregates or bins, or a discrete axis is sorted in a way Vega-Lite drops once layers share the axis.
  • UnsupportedTargetError: (a TypeError) If chart is not an Altair Chart or LayerChart.
  • 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 altair as alt
import pandas as pd
import sdvplot

df = pd.DataFrame({"epa": [0.2, 0.1], "sr": [0.48, 0.45], "team": ["KC", "BUF"]})
chart = alt.Chart(df).mark_point().encode(x="epa", y="sr")
chart = sdvplot.add_logos(chart, df["epa"], df["sr"], df["team"], league="nfl", height=0.12)

See also​

add_wordmarks​

add_wordmarks(
chart: 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',
) -> altair.vegalite.v6.api.LayerChart

Layer each team's wordmark, centred on its (x, y) point, onto an Altair chart.

Arguments​

NameTypeDescription
chartAnyAn altair.Chart or LayerChart.
xAnyThe points' x positions, in the chart'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 chart height, 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​

altair.LayerChart — A new chart, chart plus the image layer.

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 chart cannot take a layer (see add_logos).
  • UnsupportedTargetError: (a TypeError) If chart is not an Altair Chart or LayerChart.
  • 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 altair as alt
import pandas as pd
import sdvplot

df = pd.DataFrame({"team": ["KC", "BUF"], "wins": [12, 10]})
bars = alt.Chart(df).mark_bar().encode(x=alt.X("team", sort=None), y="wins")
sdvplot.add_wordmarks(bars, df["team"], df["wins"], df["team"], league="nfl", height=0.06)

See also​

axis_logos​

axis_logos(
chart: 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',
) -> altair.vegalite.v6.api.LayerChart

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

The images are a layer placed just outside the plot (under the x axis, left of the y axis), height of the chart height tall; the axis' labelExpr blanks only the labels that became images and its labelPadding grows past them, so labels that are not teams stay as text (with one SdvplotWarning). The categories come from an explicit scale domain or sort list, or the chart's inline data.

Arguments​

NameTypeDescription
chartAnyAn altair.Chart or LayerChart with a nominal or ordinal 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 chart 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​

altair.LayerChart — A new chart: chart with the axis labels blanked, plus the image layer.

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", the axis is not discrete or is hidden, the categories cannot be read, or the chart cannot take a layer (see add_logos).
  • UnsupportedTargetError: (a TypeError) If chart is not an Altair Chart or LayerChart.
  • 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 altair as alt
import pandas as pd
import sdvplot

df = pd.DataFrame({"team": ["KC", "BUF", "BAL"], "wins": [12, 10, 9]})
bars = alt.Chart(df).mark_bar().encode(x=alt.X("team", sort=None), y="wins")
sdvplot.axis_logos(bars, "x", league="nfl", height=0.1)

See also​

logo_layer​

logo_layer(
x: Any,
y: Any,
teams: Any,
*,
league: str,
season: Any = None,
height: float = 0.1,
chart_height: float | None = None,
alpha: float = 1,
variant: str = 'default',
x_type: str = 'quantitative',
y_type: str = 'quantitative',
embed: bool = False,
id_system: str = 'auto',
) -> altair.vegalite.v6.api.Chart

A Vega-Lite image layer of team logos, to layer onto a chart: alt.layer(chart, logo_layer(...)).

The layer encodes its own columns named x and y, so give your chart explicit axis titles (an explicit title wins over the layer's), or use add_logos, which reuses the chart's own field names, types and sort.

Arguments​

NameTypeDescription
xAnyThe points' x positions, in the chart's x values (numbers, category names or dates).
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 chart height, in (0, 1].
chart_heightfloat | NoneThe chart's height in pixels (a positive number); None means Vega-Lite's default (300).
alphafloatOpacity, 0 to 1.
variantstr"default", "dark", or a named variant from marks().
x_typestrThe Vega-Lite type of the chart's x axis ("quantitative", "nominal", "ordinal", "temporal").
y_typestrThe Vega-Lite type of the chart's y axis.
embedboolInline each image as a data URI (HTML that renders offline, and PNG export with vl-convert) instead of linking its URL.
id_systemstrThe id system of teams; "auto" tries each in order.

Returns​

altair.Chart — The image layer.

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 chart_height is not a positive number of pixels, or the inputs differ in length.
  • 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 altair as alt
import pandas as pd
import sdvplot.altair as salt

df = pd.DataFrame({"x": [10, 20], "y": [-3, -7], "team": ["KC", "BUF"]})
points = alt.Chart(df).mark_point().encode(x=alt.X("x", title="EPA"), y=alt.Y("y", title="Success"))
alt.layer(points, salt.logo_layer(df["x"], df["y"], df["team"], league="nfl", height=0.12))

See also​