@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/business/TornadoChart.js

@@ -0,0 +1,436 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SampleData } from "../../data/SampleData.js";
+import { BandChart } from "../bars/BandChart.js";
+import { BarRows } from "../bars/BarRows.js";
+import { max, min } from "d3";
+// src/charts/business/TornadoChart.ts
+var TornadoForm = /* @__PURE__ */ function(TornadoForm) {
+	TornadoForm["Bars"] = "bars";
+	TornadoForm["Lanes"] = "lanes";
+	TornadoForm["Range"] = "range";
+	return TornadoForm;
+}({});
+/** What the value axis reads: the output itself, its change from base, or that change as a percent of base. */
+var TornadoMeasure = /* @__PURE__ */ function(TornadoMeasure) {
+	TornadoMeasure["Output"] = "output";
+	TornadoMeasure["Delta"] = "delta";
+	TornadoMeasure["Percent"] = "percent";
+	return TornadoMeasure;
+}({});
+/** Widest total swing on top, or the biggest shortfall below base on top. */
+var TornadoSort = /* @__PURE__ */ function(TornadoSort) {
+	TornadoSort["Swing"] = "swing";
+	TornadoSort["Downside"] = "downside";
+	return TornadoSort;
+}({});
+/** What the text at each bar end states: the input tested, or the output it gave. */
+var TornadoEnds = /* @__PURE__ */ function(TornadoEnds) {
+	TornadoEnds["Inputs"] = "inputs";
+	TornadoEnds["Outputs"] = "outputs";
+	TornadoEnds["None"] = "no-ends";
+	return TornadoEnds;
+}({});
+var CHAR = 5.8;
+var CASE = {
+	price: 100,
+	volume: 4e4,
+	unitCost: 62,
+	fixedCost: 42e4,
+	capex: 24e5,
+	discount: .1,
+	tax: .25,
+	growth: .04
+};
+var usd = (value) => `$${Math.round(value)}`;
+var thousands = (value) => `${Math.round(value / 1e3)}k`;
+var dollarsK = (value) => `$${thousands(value)}`;
+var dollarsM = (value) => `$${(value / 1e6).toFixed(1)}M`;
+var percent = (value) => `${+(value * 100).toFixed(1)}%`;
+var DRIVERS = [
+	{
+		name: "Discount rate",
+		key: "discount",
+		low: .08,
+		high: .13,
+		show: percent
+	},
+	{
+		name: "Unit cost",
+		key: "unitCost",
+		low: 58,
+		high: 68,
+		show: usd
+	},
+	{
+		name: "Volume growth",
+		key: "growth",
+		low: 0,
+		high: .07,
+		show: percent
+	},
+	{
+		name: "Capex",
+		key: "capex",
+		low: 23e5,
+		high: 31e5,
+		show: dollarsM
+	},
+	{
+		name: "Unit price",
+		key: "price",
+		low: 93,
+		high: 110,
+		show: usd
+	},
+	{
+		name: "Fixed costs",
+		key: "fixedCost",
+		low: 38e4,
+		high: 52e4,
+		show: dollarsK
+	},
+	{
+		name: "Tax rate",
+		key: "tax",
+		low: .21,
+		high: .3,
+		show: percent
+	},
+	{
+		name: "Sales volume",
+		key: "volume",
+		low: 27e3,
+		high: 43e3,
+		show: thousands
+	}
+];
+/** Five-year project NPV in $M: the model the sample sensitivities are actually run on. */
+var npv = ({ price, volume, unitCost, fixedCost, capex, discount, tax, growth }) => {
+	return +([
+		1,
+		2,
+		3,
+		4,
+		5
+	].map((year) => (volume * (1 + growth) ** (year - 1) * (price - unitCost) - fixedCost) * (1 - tax) / (1 + discount) ** year).reduce((total, flow) => total + flow, -capex) / 1e6).toFixed(3);
+};
+/** One-at-a-time sensitivity of a project NPV; SampleData scales how far each input range reaches. */
+var sensitivities = (seed) => {
+	const reach = SampleData.categories(seed, DRIVERS.length, 2).map((row) => .75 + +row.value / 100 * .5);
+	const base = npv(CASE);
+	return DRIVERS.map(({ name, key, low, high, show }, i) => {
+		const lowInput = CASE[key] + (low - CASE[key]) * reach[i * 2], highInput = CASE[key] + (high - CASE[key]) * reach[i * 2 + 1];
+		return {
+			driver: name,
+			low: npv({
+				...CASE,
+				[key]: lowInput
+			}),
+			high: npv({
+				...CASE,
+				[key]: highInput
+			}),
+			base,
+			lowInput: show(lowInput),
+			highInput: show(highInput)
+		};
+	});
+};
+/**
+* Sensitivity analysis: each driver's output at its low and high input, drawn about the base case
+* and sorted so the biggest swing is on top. Colour marks the input case, not the outcome, so an
+* inverse driver such as cost shows its high case on the downside.
+*/
+var TornadoChart = class extends BandChart {
+	static meta = {
+		id: "tornado",
+		name: "Tornado chart",
+		family: ChartFamily.Comparison,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Ranks the drivers of a forecast by how far their low and high cases swing the output around the base case.",
+		tags: [
+			"sensitivity",
+			"what-if",
+			"one-way",
+			"swing",
+			"risk",
+			"npv"
+		],
+		sample: sensitivities,
+		variants: {
+			form: [
+				"bars",
+				"lanes",
+				"range"
+			],
+			measure: [
+				"output",
+				"delta",
+				"percent"
+			],
+			sort: ["swing", "downside"],
+			ends: ["inputs", "no-ends"],
+			breakeven: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			x: "driver",
+			low: "low",
+			high: "high",
+			base: "base",
+			lowInput: "lowInput",
+			highInput: "highInput",
+			lowName: "Low input",
+			highName: "High input",
+			form: "bars",
+			measure: "output",
+			sort: "swing",
+			ends: "inputs",
+			breakeven: false,
+			breakevenAt: 0
+		};
+	}
+	get vertical() {
+		return false;
+	}
+	bandPadding() {
+		return .24;
+	}
+	unit() {
+		return this.options.measure === "percent" ? "%" : "";
+	}
+	baseline() {
+		return this.drivers.length ? this.origin : null;
+	}
+	plotMargin() {
+		return {
+			...super.plotMargin(),
+			top: 26
+		};
+	}
+	get records() {
+		return Array.isArray(this.options.data) ? this.options.data : [];
+	}
+	get baseCase() {
+		const { baseValue, base } = this.options;
+		if (baseValue !== void 0) return baseValue;
+		return this.records.map((row) => BarRows.number(row[base])).find((value) => value !== null) ?? 0;
+	}
+	/** Output in the units the axis reads. Percent of a zero base is undefined, so it reads as delta. */
+	at(output) {
+		const { measure } = this.options;
+		const base = this.baseCase;
+		if (measure === "output") return output;
+		return measure === "percent" && base ? (output - base) / Math.abs(base) * 100 : output - base;
+	}
+	get origin() {
+		return this.at(this.baseCase);
+	}
+	get flip() {
+		return this.options.breakeven ? this.at(this.options.breakevenAt) : null;
+	}
+	/** First row per driver wins; a one-sided driver stays at base on its missing side. */
+	get drivers() {
+		const { x, low, high, lowInput, highInput, sort, limit } = this.options;
+		const base = this.baseCase;
+		const input = (cell) => cell === null || cell === void 0 || cell === "" ? null : BarRows.label(cell);
+		const found = /* @__PURE__ */ new Map();
+		for (const row of this.records) {
+			const name = BarRows.label(row[x]);
+			const lo = BarRows.number(row[low]), hi = BarRows.number(row[high]);
+			if (found.has(name) || lo === null && hi === null) continue;
+			found.set(name, {
+				name,
+				low: lo ?? base,
+				high: hi ?? base,
+				lowInput: input(row[lowInput]),
+				highInput: input(row[highInput])
+			});
+		}
+		const rank = sort === "downside" ? (d) => base - Math.min(d.low, d.high) : (d) => Math.abs(d.high - d.low);
+		return [...found.values()].sort((a, b) => rank(b) - rank(a)).slice(0, limit || void 0);
+	}
+	bandNames() {
+		return this.drivers.map((driver) => driver.name);
+	}
+	valueExtent() {
+		const values = [
+			...this.drivers.flatMap((driver) => [this.at(driver.low), this.at(driver.high)]),
+			this.origin,
+			...this.flip === null ? [] : [this.flip]
+		];
+		return [min(values) ?? 0, max(values) ?? 1];
+	}
+	say(value) {
+		const [low, high] = this.valueExtent();
+		const text = Scales.format(value, Math.max(Math.abs(low), Math.abs(high)));
+		return this.options.measure === "output" ? text : `${value > 0 ? "+" : ""}${text}${this.unit()}`;
+	}
+	tickFormat(scale) {
+		const format = super.tickFormat(scale);
+		if (!format || this.options.measure === "output" || typeof scale.domain?.()[0] !== "number") return format;
+		return (value) => `${+value > 0 ? "+" : ""}${format(value)}`;
+	}
+	endText(driver, side) {
+		const input = side === "low" ? driver.lowInput : driver.highInput;
+		return this.options.ends === "inputs" && input !== null ? input : this.say(this.at(driver[side]));
+	}
+	/** Room each label side needs, sized to the text that actually lands on it. */
+	endRoom(leftward) {
+		if (this.options.ends === "no-ends") return 0;
+		const widest = max(this.drivers, (driver) => {
+			const sides = ["low", "high"].filter((side, i, all) => driver[side] < driver[all[1 - i]] === leftward);
+			return max(sides, (side) => this.endText(driver, side).length) ?? 0;
+		}) ?? 0;
+		return Math.min(widest * CHAR + 10, this.size.width * .2);
+	}
+	reserve() {
+		const dot = this.options.form === "range" ? 6 : 0;
+		return [this.endRoom(true) + dot, this.endRoom(false) + dot];
+	}
+	/** One mark per case. Two cases on one side of base stack end to end, so neither hides the other. */
+	pieces(frame) {
+		const { form } = this.options;
+		const origin = this.origin;
+		const lanes = form === "lanes", range = form === "range";
+		const lane = (frame.thick - 2) / 2;
+		return this.drivers.flatMap((driver) => {
+			const start = frame.band(driver.name) ?? 0;
+			const low = this.at(driver.low), high = this.at(driver.high);
+			const opposed = (low - origin) * (high - origin) < 0;
+			const outer = Math.abs(high - origin) > Math.abs(low - origin) ? "high" : "low";
+			const inner = outer === "high" ? low : high;
+			return ["low", "high"].flatMap((side, i) => {
+				const value = side === "low" ? low : high;
+				if (!range && value === origin) return [];
+				const stacked = !lanes && !range && !opposed && side === outer && inner !== origin;
+				const leftward = range ? value === Math.min(low, high) && (low !== high || i === 0) : value < origin;
+				const along = lanes ? start + i * (lane + 2) : start;
+				const roomy = lanes && lane >= 12;
+				return [{
+					driver,
+					side,
+					value,
+					along,
+					thick: lanes ? lane : frame.thick,
+					textAt: (roomy ? along + lane / 2 : start + frame.thick / 2) + 3.5,
+					from: stacked ? inner : origin,
+					radius: !opposed && !lanes && side !== outer ? 0 : 4,
+					inset: stacked ? 2 : 1,
+					labelled: opposed || side === outer || range || roomy,
+					leftward
+				}];
+			});
+		});
+	}
+	tooltip(driver, color) {
+		const { lowName, highName, breakevenAt, breakeven } = this.options;
+		const line = (name, input, output) => [input === null ? name : `${name} (${input})`, this.say(this.at(output))];
+		const crosses = breakeven && (driver.low - breakevenAt) * (driver.high - breakevenAt) < 0;
+		return {
+			title: driver.name,
+			color,
+			rows: [
+				line(lowName, driver.lowInput, driver.low),
+				line(highName, driver.highInput, driver.high),
+				["Swing", Scales.format(Math.abs(this.at(driver.high) - this.at(driver.low)), Math.abs(this.origin) || 1)],
+				...crosses ? [["Crosses break-even", "Yes"]] : []
+			]
+		};
+	}
+	drawBands(ctx, frame) {
+		const parts = this.pieces(frame);
+		const range = this.options.form === "range";
+		const color = (d) => ctx.palette.color(d.side === "low" ? this.options.lowName : this.options.highName);
+		const shape = (d, to) => frame.bar(d.along, d.thick, d.from, to, d.radius, d.inset);
+		const key = (d) => `${d.driver.name}/${d.side}`;
+		const bars = ctx.marks("bars", "path", range ? [] : parts, key).attr("fill", color);
+		ctx.set(bars, { d: (d) => shape(d, d.value) }, { d: (d) => shape(d, d.from) }, 12);
+		ctx.hover(bars, (d) => this.tooltip(d.driver, color(d)));
+		const spans = ctx.marks("spans", "line", range ? this.drivers : [], (d) => d.name).attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 2).attr("stroke-linecap", "round");
+		const place = (d, side) => frame.value(this.at(d[side]));
+		const middle = (d) => frame.center(d.name);
+		ctx.set(spans, {
+			x1: (d) => place(d, "low"),
+			x2: (d) => place(d, "high"),
+			y1: middle,
+			y2: middle
+		}, {
+			x1: frame.value(this.origin),
+			x2: frame.value(this.origin),
+			y1: middle,
+			y2: middle
+		});
+		const dots = ctx.marks("dots", "circle", range ? parts : [], key).attr("fill", color).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (d) => frame.value(d.value),
+			cy: (d) => frame.center(d.driver.name),
+			r: 6
+		}, {
+			cy: (d) => frame.center(d.driver.name),
+			r: 0
+		});
+		ctx.hover(dots, (d) => this.tooltip(d.driver, color(d)));
+		this.drawEnds(ctx, frame, parts);
+		this.drawReferences(ctx, frame);
+	}
+	drawEnds(ctx, frame, parts) {
+		const shown = this.options.ends === "no-ends" || frame.band.step() < 13 ? [] : parts.filter((d) => d.labelled);
+		const gap = this.options.form === "range" ? 10 : 6;
+		const { surface } = ctx.theme;
+		const labels = ctx.text(ctx.marks("ends", "text", shown, (d) => `${d.driver.name}/${d.side}`), 10.5).attr("text-anchor", (d) => d.leftward ? "end" : "start").attr("stroke", surface).attr("stroke-width", 3).attr("paint-order", "stroke").style("pointer-events", "none").text((d) => BarRows.clip(this.endText(d.driver, d.side), Math.floor(this.endRoom(d.leftward) / CHAR)));
+		ctx.set(labels, {
+			x: (d) => frame.value(d.value) + (d.leftward ? -gap : gap),
+			y: (d) => d.textAt
+		});
+	}
+	drawReferences(ctx, frame) {
+		const { height, width } = ctx.plot;
+		const flip = this.flip;
+		const rule = ctx.marks("breakeven", "line", flip === null ? [] : [flip]).attr("stroke", ctx.theme.ink).attr("stroke-width", 1).attr("stroke-dasharray", "4 3");
+		ctx.set(rule, {
+			x1: (d) => frame.value(d),
+			x2: (d) => frame.value(d),
+			y1: 0,
+			y2: height
+		});
+		const base = this.baseCase;
+		const references = !this.drivers.length ? [] : [{
+			key: "base",
+			at: frame.value(this.origin),
+			text: `Base ${Scales.format(base, Math.abs(base))}`
+		}, ...flip === null ? [] : [{
+			key: "breakeven",
+			at: frame.value(flip),
+			text: "Break-even"
+		}]];
+		const labels = ctx.text(ctx.marks("reference-labels", "text", this.spread(references, width), (d) => d.key), 11, "ink").attr("text-anchor", "middle").text((d) => d.text);
+		ctx.set(labels, {
+			x: (d) => d.at,
+			y: -8
+		});
+	}
+	/** Slides labels along the top edge so they stay inside the plot and clear of each other. */
+	spread(references, width) {
+		const half = (d) => d.text.length * CHAR / 2;
+		let edge = 0;
+		const placed = [...references].sort((a, b) => a.at - b.at).map((d) => {
+			const at = Math.max(d.at, edge + half(d));
+			edge = at + half(d) + 8;
+			return {
+				...d,
+				at
+			};
+		});
+		let limit = width;
+		for (const d of [...placed].reverse()) {
+			d.at = Math.min(d.at, limit - half(d));
+			limit = d.at - half(d) - 8;
+		}
+		return placed.filter((d) => d.at >= half(d));
+	}
+};
+export { TornadoChart, TornadoEnds, TornadoForm, TornadoMeasure, TornadoSort };

package/dist/charts/business/index.js

@@ -0,0 +1,5 @@
+import { SparkBar, SparkBarForm, SparkBarReference, SparkBarScale, SparkBarTies } from "./SparkBar.js";
+import { TornadoChart, TornadoEnds, TornadoForm, TornadoMeasure, TornadoSort } from "./TornadoChart.js";
+// src/charts/business/index.ts
+var businessCatalog = [TornadoChart, SparkBar];
+export { SparkBar, SparkBarForm, SparkBarReference, SparkBarScale, SparkBarTies, TornadoChart, TornadoEnds, TornadoForm, TornadoMeasure, TornadoSort, businessCatalog };

package/dist/charts/comparison/BandValueChart.js

@@ -0,0 +1,153 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { CurveKind, Orientation } from "../../core/enums.js";
+import { Tally } from "./Tally.js";
+import { area, curveBumpX, curveBumpY, curveCatmullRom, curveLinear, curveMonotoneX, curveMonotoneY, line, max, min, scaleBand, scaleLinear } from "d3";
+// src/charts/comparison/BandValueChart.ts
+var fixed = (value) => typeof value === "number" ? () => value : value;
+/** Categories on one axis, values on the other, in either orientation. Marks are written in band/value pixels. */
+var BandValueChart = class extends CartesianChart {
+	bandPadding() {
+		return .3;
+	}
+	valueScale() {
+		return scaleLinear();
+	}
+	/** Pixels the value axis may use; smaller than the plot when a chart keeps a text column. */
+	valueReach(ctx) {
+		return this.vertical ? ctx.plot.height : ctx.plot.width;
+	}
+	flipped() {
+		return false;
+	}
+	/** Pixels kept clear at the start of the value axis, so marks on it do not touch horizontal band labels. */
+	valueInset() {
+		return 0;
+	}
+	get vertical() {
+		return (this.options.orientation ?? Orientation.Vertical) === Orientation.Vertical;
+	}
+	scales(ctx) {
+		const { bands, values, items } = this.bandLayout();
+		const finite = values.filter(Number.isFinite);
+		let low = min(finite) ?? 0, high = max(finite) ?? 1;
+		if (low === high) {
+			const pad = Math.abs(low) / 2 || 1;
+			low -= pad;
+			high += pad;
+		}
+		const reach = this.valueReach(ctx);
+		const value = this.valueScale().domain(this.flipped() ? [high, low] : [low, high]).range(this.vertical ? [reach, 0] : [this.valueInset(), reach]).nice();
+		const band = scaleBand(bands, [0, this.vertical ? ctx.plot.width : ctx.plot.height]).padding(this.bandPadding());
+		const mid = (name) => (band(name) ?? 0) + band.bandwidth() / 2;
+		return {
+			x: this.vertical ? band : value,
+			y: this.vertical ? value : band,
+			band,
+			value,
+			items,
+			mid
+		};
+	}
+	plotMarks(ctx, axes) {
+		this.tidyBandAxis(ctx, axes.band);
+		this.valueGuides(ctx, axes.value);
+		this.plotBands(ctx, axes);
+	}
+	/** Thins and clips band labels so none overlap, whatever the data. */
+	tidyBandAxis(ctx, band) {
+		const longest = max(band.domain(), (name) => Tally.width(name)) ?? 0;
+		const step = band.step() || 1;
+		const every = this.vertical ? Math.max(1, Math.ceil(Math.min(longest + 6, 64) / step)) : Math.max(1, Math.ceil(13 / step));
+		const room = this.vertical ? step * every - 4 : 84;
+		ctx.group(this.vertical ? "axis-x" : "axis-y").selectAll(".tick text").text((name, i) => i % every ? "" : Tally.clip(name, room));
+	}
+	valueGuides(ctx, value) {
+		const { width, height } = ctx.plot;
+		const [start, end] = value.range();
+		const ticks = !this.vertical && this.options.grid !== false ? value.ticks(Math.min(this.xTicks(), Math.floor(width / 80))) : [];
+		ctx.group("grid-value").lower().selectAll("line").data(ticks).join("line").attr("x1", (tick) => value(tick)).attr("x2", (tick) => value(tick)).attr("y1", 0).attr("y2", height).attr("stroke", ctx.theme.grid);
+		const [a, b] = value.domain();
+		const zero = Math.min(a, b) < 0 && Math.max(a, b) > 0 ? [value(0)] : [];
+		const rule = ctx.marks("zero", "line", zero).attr("stroke", ctx.theme.axis).attr("stroke-width", 1);
+		if (this.vertical) rule.attr("x1", 0).attr("x2", width).attr("y1", (at) => at).attr("y2", (at) => at);
+		else rule.attr("x1", (at) => at).attr("x2", (at) => at).attr("y1", 0).attr("y2", height);
+		if (start === end) rule.remove();
+	}
+	/** Rectangle across the band centred on `along`, spanning `from..to` on the value axis. */
+	span(along, thick, from, to) {
+		const size = fixed(thick);
+		const low = (d, i) => Math.min(from(d, i), to(d, i));
+		const length = (d, i) => Math.abs(to(d, i) - from(d, i));
+		const across = (d, i) => along(d, i) - size(d, i) / 2;
+		return this.vertical ? {
+			x: across,
+			width: size,
+			y: low,
+			height: length
+		} : {
+			y: across,
+			height: size,
+			x: low,
+			width: length
+		};
+	}
+	/** Line along the value axis at band position `along`. */
+	rule(along, from, to) {
+		return this.vertical ? {
+			x1: along,
+			x2: along,
+			y1: from,
+			y2: to
+		} : {
+			y1: along,
+			y2: along,
+			x1: from,
+			x2: to
+		};
+	}
+	/** Line across the band at value position `at`, `half` px either side of `along`. */
+	cross(along, at, half) {
+		const a = (d, i) => along(d, i) - half, b = (d, i) => along(d, i) + half;
+		return this.vertical ? {
+			x1: a,
+			x2: b,
+			y1: at,
+			y2: at
+		} : {
+			y1: a,
+			y2: b,
+			x1: at,
+			x2: at
+		};
+	}
+	spot(along, at) {
+		return this.vertical ? {
+			cx: along,
+			cy: at
+		} : {
+			cy: along,
+			cx: at
+		};
+	}
+	point(along, at) {
+		return { transform: (d, i) => this.vertical ? `translate(${along(d, i)},${at(d, i)})` : `translate(${at(d, i)},${along(d, i)})` };
+	}
+	curve(kind) {
+		switch (kind) {
+			case CurveKind.Monotone: return this.vertical ? curveMonotoneX : curveMonotoneY;
+			case CurveKind.Bump: return this.vertical ? curveBumpX : curveBumpY;
+			case CurveKind.CatmullRom: return curveCatmullRom;
+			default: return curveLinear;
+		}
+	}
+	/** Path through `along`/`at` pixels in reading order of the bands. */
+	trace(along, at, kind = CurveKind.Linear) {
+		const path = line().curve(this.curve(kind));
+		return this.vertical ? path.x(along).y(at) : path.x(at).y(along);
+	}
+	ribbon(along, low, high, kind = CurveKind.Linear) {
+		const path = area().curve(this.curve(kind));
+		return this.vertical ? path.x(along).y0(low).y1(high) : path.y(along).x0(low).x1(high);
+	}
+};
+export { BandValueChart };