{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# Logos and eras\n",
    "\n",
    "A franchise changes marks over time. `logo_url` and `logo_image` take a `season` and return the mark in use that\n",
    "year."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import sdvplot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2",
   "metadata": {},
   "outputs": [],
   "source": [
    "sdvplot.logo_url(\"LV\", \"nfl\"), sdvplot.logo_url(\"OAK\", \"nfl\", season=2010)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3",
   "metadata": {},
   "source": [
    "## The marks table\n",
    "\n",
    "The marks table lists every mark with the seasons it is valid for. Sorted by `valid_from`, the dated Oakland-era marks\n",
    "(1960-2019) come first; marks with no dates are the current ones."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4",
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    sdvplot.marks(\"LV\", \"nfl\")\n",
    "    .sort(\"valid_from\", nulls_last=True)\n",
    "    .select(\"entity_name\", \"variant\", \"mark_type\", \"valid_from\", \"valid_to\", \"source\")\n",
    "    .head(8)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5",
   "metadata": {},
   "source": [
    "## Logos by season\n",
    "\n",
    "`logo_image` returns a PIL image (or `None` when no mark exists), so it drops straight into `imshow`. Here are the Raiders in 2010, 2019 and 2024."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6",
   "metadata": {
    "sdvplot_gallery": {
     "alt": "The Raiders logo in 2010, 2019 and 2024: the Oakland mark for 2010 and 2019, the Las Vegas mark for 2024.",
     "title": "Raiders logos by season"
    },
    "tags": [
     "gallery"
    ]
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "fig, axes = plt.subplots(1, 3, figsize=(9, 3))\n",
    "for ax, s in zip(axes, (2010, 2019, 2024), strict=True):\n",
    "    ax.imshow(sdvplot.logo_image(\"LV\", \"nfl\", season=s, size=200))\n",
    "    ax.set_title(str(s))\n",
    "    ax.axis(\"off\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7",
   "metadata": {},
   "source": [
    "2010 and 2019 are the same Oakland mark (valid 1960-2019); the Las Vegas mark starts after that."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8",
   "metadata": {},
   "source": [
    "## SVG marks\n",
    "\n",
    "NHL marks are SVGs, rasterized by the `svg` extra. The Avalanche moved from Quebec in 1995, so 1993 is the Nordiques mark."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9",
   "metadata": {
    "sdvplot_gallery": {
     "alt": "The Quebec Nordiques logo for 1993 and the Colorado Avalanche logo for 2024, rasterized from SVG.",
     "title": "Nordiques and Avalanche marks"
    },
    "tags": [
     "gallery"
    ]
   },
   "outputs": [],
   "source": [
    "fig, axes = plt.subplots(1, 2, figsize=(6, 3))\n",
    "for ax, s in zip(axes, (1993, 2024), strict=True):\n",
    "    ax.imshow(sdvplot.logo_image(\"COL\", \"nhl\", season=s, size=200))\n",
    "    ax.set_title(str(s))\n",
    "    ax.axis(\"off\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10",
   "metadata": {},
   "source": [
    "## How era selection works\n",
    "\n",
    "Each mark carries `valid_from` / `valid_to` seasons (inclusive), or none. With a `season`, sdvplot picks, within the\n",
    "requested variant, a mark with explicit dates that cover the season first, then an undated mark, and only then any\n",
    "other row. Without a `season` you get the current (undated) mark. See [Seasons and eras](../concepts/seasons-and-eras.md) for the full rules."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "sdvplot": {
   "description": "Get the logo a team used in a given season, from the marks table to images in a matplotlib figure.",
   "label": "Logos and eras",
   "position": 3
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}