Skip to main content
Version: main

Team identity

Every team in sdvplot has one canonical key: (league, team_id).

  • league is an SDV league key such as "nfl", "cfb", "nhl" or "ohl". It is always required, because the same abbreviation means different teams in different leagues.
  • team_id is always a string: the id the logo archive uses for that team. For ESPN leagues that is ESPN's team id, so the Kansas City Chiefs are ("nfl", "12").

sdvplot.teams(league) returns the bundled index, one row per team:

import sdvplot

sdvplot.teams("nfl").shape # (32, 13)

A college team's division is its NCAA division in its latest season in ESPN's groups: "FBS", "FCS", "DII" or "DIII" in cfb (teams("cfb").filter(pl.col("division") == "FCS")), "DI", "DII" or "DIII" in the other college leagues, and null for a team with no NCAA division there (NAIA, a dropped program) and for pro teams. cfbplotR's P5/G5 split is not a column: it is a grouping of conferences that changes (the Power Five became the Power Four in 2024), so take it from conference_id (the Power Four today: cfb:acc, cfb:big-ten, cfb:big-12, cfb:sec) for the seasons you mean.

Conferences are opt-in (sdvplotR's include_conferences): teams("cfb", include_conferences=True) adds the league's conference rows (and the league's own: the AFC, NFC and NFL; MLB, AL and NL; the NBA and WNBA with East and West; the NHL with its division marks; the AAF; NCAA in every college league), with program "conference" or "league" and the short name ("SEC", "Big 12", "AFC", "East") as team_id and abbr; a team's conference_id equals its conference row's. Every other listing shows teams only, and resolve() and palette() never answer a conference key (CFB's MAC is Macalester, not the Mid-American Conference). The logo functions take a conference's key and sdvplotR's other names for it (logo_url("Southeastern Conference", "cfb") is logo_url("SEC", "cfb")), after every team.

Soccer is one league key, soccer, for every club ESPN covers. There conference_id and conference mean a club's domestic league: the league competition it was seen in in its latest season, as ESPN's slug and name ("eng.1", "English Premier League"), so teams("soccer").filter(pl.col("conference_id") == "eng.1") is the Premier League. Cups and the confederations' competitions are not leagues, and a club in two leagues that season gets none. National teams (a World Cup or its qualifying) have program "national" and no domestic league. Every competition a club was seen in, the Champions League and the cups included, is an alias of id system "competition" (value: the slug, dated by that competition's season) in the index's alias table; resolve() never reads it, since one slug names many clubs.

Resolving what you have​

resolve() turns the identifiers in your data into canonical team_ids:

sdvplot.resolve("LV", "nfl") # '13'
sdvplot.resolve(["KC", "kc", "Kansas City Chiefs", 12, "12.0"], "nfl") # ['12', '12', '12', '12', '12']

Values are compared in one normal form: trimmed, case-folded, with accents and typographic punctuation folded, so "San José State" matches "San Jose State". Eight Latin letters with no accent to drop fold too: ø to o, æ to ae, œ to oe, đ and ð to d, ł to l, þ to th and ı to i (ß is ss), so "Køge" matches "Koge" and "Łódź" matches "Lodz". Integral numbers lose their decimal point, so 12, "12", 12.0 and "12.0" are the same value.

Id systems​

The index holds aliases from these id systems. With the default id_system="auto", resolve() tries them in this order (sdvplot._resolve.PRIORITY):

Orderid_systemWhat it holds
1team_idthe canonical id itself
2espnESPN team ids
3espn_abbrESPN abbreviations
4nhlNHL tri-codes, such as "NJD"
5nflversenflverse abbreviations
6mlbstatsMLB Stats API team ids (MLB and MiLB)
7nba_apiNBA and WNBA Stats team ids, such as 1610612747 (the Lakers) and 1611661319 (the Aces), and their tricodes (WNBA: LVA)
8hockeytechHockeyTech team ids (AHL, ECHL, OHL, PWHL, QMJHL, USHL, WHL, and the junior and minor leagues SPHL, CHL, BCHL, AJHL, SJHL, OJHL, CCHL, GOJHL, MHL, NOJHL, VIJHL, KIJHL, MJHL)
9ncaastats.ncaa.org team ids: each season's team id (college football, men's and women's basketball, college baseball) and, outside football, each school's org id (Duke is 193; college softball has org ids only)
10pffPFF franchise ids (AAF)
11cricinfoCricinfo team ids
12cfbdCFBD school names and abbreviations
13brefSports Reference abbreviations (MLB, NBA, NFL, WNBA)
14sportsipysportsipy abbreviations (MLB, NBA, NFL, WNBA)
15fangraphsFanGraphs abbreviations (MLB)
16yahooYahoo team ids, such as "nba.t.1" and "ncaaf.t.1" (NFL, college football, NBA, WNBA, men's and women's college basketball, MLB, NHL)
17kenpomKenPom team names (men's college basketball)
18torvikTorvik (Barttorvik) team names (men's and women's college basketball)
19sdvplotrsdvplotR's clean_team_abbrs keys
20nameteam names, short names and locations, and cfbplotR's team_name_mapping spellings

sdvplotr sits after every id system, so it only fills gaps. name comes last. A name that name or cfbd gives several teams, none of them for a season range, goes to the one team whose own name (name or short_name) it is, so another team's location never shadows it: "Charlotte" is the 49ers, not the Charlotte Saints (Faith NC, located in Charlotte). One that is several teams' own name ("Bethany"), or no team's ("New York"), stays ambiguous. A season-dated alias keeps its range: in a season it covers that also has another team's own-name alias, the value stays ambiguous. cfbplotR's spellings (the ARK STATE, VA TECH feed forms, NC St., UT San Antonio) only fill gaps: one the index already has, for any team, adds nothing, and one cfbplotR's rows give two teams or no team adds nothing.

Pass id_system= to use a single system instead, for example resolve(values, "mlb", id_system="fangraphs"). An id_system or league sdvplot does not know raises InputError (a ValueError), as does a season that is not a year or is outside the seasons the index knows for the league.

How "auto" decides​

  • The first system that has a candidate for the value decides. Later systems are not consulted.
  • Only a unique match counts. If that system names more than one team, the value is ambiguous.
  • With a season, sdvplot first considers only aliases whose season range covers that season. Then (or first, without a season) it reads the value in the latest season the league's aliases name, so a code two franchises used means its current holder. Last, it considers every alias, so a unique code still resolves when no range covers the season. See Seasons and eras.

Never guessing​

An unknown or ambiguous value comes back as None. One SdvplotWarning lists every value that failed, and why:

sdvplot.resolve(["KC", "XXX"], "nfl")
# ['12', None]
# SdvplotWarning: 1 value(s) did not resolve to a nfl team: 'XXX' (unknown). Use sdvplot.suggest() for
# candidates, or strict=True to raise.

sdvplot.resolve("New York", "nfl")
# None, with a warning: 'New York' (ambiguous), because the Giants and the Jets share it

Pass strict=True to raise UnresolvedTeamError (a ValueError) instead.

suggest() is the only fuzzy matching in sdvplot. It returns (team_id, name) candidates, best first, and never picks one for you:

sdvplot.suggest("Kansas Cty Chiefs", "nfl") # [('12', 'Kansas City Chiefs')]
sdvplot.suggest("New York", "nfl")
# [('19', 'New York Giants'), ('20', 'New York Jets'), ('18', 'New Orleans Saints')]

Numeric NHL API, Fox, CBS, 247Sports and On3 ids​

The NHL stats API numbers its teams 1 and up, and those numbers are also ESPN ids for other NHL teams. Under "auto" a number is read as an ESPN id, so pass id_system="nhl_id" for NHL API ids. "auto" never tries nhl_id (sdvplot._resolve.EXPLICIT_ONLY). NHL tri-codes resolve under "auto".

sdvplot.resolve(1, "nhl") # '1' (ESPN id 1: the Boston Bruins)
sdvplot.resolve(1, "nhl", id_system="nhl_id") # '11' (NHL API id 1: the New Jersey Devils)
sdvplot.resolve("NJD", "nhl") # '11'

Fox, CBS, 247Sports and On3 number teams too, and their numbers are also other teams' ESPN ids, so they are explicit-only as well: id_system="fox", "cbs", "sports247" (247Sports team ids and institution keys) or "on3" (On3 org keys). They come from sdv-reference-data's {league}_team_aliases tables, as do the Yahoo, KenPom and Torvik aliases, with the seasons the source gives each id.

sdvplot.resolve("25", "cfb") # '25' (ESPN id 25: California)
sdvplot.resolve("25", "cfb", id_system="fox") # '194' (Fox id 25: Ohio State)
sdvplot.resolve("ncaaf.t.1", "cfb") # Yahoo's dotted ids resolve under "auto"

Containers​

resolve() returns the shape it was given:

InputOutput
a scalara str, or None
a list, tuple or numpy arraya list
a pandas Seriesa pandas Series of strings, with the same name and index
a polars Seriesa polars String Series with the same name
import pandas as pd

sdvplot.resolve(pd.Series(["KC", "SF"], index=[10, 20], name="team"), "nfl")
# 10 12
# 20 25
# Name: team

team_colors() follows the same rule.