sdvplot 0.1.0__py3-none-any.whl

sdvplot/_colors.py

@@ -0,0 +1,206 @@
+"""Team colors as plain {team: "#hex"} dicts, which seaborn, Plotly, Altair, Bokeh and PyPalettes all accept."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import TYPE_CHECKING, Any, overload
+
+from sdvplot import _index
+from sdvplot._errors import InputError, warn
+from sdvplot._resolve import _seasons, _unpack, resolve
+from sdvplot._types import IdSystem, Which
+
+if TYPE_CHECKING:
+    import numpy as np
+    import pandas as pd
+    import polars as pl
+else:
+    from sdvplot._lazy import pl
+
+_COLUMNS = {"primary": "color_primary", "secondary": "color_secondary"}
+
+
+def _column(which: str) -> str:
+    if which not in _COLUMNS:
+        raise InputError(f"which must be one of {sorted(_COLUMNS)}, got {which!r}")
+    return _COLUMNS[which]
+
+
+def _colors(league: str, column: str) -> dict[str, str]:
+    t = _index.team_table().filter(pl.col("league") == league)
+    return {tid: c for tid, c in t.select("team_id", column).iter_rows() if c}
+
+
+def palette(
+    league: str,
+    teams: Any = None,
+    *,
+    which: Which = "primary",
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> dict[Any, str]:
+    """A ``{team: "#hex"}`` dict for a league, ready for seaborn, Plotly, Altair, Bokeh or PyPalettes.
+
+    Without ``teams`` the keys are canonical abbreviations, or the team_id where a team has no abbreviation or shares
+    it with another team of the league (never guessing which team an abbreviation means). With ``teams`` the keys are
+    the caller's own values, so they match a seaborn ``hue`` column or a Plotly color column exactly.
+
+    Args:
+        league: The SDV league key, e.g. "nfl".
+        teams: Team values to key the dict by; None returns the whole league.
+        which: "primary" or "secondary".
+        season: One season, or one per team, for values reused across eras.
+        id_system: The id system of ``teams``, as in ``resolve``: "auto" tries each in order; NHL stats ids need
+            "nhl_id".
+        strict: Raise UnresolvedTeamError instead of warning when a team does not resolve.
+
+    Returns:
+        dict: ``{team: "#hex"}``. Teams that do not resolve, or have no color, are left out. Without ``teams``, a team
+        whose abbreviation another team of the league shares is keyed by its team_id, with one SdvplotWarning naming
+        the shared abbreviations.
+
+    Raises:
+        TypeError: If ``teams`` is not a scalar, list, tuple, numpy array, or pandas/polars Series.
+        InputError: (a ValueError) If ``league`` is not a known league key or ``which`` is not "primary"/"secondary";
+            and, when ``teams`` is given, if it holds "primary" or "secondary" (the slot goes in ``which=``),
+            ``id_system`` is unknown, or ``season`` is not a year, is outside the seasons sdvplot knows for the league,
+            or is a list whose length does not match the teams. Without ``teams`` they are not checked.
+        UnresolvedTeamError: (a ValueError) If ``strict=True`` and a team does not resolve.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.palette("nfl", teams=["KC", "SF"])   # {'KC': '#e31837', 'SF': '#aa0000'}
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    column = _column(which)
+    _index.check_league(league)
+    colors = _colors(league, column)
+    if teams is None:
+        rows = _index.team_table().filter(pl.col("league") == league).select("team_id", "abbr").rows()
+        shared = {a for a, n in Counter(a for _, a in rows if a).items() if n > 1}
+        if shared:
+            warn(f"abbreviations shared by several {league} teams are keyed by team_id: {', '.join(sorted(shared))}")
+        return {(tid if not abbr or abbr in shared else abbr): colors[tid] for tid, abbr in rows if tid in colors}
+    values, _ = _unpack(teams)
+    if slots := [v for v in values if isinstance(v, str) and v in _COLUMNS]:  # pre-0.1: palette(league, which)
+        raise InputError(
+            f"{slots[0]!r} is a color slot, not a team; pass it by keyword: "
+            f'palette(league, teams=..., which="{slots[0]}")'
+        )
+    pairs = [p for p in dict.fromkeys(zip(values, _seasons(season, len(values)), strict=True)) if p[0] is not None]
+    ids = resolve([v for v, _ in pairs], league, season=[s for _, s in pairs], id_system=id_system, strict=strict)
+    out: dict[Any, str] = {}
+    for (v, _), i in zip(pairs, ids, strict=True):
+        if i is not None and i in colors:
+            out.setdefault(v, colors[i])  # a value two teams wore across the seasons keeps its first team's color
+    return out
+
+
+# resolve()'s container rule, and so its overloads (the last one's ignore included).
+@overload
+def team_colors(
+    league: str,
+    teams: str | bytes | int | float | None,
+    *,
+    which: Which = "primary",
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> str | None: ...
+@overload
+def team_colors(
+    league: str,
+    teams: pl.Series,
+    *,
+    which: Which = "primary",
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> pl.Series: ...
+@overload
+def team_colors(
+    league: str,
+    teams: list[Any] | tuple[Any, ...] | np.ndarray[Any, Any],
+    *,
+    which: Which = "primary",
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> list[str | None]: ...
+@overload
+def team_colors(
+    league: str,
+    teams: pd.Series,
+    *,
+    which: Which = "primary",
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> pd.Series: ...
+@overload
+def team_colors(  # type: ignore[overload-cannot-match]
+    league: str,
+    teams: Any,
+    *,
+    which: Which = "primary",
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> Any: ...
+def team_colors(
+    league: str,
+    teams: Any,
+    *,
+    which: Which = "primary",
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> Any:
+    """One "#hex" (or None) per team value, in the same container the values came in.
+
+    Args:
+        league: The SDV league key, e.g. "nfl".
+        teams: A scalar, list/tuple, numpy array, or pandas/polars Series of team identifiers.
+        which: "primary" or "secondary".
+        season: One season, or one per team, for values reused across eras.
+        id_system: The id system of ``teams``, as in ``resolve``: "auto" tries each in order; NHL stats ids need
+            "nhl_id".
+        strict: Raise UnresolvedTeamError instead of warning when a team does not resolve.
+
+    Returns:
+        str | list | Series | None: The hex color for each team, None where a team does not resolve or has no color.
+
+    Raises:
+        TypeError: If ``teams`` is not a scalar, list, tuple, numpy array, or pandas/polars Series.
+        InputError: (a ValueError) If ``league`` is not a known league key (a list or Series there is the pre-0.1
+            ``team_colors(teams, league)`` order), ``which`` is not "primary"/"secondary", ``id_system`` is unknown,
+            or ``season`` is not a year, is outside the seasons sdvplot knows for the league, or is a list whose
+            length does not match the teams.
+        UnresolvedTeamError: (a ValueError) If ``strict=True`` and a team does not resolve.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.team_colors("nfl", ["KC", "SF"])              # ['#e31837', '#aa0000']
+            sdvplot.team_colors("nfl", "KC", which="secondary")   # '#ffb612'
+            sdvplot.team_colors("nhl", [1, 6, 10], id_system="nhl_id")   # NHL stats ids: Devils, Bruins, Leafs
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    column = _column(which)
+    _index.check_league(league)
+    colors = _colors(league, column)
+    values, wrap = _unpack(teams)
+    ids = resolve(values, league, season=season, id_system=id_system, strict=strict)
+    return wrap([colors.get(i) if i is not None else None for i in ids])

sdvplot/_contrast.py

@@ -0,0 +1,60 @@
+"""Color readability, ported from sdvplotR (R/utils-theme.R): WCAG luminance and contrast, a readable ink, mixing."""
+
+from __future__ import annotations
+
+_HEX = set("0123456789abcdefABCDEF")
+
+
+def hex6(color: str, *, drop_alpha: bool = False) -> str:
+    """A color as lowercase ``#rrggbb``: accepts ``#rgb``, ``#rrggbb``, ``#rgba`` and ``#rrggbbaa`` (``#`` optional).
+
+    Callers draw and measure the result as an opaque color (contrast, ramps, theme accents), so a color with
+    transparency is a ValueError rather than silently drawn solid; an opaque alpha (``ff``) is dropped. A caller that
+    sets its own alpha passes ``drop_alpha=True`` (as R's ``scales::alpha()`` replaces a color's alpha). Named colors
+    and tuples are not hex colors.
+    """
+    c = str(color).strip().lstrip("#")
+    if len(c) in (3, 4):
+        c = "".join(ch * 2 for ch in c)
+    if len(c) not in (6, 8) or not set(c) <= _HEX:
+        raise ValueError(f"not a hex color: {color!r}")
+    if len(c) == 8 and c[6:].lower() != "ff" and not drop_alpha:
+        raise ValueError(f"{color!r} has transparency; give an opaque color such as '#{c[:6].lower()}'")
+    return "#" + c[:6].lower()
+
+
+def luminance(color: str) -> float:
+    """WCAG relative luminance, 0 (black) to 1 (white)."""
+    c = hex6(color)
+    rgb = [int(c[i : i + 2], 16) / 255 for i in (1, 3, 5)]
+    lin = [v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4 for v in rgb]
+    return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+
+
+def contrast(a: str, b: str) -> float:
+    """WCAG contrast ratio between two colors, 1 (same) to 21 (black on white)."""
+    la, lb = luminance(a), luminance(b)
+    return (max(la, lb) + 0.05) / (min(la, lb) + 0.05)
+
+
+def on_color(background: str) -> str:
+    """Black or white, whichever reads better on ``background`` (sdvplotR's ``.theme_on_color``)."""
+    return "#000000" if contrast("#000000", background) >= contrast("#ffffff", background) else "#ffffff"
+
+
+def mix(a: str, b: str, t: float) -> str:
+    """The color ``t`` of the way from ``a`` to ``b`` in sRGB (``t`` in [0, 1])."""
+    if not 0 <= t <= 1:
+        raise ValueError(f"t must be in [0, 1], got {t!r}")
+    ca, cb = hex6(a), hex6(b)
+    out = [round(int(ca[i : i + 2], 16) * (1 - t) + int(cb[i : i + 2], 16) * t) for i in (1, 3, 5)]
+    return "#" + "".join(f"{v:02x}" for v in out)
+
+
+def solid(color: str, background: str = "#ffffff") -> str:
+    """The opaque ``#rrggbb`` a hex color shows as over ``background``: a translucent ``#rgba``/``#rrggbbaa`` is
+    alpha-composited onto it, so its contrast can be measured; an opaque color is itself."""
+    opaque = hex6(color, drop_alpha=True)  # ValueError for anything but a hex color
+    c = str(color).strip().lstrip("#")
+    alpha = int(c[3] * 2, 16) / 255 if len(c) == 4 else int(c[6:], 16) / 255 if len(c) == 8 else 1.0
+    return mix(background, opaque, alpha)

sdvplot/_court.py

@@ -0,0 +1,110 @@
+"""Shot locations from the stats.nba.com legacy frame to sportypy's court: the port of sdvplotR's sdv_court_coords()."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import narwhals as nw
+
+from sdvplot._placement import _missing
+
+BASKET_X = -47 + 5.25  # sportypy's NBA/WNBA/NCAA courts: center-court origin, baseline at -47, basket 5.25 ft in
+
+
+def _tenths(frame: Any, name: str) -> Any:
+    """Column ``name`` (tenths of a foot) as a Float64 Series; strings of numbers are coerced."""
+    s = frame[name]
+    if s.dtype.is_numeric():  # rebuilt like the coerced columns, so both outputs share one dtype (pandas nullable too)
+        floats = [None if _missing(v) else v for v in s.cast(nw.Float64).to_list()]
+        return nw.new_series(name, floats, nw.Float64(), backend=nw.get_native_namespace(frame))
+    all_null_bool = s.dtype == nw.Boolean and s.null_count() == len(s)  # R/arrow write an all-NA column as logical
+    if s.dtype not in (nw.String, nw.Object, nw.Unknown) and not all_null_bool:  # Unknown: a polars Null column
+        raise TypeError(f"column {name!r} must be numeric or strings of numbers, not {s.dtype}")
+    values: list[float | None] = []
+    bad: list[Any] = []
+    for v in s.to_list():
+        if _missing(v):
+            values.append(None)
+            continue
+        if type(v).__name__ in ("bool", "bool_"):  # Python and numpy booleans, which float() reads as 1.0 / 0.0
+            raise TypeError(f"column {name!r} must be numeric or strings of numbers, not booleans")
+        try:  # float() reads strings and numbers; R's as.numeric() reads no "_" digit separators, so neither do we
+            f = math.nan if isinstance(v, str) and "_" in v else float(v)
+        except (TypeError, ValueError):
+            f = math.nan
+        if math.isnan(f):
+            bad.append(v)
+        values.append(f)
+    if bad:
+        raise ValueError(
+            f"column {name!r} has values that are not numbers: {sorted(set(map(str, bad)))}; name the coordinate "
+            "columns with x=/y=, or fix the input data"
+        )
+    return nw.new_series(name, values, nw.Float64(), backend=nw.get_native_namespace(frame))
+
+
+def court_coords(data: Any, *, x: str = "x_legacy", y: str = "y_legacy") -> Any:
+    """Convert stats.nba.com / stats.wnba.com shot locations to the court frame sportypy draws.
+
+    The stats API's legacy shot frame (``LOC_X``/``LOC_Y``; hoopR, wehoop and sdv-py ``x_legacy``/``y_legacy``) is in
+    tenths of a foot with the hoop at the origin, relative to the shooter's basket. sportypy's ``NBACourt``,
+    ``WNBACourt`` and ``NCAACourt`` (what ``surface("nba")`` draws) put the origin at center court, the baseline at
+    ``x = -47`` and the basket at ``x = -41.75``. So ``court_x = -47 + 5.25 + y / 10`` and ``court_y = x / 10``, with no
+    sign flip: a left-corner three lands at negative ``court_y``. Every shot falls on the TV-left half; draw a half
+    court with ``surface("nba", display_range="defense")``. Don't pass ESPN ``coordinate_x``/``coordinate_y``: they
+    are already in feet on a center-court frame.
+
+    Args:
+        data: A pandas or polars DataFrame of shots.
+        x: The column holding ``LOC_X`` / ``x_legacy`` (tenths of a foot, across the court).
+        y: The column holding ``LOC_Y`` / ``y_legacy`` (tenths of a foot, toward half court).
+
+    Returns:
+        DataFrame: ``data``'s type, with ``court_x`` and ``court_y`` (feet, Float64) added; existing columns of those
+        names are replaced in place, every other column is kept. Numeric columns and strings of numbers (stats.nba.com
+        payloads arrive as strings) convert; nulls stay null, and an all-null column gives null coordinates.
+
+    Raises:
+        TypeError: If ``data`` is not a pandas/polars DataFrame, ``x``/``y`` is not a string, or a coordinate column
+            is boolean (or holds booleans), categorical or another non-numeric type.
+        ValueError: If ``x`` and ``y`` name the same column, a column is missing, or a string is not a number (such
+            as ``""``, ``"NA"`` or ``"1_0"``).
+
+    Example:
+        ::
+
+            import polars as pl
+            import sdvplot
+
+            shots = pl.DataFrame({"LOC_X": [-224, 240], "LOC_Y": [39, 29]})
+            out = sdvplot.court_coords(shots, x="LOC_X", y="LOC_Y")
+            out["court_y"].to_list()   # [-22.4, 24.0]: a left and a right corner three
+
+            ax = sdvplot.surface("nba", display_range="defense")
+            ax.scatter(out["court_x"], out["court_y"], zorder=20)
+
+    See Also:
+        sdvplotR sdv_court_coords(): https://sdvplotR.sportsdataverse.org/ ;
+        sportypy: https://sportypy.sportsdataverse.org/ ;
+        nba_api shotchartdetail: https://github.com/swar/nba_api
+    """
+    try:
+        frame = nw.from_native(data, eager_only=True)
+    except TypeError:
+        raise TypeError(f"data must be a pandas or polars DataFrame, got {type(data).__name__}") from None
+    for arg, column in (("x", x), ("y", y)):
+        if not isinstance(column, str):
+            raise TypeError(f"{arg} must be a single column name (a string), got {column!r}")
+    if x == y:
+        raise ValueError(f"x and y must name different columns, not both {x!r}")
+    missing = [c for c in (x, y) if c not in frame.columns]
+    if missing:
+        raise ValueError(
+            f"data is missing column(s) {missing}; name the stats-API columns with x=/y=, e.g. x='LOC_X', y='LOC_Y'"
+        )
+    # Divide by a Series of tens, not the scalar: polars divides by a scalar through its reciprocal, so -224 / 10 would
+    # be -22.400000000000002 instead of R's (and IEEE division's) -22.4.
+    ten = nw.new_series("ten", [10.0] * len(frame), nw.Float64(), backend=nw.get_native_namespace(frame))
+    xs, ys = _tenths(frame, x) / ten, _tenths(frame, y) / ten
+    return frame.with_columns(court_x=ys + BASKET_X, court_y=xs).to_native()

sdvplot/_deprecate.py

@@ -0,0 +1,39 @@
+"""Deprecations: one warning category and one way to emit it, so every rename warns the same way (CONTRIBUTING:
+Deprecation policy). Nothing in sdvplot is deprecated yet."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from sdvplot._errors import SdvplotDeprecationWarning, warn
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def deprecate(old: str, *, replacement: str, removal: str) -> None:
+    """Warn, at the caller's line, that ``old`` is deprecated: it names ``replacement`` and ``removal``, the release
+    that removes it. Call it from the deprecated function or branch, which keeps working."""
+    warn(f"{old} is deprecated and will be removed in sdvplot {removal}; use {replacement} instead",
+         SdvplotDeprecationWarning)  # fmt: skip
+
+
+def deprecated_alias(*, removal: str, **renames: str) -> Callable[[F], F]:
+    """A decorator for renamed keyword arguments: ``@deprecated_alias(removal="0.3.0", which="kind")`` keeps
+    ``fn(which=...)`` working as ``fn(kind=...)``, with one warning per call. Passing both names is a TypeError."""
+
+    def decorate(fn: F) -> F:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            for old, new in renames.items():
+                if old in kwargs:
+                    if new in kwargs:
+                        raise TypeError(f"{fn.__name__}() got both {old}= (deprecated) and {new}=; pass only {new}=")
+                    deprecate(f"{fn.__name__}({old}=...)", replacement=f"{new}=", removal=removal)
+                    kwargs[new] = kwargs.pop(old)
+            return fn(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorate