@sportsdataverse/sdvplot 0.0.0-stage → 0.1.0

package/dist/shots.d.ts

@@ -0,0 +1,364 @@
+import { Lattice, BinnerOptions } from './bins.js';
+export { BinOf, BinShape, Binner, binner, cellPath, cellPoints, hexagonPath, hexbin, squarePath, squarebin } from './bins.js';
+import { BasketballZone } from '@sportsdataverse/sporty';
+
+/** The diff colours: `"rdbu"` (blazing-the-nets `main`, the default) or `"master"` (its 2021 five stops). */
+type DiffPalette = "rdbu" | "master";
+/** Options for `diffScale`. */
+interface DiffScaleOptions {
+    /**
+     * `"rdbu"` (default): RdBu reversed, above league red (blazing-the-nets `main`), clamped at `±domain`.
+     * `"master"`: the 2021 five-stop red-yellow-green, UNCLAMPED like master's d3 `scaleLinear`: a diff past the end
+     * stops (±0.99) extrapolates, each channel then clamped to 0-255. An infinite diff takes the end colour (d3 gives
+     * `rgb(0, 0, 0)` for `Infinity` and `rgb(0, 255, 0)` for `-Infinity`).
+     */
+    palette?: DiffPalette;
+    /** `"dark"` swaps RdBu's near-white centre for `#303030` so an average mark recedes (`theme.ts:52-58`). Ignored by `"master"`. */
+    theme?: "light" | "dark";
+    /** Saturation in FG% fraction, finite and above 0 (else InputError); default 0.15 (`theme.ts:29`). `"master"` keeps its own stops. */
+    domain?: number;
+    /** Colour for `null` (no league figure); default `var(--sdv-muted, #525252)`. */
+    nullColor?: string;
+}
+/** A diff colour function plus the equivalent Plot colour-scale options (for fills and `Plot.legend`). */
+interface DiffScale {
+    (diff: number | null): string;
+    /** Diffs to place gradient stops at: 5 across [-D, D] (`theme.ts:127-130`), or `master`'s own 5 stops. */
+    readonly stops: readonly number[];
+    readonly plot: {
+        readonly type: "diverging" | "linear";
+        readonly domain: readonly number[];
+        readonly range?: readonly string[];
+        readonly scheme?: "RdBu";
+        readonly reverse?: boolean;
+        readonly pivot?: number;
+        readonly interpolate?: "rgb";
+        readonly clamp: boolean;
+    };
+}
+/**
+ * The FG%-vs-league colour: `diffScale()(0.05)`. Light RdBu, dark RdBu, or `master`'s palette; `null` is
+ * `nullColor`. `.plot` is the same scale as Observable Plot `color` options, so `Plot.legend({ color: s.plot })`
+ * draws the matching key.
+ *
+ * @example
+ * ```ts
+ * import { diffScale } from "@sportsdataverse/sdvplot/shots";
+ *
+ * diffScale({ theme: "dark" })(0.05);
+ * ```
+ */
+declare function diffScale(o?: DiffScaleOptions): DiffScale;
+
+/**
+ * One field-goal attempt, as the `nba_stats_shots` release ships it: `x_legacy`/`y_legacy` in tenths of a foot,
+ * hoop at the origin, y toward half court; `shot_distance` in ROUNDED feet. Map other schemas once, first.
+ */
+interface ShotRow {
+    readonly x_legacy: number;
+    readonly y_legacy: number;
+    readonly shot_distance: number;
+    /** 2 or 3; zones read it (the scorer's call, not the coordinates). */
+    readonly shot_value: number;
+    /** `"Made"` or `"Missed"`. */
+    readonly shot_result: string;
+}
+/** Attempts, makes and FG% (`makes / attempts`, null with no attempts): the counts every shot aggregate carries. */
+interface Split {
+    readonly attempts: number;
+    readonly makes: number;
+    readonly fgPct: number | null;
+}
+/** One cell of `binShots`: its centre, counts, mean shot distance and majority zone. */
+interface CellBin extends Split {
+    /** Cell centre, legacy tenths. */
+    readonly x: number;
+    readonly y: number;
+    readonly meanDistance: number;
+    /** The zone most of the cell's attempts fall in (first seen wins a tie). */
+    readonly zone: BasketballZone;
+}
+/**
+ * Bin shots in DATA space (legacy tenths), dropping off-court points (aggregate.ts:86-104) and points with a
+ * non-finite coordinate (`main` lets `y_legacy = Infinity` through). `cell` is a hexagon
+ * radius (10 = a 1 ft hex) or any `binner` lattice, e.g. `{ shape: "square", side: 15 }`. Bins come out in
+ * first-seen order (d3-hexbin's, for hexagons).
+ *
+ * @example
+ * ```ts
+ * import { binShots } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const shots = [
+ *   { x_legacy: -1, y_legacy: 7, shot_distance: 1, shot_value: 2, shot_result: "Made" },
+ *   { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Missed" },
+ *   { x_legacy: -44, y_legacy: 252, shot_distance: 26, shot_value: 3, shot_result: "Made" },
+ * ];
+ * binShots(shots, 15);
+ * binShots(shots, { shape: "square", side: 15 });
+ * ```
+ */
+declare function binShots(shots: readonly ShotRow[], cell: number | BinnerOptions): CellBin[];
+/**
+ * League attempts behind a cell's league rate before it falls back to the zone, and the colour prior: one number for
+ * both (aggregate.ts:106-110). It is blazing-the-nets' tunable, set in its commit 25c3ab9f ("shrunk colours"), not a
+ * derived or measured constant; `cellsVsLeague`'s `minLeague`, `shrunkDiff`'s `k` and `signaturePoints`' `prior`
+ * override it per call.
+ */
+declare const LEAGUE_PRIOR_ATTEMPTS = 25;
+/**
+ * FG% minus the league rate `league`, shrunk toward it by a `k`-attempt prior: `(makes + k*L)/(attempts + k) - L`
+ * (aggregate.ts:112-119). `k = 0` is the raw difference (blazing-the-nets `master`). For colour, not labels.
+ *
+ * @example
+ * ```ts
+ * import { LEAGUE_PRIOR_ATTEMPTS, shrunkDiff } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn 2025-26, the radius-15 hexagon centred (77.9, 45): 4 of 4, where the league made 270 of 636
+ * shrunkDiff(4, 4, 270 / 636, LEAGUE_PRIOR_ATTEMPTS); // +0.08, not the raw +0.58
+ * ```
+ */
+declare function shrunkDiff(makes: number, attempts: number, league: number, k?: number): number;
+/** One league cell in a `LeagueIndex`: centre (legacy tenths), attempts and FG%. */
+interface LeagueCell {
+    readonly x: number;
+    readonly y: number;
+    readonly attempts: number;
+    readonly fgPct: number | null;
+}
+/**
+ * A season's league cells and zone rates on one lattice (`{ radius }` for hexagons, `{ shape: "square", side }`):
+ * plain JSON, computed once (aggregate.ts:125-146). blazing-the-nets names the cells `hexes`; here they are `cells`
+ * for either shape, so map that key when loading its JSON.
+ */
+type LeagueIndex = Lattice & {
+    readonly cells: readonly LeagueCell[];
+    readonly zones: Readonly<Record<BasketballZone, Split>>;
+};
+/** A player cell with the league FG% it is compared to (`cellsVsLeague`, `cellsVsDistance`); null with no league figure. */
+interface CellVsLeague extends CellBin {
+    readonly leagueFgPct: number | null;
+}
+/**
+ * The league index every player chart compares against (aggregate.ts:140-146), on a hexagon radius or any `binner`
+ * lattice; it stores the resolved lattice, so `equalArea` becomes the square's `side`.
+ *
+ * @example
+ * ```ts
+ * import { leagueIndex } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const shots = [
+ *   { x_legacy: -1, y_legacy: 7, shot_distance: 1, shot_value: 2, shot_result: "Made" },
+ *   { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Missed" },
+ *   { x_legacy: -44, y_legacy: 252, shot_distance: 26, shot_value: 3, shot_result: "Made" },
+ * ];
+ * leagueIndex(shots, 15).cells;
+ * ```
+ */
+declare function leagueIndex(league: readonly ShotRow[], cell: number | BinnerOptions): LeagueIndex;
+/**
+ * Player cells with the league FG% of the SAME cell (the player is binned on the index's own lattice, so the
+ * centres are equal); a cell the league shot fewer than `minLeague` times from falls back to its zone's league rate
+ * (aggregate.ts:155-165; blazing-the-nets `main`).
+ *
+ * @example
+ * ```ts
+ * import { cellsVsLeague, leagueIndex } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const made = { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Made" };
+ * const missed = { ...made, shot_result: "Missed" };
+ * cellsVsLeague([made], leagueIndex([made, missed], 15));
+ * ```
+ */
+declare function cellsVsLeague(player: readonly ShotRow[], league: LeagueIndex, minLeague?: number): CellVsLeague[];
+/** How a cell's attempts set its size: `main` (sqrt to the 95th percentile) or `master` (linear, capped). */
+type SizeRule = "sqrt-p95" | "linear-cap";
+/** `sizeCells`' result: each cell's size, the cap, the size of any count, and the counts for a size key. */
+interface CellSizes {
+    /** Size per cell in legacy tenths: a hexagon's circumradius, or a square's side. 0 hides a cell. */
+    readonly r: readonly number[];
+    /** Attempts at which size saturates. */
+    readonly cap: number;
+    /** The size of any attempt count, for a size key. */
+    readonly size: (attempts: number) => number;
+    /** A size key: 1, half the cap, the cap (blazing-the-nets `main` `lib/charts/hexShotChart.ts:199`). */
+    readonly steps: readonly number[];
+}
+/**
+ * Frequency size for each cell (the dual encoding's size half; colour is `diffScale`), on the lattice's full cell
+ * size `R` (a hexagon's radius, or a square's side; pass the index itself: `sizeCells(cells, index)`).
+ * `"sqrt-p95"` (default, `main` `hexShotChart.ts:65-81`): a sqrt scale of attempts to `R`, capped at the 95th
+ * percentile so one busy rim cell does not shrink the rest; area follows attempts for either shape.
+ * `"linear-cap"` (`master` `Hexagon/index.js:22-30`): attempts in tenths, capped at `R`, cells under 2 attempts
+ * hidden.
+ *
+ * @example
+ * ```ts
+ * import { binShots, sizeCells } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const shots = [
+ *   { x_legacy: -1, y_legacy: 7, shot_distance: 1, shot_value: 2, shot_result: "Made" },
+ *   { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Missed" },
+ *   { x_legacy: -44, y_legacy: 252, shot_distance: 26, shot_value: 3, shot_result: "Made" },
+ * ];
+ * sizeCells(binShots(shots, 15), { radius: 15 }).r; // the 2-attempt rim cell is full size, the 1-attempt three smaller
+ * ```
+ */
+declare function sizeCells(cells: readonly {
+    readonly attempts: number;
+}[], o: BinnerOptions & {
+    readonly rule?: SizeRule;
+}): CellSizes;
+/**
+ * Attempts, makes and FG% per zone (aggregate.ts:269-277).
+ *
+ * @example
+ * ```ts
+ * import { statsByZone } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // a Brooklyn corner three, 2025-26 (sportsdataverse-data nba_stats_shots)
+ * statsByZone([{ x_legacy: 237, y_legacy: 34, shot_distance: 24, shot_value: 3, shot_result: "Made" }]);
+ * ```
+ */
+declare function statsByZone(shots: readonly ShotRow[]): Record<BasketballZone, Split>;
+
+/** One `fgPctByDistance` bin: the counts of the shots `distance` to `distance + binFt` ft out, and their share. */
+interface DistanceBin extends Split {
+    /** First foot of the bin; `shot_distance` is rounded, so a 1-ft bin is centred on it. */
+    readonly distance: number;
+    /** Share of the attempts within `maxFt`. */
+    readonly share: number;
+}
+/**
+ * FG% by `shot_distance` in `binFt` bins from 0 to `maxFt`; longer attempts are left out (aggregate.ts:177-192).
+ * The total within `maxFt` is the sum of `attempts`. `binFt` and `maxFt` must be finite numbers above 0 (else
+ * InputError).
+ *
+ * @example
+ * ```ts
+ * import { fgPctByDistance } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const shots = [
+ *   { x_legacy: -1, y_legacy: 7, shot_distance: 1, shot_value: 2, shot_result: "Made" },
+ *   { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Missed" },
+ *   { x_legacy: -44, y_legacy: 252, shot_distance: 26, shot_value: 3, shot_result: "Made" },
+ * ];
+ * fgPctByDistance(shots, 3)[0];
+ * ```
+ */
+declare function fgPctByDistance(shots: readonly ShotRow[], binFt?: number, maxFt?: number): DistanceBin[];
+/** A player distance bin with the league's FG% at the same distance and the difference (`vsLeague`). */
+interface DistanceVsLeague extends DistanceBin {
+    readonly leagueFgPct: number | null;
+    /** Player minus league FG% (a fraction), null when either side has no attempts. */
+    readonly diff: number | null;
+}
+/**
+ * Pair player and league distance bins (same `binFt` and `maxFt`, else InputError) and take the difference
+ * (aggregate.ts:200-209).
+ *
+ * @example
+ * ```ts
+ * import { fgPctByDistance, vsLeague } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const made = { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Made" };
+ * const missed = { ...made, shot_result: "Missed" };
+ * vsLeague(fgPctByDistance([made]), fgPctByDistance([made, missed]))[0];
+ * ```
+ */
+declare function vsLeague(player: readonly DistanceBin[], league: readonly DistanceBin[]): DistanceVsLeague[];
+/** One `statsBySide` bin: left, centre and right of the hoop for the shots in the bin that starts `distance` ft out. */
+interface SideBin {
+    readonly distance: number;
+    readonly left: Split;
+    readonly centre: Split;
+    readonly right: Split;
+}
+/**
+ * Left / centre / right of the hoop by distance (aggregate.ts:218-240): left is `x < -centreHalfWidth`, right is
+ * `x > centreHalfWidth`. The default 0 puts `x == 0` in centre (`main`); `false` drops it, as `master`'s
+ * `binLeftRight` did (`src/utils/visuals/bin.ts:36-42`). `binFt` and `maxFt` as for `fgPctByDistance`; a
+ * `centreHalfWidth` that is negative or not finite throws InputError.
+ *
+ * @example
+ * ```ts
+ * import { statsBySide } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const shots = [
+ *   { x_legacy: -1, y_legacy: 7, shot_distance: 1, shot_value: 2, shot_result: "Made" },
+ *   { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Missed" },
+ *   { x_legacy: -44, y_legacy: 252, shot_distance: 26, shot_value: 3, shot_result: "Made" },
+ * ];
+ * statsBySide(shots, 3, 35, 7.5)[0];
+ * ```
+ */
+declare function statsBySide(shots: readonly ShotRow[], binFt?: number, maxFt?: number, centreHalfWidth?: number | false): SideBin[];
+/**
+ * Player cells against the league FG% at the cell centre's distance, `floor(|centre| / 10)` ft, falling back one
+ * foot when that bin is empty (blazing-the-nets `master` `src/components/Hexagon/index.js:44-49`). `cell` is a
+ * hexagon radius (default 10, master's) or any `binner` lattice, e.g. `{ shape: "square", side: 10 }`. `byFoot` is
+ * read as feet, so it must be 1-ft bins from 0 (`fgPctByDistance(league)`), else InputError.
+ *
+ * The distance is `Math.hypot(x, y)`, a deliberate divergence from master's `Math.sqrt(x ** 2 + y ** 2)`
+ * (`src/lib/distance.js:3-4`). On a hexagon centre exactly a whole number of feet out, such as (15√3, 15) at 3 ft,
+ * master's sqrt returns 29.999…96 and reads the foot below; hypot reads the true foot. On the real BKN fixture at
+ * radius 10 that is 13 of 374 cells, among them the cells beside the rim (0.572 at 3 ft, where master reads 0.669
+ * at 2 ft). Every other cell reads master's foot.
+ *
+ * @example
+ * ```ts
+ * import { cellsVsDistance, fgPctByDistance } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const made = { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Made" };
+ * const missed = { ...made, shot_result: "Missed" };
+ * cellsVsDistance([made], fgPctByDistance([made, missed]), { shape: "square", side: 10 });
+ * ```
+ */
+declare function cellsVsDistance(player: readonly ShotRow[], byFoot: readonly DistanceBin[], cell?: number | BinnerOptions): CellVsLeague[];
+
+/** One shooting-signature sample (`signaturePoints`): the input of the Plot `shootingSignature` and d3 `appendSignature`. */
+interface SignaturePoint {
+    readonly distance: number;
+    /** Effective makes / attempts near this distance; null (a gap in the ribbon) under `minAttempts`. */
+    readonly fgPct: number | null;
+    readonly leagueFgPct: number | null;
+    readonly share: number;
+    /** The colour value: `shrunkDiff(makes, attempts, league, prior)`, null in a gap. */
+    readonly colourDiff: number | null;
+}
+/** Options for `signaturePoints`; `master` mode is `{ step: 1, smooth: false, minAttempts: 1, prior: 0 }`. */
+interface SignatureOptions {
+    /** Feet between samples; default 0.25 (`:16`). `master` sampled each 1-ft bin. */
+    step?: number;
+    /** Kernel smoothing (sigma 0.9 ft for makes/attempts, 1 for share, 0.6 for league; `:17`, `:76-77`); default true. */
+    smooth?: boolean;
+    /** No ribbon past the last bin with this many attempts, nor where the effective attempts fall below it; default 5 (`:19-21`). */
+    minAttempts?: number;
+    /** Colour prior in attempts (`shrunkDiff` k); default 25. 0 = the raw difference (`master`). */
+    prior?: number;
+}
+/**
+ * The shooting signature's samples: FG% from separately kernel-summed makes and attempts (a stretch with no
+ * shots is a gap, never 0%), the smoothed league FG% and shot share, and the shrunk colour value (`:69-100`).
+ * Input: 1-ft bins from `vsLeague(fgPctByDistance(player), fgPctByDistance(league))`.
+ *
+ * @example
+ * ```ts
+ * import { fgPctByDistance, signaturePoints, vsLeague } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const made = { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Made" };
+ * const missed = { ...made, shot_result: "Missed" };
+ * signaturePoints(vsLeague(fgPctByDistance([made]), fgPctByDistance([made, missed])), { minAttempts: 1 })[0];
+ * ```
+ */
+declare function signaturePoints(bins: readonly DistanceVsLeague[], o?: SignatureOptions): SignaturePoint[];
+
+export { BinnerOptions, type CellBin, type CellSizes, type CellVsLeague, type DiffPalette, type DiffScale, type DiffScaleOptions, type DistanceBin, type DistanceVsLeague, LEAGUE_PRIOR_ATTEMPTS, Lattice, type LeagueCell, type LeagueIndex, type ShotRow, type SideBin, type SignatureOptions, type SignaturePoint, type SizeRule, type Split, binShots, cellsVsDistance, cellsVsLeague, diffScale, fgPctByDistance, leagueIndex, shrunkDiff, signaturePoints, sizeCells, statsBySide, statsByZone, vsLeague };

package/dist/shots.js

@@ -0,0 +1,85 @@
+import { made, split, binShots } from './chunk-QY65DUEF.js';
+export { LEAGUE_PRIOR_ATTEMPTS, binShots, cellsVsLeague, diffScale, leagueIndex, shrunkDiff, signaturePoints, sizeCells, statsByZone } from './chunk-QY65DUEF.js';
+export { binner, cellPath, cellPoints, hexagonPath, hexbin, squarePath, squarebin } from './chunk-C2CDY5OG.js';
+import { InputError } from './chunk-E7G7VSLV.js';
+
+// src/shots/distance.ts
+function binCount(binFt, maxFt) {
+  for (const [name, v] of Object.entries({ binFt, maxFt }))
+    if (!(Number.isFinite(v) && v > 0))
+      throw new InputError(`${name} must be a finite number > 0, got ${String(v)}`);
+  return Math.floor(maxFt / binFt) + 1;
+}
+function fgPctByDistance(shots, binFt = 1, maxFt = 35) {
+  const bins = Array.from({ length: binCount(binFt, maxFt) }, () => ({ attempts: 0, makes: 0 }));
+  let total = 0;
+  for (const s of shots) {
+    if (s.shot_distance > maxFt) continue;
+    const b = bins[Math.floor(s.shot_distance / binFt)];
+    if (b === void 0) continue;
+    b.attempts += 1;
+    if (made(s)) b.makes += 1;
+    total += 1;
+  }
+  return bins.map((b, i) => ({
+    distance: i * binFt,
+    ...split(b.attempts, b.makes),
+    share: total ? b.attempts / total : 0
+  }));
+}
+function vsLeague(player, league) {
+  if (player.length !== league.length || player.some((b, i) => b.distance !== league[i]?.distance)) {
+    throw new InputError("vsLeague: player and league bins differ (use the same binFt and maxFt)");
+  }
+  return player.map((b, i) => {
+    const leagueFgPct = league[i]?.fgPct ?? null;
+    return {
+      ...b,
+      leagueFgPct,
+      diff: b.fgPct !== null && leagueFgPct !== null ? b.fgPct - leagueFgPct : null
+    };
+  });
+}
+function statsBySide(shots, binFt = 1, maxFt = 35, centreHalfWidth = 0) {
+  if (centreHalfWidth !== false && !(Number.isFinite(centreHalfWidth) && centreHalfWidth >= 0))
+    throw new InputError(
+      `statsBySide centreHalfWidth must be a finite number >= 0 or false, got ${String(centreHalfWidth)}`
+    );
+  const half = centreHalfWidth === false ? 0 : centreHalfWidth;
+  const acc = Array.from({ length: binCount(binFt, maxFt) }, () => ({
+    left: [0, 0],
+    centre: [0, 0],
+    right: [0, 0]
+  }));
+  for (const s of shots) {
+    if (s.shot_distance > maxFt) continue;
+    const bin = acc[Math.floor(s.shot_distance / binFt)];
+    if (bin === void 0) continue;
+    const x = s.x_legacy;
+    const side = x < -half ? bin.left : x > half ? bin.right : centreHalfWidth === false ? void 0 : bin.centre;
+    if (side === void 0) continue;
+    side[0] = (side[0] ?? 0) + 1;
+    if (made(s)) side[1] = (side[1] ?? 0) + 1;
+  }
+  return acc.map((b, i) => ({
+    distance: i * binFt,
+    left: split(b.left[0] ?? 0, b.left[1] ?? 0),
+    centre: split(b.centre[0] ?? 0, b.centre[1] ?? 0),
+    right: split(b.right[0] ?? 0, b.right[1] ?? 0)
+  }));
+}
+function cellsVsDistance(player, byFoot, cell = 10) {
+  const bad = byFoot.findIndex((b, i) => b.distance !== i);
+  if (bad >= 0)
+    throw new InputError(
+      `cellsVsDistance needs 1-ft distance bins from 0 (fgPctByDistance(shots, 1)); bin ${bad} is at ${String(byFoot[bad]?.distance)} ft`
+    );
+  return binShots(player, cell).map((h) => {
+    const d = Math.floor(Math.hypot(h.x, h.y) / 10);
+    return { ...h, leagueFgPct: byFoot[d]?.fgPct ?? byFoot[d - 1]?.fgPct ?? null };
+  });
+}
+
+export { cellsVsDistance, fgPctByDistance, statsBySide, vsLeague };
+//# sourceMappingURL=shots.js.map
+//# sourceMappingURL=shots.js.map

package/dist/shots.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shots/distance.ts"],"names":[],"mappings":"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","file":"shots.js","sourcesContent":["// Distance and side bins, ported from blazing-the-nets `main` lib/data/aggregate.ts (@31427b8), plus `master`'s\n// distance baseline for cells (src/components/Hexagon/index.js @35dfda6). Pure; the parity gate is fixtures/shots/oracle.json.\nimport type { BinnerOptions } from \"../bins/index.js\";\nimport { InputError } from \"../errors.js\";\nimport { type CellVsLeague, type ShotRow, type Split, binShots, made, split } from \"./aggregate.js\";\n\n/** One `fgPctByDistance` bin: the counts of the shots `distance` to `distance + binFt` ft out, and their share. */\nexport interface DistanceBin extends Split {\n  /** First foot of the bin; `shot_distance` is rounded, so a 1-ft bin is centred on it. */\n  readonly distance: number;\n  /** Share of the attempts within `maxFt`. */\n  readonly share: number;\n}\n\n/** The number of `binFt` bins from 0 to `maxFt`; both must be finite numbers above 0 (else InputError, naming it). */\nfunction binCount(binFt: number, maxFt: number): number {\n  for (const [name, v] of Object.entries({ binFt, maxFt }))\n    if (!(Number.isFinite(v) && v > 0))\n      throw new InputError(`${name} must be a finite number > 0, got ${String(v)}`);\n  return Math.floor(maxFt / binFt) + 1;\n}\n\n/**\n * FG% by `shot_distance` in `binFt` bins from 0 to `maxFt`; longer attempts are left out (aggregate.ts:177-192).\n * The total within `maxFt` is the sum of `attempts`. `binFt` and `maxFt` must be finite numbers above 0 (else\n * InputError).\n *\n * @example\n * ```ts\n * import { fgPctByDistance } from \"@sportsdataverse/sdvplot/shots\";\n *\n * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26\n * const shots = [\n *   { x_legacy: -1, y_legacy: 7, shot_distance: 1, shot_value: 2, shot_result: \"Made\" },\n *   { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: \"Missed\" },\n *   { x_legacy: -44, y_legacy: 252, shot_distance: 26, shot_value: 3, shot_result: \"Made\" },\n * ];\n * fgPctByDistance(shots, 3)[0];\n * ```\n */\nexport function fgPctByDistance(shots: readonly ShotRow[], binFt = 1, maxFt = 35): DistanceBin[] {\n  const bins = Array.from({ length: binCount(binFt, maxFt) }, () => ({ attempts: 0, makes: 0 }));\n  let total = 0;\n  for (const s of shots) {\n    if (s.shot_distance > maxFt) continue;\n    const b = bins[Math.floor(s.shot_distance / binFt)];\n    if (b === undefined) continue; // a negative distance\n    b.attempts += 1;\n    if (made(s)) b.makes += 1;\n    total += 1;\n  }\n  return bins.map((b, i) => ({\n    distance: i * binFt,\n    ...split(b.attempts, b.makes),\n    share: total ? b.attempts / total : 0,\n  }));\n}\n\n/** A player distance bin with the league's FG% at the same distance and the difference (`vsLeague`). */\nexport interface DistanceVsLeague extends DistanceBin {\n  readonly leagueFgPct: number | null;\n  /** Player minus league FG% (a fraction), null when either side has no attempts. */\n  readonly diff: number | null;\n}\n\n/**\n * Pair player and league distance bins (same `binFt` and `maxFt`, else InputError) and take the difference\n * (aggregate.ts:200-209).\n *\n * @example\n * ```ts\n * import { fgPctByDistance, vsLeague } from \"@sportsdataverse/sdvplot/shots\";\n *\n * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26\n * const made = { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: \"Made\" };\n * const missed = { ...made, shot_result: \"Missed\" };\n * vsLeague(fgPctByDistance([made]), fgPctByDistance([made, missed]))[0];\n * ```\n */\nexport function vsLeague(player: readonly DistanceBin[], league: readonly DistanceBin[]): DistanceVsLeague[] {\n  if (player.length !== league.length || player.some((b, i) => b.distance !== league[i]?.distance)) {\n    throw new InputError(\"vsLeague: player and league bins differ (use the same binFt and maxFt)\");\n  }\n  return player.map((b, i) => {\n    const leagueFgPct = league[i]?.fgPct ?? null;\n    return {\n      ...b,\n      leagueFgPct,\n      diff: b.fgPct !== null && leagueFgPct !== null ? b.fgPct - leagueFgPct : null,\n    };\n  });\n}\n\n/** One `statsBySide` bin: left, centre and right of the hoop for the shots in the bin that starts `distance` ft out. */\nexport interface SideBin {\n  readonly distance: number;\n  readonly left: Split;\n  readonly centre: Split;\n  readonly right: Split;\n}\n\n/**\n * Left / centre / right of the hoop by distance (aggregate.ts:218-240): left is `x < -centreHalfWidth`, right is\n * `x > centreHalfWidth`. The default 0 puts `x == 0` in centre (`main`); `false` drops it, as `master`'s\n * `binLeftRight` did (`src/utils/visuals/bin.ts:36-42`). `binFt` and `maxFt` as for `fgPctByDistance`; a\n * `centreHalfWidth` that is negative or not finite throws InputError.\n *\n * @example\n * ```ts\n * import { statsBySide } from \"@sportsdataverse/sdvplot/shots\";\n *\n * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26\n * const shots = [\n *   { x_legacy: -1, y_legacy: 7, shot_distance: 1, shot_value: 2, shot_result: \"Made\" },\n *   { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: \"Missed\" },\n *   { x_legacy: -44, y_legacy: 252, shot_distance: 26, shot_value: 3, shot_result: \"Made\" },\n * ];\n * statsBySide(shots, 3, 35, 7.5)[0];\n * ```\n */\nexport function statsBySide(\n  shots: readonly ShotRow[],\n  binFt = 1,\n  maxFt = 35,\n  centreHalfWidth: number | false = 0,\n): SideBin[] {\n  if (centreHalfWidth !== false && !(Number.isFinite(centreHalfWidth) && centreHalfWidth >= 0))\n    throw new InputError(\n      `statsBySide centreHalfWidth must be a finite number >= 0 or false, got ${String(centreHalfWidth)}`,\n    );\n  const half = centreHalfWidth === false ? 0 : centreHalfWidth;\n  const acc = Array.from({ length: binCount(binFt, maxFt) }, () => ({\n    left: [0, 0],\n    centre: [0, 0],\n    right: [0, 0],\n  }));\n  for (const s of shots) {\n    if (s.shot_distance > maxFt) continue;\n    const bin = acc[Math.floor(s.shot_distance / binFt)];\n    if (bin === undefined) continue;\n    const x = s.x_legacy;\n    const side =\n      x < -half ? bin.left : x > half ? bin.right : centreHalfWidth === false ? undefined : bin.centre;\n    if (side === undefined) continue;\n    side[0] = (side[0] ?? 0) + 1;\n    if (made(s)) side[1] = (side[1] ?? 0) + 1;\n  }\n  return acc.map((b, i) => ({\n    distance: i * binFt,\n    left: split(b.left[0] ?? 0, b.left[1] ?? 0),\n    centre: split(b.centre[0] ?? 0, b.centre[1] ?? 0),\n    right: split(b.right[0] ?? 0, b.right[1] ?? 0),\n  }));\n}\n\n/**\n * Player cells against the league FG% at the cell centre's distance, `floor(|centre| / 10)` ft, falling back one\n * foot when that bin is empty (blazing-the-nets `master` `src/components/Hexagon/index.js:44-49`). `cell` is a\n * hexagon radius (default 10, master's) or any `binner` lattice, e.g. `{ shape: \"square\", side: 10 }`. `byFoot` is\n * read as feet, so it must be 1-ft bins from 0 (`fgPctByDistance(league)`), else InputError.\n *\n * The distance is `Math.hypot(x, y)`, a deliberate divergence from master's `Math.sqrt(x ** 2 + y ** 2)`\n * (`src/lib/distance.js:3-4`). On a hexagon centre exactly a whole number of feet out, such as (15√3, 15) at 3 ft,\n * master's sqrt returns 29.999…96 and reads the foot below; hypot reads the true foot. On the real BKN fixture at\n * radius 10 that is 13 of 374 cells, among them the cells beside the rim (0.572 at 3 ft, where master reads 0.669\n * at 2 ft). Every other cell reads master's foot.\n *\n * @example\n * ```ts\n * import { cellsVsDistance, fgPctByDistance } from \"@sportsdataverse/sdvplot/shots\";\n *\n * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26\n * const made = { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: \"Made\" };\n * const missed = { ...made, shot_result: \"Missed\" };\n * cellsVsDistance([made], fgPctByDistance([made, missed]), { shape: \"square\", side: 10 });\n * ```\n */\nexport function cellsVsDistance(\n  player: readonly ShotRow[],\n  byFoot: readonly DistanceBin[],\n  cell: number | BinnerOptions = 10,\n): CellVsLeague[] {\n  const bad = byFoot.findIndex((b, i) => b.distance !== i);\n  if (bad >= 0)\n    throw new InputError(\n      `cellsVsDistance needs 1-ft distance bins from 0 (fgPctByDistance(shots, 1)); bin ${bad} is at ${String(byFoot[bad]?.distance)} ft`,\n    );\n  return binShots(player, cell).map((h) => {\n    // hypot, not master's sqrt(x ** 2 + y ** 2) (distance.js:3-4), which reads a whole-foot centre one foot short\n    const d = Math.floor(Math.hypot(h.x, h.y) / 10);\n    return { ...h, leagueFgPct: byFoot[d]?.fgPct ?? byFoot[d - 1]?.fgPct ?? null };\n  });\n}\n"]}