sdvplot.altair
The Altair adapter: logos, wordmarks and headshots as a native Vega-Lite image layer.
| Name | What it is |
|---|---|
| add_bins | Layer hexagonal or square bins, colored by count or weight, onto an Altair chart. |
| add_headshots | Layer each player's headshot, centred on its (x, y) point, onto an Altair chart. |
| add_logos | Layer each team's logo, centred on its (x, y) point, onto an Altair chart. |
| add_wordmarks | Layer each team's wordmark, centred on its (x, y) point, onto an Altair chart. |
| axis_logos | Replace a discrete axis' team labels with the teams' logos (or wordmarks), or a player axis' with headshots. |
| logo_layer | A Vega-Lite image layer of team logos, to layer onto a chart: alt.layer(chart, logo_layer(...)). |
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,
weights: Any = None,
origin: tuple[float, float] = (0.0, 0.0),
value: Literal['count', 'weight'] = 'count',
fill: float | None = None,
min_count: int = 1,
scheme: str = 'viridis',
opacity: float = 1.0,
link: Any = None,
) -> Any
Layer hexagonal or square bins, colored by count or weight, onto an Altair chart.
The cells are sdvplot.binner's, in data units, drawn as one area mark split by cell (detail): a
pointy-top hexagon and a square are both x-monotone, so each is the band between its top and bottom edges, on the
chart's own x and y scales. The layer is named "sdvplot_bins"; its rows carry bin_id ("x,y", as
sdvplot-js stamps data-sdv-id), count and weight, and it adds a point selection param named
"sdvplot_bins" on bin_id (click a cell; shift-click adds).
Linking: Vega-Lite links views through a shared field, and the field is bin_id: give the points' data a
bin_id column with sdvplot.bin_ids (on the same x/y), then encode them with
alt.condition(alt.param("sdvplot_bins"), ...) (an alt.param of that name refers to this one) to highlight
a clicked cell's points. The other way, pass the points layer's own selection param on fields=["bin_id"] as
link: the cells holding its selected points stay opaque (and clicking a cell no longer dims the others). The
cells hold no point ids, so a large chart stays small.
Arguments
| Name | Type | Description |
|---|---|---|
target | Any | An Altair Chart or LayerChart. |
x | Any | The points' x values, in the chart's x units. |
y | Any | The points' y values. |
shape | Literal['hex', 'square'] | "hex" (the default) or "square". |
radius | float | None | The hexagon's circumradius, in data units; for squares, with equal_area=True. |
side | float | None | The square's side (shape="square"). |
equal_area | bool | Squares of a radius-radius hexagon's area. |
weights | Any | Optional non-negative weights, one per point (see sdvplot.hexbin): each bin's weight. |
origin | tuple[float, float] | The point a cell centre falls on (default (0.0, 0.0)): a hoop-centred lattice, origin = the basket's coordinates. |
value | Literal['count', 'weight'] | What the color encodes: "count" (the default) or "weight" (the sum of weights). |
fill | float | None | The 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_count | int | Cells 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. |
scheme | str | A Vega color scheme for the values (default "viridis"). |
opacity | float | The cells' opacity, 0 to 1; a cell outside the selection is drawn at a quarter of it. |
link | Any | Optional selection param of the points' layer, on fields=["bin_id"], that picks the cells to show. |
Returns
LayerChart — target with the cells layered on top.
Raises
InputError: If the lattice options are not valid (seesdvplot.binner),valueis not "count" or "weight",fillis not in (0, 1],min_countis not a whole number >= 1, oropacityis outside [0, 1].UnsupportedTargetError: Iftargetis not an Altair Chart or LayerChart.ValueError: Ifxandydiffer in length, ortargetis a facet, repeat or concat chart.
Example
import altair as alt
import polars as pl
import sdvplot
from sdvplot.altair import add_bins
# three Brooklyn shots of 2025-26, legacy tenths of a foot (sportsdataverse-data nba_stats_shots)
shots = pl.DataFrame({"x": [0, -1, -44], "y": [0, 7, 252]})
bins = sdvplot.binner(shape="square", side=15).bins(shots["x"], shots["y"])
shots = shots.with_columns(bin_id=pl.Series(sdvplot.bin_ids(bins, shots.height)))
points = alt.Chart(shots).mark_circle().encode(
x="x:Q", y="y:Q", opacity=alt.condition(alt.param("sdvplot_bins"), alt.value(1), alt.value(0.2))
)
chart = add_bins(points, shots["x"], shots["y"], shape="square", side=15, opacity=0.6)
See also
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
| Name | Type | Description |
|---|---|---|
chart | Any | An altair.Chart or LayerChart. |
x | Any | The points' x positions, in the chart's x 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 chart height, in (0, 1]. |
alpha | float | Opacity, 0 to 1. |
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
altair.LayerChart — A new chart, chart plus the image layer.
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 the chart cannot take a layer (seeadd_logos).UnsupportedTargetError: (a TypeError) Ifchartis not an AltairChartorLayerChart.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 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
| Name | Type | Description |
|---|---|---|
chart | Any | An altair.Chart or LayerChart (facet, concat and repeat charts: pass one of their charts). |
x | Any | The points' x positions, in the chart's x 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, to pick each team's mark for that era. |
height | float | The logo height as a fraction of the chart height, in (0, 1]. |
alpha | float | Opacity, 0 to 1. |
variant | str | "default", "dark", or a named variant from marks(). |
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
altair.LayerChart — A new chart, chart plus the image layer (chart itself is unchanged).
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, 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) Ifchartis not an AltairChartorLayerChart.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 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
| Name | Type | Description |
|---|---|---|
chart | Any | An altair.Chart or LayerChart. |
x | Any | The points' x positions, in the chart's x 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 chart height, in (0, 1]. |
alpha | float | Opacity, 0 to 1. |
variant | str | "default", "dark", or a named variant from marks(). |
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
altair.LayerChart — A new chart, chart plus the image layer.
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 the chart cannot take a layer (seeadd_logos).UnsupportedTargetError: (a TypeError) Ifchartis not an AltairChartorLayerChart.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 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
| Name | Type | Description |
|---|---|---|
chart | Any | An altair.Chart or LayerChart with a nominal or ordinal axis. |
axis | str | "x" or "y". |
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 chart 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
altair.LayerChart — A new chart: chart with the axis labels blanked, plus the image layer.
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", the axis is not discrete or is hidden, the categories cannot be read, or the chart cannot take a layer (seeadd_logos).UnsupportedTargetError: (a TypeError) Ifchartis not an AltairChartorLayerChart.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 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
| Name | Type | Description |
|---|---|---|
x | Any | The points' x positions, in the chart's x values (numbers, category names or dates). |
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 chart height, in (0, 1]. |
chart_height | float | None | The chart's height in pixels (a positive number); None means Vega-Lite's default (300). |
alpha | float | Opacity, 0 to 1. |
variant | str | "default", "dark", or a named variant from marks(). |
x_type | str | The Vega-Lite type of the chart's x axis ("quantitative", "nominal", "ordinal", "temporal"). |
y_type | str | The Vega-Lite type of the chart's y axis. |
embed | bool | Inline each image as a data URI (HTML that renders offline, and PNG export with vl-convert) instead of linking its URL. |
id_system | str | The id system of teams; "auto" tries each in order. |
Returns
altair.Chart — The image layer.
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: Ifchart_heightis not a positive number of pixels, or the inputs differ in length.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 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))