@johnmorrisdotca/kyogijo-stadiums 0.0.0-stage → 0.4.0

package/dist/charts.js

@@ -0,0 +1,508 @@
+// Ready-made charts on the data layers: a shot chart for the NBA, a shot map for the NHL, a pass chart for the NFL (here), a spray chart for
+// baseball (charts.baseball.ts) and a shot map for soccer with a goal-mouth view (charts.soccer.ts). Each is a function of plain data that
+// returns the layers and the drawing options to put them on, so that one call gives a good chart and the layers can still be changed.
+// Written for this package. The charts match the kinds that mplsoccer (MIT, shot maps and pass maps), hockey_rink (shot maps) and sporty (MIT)
+// draw; the code of GeomMLBStadiums (GPL) and of sportypy, sportyR and hockey_rink (GPL) was not read.
+import { drawKyogijo } from "./draw.js";
+import { fromSurface, frameByName, toSurface } from "./frames.js";
+import { zoneCounts } from "./heat.js";
+import { isPortrait } from "./common.js";
+import { envFor, isNum, place, unitOfLayer } from "./layers.env.js";
+import { layerTable } from "./layers.js";
+import { outlineOf } from "./outline.js";
+import { KYOGIJO_STRINGS, fill } from "./strings.js";
+import { textWidth } from "./text.js";
+// ----- what the charts share
+/** The language of a chart's words. */
+export const languageOf = (o) => (o.language === "ja" ? "ja" : "en");
+/** The words of a chart. */
+export const wordsOf = (language) => KYOGIJO_STRINGS[language];
+export { isNum };
+/** An object without the properties that are `undefined`, so that a layer is plain data and the same input gives the same JSON. */
+export function clean(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+/** The ground round each surface that a chart draws, in feet: room above the surface for the key. */
+export const MARGIN = Object.freeze({ nba: 9, nhl: 10, nfl: 14, cfl: 14, ifaf: 14, mlb: 40, soccer: 16 });
+/** A frame by name, or the frame given. */
+export const frameOf = (from, fallback) => (typeof from === "object" && from !== null ? from : frameByName(from ?? fallback));
+/** What a layer's `from` is: the frame given, or the name of the one asked for (a name stays a name in the layer's JSON). */
+export const fromOf = (given, frame) => (typeof given === "object" && given !== null ? given : frame.name);
+/** The drawing's options for a chart: the sport, the language, the title and the ground round the surface, then whatever the caller laid over them. */
+export function drawingOptions(sport, options, title, extra = {}) {
+    return {
+        sport,
+        language: languageOf(options),
+        ...(options.id === undefined ? {} : { id: options.id }),
+        title,
+        margin: MARGIN[sport],
+        ...extra,
+        ...(options.surface ?? {}),
+    };
+}
+/**
+ * The key of a chart: one row of marks and their names in the margin above the surface (drawn over the ground round it), as two layers:
+ * the marks, in the look the chart's own marks have, and their words. `extra` is more words with no mark (the size of a mark, a total).
+ */
+export function keyLayers(o, entries, looks, all, extra = [], at = {}) {
+    const words = all.charts;
+    const sep = all.layers.listSep;
+    const { box } = outlineOf(o);
+    const margin = o.margin ?? 8;
+    const base = Math.max(box.w, box.h) * 0.013;
+    // The row is centred on the part of the surface that is shown: all of it, or the half of a pitch.
+    const view = { x: at.x ?? box.x, w: at.w ?? box.w };
+    const items = [...entries.map((e) => ({ text: e.label, mark: true })), ...extra.map((text) => ({ text, mark: false }))];
+    const widthAt = (size) => items.reduce((sum, item) => sum + (item.mark ? size * 0.9 + size * 0.45 : 0) + textWidth(item.text) * size + size * 1.4, 0) - size * 1.4;
+    let size = Math.min(base * 1.25, margin * 0.5);
+    const room = view.w * 0.96;
+    if (widthAt(size) > room)
+        size *= room / widthAt(size);
+    const y = at.y ?? box.y - margin * 0.5;
+    let x = view.x + (view.w - widthAt(size)) / 2;
+    const marks = [];
+    const text = [];
+    for (const [i, item] of items.entries()) {
+        if (item.mark) {
+            marks.push(clean({ x: x + size * 0.45, y, outcome: entries[i].outcome }));
+            x += size * 0.9 + size * 0.45;
+        }
+        text.push({ x, y, text: item.text });
+        x += textWidth(item.text) * size + size * 1.4;
+    }
+    const hollowWords = Object.fromEntries(Object.entries(looks).map(([name, look]) => [name, clean({ hollow: look.hollow, shape: look.shape, scale: look.scale })]));
+    const labels = entries.map((e) => e.label).join(sep);
+    const keyMarks = {
+        kind: "points",
+        id: "key-marks",
+        name: words.key,
+        title: words.key,
+        description: labels,
+        units: "ft",
+        clip: "none",
+        data: marks,
+        style: { size: size * 0.9, outcomes: hollowWords },
+    };
+    const keyText = {
+        kind: "text",
+        id: "key-text",
+        name: words.key,
+        title: words.key,
+        description: extra.join(sep),
+        units: "ft",
+        clip: "none",
+        data: text,
+        style: { size, anchor: "start" },
+    };
+    return [keyMarks, keyText];
+}
+/** The layers of the key are named `key-marks` and `key-text`. */
+export const isKey = (layer) => layer.id === "key-marks" || layer.id === "key-text";
+/** The key of a chart as data, from its entries and looks. */
+export function keyItems(entries, looks) {
+    return entries.map((e) => ({ outcome: e.outcome ?? "", label: e.label, shape: looks[e.outcome ?? ""]?.shape ?? "circle", hollow: looks[e.outcome ?? ""]?.hollow === true }));
+}
+/** Put a chart together: the options, the layers and the ways to draw them. */
+export function assemble(options, layers, parts) {
+    const all = { ...options, layers };
+    const language = options.language === "ja" ? "ja" : "en";
+    const chart = {
+        options: all,
+        layers,
+        title: parts.title,
+        summary: parts.summary,
+        totals: parts.totals,
+        key: [],
+        draw(extra = {}) {
+            const merged = { ...all, ...extra };
+            // The key runs along one edge of the surface as the eye sees it wide: a tall drawing leaves it out.
+            const shown = extra.layers ?? (isPortrait(merged) ? layers.filter((layer) => !isKey(layer)) : layers);
+            return drawKyogijo({ ...merged, layers: shown });
+        },
+        table(tableOptions = {}) {
+            return layerTable(layers.filter((layer) => !isKey(layer) && (parts.tableLayers === undefined || parts.tableLayers.includes(layer.id ?? ""))), { ...tableOptions, language, surface: all });
+        },
+    };
+    return chart;
+}
+/** `shot`s counted by outcome, as the words of the key and in the key's order, for a layer's description: "Made 3, Missed 5." */
+export function describeCounts(entries, counts, words) {
+    const list = entries
+        .filter((e) => (counts.get(e.outcome ?? "") ?? 0) > 0)
+        .map((e) => fill(words.layers.item, { name: e.label, n: counts.get(e.outcome ?? "") ?? 0 }))
+        .join(words.layers.listSep);
+    return list === "" ? "" : fill(words.layers.outcomes, { list });
+}
+/** Round to a number of decimal places. */
+export const round = (value, places = 1) => Math.round(value * 10 ** places) / 10 ** places;
+/** A percent, one decimal, or null with nothing to divide. */
+export const percentOf = (part, whole) => (whole === 0 ? null : round((100 * part) / whole));
+/** The marks counted into the zones of a layer, as zone totals. */
+export function zoneTotals(o, layer) {
+    return zoneCounts(layer, envFor(o, false)).map((z) => ({ id: z.id, name: z.name, taken: z.n, made: z.hits, percent: percentOf(z.hits, z.n) }));
+}
+/** Count marks by outcome, skipping the ones with no place. */
+export function countOutcomes(rows) {
+    const counts = new Map();
+    let placed = 0;
+    let skipped = 0;
+    for (const row of rows) {
+        if (isNum(row.x) && isNum(row.y)) {
+            placed += 1;
+            const key = row.outcome ?? "";
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        else
+            skipped += 1;
+    }
+    return { counts, placed, skipped };
+}
+/** True when a mark carries a place. */
+export const hasPlace = (d) => isNum(d.x) && isNum(d.y);
+/**
+ * Turn the shots at the left end of a surface a half turn so that every one is at the right end, in the numbers of the frame they are in.
+ * Rounded to hundredths of the frame's unit, so that a shot at the right end comes back as it was given.
+ */
+export function foldToRight(rows, frame, o) {
+    const { box } = outlineOf(o);
+    const size = o.sport === "soccer" ? { length: box.w, width: box.h, unit: "ft" } : undefined;
+    return rows.map((row) => {
+        if (!isNum(row.x) || !isNum(row.y))
+            return row;
+        const [sx, sy] = toSurface([[row.x, row.y]], { from: frame, size })[0];
+        if (sx >= box.x + box.w / 2)
+            return row;
+        const [bx, by] = fromSurface([[box.x + box.w - (sx - box.x), box.y + box.h - (sy - box.y)]], { to: frame, size })[0];
+        return { ...row, x: round(bx, 2), y: round(by, 2) };
+    });
+}
+/** The marks' places on the surface, in feet, in the same frame and ends as a layer will draw them. */
+export function placed(o, layer, rows) {
+    const env = envFor(o, false);
+    const unit = unitOfLayer(layer, env);
+    const at = place(layer, env, rows.filter(hasPlace).map((r) => [r.x, r.y]), unit);
+    let k = 0;
+    return rows.map((r) => (hasPlace(r) ? at[k++] : undefined));
+}
+// ----- basketball
+const NBA_LOOKS = { made: {}, missed: { shape: "x", hollow: true } };
+/**
+ * A shot chart for the NBA from stats.nba.com's shot data: each shot as a mark (filled when it went in, an open x when it missed), and the
+ * six shot zones coloured by their field-goal percentage, with the percentage and made over taken written on each, a legend and a table. Give
+ * `league` (the league's percentage) and the zones are coloured by how far they are above or below it, on a diverging ramp.
+ * @example
+ * ```ts
+ * import { nbaShotChart } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const chart = nbaShotChart(
+ *   [
+ *     { x: 0, y: 12, made: true },
+ *     { x: -231, y: 18, made: false },
+ *     { x: 120, y: 140, made: true },
+ *     { x: -30, y: 70, made: true },
+ *   ],
+ *   { league: 46, minShots: 1 },
+ * );
+ * console.log(chart.totals.shots, chart.totals.made, chart.layers.map((layer) => layer.kind).join(" "));
+ * console.log(chart.draw().startsWith("<svg"), chart.table().includes("Restricted area"));
+ * // 4 3 zones points points text
+ * // true true
+ * ```
+ */
+export function nbaShotChart(shots, options = {}) {
+    if (!Array.isArray(shots))
+        throw new TypeError("shots is a list of shots");
+    const language = languageOf(options);
+    const all = wordsOf(language);
+    const w = all.charts;
+    const frame = frameOf(options.from, "nba-stats");
+    const end = options.end === "left" ? "left" : "right";
+    // A shot chart puts every shot at the basket it was taken at; a frame fixed to the court says where each one is.
+    const shooter = frame.ends === "shooter";
+    const data = shots.map((s) => clean({ x: s.x, y: s.y, outcome: s.made === undefined ? s.outcome : s.made ? "made" : "missed", value: s.value, team: s.team, title: s.title }));
+    const { counts, placed: count, skipped } = countOutcomes(data);
+    const entries = [{ label: w.made, outcome: "made" }, { label: w.missed, outcome: "missed" }];
+    const o = drawingOptions("nba", options, w.titleNba);
+    const where = clean({ from: fromOf(options.from, frame), attacking: shooter && end === "left" ? "left" : undefined });
+    const layers = [];
+    const league = isNum(options.league) ? options.league : undefined;
+    const zonesLayer = options.zones === false
+        ? undefined
+        : clean({
+            kind: "zones",
+            id: "zones",
+            name: w.shots,
+            zones: "nba-shot",
+            ...where,
+            end: shooter || options.end !== undefined ? end : undefined,
+            data,
+            statistic: "rate",
+            statisticName: w.fgRate,
+            minCount: isNum(options.minShots) ? options.minShots : 3,
+            labels: options.labels === false ? undefined : { show: ["value", "ratio"] },
+            ramp: options.ramp,
+            center: league,
+            legend: options.legend === false ? undefined : { title: w.fgRate, position: end === "right" ? "bottom-left" : "bottom-right" },
+        });
+    if (zonesLayer !== undefined)
+        layers.push(zonesLayer);
+    if (options.marks !== false) {
+        layers.push(clean({
+            kind: "points",
+            id: "shots",
+            name: w.shots,
+            description: describeCounts(entries, counts, all),
+            ...where,
+            data,
+            style: { outcomes: NBA_LOOKS, scale: zonesLayer === undefined ? 0.85 : 0.6, opacity: 0.85 },
+        }));
+    }
+    if (options.key !== false)
+        layers.push(...keyLayers(o, entries, NBA_LOOKS, all));
+    const made = counts.get("made") ?? 0;
+    const zones = zonesLayer === undefined ? [] : zoneTotals(o, zonesLayer);
+    const totals = { shots: count, made, percent: percentOf(made, count), skipped, zones };
+    const summary = [fill(w.sumNba, { shots: count, made, pct: totals.percent ?? 0 }), league !== undefined && zonesLayer !== undefined ? fill(w.leagueNote, { league }) : ""].filter((s) => s !== "").join(all.said.gap);
+    const chart = assemble(o, layers, { title: w.titleNba, summary, totals });
+    chart.key = keyItems(entries, NBA_LOOKS);
+    return chart;
+}
+// ----- hockey
+const NHL_LOOKS = {
+    goal: { shape: "star", scale: 1.4 },
+    saved: { hollow: true },
+    missed: { shape: "x", hollow: true },
+    blocked: { shape: "triangle", hollow: true },
+    shot: { hollow: true },
+};
+/** A shot's outcome word: its own, `goal` for a goal, else `shot`. */
+const hockeyOutcome = (s) => (s.goal === true ? "goal" : typeof s.outcome === "string" && s.outcome !== "" ? s.outcome.toLowerCase() : "shot");
+/** The key entries a set of outcomes calls for, in the order shots are usually read: goals first. */
+function shotEntries(counts, w, order) {
+    const label = { goal: w.goal, saved: w.saved, missed: w.missedNet, blocked: w.blocked, shot: w.shot, post: w.post };
+    const present = [...counts.keys()].filter((k) => k !== "");
+    const known = order.filter((k) => present.includes(k));
+    const other = present.filter((k) => !order.includes(k));
+    return [...known, ...other].map((k) => ({ label: label[k] ?? k, outcome: k }));
+}
+/** Per-team totals of shots, goals and expected goals. */
+export function teamTotals(rows) {
+    var _a;
+    const out = {};
+    for (const r of rows) {
+        if (!hasPlace(r) || typeof r.team !== "string" || r.team === "")
+            continue;
+        const t = (out[_a = r.team] ?? (out[_a] = { shots: 0, goals: 0, xg: null }));
+        t.shots += 1;
+        if (r.outcome === "goal")
+            t.goals += 1;
+        if (isNum(r.value))
+            t.xg = round((t.xg ?? 0) + r.value, 2);
+    }
+    return out;
+}
+/**
+ * A shot map for the NHL from play-by-play shots: each shot a mark (a goal a star, a save an open circle, a miss an open x, a block an open
+ * triangle) sized by its chance of scoring, with an optional count of the shots into the slot zones or hexagons, a legend, a key and a table.
+ * With `fold` the shots at the left end are turned a half turn, so that every shot is at the right end.
+ * @example
+ * ```ts
+ * import { nhlShotMap } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const chart = nhlShotMap(
+ *   [
+ *     { x: 75, y: 4, outcome: "goal", xg: 0.31 },
+ *     { x: -60, y: -12, outcome: "saved", xg: 0.07 },
+ *     { x: 40, y: 20, outcome: "missed", xg: 0.03 },
+ *   ],
+ *   { fold: true, zones: true },
+ * );
+ * console.log(chart.totals.shots, chart.totals.goals, chart.totals.xg);
+ * console.log(chart.layers.map((layer) => layer.id).join(" "));
+ * // 3 1 0.41
+ * // zones shots key-marks key-text
+ * ```
+ */
+export function nhlShotMap(shots, options = {}) {
+    if (!Array.isArray(shots))
+        throw new TypeError("shots is a list of shots");
+    const language = languageOf(options);
+    const all = wordsOf(language);
+    const w = all.charts;
+    const frame = frameOf(options.from, "nhl-api");
+    const o = drawingOptions("nhl", options, w.titleNhl);
+    const folded = options.fold === true;
+    const given = shots.map((s) => clean({ x: s.x, y: s.y, outcome: hockeyOutcome(s), value: s.xg, team: s.team, title: s.title }));
+    const data = folded ? foldToRight(given, frame, o) : given;
+    const { counts, placed: count, skipped } = countOutcomes(data);
+    const hasXg = data.some((d) => isNum(d.value));
+    const sized = options.sizeBy === "none" ? false : options.sizeBy === "xg" || hasXg;
+    const entries = shotEntries(counts, w, ["goal", "saved", "missed", "blocked", "shot"]);
+    const attacking = folded ? undefined : options.attacking === "left" ? "left" : undefined;
+    const where = clean({ from: fromOf(options.from, frame), attacking });
+    const single = folded || options.attacking !== undefined;
+    const statistic = options.statistic ?? "shots";
+    const stat = statistic === "xg" ? { statistic: "sum", statisticName: w.xgStat } : statistic === "goals" ? { statistic: "rate", statisticName: w.goalRate } : { statistic: "count" };
+    const legend = options.legend === false ? undefined : { position: single ? "bottom-left" : "bottom", ...(statistic === "shots" ? {} : { title: stat.statisticName }) };
+    const layers = [];
+    let zonesLayer;
+    if (options.zones !== undefined && options.zones !== false) {
+        zonesLayer = clean({
+            kind: "zones",
+            id: "zones",
+            name: w.shots,
+            zones: (options.zones === true ? "nhl-slot" : options.zones),
+            ...where,
+            end: single ? "right" : undefined,
+            data,
+            ...stat,
+            labels: options.labels === false ? undefined : true,
+            ramp: options.ramp,
+            legend,
+        });
+        layers.push(zonesLayer);
+    }
+    else if (options.hexbin !== undefined && options.hexbin !== false) {
+        layers.push(clean({
+            kind: "hexbin",
+            id: "hexagons",
+            name: w.shots,
+            ...where,
+            data,
+            size: typeof options.hexbin === "object" ? options.hexbin.size : undefined,
+            ...stat,
+            labels: options.labels === true ? true : undefined,
+            ramp: options.ramp,
+            legend,
+        }));
+    }
+    const xgMax = isNum(options.xgMax) && options.xgMax > 0 ? options.xgMax : 0.5;
+    const style = { outcomes: NHL_LOOKS, ...(sized ? { size: { domain: [0, xgMax], range: [1.5, 5.2] } } : {}) };
+    const xg = data.some((d) => isNum(d.value)) ? round(data.reduce((sum, d) => sum + (hasPlace(d) && isNum(d.value) ? d.value : 0), 0), 2) : null;
+    if (options.marks !== false) {
+        layers.push(clean({ kind: "points", id: "shots", name: w.shots, description: [describeCounts(entries, counts, all), sized ? w.sizeNote : ""].filter(Boolean).join(all.said.gap), ...where, data, style }));
+    }
+    const extras = [...(sized ? [w.sizeXg] : []), ...(xg === null ? [] : [fill(w.xgTotal, { n: xg })])];
+    if (options.key !== false)
+        layers.push(...keyLayers(o, entries, NHL_LOOKS, all, extras));
+    const goals = counts.get("goal") ?? 0;
+    const totals = { shots: count, goals, xg, skipped, zones: zonesLayer === undefined ? [] : zoneTotals(o, zonesLayer), teams: teamTotals(data) };
+    const summary = xg === null ? fill(w.sumShots, { shots: count, goals }) : fill(w.sumShotsXg, { shots: count, goals, xg });
+    const chart = assemble(o, layers, { title: w.titleNhl, summary, totals });
+    chart.key = keyItems(entries, NHL_LOOKS);
+    return chart;
+}
+// ----- football
+const NFL_LOOKS = {
+    complete: {},
+    incomplete: { hollow: true },
+    touchdown: { shape: "star", scale: 1.5 },
+    interception: { shape: "x", scale: 1.25 },
+};
+/**
+ * A pass chart for the NFL from tracking data: where each pass came down as a mark (a completion filled, an incompletion open, a touchdown a
+ * star, an interception an x), the line of scrimmage, and the pass grid (short and deep by left, middle and right) coloured by completion
+ * percentage with the air yards of each pass in its table. The offence goes to the right whichever way `direction` says it went in the data.
+ * @example
+ * ```ts
+ * import { nflPassChart } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const chart = nflPassChart(
+ *   [
+ *     { x: 72, y: 26, outcome: "complete" },
+ *     { x: 88, y: 14, outcome: "incomplete" },
+ *     { x: 104, y: 30, outcome: "touchdown" },
+ *   ],
+ *   { los: 65, minPasses: 1 },
+ * );
+ * console.log(chart.totals.passes, chart.totals.complete, chart.totals.airYards);
+ * // 3 2 23
+ * ```
+ */
+export function nflPassChart(passes, options = {}) {
+    if (!Array.isArray(passes))
+        throw new TypeError("passes is a list of passes");
+    const language = languageOf(options);
+    const all = wordsOf(language);
+    const w = all.charts;
+    const frame = frameOf(options.from, "nfl-tracking");
+    const o = drawingOptions("nfl", options, w.titleNfl);
+    const left = options.direction === "left";
+    const attacking = left ? "left" : undefined;
+    const where = clean({ from: fromOf(options.from, frame), attacking });
+    const { box } = outlineOf(o);
+    const los = isNum(options.los) ? options.los : undefined;
+    // The line of scrimmage on the surface, in feet from the left end line as the offence goes right: the frame's own number, placed.
+    const losFeet = los === undefined ? box.w / 2 : placed(o, where, [{ x: los, y: 0 }])[0][0];
+    const inYards = (feet) => feet / 3;
+    const rows = passes.map((p) => {
+        const outcome = typeof p.outcome === "string" && p.outcome !== "" ? p.outcome.toLowerCase() : undefined;
+        return { p, outcome };
+    });
+    // Air yards: given, else the yards past the line of scrimmage in the way the offence goes.
+    const at = placed(o, where, rows.map(({ p }) => ({ x: p.x, y: p.y })));
+    const data = rows.map(({ p, outcome }, i) => {
+        const place_ = at[i];
+        const air = isNum(p.airYards) ? p.airYards : place_ === undefined ? undefined : round(inYards(place_[0] - losFeet), 1);
+        return clean({ x: p.x, y: p.y, outcome, value: air, team: p.team, title: p.title });
+    });
+    const { counts, placed: count, skipped } = countOutcomes(data);
+    const entries = [["complete", w.complete], ["incomplete", w.incomplete], ["touchdown", w.touchdown], ["interception", w.interception]].filter(([k]) => counts.has(k) || counts.size === 0 || ["complete", "incomplete"].includes(k)).map(([outcome, label]) => ({ label, outcome }));
+    const layers = [];
+    const success = ["complete", "touchdown"];
+    let zonesLayer;
+    if (options.zones !== false) {
+        zonesLayer = clean({
+            kind: "zones",
+            id: "zones",
+            name: w.passes,
+            zones: "football-pass",
+            ...where,
+            los,
+            data,
+            statistic: "rate",
+            statisticName: w.completionRate,
+            success,
+            minCount: isNum(options.minPasses) ? options.minPasses : 3,
+            labels: options.labels === false ? undefined : { show: ["value", "ratio"] },
+            ramp: options.ramp,
+            legend: options.legend === false ? undefined : { title: w.completionRate, position: "bottom-left" },
+        });
+        layers.push(zonesLayer);
+    }
+    if (options.line !== false) {
+        const width = box.h / 3;
+        const line = clean({
+            kind: "lines",
+            id: "los",
+            name: w.lineOfScrimmage,
+            units: "ft",
+            data: [{ x: losFeet, y: 0, x2: losFeet, y2: width * 3 }],
+            style: { width: 0.9, dash: "dashed", color: "var(--ky-layer-ink)" },
+        });
+        layers.push(line);
+    }
+    if (options.arrows === true) {
+        const arrows = rows.filter(({ p }) => isNum(p.fromX) && isNum(p.fromY) && isNum(p.x) && isNum(p.y)).map(({ p, outcome }) => clean({ x: p.fromX, y: p.fromY, x2: p.x, y2: p.y, outcome, team: p.team, title: p.title }));
+        layers.push(clean({ kind: "arrows", id: "arrows", name: w.passes, ...where, data: arrows, style: { width: 0.7, opacity: 0.7, curve: 0.08, outcomes: { touchdown: {}, interception: {}, complete: {}, incomplete: { hollow: true } } } }));
+    }
+    const values = data.map((d) => d.value).filter(isNum);
+    if (options.marks !== false) {
+        const description = [describeCounts(entries, counts, all), values.length === 0 ? "" : fill(w.airYards, { min: Math.min(...values), max: Math.max(...values) })].filter(Boolean).join(all.said.gap);
+        layers.push(clean({ kind: "points", id: "passes", name: w.passes, description, ...where, data, style: { outcomes: NFL_LOOKS } }));
+    }
+    if (options.key !== false)
+        layers.push(...keyLayers(o, entries, NFL_LOOKS, all));
+    const complete = (counts.get("complete") ?? 0) + (counts.get("touchdown") ?? 0);
+    const totals = {
+        passes: count,
+        complete,
+        touchdowns: counts.get("touchdown") ?? 0,
+        interceptions: counts.get("interception") ?? 0,
+        percent: percentOf(complete, count),
+        airYards: values.length === 0 ? null : round(values.reduce((a, b) => a + b, 0) / values.length, 1),
+        skipped,
+        zones: zonesLayer === undefined ? [] : zoneTotals(o, zonesLayer),
+    };
+    const summary = fill(w.sumNfl, { passes: count, complete, pct: totals.percent ?? 0, td: totals.touchdowns, int: totals.interceptions });
+    const chart = assemble(o, layers, { title: w.titleNfl, summary, totals });
+    chart.key = keyItems(entries, NFL_LOOKS);
+    return chart;
+}

package/dist/charts.network.d.ts

@@ -0,0 +1,66 @@
+import type { Chart, ChartOptions, KeyItem } from "./charts.types.ts";
+import type { Frame } from "./frames.ts";
+import type { SoccerProviderId } from "./surfaces/soccer-providers.ts";
+import type { PassDatum } from "./team.types.ts";
+import type { SurfaceOptions } from "./types.ts";
+/** A pass of a pass network: who made it and who received it, from where to where. */
+export type PassNetworkPass = PassDatum;
+/** What `passNetwork` takes. */
+export interface PassNetworkOptions extends ChartOptions {
+    /** The provider the passes are in (`opta`, `statsbomb`, `wyscout`, ...): the pitch is drawn in its numbers. Or a `Frame` of your own. `international` (metres) by default. */
+    provider?: SoccerProviderId | Frame;
+    /** The end the passes attack, in the provider's numbers: `right` (the default) or `left`. */
+    attacking?: "left" | "right";
+    /** Leave out links of fewer passes than this. 3 by default, so that a network of a match is readable; 1 draws every link. */
+    minPasses?: number;
+    /** Draw a link for each direction, with a head. */
+    directed?: boolean;
+    /** What is written in a node: the shirt `number` (the default), the `name`, the `id` or `none`. */
+    labels?: "number" | "name" | "id" | "none";
+    /** The pitch: a preset or a size, as `pitch` of a drawing. */
+    pitch?: SurfaceOptions["pitch"];
+    /** The ground, as `ground` of a drawing. */
+    ground?: string;
+}
+/** The numbers behind a pass network. */
+export interface PassNetworkTotals {
+    /** Passes counted, and rows left out for want of a passer or a receiver. */
+    passes: number;
+    skipped: number;
+    /** Players with a place, and links drawn (those of at least `minPasses` passes). */
+    players: number;
+    links: number;
+    /** The player with most touches, or null with none. */
+    busiest: {
+        id: string | number;
+        name: string;
+        touches: number;
+    } | null;
+    /** The link with most passes, or null with none. */
+    strongest: {
+        from: string;
+        to: string;
+        passes: number;
+    } | null;
+}
+/**
+ * A pass network for soccer: a node for each player at the average place of the passes he made and received, sized by touches, and a link for each pair of
+ * players, wider and darker the more passes there were between them. Links of fewer than `minPasses` passes (3) are left out. The numbers behind it are in `totals`,
+ * and `table()` lists the players and the links as text.
+ * @example
+ * ```ts
+ * import { passNetwork } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const passes = [
+ *   { from: 4, to: 8, x: 30, y: 40, x2: 45, y2: 55, team: "home" },
+ *   { from: 8, to: 4, x: 45, y: 55, x2: 32, y2: 42, team: "home" },
+ *   { from: 4, to: 8, x: 31, y: 41, x2: 46, y2: 54, team: "home" },
+ *   { from: 8, to: 9, x: 46, y: 54, x2: 70, y2: 50, team: "home" },
+ * ];
+ * const chart = passNetwork(passes, { provider: "opta", minPasses: 2 });
+ * console.log(chart.totals.passes, chart.totals.players, chart.totals.links, chart.totals.strongest);
+ * // 4 3 1 { from: '4', to: '8', passes: 3 }
+ * ```
+ */
+export declare function passNetwork(passes: readonly PassNetworkPass[], options?: PassNetworkOptions): Chart<PassNetworkTotals> & {
+    key: KeyItem[];
+};

package/dist/charts.network.js

@@ -0,0 +1,64 @@
+// The pass network chart: who passed to whom on a pitch, each player a node at the average place of his passes, sized by touches, and each pair of players a link
+// sized by their passes, with a key and a table. The idea is that of mplsoccer's pass-network example (MIT); no code of it, nor of sportypy or sportyR (GPL), is used.
+import { envFor } from "./layers.env.js";
+import { fill } from "./strings.js";
+import { assemble, clean, drawingOptions, frameOf, fromOf, keyLayers, languageOf, wordsOf } from "./charts.js";
+import { computeNetwork, nodeName } from "./team.network.js";
+/**
+ * A pass network for soccer: a node for each player at the average place of the passes he made and received, sized by touches, and a link for each pair of
+ * players, wider and darker the more passes there were between them. Links of fewer than `minPasses` passes (3) are left out. The numbers behind it are in `totals`,
+ * and `table()` lists the players and the links as text.
+ * @example
+ * ```ts
+ * import { passNetwork } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const passes = [
+ *   { from: 4, to: 8, x: 30, y: 40, x2: 45, y2: 55, team: "home" },
+ *   { from: 8, to: 4, x: 45, y: 55, x2: 32, y2: 42, team: "home" },
+ *   { from: 4, to: 8, x: 31, y: 41, x2: 46, y2: 54, team: "home" },
+ *   { from: 8, to: 9, x: 46, y: 54, x2: 70, y2: 50, team: "home" },
+ * ];
+ * const chart = passNetwork(passes, { provider: "opta", minPasses: 2 });
+ * console.log(chart.totals.passes, chart.totals.players, chart.totals.links, chart.totals.strongest);
+ * // 4 3 1 { from: '4', to: '8', passes: 3 }
+ * ```
+ */
+export function passNetwork(passes, options = {}) {
+    if (!Array.isArray(passes))
+        throw new TypeError("passes is a list of passes");
+    const language = languageOf(options);
+    const all = wordsOf(language);
+    const w = all.charts;
+    const provider = options.provider ?? "international";
+    const frame = frameOf(provider, "international");
+    const o = drawingOptions("soccer", options, w.titlePassNetwork, {
+        ...(typeof provider === "string" ? { pitchType: provider } : {}),
+        ...(options.pitch === undefined ? {} : { pitch: options.pitch }),
+        ...(options.ground === undefined ? {} : { ground: options.ground }),
+    });
+    const attacking = options.attacking === "left" ? "left" : undefined;
+    const layer = clean({
+        kind: "network",
+        id: "network",
+        name: w.passes,
+        ...clean({ from: fromOf(typeof provider === "object" ? provider : undefined, frame), attacking }),
+        data: passes,
+        minPasses: typeof options.minPasses === "number" ? options.minPasses : 3,
+        directed: options.directed,
+        labels: options.labels,
+    });
+    const layers = [layer];
+    if (options.key !== false)
+        layers.push(...keyLayers(o, [], {}, all, [w.sizeTouches, w.widthPasses]));
+    const net = computeNetwork(layer, envFor(o, false));
+    let busiest = null;
+    for (const n of net.nodes)
+        if (busiest === null || n.touches > busiest.touches)
+            busiest = { id: n.id, name: nodeName(n), touches: n.touches };
+    let strongest = null;
+    for (const l of net.links)
+        if (strongest === null || l.n > strongest.passes)
+            strongest = { from: nodeName(l.a), to: nodeName(l.b), passes: l.n };
+    const totals = { passes: net.passes, skipped: net.skipped, players: net.nodes.length, links: net.links.length, busiest, strongest };
+    const summary = fill(w.sumNetwork, { passes: totals.passes, players: totals.players, links: totals.links });
+    return assemble(o, layers, { title: w.titlePassNetwork, summary, totals });
+}