Skip to main content
Version: 0.1.1

sdvplot.folium

The Folium adapter: logos, wordmarks and headshots as map markers with image icons.

NameWhat it is
add_headshotsPut each player's headshot on a Folium map at its (longitude, latitude).
add_logosPut each team's logo on a Folium map at its (longitude, latitude), with the team name as a tooltip.
add_wordmarksPut each team's wordmark on a Folium map at its (longitude, latitude).
axis_logosNot supported: a map has no category axes.

add_headshots​

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

Put each player's headshot on a Folium map at its (longitude, latitude).

Arguments​

NameTypeDescription
targetAnyA folium.Map.
xAnyThe longitudes.
yAnyThe latitudes, the same length as x.
playersAnyThe player id for each point (shown as the tooltip).
leaguestrThe SDV league key, e.g. "nfl".
heightfloatThe headshot height as a fraction of the map's reference height (see add_logos), 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​

object — target itself, with the markers 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 a location is not a number.
  • UnsupportedTargetError: (a TypeError) If target is not a folium.Map.
  • 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 folium
import sdvplot

m = folium.Map(location=[39, -95], zoom_start=4)
sdvplot.add_headshots(m, [-94.48], [39.05], ["3139477"], league="nfl", height=0.08)

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',
embed: bool = False,
id_system: str = 'auto',
) -> Any

Put each team's logo on a Folium map at its (longitude, latitude), with the team name as a tooltip.

Arguments​

NameTypeDescription
targetAnyA folium.Map.
xAnyThe longitudes.
yAnyThe latitudes, 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 map's pixel height (or of _FOLIUM_REFERENCE_HEIGHT, 500 px, when the map height is not in pixels), in (0, 1].
alphafloatOpacity, 0 to 1.
variantstr"default", "dark", or a named variant from marks().
embedboolInline each image as a data URI (a map that renders offline) instead of linking its URL.
id_systemstrThe id system of teams; "auto" tries each in order.

Returns​

object — target itself, with the markers in the "sdvplot logos" feature group.

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 a location is not a number.
  • UnsupportedTargetError: (a TypeError) If target is not a folium.Map.
  • 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 folium
import sdvplot

m = folium.Map(location=[39, -95], zoom_start=4, height=600)
sdvplot.add_logos(m, [-94.48, -78.79], [39.05, 42.77], ["KC", "BUF"], league="nfl", height=0.06)

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',
embed: bool = False,
id_system: str = 'auto',
) -> Any

Put each team's wordmark on a Folium map at its (longitude, latitude).

Arguments​

NameTypeDescription
targetAnyA folium.Map.
xAnyThe longitudes.
yAnyThe latitudes, 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 map's reference height (see add_logos), 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​

object — target itself, with the markers 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 a location is not a number.
  • UnsupportedTargetError: (a TypeError) If target is not a folium.Map.
  • 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 folium
import sdvplot

m = folium.Map(location=[39, -95], zoom_start=4)
sdvplot.add_wordmarks(m, [-94.48], [39.05], ["KC"], league="nfl", height=0.04)

See also​

axis_logos​

axis_logos(target: Any, axis: str, **kwargs: Any) -> Any

Not supported: a map has no category axes.

Arguments​

NameTypeDescription
targetAnyA folium.Map.
axisstr"x" or "y".
**kwargsAnyIgnored.

Returns​

object — Never returns.

Raises​

  • UnsupportedTargetError: (a TypeError) Always. Put the logos on the map with add_logos instead.

Example​

import folium
import sdvplot

try:
sdvplot.axis_logos(folium.Map(), "x", league="nfl")
except TypeError:
pass # raised: maps have no axis logos

See also​