{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# sdvplot quickstart\n",
    "\n",
    "sdvplot gives every SportsDataverse team a canonical id, a color pair, and logos (with eras) so you can label and\n",
    "color charts the same way in any plotting library. Lookups run against a bundled team index; logos and headshots are\n",
    "fetched on demand and cached.\n",
    "\n",
    "## Install\n",
    "\n",
    "```bash\n",
    "pip install \"sdvplot[mpl,svg] @ git+https://github.com/sportsdataverse/sdvplot\"\n",
    "```\n",
    "\n",
    "The `mpl` extra installs matplotlib, used here to plot `logo_image` marks (`add_logos()`, `add_wordmarks()` and `add_headshots()` draw the same marks straight onto a matplotlib plot), and the `svg` extra rasterizes SVG marks (many NHL logos are SVG)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import sdvplot"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2",
   "metadata": {},
   "source": [
    "## Resolve team values\n",
    "\n",
    "`resolve` turns team values from any supported source (abbreviations, names, ESPN ids) into one canonical `team_id`. The league is always required."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3",
   "metadata": {},
   "outputs": [],
   "source": [
    "sdvplot.resolve([\"LV\", \"OAK\", \"Las Vegas Raiders\", 13], \"nfl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4",
   "metadata": {},
   "source": [
    "## Seasons\n",
    "\n",
    "`season=` is optional. It picks the right team when a code was reused, and it is how era-aware lookups such as logos choose a mark."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5",
   "metadata": {},
   "outputs": [],
   "source": [
    "sdvplot.resolve(\"OAK\", \"nfl\", season=2010), sdvplot.resolve(\"OAK\", \"nfl\", season=2024)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6",
   "metadata": {},
   "source": [
    "Both seasons give the Raiders (`'13'`): in the shipped NFL index no code is shared by two franchises, so the season does not change\n",
    "the answer here, and a unique code still resolves when the season is outside its dates. The era only changes *logos*, which\n",
    "[the logos tutorial](03_logos_and_seasons.ipynb) shows.\n",
    "\n",
    "## Suggestions\n",
    "\n",
    "When a value does not resolve, `suggest` lists close candidates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7",
   "metadata": {},
   "outputs": [],
   "source": [
    "sdvplot.suggest(\"Las Vegas Raider\", \"nfl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8",
   "metadata": {},
   "source": [
    "## The team table\n",
    "\n",
    "`teams` returns the team table for a league."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9",
   "metadata": {},
   "outputs": [],
   "source": [
    "sdvplot.teams(\"nfl\").head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10",
   "metadata": {},
   "source": [
    "## Colors\n",
    "\n",
    "`palette` maps team ids or abbreviations to primary colors, ready for a plotting library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11",
   "metadata": {},
   "outputs": [],
   "source": [
    "sdvplot.palette(\"nfl\", teams=[\"LV\", \"KC\", \"SF\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12",
   "metadata": {},
   "source": [
    "## Logos\n",
    "\n",
    "`logo_url` returns a CDN url for a team's mark."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "13",
   "metadata": {},
   "outputs": [],
   "source": [
    "sdvplot.logo_url(\"KC\", \"nfl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14",
   "metadata": {},
   "source": [
    "## Versions\n",
    "\n",
    "`versions` reports the package, bundled index, and logo manifest versions in use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15",
   "metadata": {},
   "outputs": [],
   "source": [
    "sdvplot.versions()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "sdvplot": {
   "description": "Resolve team values, pick a season, and get team colors and logo urls with sdvplot.",
   "label": "Quickstart",
   "position": 1
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}