prographs 0.12.0 → 0.13.0

package/dist/charts/sportscharts/TrainingLoadChart.js

@@ -0,0 +1,325 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { ZoomAxis } from "../../core/ChartViewport.js";
+import { SportsSamples } from "./SportsSamples.js";
+import { SportsTimelineChart } from "./SportsTimelineChart.js";
+import { area, axisLeft, line, scaleLinear, scaleUtc } from "d3";
+// src/charts/sportscharts/TrainingLoadChart.ts
+var TrainingLoadForm = /* @__PURE__ */ function(TrainingLoadForm) {
+	TrainingLoadForm["Band"] = "band";
+	TrainingLoadForm["Line"] = "line";
+	return TrainingLoadForm;
+}({});
+var TrainingLoadLayout = /* @__PURE__ */ function(TrainingLoadLayout) {
+	TrainingLoadLayout["Split"] = "split";
+	TrainingLoadLayout["Overlay"] = "overlay";
+	return TrainingLoadLayout;
+}({});
+var DAY = 864e5;
+var MOST_DAYS = 3660;
+var END_ROOM = 34;
+var PANEL_GAP = 12;
+var ZONES = [
+	{
+		name: "Transition",
+		from: 25,
+		to: Infinity,
+		token: "warning"
+	},
+	{
+		name: "Fresh",
+		from: 5,
+		to: 25,
+		token: "grid"
+	},
+	{
+		name: "Neutral",
+		from: -10,
+		to: 5,
+		token: null
+	},
+	{
+		name: "Productive",
+		from: -30,
+		to: -10,
+		token: "good"
+	},
+	{
+		name: "Overreaching",
+		from: -Infinity,
+		to: -30,
+		token: "critical"
+	}
+];
+/**
+* The performance management chart: how much an athlete trained each day, the fitness that built, the fatigue it cost and the form left over.
+* Use it to plan a build and a taper, and to see when load is rising faster than the athlete can absorb.
+*/
+var TrainingLoadChart = class TrainingLoadChart extends SportsTimelineChart {
+	static meta = {
+		id: "training-load",
+		name: "Training load chart",
+		family: ChartFamily.Trend,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Draws daily training stress as bars with fitness (a 42 day exponentially weighted average), fatigue (7 day) and form (fitness less fatigue) as a line or a filled band over its zones. The sample athlete is invented.",
+		tags: [
+			"sports",
+			"performance management",
+			"fitness",
+			"fatigue",
+			"form",
+			"training stress",
+			"endurance"
+		],
+		sample: (seed) => SportsSamples.trainingLoad(seed),
+		variants: {
+			form: ["band", "line"],
+			layout: ["split", "overlay"],
+			loadBars: [true, false],
+			zones: [true, false]
+		}
+	};
+	#days = [];
+	#dated = false;
+	#who = "";
+	#formAxis = scaleLinear();
+	defaults() {
+		return {
+			x: "date",
+			y: "load",
+			athlete: "athlete",
+			fitnessDays: 42,
+			fatigueDays: 7,
+			form: "band",
+			layout: "split",
+			loadBars: true,
+			zones: true
+		};
+	}
+	/** The form panel has an axis of its own, so only time zooms. */
+	zoomAxes() {
+		return ZoomAxis.X;
+	}
+	legendItems() {
+		const items = super.legendItems();
+		return this.options.loadBars && items.length ? [{
+			key: "Daily load",
+			color: this.theme.inkMuted
+		}, ...items] : items;
+	}
+	/**
+	* Fitness, fatigue and form for a run of daily loads. Each average moves toward the day's load by 1 - exp(-1 / days) of the gap,
+	* and form is the day's fitness less its fatigue. Both averages start at `baseline`, or at the mean of the first `fitnessDays` loads.
+	*/
+	static model(loads, fitnessDays, fatigueDays, baseline) {
+		const gain = (days) => days > 0 ? 1 - Math.exp(-1 / days) : 1, slow = gain(fitnessDays), fast = gain(fatigueDays);
+		const early = loads.slice(0, Math.max(1, Math.ceil(fitnessDays) || 1));
+		let fitness = baseline ?? (early.length ? early.reduce((sum, load) => sum + load, 0) / early.length : 0), fatigue = fitness;
+		return loads.map((load) => {
+			fitness += (load - fitness) * slow;
+			fatigue += (load - fatigue) * fast;
+			return {
+				load,
+				fitness,
+				fatigue,
+				form: fitness - fatigue
+			};
+		});
+	}
+	/** Every day from the first athlete's first session to the last, with the sessions of a day added up and rest days at zero. */
+	get days() {
+		const { x, y, athlete, fitnessDays, fatigueDays, baseline } = this.options, rows = this.rows();
+		const who = this.#who = rows.map((row) => this.word(row[athlete])).find(Boolean) ?? "";
+		const totals = /* @__PURE__ */ new Map();
+		let dated = false;
+		for (const row of rows) {
+			const cell = row[x], load = this.number(row[y]), numbered = this.number(cell);
+			const stamp = numbered !== null ? NaN : cell instanceof Date ? cell.getTime() : typeof cell === "string" ? Date.parse(cell) : NaN;
+			const day = numbered !== null ? Math.floor(numbered) : Number.isFinite(stamp) ? Math.floor(stamp / DAY) : null;
+			if (this.word(row[athlete], who) !== who || day === null || load === null) continue;
+			dated ||= numbered === null;
+			totals.set(day, (totals.get(day) ?? 0) + Math.max(0, load));
+		}
+		this.#dated = dated;
+		if (!totals.size) return [];
+		const last = Math.max(...totals.keys()), first = Math.max(Math.min(...totals.keys()), last - MOST_DAYS + 1);
+		const loads = Array.from({ length: last - first + 1 }, (_, i) => totals.get(first + i) ?? 0);
+		return TrainingLoadChart.model(loads, fitnessDays, fatigueDays, baseline).map((entry, i) => ({
+			day: first + i,
+			...entry
+		}));
+	}
+	get #split() {
+		return this.options.layout === "split";
+	}
+	/** The range of form the zones are drawn over: wide enough to show the three middle zones whole. */
+	#reach(days) {
+		const forms = days.map((entry) => entry.form);
+		return [Math.min(-30, ...forms) - 6, Math.max(25, ...forms) + 6];
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot, { loadBars } = this.options, days = this.#days = this.days, split = this.#split;
+		const first = days[0]?.day ?? 0, last = days.at(-1)?.day ?? first, range = [0, Math.max(10, width - END_ROOM)];
+		const x = this.#dated ? scaleUtc([/* @__PURE__ */ new Date((first - .5) * DAY), /* @__PURE__ */ new Date((last + .5) * DAY)], range) : scaleLinear([first - .5, last + .5], range);
+		const panel = split ? Math.max(36, Math.min(110, height * .3)) : 0, main = Math.max(10, height - (split ? panel + PANEL_GAP : 0));
+		const top = Math.max(1, ...days.flatMap((entry) => [
+			loadBars ? entry.load : 0,
+			entry.fitness,
+			entry.fatigue
+		]));
+		const y = scaleLinear([0, top], [main, 0]).nice(), deepest = split ? 0 : Math.min(0, ...days.map((entry) => entry.form));
+		if (deepest < 0) y.domain([deepest * 1.1, y.domain()[1]]);
+		this.#formAxis = split ? scaleLinear(this.#reach(days), [height, height - panel]) : y;
+		return {
+			x,
+			y
+		};
+	}
+	plotMarks(ctx, { x, y }) {
+		const { form, loadBars, zones, fitnessDays, fatigueDays } = this.options, days = this.#days, split = this.#split, formY = this.#formAxis, { theme } = ctx;
+		const at = (day) => x(this.#dated ? /* @__PURE__ */ new Date(day * DAY) : day);
+		const named = (day) => this.#dated ? (/* @__PURE__ */ new Date(day * DAY)).toISOString().slice(0, 10) : `Day ${day}`;
+		const whole = (value) => `${Math.round(value)}`;
+		const series = [{
+			key: "Fitness",
+			value: (entry) => entry.fitness,
+			scale: y,
+			days: fitnessDays
+		}, {
+			key: "Fatigue",
+			value: (entry) => entry.fatigue,
+			scale: y,
+			days: fatigueDays
+		}];
+		const color = (key) => ctx.palette.color(key);
+		if (days.length) for (const key of [
+			"Fitness",
+			"Fatigue",
+			"Form"
+		]) color(key);
+		const right = at((days.at(-1)?.day ?? 0) + .5), [low, high] = this.#reach(days);
+		const shaded = zones && days.length ? ZONES.flatMap((zone) => {
+			const y0 = formY(Math.min(high, zone.to)), y1 = formY(Math.max(low, zone.from));
+			return y1 - y0 > .5 ? [{
+				...zone,
+				y0,
+				y1
+			}] : [];
+		}) : [];
+		const strips = ctx.marks("axis-zones", "rect", shaded.filter((zone) => zone.token), (d) => d.name).attr("fill", (d) => theme[d.token]).attr("fill-opacity", (d) => d.token === "grid" ? .6 : .14);
+		ctx.set(strips, {
+			x: 0,
+			width: Math.max(0, right),
+			y: (d) => d.y0,
+			height: (d) => d.y1 - d.y0
+		});
+		const step = Math.abs(at(1) - at(0)), wide = Math.max(1, step - (step > 4 ? 2 : step > 2.5 ? 1 : 0));
+		const bars = ctx.marks("loads", "rect", loadBars ? days.filter((entry) => entry.load > 0) : [], (d) => d.day).attr("fill", theme.inkMuted).attr("fill-opacity", .45);
+		ctx.set(bars, {
+			x: (d) => at(d.day) - wide / 2,
+			width: wide,
+			y: (d) => y(d.load),
+			height: (d) => Math.max(0, y(0) - y(d.load))
+		}, {
+			y: y(0),
+			height: 0
+		});
+		ctx.hover(bars, (d) => ({
+			title: named(d.day),
+			rows: [
+				["Load", whole(d.load)],
+				["Fitness", whole(d.fitness)],
+				["Fatigue", whole(d.fatigue)],
+				["Form", whole(d.form)]
+			]
+		}));
+		const zero = ctx.marks("axis-form-zero", "line", days.length && (split || y.domain()[0] < 0) ? [0] : []).attr("stroke", theme.axis).attr("stroke-width", 1);
+		ctx.set(zero, {
+			x1: 0,
+			x2: ctx.plot.width,
+			y1: formY(0),
+			y2: formY(0)
+		});
+		if (split) {
+			const axis = ctx.group("axis-form").call(axisLeft(formY).ticks(3).tickSize(0).tickFormat((value) => whole(+value)));
+			axis.select(".domain").attr("stroke", "none");
+			axis.selectAll("text").attr("fill", theme.inkSecondary).attr("font-size", 11).attr("font-family", theme.fontFamily);
+		} else ctx.group("axis-form").selectAll("*").remove();
+		const joined = days.length > 1 ? days : [];
+		const latest = days.at(-1);
+		const tell = (key, value, span) => ({
+			title: key,
+			color: color(key),
+			rows: [["Latest", whole(value)], ...span ? [["Time constant", `${span} days`]] : []]
+		});
+		const fill = area().curve(Scales.curve()).x((d) => at(d.day)).y0(formY(0));
+		const bands = ctx.marks("form-band", "path", form === "band" && joined.length ? [joined] : []).attr("fill", color("Form")).attr("fill-opacity", .7);
+		ctx.set(bands, { d: (d) => fill.y1((entry) => formY(entry.form))(d) ?? "" }, { d: (d) => fill.y1(formY(0))(d) ?? "" });
+		ctx.hover(bands, () => tell("Form", latest?.form ?? 0));
+		const trace = (value, scale) => line().curve(Scales.curve()).x((d) => at(d.day)).y((d) => scale(value(d)));
+		const traced = [...series, ...form === "line" ? [{
+			key: "Form",
+			value: (entry) => entry.form,
+			scale: formY,
+			days: 0
+		}] : []];
+		const lines = ctx.marks("lines", "path", joined.length ? traced : [], (d) => d.key).attr("fill", "none").attr("stroke", (d) => color(d.key)).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("stroke-linecap", "round");
+		ctx.set(lines, { d: (d) => trace(d.value, d.scale)(joined) ?? "" });
+		ctx.drawOn(lines);
+		ctx.hover(lines, (d) => tell(d.key, latest ? d.value(latest) : 0, d.days));
+		const ends = !latest ? [] : [
+			{
+				key: "fitness",
+				text: whole(latest.fitness),
+				x: right + 5,
+				y: y(latest.fitness) + 4,
+				tone: "ink"
+			},
+			{
+				key: "fatigue",
+				text: whole(latest.fatigue),
+				x: right + 5,
+				y: y(latest.fatigue) + 4,
+				tone: "ink"
+			},
+			{
+				key: "form",
+				text: whole(latest.form),
+				x: right + 5,
+				y: formY(latest.form) + 4,
+				tone: "ink"
+			}
+		].sort((a, b) => a.y - b.y);
+		ends.forEach((label, i) => {
+			if (i && label.y - ends[i - 1].y < 12) label.y = ends[i - 1].y + 12;
+		});
+		const zoneNames = shaded.filter((zone) => zone.y1 - zone.y0 >= 11).map((zone) => ({
+			key: `zone-${zone.name}`,
+			text: zone.name,
+			x: 4,
+			y: (zone.y0 + zone.y1) / 2 + 3.5,
+			tone: "muted",
+			size: 10
+		}));
+		const corner = !days.length ? [{
+			key: "empty",
+			text: "No training load",
+			x: 4,
+			y: 12,
+			tone: "muted"
+		}] : this.#who ? [{
+			key: "who",
+			text: this.#who,
+			x: 4,
+			y: 12,
+			tone: "muted"
+		}] : [];
+		this.notes(ctx, "notes", [
+			...zoneNames,
+			...ends,
+			...corner
+		]);
+	}
+};
+export { TrainingLoadChart, TrainingLoadForm, TrainingLoadLayout };

package/dist/charts/sportscharts/index.js

@@ -12,10 +12,12 @@ import { PassLinkMode, PassPositionBasis, PassingNetworkPitch } from "./PassingN
 import { PitchHeatBins, PitchHeatmap } from "./PitchHeatmap.js";
 import { PizzaChart, PizzaSort } from "./PizzaChart.js";
 import { SportsTimelineChart } from "./SportsTimelineChart.js";
+import { PowerDurationCurve, PowerDurationUnit } from "./PowerDurationCurve.js";
 import { RaceLapChart } from "./RaceLapChart.js";
 import { ScoreWormChart, WormMeasure } from "./ScoreWormChart.js";
 import { StrikeZoneMarks, StrikeZonePlot, StrikeZoneView } from "./StrikeZonePlot.js";
 import { ServeFilter, ServeMarks, ServeView, TennisServePlacement } from "./TennisServePlacement.js";
+import { TrainingLoadChart, TrainingLoadForm, TrainingLoadLayout } from "./TrainingLoadChart.js";
 import { TyreStrategyChart, TyreStrategyOrder } from "./TyreStrategyChart.js";
 import { WinProbabilityChart, WinProbabilityForm } from "./WinProbabilityChart.js";
 import { XgMarks, XgShotMap } from "./XgShotMap.js";
@@ -34,6 +36,8 @@ var sportschartsCatalog = [
 	TyreStrategyChart,
 	PitchHeatmap,
 	HockeyRinkShotMap,
-	GolfShotDispersion
+	GolfShotDispersion,
+	PowerDurationCurve,
+	TrainingLoadChart
 ];
-export { BaseballSprayChart, BatterHand, CricketWagonWheel, FieldClip, FootballPitch, GolfDispersionView, GolfShotDispersion, HockeyRink, HockeyRinkMarks, HockeyRinkShotMap, HockeyRinkShots, HockeyRinkView, HockeyShotResult, PassLinkMode, PassPositionBasis, PassingNetworkPitch, PitchCoordinates, PitchHeatBins, PitchHeatmap, PitchView, PizzaChart, PizzaSort, RaceLapChart, ScoreWormChart, ServeFilter, ServeMarks, ServeView, SportsCells, SportsFieldChart, SportsSamples, SportsTimelineChart, SprayMarks, StrikeZoneMarks, StrikeZonePlot, StrikeZoneView, TennisServePlacement, TyreStrategyChart, TyreStrategyOrder, WagonMarks, WagonShots, WinProbabilityChart, WinProbabilityForm, WormMeasure, XgMarks, XgShotMap, sportschartsCatalog };
+export { BaseballSprayChart, BatterHand, CricketWagonWheel, FieldClip, FootballPitch, GolfDispersionView, GolfShotDispersion, HockeyRink, HockeyRinkMarks, HockeyRinkShotMap, HockeyRinkShots, HockeyRinkView, HockeyShotResult, PassLinkMode, PassPositionBasis, PassingNetworkPitch, PitchCoordinates, PitchHeatBins, PitchHeatmap, PitchView, PizzaChart, PizzaSort, PowerDurationCurve, PowerDurationUnit, RaceLapChart, ScoreWormChart, ServeFilter, ServeMarks, ServeView, SportsCells, SportsFieldChart, SportsSamples, SportsTimelineChart, SprayMarks, StrikeZoneMarks, StrikeZonePlot, StrikeZoneView, TennisServePlacement, TrainingLoadChart, TrainingLoadForm, TrainingLoadLayout, TyreStrategyChart, TyreStrategyOrder, WagonMarks, WagonShots, WinProbabilityChart, WinProbabilityForm, WormMeasure, XgMarks, XgShotMap, sportschartsCatalog };