prographs 0.12.0 → 0.13.0

package/dist/charts/strategycharts/BassDiffusionChart.js

@@ -0,0 +1,362 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { ChartFamily, CurveKind, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { ZoomAxis } from "../../core/ChartViewport.js";
+import { FrameworkText } from "../frameworks/FrameworkText.js";
+import { BassModel } from "./BassModel.js";
+import { StrategyPane } from "./StrategyPane.js";
+import { StrategyRows } from "./StrategyRows.js";
+import { StrategySamples } from "./StrategySamples.js";
+import { StrategyWords } from "./StrategyWords.js";
+import { area, line, max, scaleLinear, sum } from "d3";
+// src/charts/strategycharts/BassDiffusionChart.ts
+/** The bell of new adopters over the S-curve of cumulative adopters, or either alone. */
+var BassDiffusionView = /* @__PURE__ */ function(BassDiffusionView) {
+	BassDiffusionView["Both"] = "both";
+	BassDiffusionView["Adopters"] = "adopters";
+	BassDiffusionView["Cumulative"] = "cumulative";
+	return BassDiffusionView;
+}({});
+var OBSERVED = "Observed";
+var MODEL = "Bass model";
+var SOURCES = ["Innovators", "Imitators"];
+var TITLES = {
+	["adopters"]: "New adopters per period",
+	["cumulative"]: "Cumulative adopters"
+};
+var LIMIT = 60;
+var NEARLY = .985;
+var PANE_GAP = 20;
+var SIZE = 10.5;
+var figure = (value) => value.toLocaleString("en", { maximumFractionDigits: Math.abs(value) < 100 ? 1 : 0 });
+/**
+* The Bass diffusion curve of a new product: new adopters per period rise to a peak and fall away, and cumulative
+* adopters follow an S-curve up to the market potential. The model is fitted to the observed periods and carried on
+* as a dashed projection. Use it to see where a product sits on its curve and how much comes from imitation.
+*/
+var BassDiffusionChart = class extends CartesianChart {
+	static meta = {
+		id: "bass-diffusion",
+		name: "Bass diffusion curve",
+		family: ChartFamily.Trend,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Fits the Bass model to observed adoptions and draws new adopters per period and the cumulative S-curve, dashed where they run past the data.",
+		tags: [
+			"diffusion of innovations",
+			"adoption",
+			"s-curve",
+			"forecast",
+			"innovation",
+			"imitation",
+			"marketing"
+		],
+		sample: (seed) => StrategySamples.bass(seed),
+		variants: {
+			view: [
+				"both",
+				"adopters",
+				"cumulative"
+			],
+			split: [false, true],
+			peak: [false, true]
+		}
+	};
+	#x = null;
+	#ticks = 6;
+	defaults() {
+		return {
+			period: "period",
+			adopters: "adopters",
+			view: "both",
+			split: false,
+			peak: false
+		};
+	}
+	yTicks() {
+		return this.options.yTicks ?? this.#ticks;
+	}
+	/** The panes have a scale each, so with both drawn only the periods can zoom. */
+	zoomAxes() {
+		return this.options.view === "both" ? ZoomAxis.X : ZoomAxis.XY;
+	}
+	#rows() {
+		const { period, adopters } = this.options;
+		return StrategyRows.of(this.options.data).flatMap((row) => {
+			const seen = StrategyRows.number(row[adopters]);
+			return seen === null ? [] : [{
+				period: row[period],
+				adopters: Math.max(0, seen)
+			}];
+		});
+	}
+	/** The coefficients in use, and the model run from the first period until nearly the whole market has adopted. */
+	get model() {
+		const { innovation, imitation, market } = this.options, observed = this.#rows().map((row) => row.adopters);
+		const given = (value, most = Infinity) => value !== void 0 && Number.isFinite(value) && value > 0 && value <= most ? value : void 0;
+		const fit = BassModel.fit(observed), total = sum(observed);
+		const p = given(innovation, 1) ?? fit?.p ?? .03, q = given(imitation) ?? fit?.q ?? .38;
+		const m = given(market) ?? fit?.m ?? (total > 0 ? BassModel.market(p, q, total, observed.length) : 100);
+		const coefficients = {
+			p,
+			q,
+			m
+		}, done = BassModel.run(coefficients, LIMIT).findIndex((period) => period.cumulative >= NEARLY * m);
+		const count = Math.max(observed.length + 2, Math.min(LIMIT, Math.max(6, done < 0 ? LIMIT : done + 2)));
+		return {
+			coefficients,
+			fitted: !!fit && [
+				innovation,
+				imitation,
+				market
+			].every((value) => given(value) === void 0),
+			observed,
+			periods: BassModel.run(coefficients, count)
+		};
+	}
+	/** Names period `t`, counted from 1: the observed names, carried on where they are evenly spaced numbers and as +1, +2 where they are not. */
+	#namer() {
+		const cells = this.#rows().map((row) => row.period), numbers = cells.map((cell) => StrategyRows.number(cell)), step = cells.length > 1 ? numbers[1] - numbers[0] : 1;
+		if (!cells.length) return (t) => `${t}`;
+		if (step && numbers.every((value, i) => value !== null && Math.abs(value - (numbers[0] + i * step)) < 1e-9)) return (t) => `${+(numbers[0] + (t - 1) * step).toFixed(6)}`;
+		return (t) => t <= cells.length ? FrameworkText.clean(cells[t - 1]) || `${t}` : `+${t - cells.length}`;
+	}
+	tickFormat(scale) {
+		if (scale !== this.#x) return super.tickFormat(scale);
+		const name = this.#namer(), last = this.model.periods.length;
+		return (value) => Number.isInteger(+value) && +value >= 1 && +value <= last ? FrameworkText.fit(name(+value), 64, 11) : "";
+	}
+	#panes(height, { coefficients, observed, periods }) {
+		const { view, peak } = this.options;
+		const kinds = view === "both" ? ["adopters", "cumulative"] : [view === "cumulative" ? "cumulative" : "adopters"];
+		const upper = kinds.length > 1 ? Math.round((height - PANE_GAP) * .54) : height;
+		return kinds.map((kind, i) => {
+			const top = i ? upper + PANE_GAP : 0, bottom = i ? height : upper, bell = kind === "adopters";
+			const head = bell ? peak ? 36 : 18 : i ? 18 : 32;
+			const high = bell ? max([...periods.map((period) => period.adopters), ...observed]) : Math.max(coefficients.m, sum(observed));
+			const scale = scaleLinear([0, high || 1], [bottom, Math.min(bottom - 1, top + head)]);
+			return {
+				kind,
+				first: !i,
+				top,
+				bottom,
+				scale: bell ? scale.nice(4) : scale
+			};
+		});
+	}
+	scales(ctx) {
+		const fit = this.model;
+		this.#x = scaleLinear([.5, fit.periods.length + .5], [0, ctx.plot.width]);
+		const [first] = this.#panes(ctx.plot.height, fit);
+		const [low, high] = first.scale.range();
+		this.#ticks = Math.max(2, Math.min(6, Math.floor((low - high) / 24)));
+		return {
+			x: this.#x,
+			y: first.scale
+		};
+	}
+	plotMarks(ctx, { x, y }) {
+		const { split, peak } = this.options, { palette, theme, plot } = ctx;
+		const fit = this.model, { observed, periods, coefficients } = fit, name = this.#namer(), seen = observed.length;
+		const colors = {
+			observed: seen ? palette.color(OBSERVED) : theme.inkMuted,
+			model: palette.color(MODEL),
+			sources: split ? SOURCES.map((source) => palette.color(source)) : []
+		};
+		const panes = this.#panes(plot.height, fit).map((pane) => pane.first ? {
+			...pane,
+			scale: y
+		} : pane);
+		const top = BassModel.peak(periods);
+		const columns = ctx.marks("periods", "rect", periods, (period) => period.t).attr("fill", "transparent");
+		ctx.set(columns, {
+			x: (period) => x(period.t - .5),
+			y: 0,
+			width: (period) => Math.max(0, x(period.t + .5) - x(period.t - .5)),
+			height: plot.height
+		});
+		ctx.hover(columns, (period) => ({
+			title: name(period.t),
+			color: colors.model,
+			rows: [
+				...period.t <= seen ? [[OBSERVED, figure(observed[period.t - 1])]] : [],
+				["Model adopters", figure(period.adopters)],
+				[SOURCES[0], figure(period.innovators)],
+				[SOURCES[1], figure(period.imitators)],
+				["Cumulative", figure(period.cumulative)],
+				["Share of market", `${figure(period.cumulative / coefficients.m * 100)}%`]
+			]
+		}));
+		const words = [];
+		let innovators = 0, counted = 0;
+		const running = periods.map((period) => {
+			innovators += period.innovators;
+			if (period.t <= seen) counted += observed[period.t - 1];
+			return {
+				innovators,
+				counted
+			};
+		});
+		for (const pane of panes) {
+			const bell = pane.kind === "adopters";
+			const levels = periods.map((period, i) => bell ? {
+				t: period.t,
+				total: period.adopters,
+				innovators: period.innovators,
+				seen: period.t <= seen ? observed[i] : null
+			} : {
+				t: period.t,
+				total: period.cumulative,
+				innovators: running[i].innovators,
+				seen: period.t <= seen ? running[i].counted : null
+			});
+			if (!pane.first) StrategyPane.axis(ctx, pane.kind, pane.scale, Math.max(2, Math.min(4, Math.floor((pane.bottom - pane.top) / 28))), StrategyPane.compact);
+			words.push(...this.#drawPane(ctx, pane, x, levels, colors, fit, top, name));
+		}
+		words.push(...this.#heading(panes[0], fit, plot.width));
+		const rules = ctx.marks("peak-rule", "line", peak && top ? panes : [], (pane) => pane.kind).attr("stroke", theme.axis).attr("stroke-width", 1);
+		ctx.set(rules, {
+			x1: x(top?.t ?? 0),
+			x2: x(top?.t ?? 0),
+			y1: (pane) => pane.scale.range()[1] - 6,
+			y2: (pane) => pane.bottom
+		});
+		StrategyWords.draw(ctx, "words", words);
+	}
+	/** The pane's title at the left and, on the first pane, the coefficients at the right where they fit beside it. */
+	#heading(pane, { coefficients: { p, q, m }, fitted, observed }, width) {
+		const figures = `p ${p.toFixed(3)}, q ${q.toFixed(3)}, m ${StrategyPane.compact(m)}`, whole = fitted ? `Fitted to ${observed.length} periods: ${figures}` : figures;
+		const room = width - FrameworkText.width(TITLES[pane.kind], SIZE) - 24, text = [whole, figures].find((option) => FrameworkText.width(option, SIZE) <= room);
+		return text ? [{
+			key: "coefficients",
+			text,
+			x: width - 2,
+			y: pane.top + 7,
+			anchor: "end",
+			size: SIZE,
+			halo: true
+		}] : [];
+	}
+	#drawPane(ctx, pane, x, levels, colors, { observed, coefficients }, top, name) {
+		const { peak } = this.options, { theme, plot } = ctx, { kind, scale } = pane, bell = kind === "adopters";
+		const seen = observed.length, ahead = seen > 0 && seen < levels.length;
+		const spans = ahead ? [{
+			key: "fit",
+			from: 1,
+			to: seen,
+			faded: false
+		}, {
+			key: "ahead",
+			from: seen,
+			to: levels.length,
+			faded: true
+		}] : [{
+			key: "fit",
+			from: 1,
+			to: levels.length,
+			faded: false
+		}];
+		const within = (span) => levels.filter((level) => level.t >= span.from && level.t <= span.to);
+		const curve = Scales.curve(CurveKind.Monotone);
+		const market = bell ? [] : [coefficients.m];
+		const ceiling = ctx.marks(`axis-${kind}-market`, "line", market).attr("stroke", theme.axis).attr("stroke-dasharray", "4 3");
+		ctx.set(ceiling, {
+			x1: 0,
+			x2: plot.width,
+			y1: (level) => scale(level),
+			y2: (level) => scale(level)
+		});
+		const layers = colors.sources.length ? spans.flatMap((span) => [0, 1].map((source) => ({
+			key: `${SOURCES[source]}/${span.key}`,
+			source,
+			faded: span.faded,
+			levels: within(span)
+		}))) : [];
+		const stack = area().x((level) => x(level.t)).curve(curve);
+		const fills = ctx.marks(`${kind}-sources`, "path", layers.filter((layer) => layer.levels.length > 1), (layer) => layer.key).attr("fill", (layer) => colors.sources[layer.source]).attr("fill-opacity", (layer) => layer.faded ? .28 : .72);
+		ctx.set(fills, { d: (layer) => stack.y0((level) => scale(layer.source ? level.innovators : 0)).y1((level) => scale(layer.source ? level.total : level.innovators))(layer.levels) ?? "" });
+		const whole = levels.at(-1);
+		ctx.hover(fills, (layer) => ({
+			title: SOURCES[layer.source],
+			color: colors.sources[layer.source],
+			rows: [["Span", layer.faded ? "Projected" : ahead ? "Fitted to the observed periods" : "Model"], ...whole && !bell ? [["Share of all adopters", `${figure((layer.source ? whole.total - whole.innovators : whole.innovators) / (whole.total || 1) * 100)}%`]] : []]
+		}));
+		const path = line().x((level) => x(level.t)).y((level) => scale(level.total)).curve(curve);
+		const drawn = ctx.marks(`${kind}-model`, "path", spans.filter((span) => !span.faded).map(within).filter((span) => span.length > 1)).attr("fill", "none").attr("stroke", colors.model).attr("stroke-width", 2).attr("stroke-linecap", "round");
+		ctx.set(drawn, { d: (span) => path(span) ?? "" });
+		ctx.drawOn(drawn);
+		const projected = ctx.marks(`${kind}-projection`, "path", spans.filter((span) => span.faded).map(within).filter((span) => span.length > 1)).attr("fill", "none").attr("stroke", colors.model).attr("stroke-width", 2).attr("stroke-dasharray", "6 4");
+		ctx.set(projected, { d: (span) => path(span) ?? "" });
+		const dots = ctx.marks(`${kind}-observed`, "circle", levels.filter((level) => level.seen !== null), (level) => level.t).attr("fill", colors.observed).attr("stroke", theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (level) => x(level.t),
+			cy: (level) => scale(level.seen),
+			r: 4
+		}, { r: 0 }, 12);
+		ctx.hover(dots, (level) => ({
+			title: name(level.t),
+			color: colors.observed,
+			rows: [[OBSERVED, figure(level.seen)], ["Model", figure(level.total)]]
+		}));
+		const crest = peak && top ? levels.filter((level) => level.t === top.t) : [];
+		const turn = ctx.marks(`${kind}-peak`, "circle", crest, (level) => level.t).attr("fill", colors.model).attr("stroke", theme.surface).attr("stroke-width", 2);
+		ctx.set(turn, {
+			cx: (level) => x(level.t),
+			cy: (level) => scale(level.total),
+			r: 5
+		}, { r: 0 });
+		ctx.hover(turn, (level) => ({
+			title: `Peak in ${name(level.t)}`,
+			color: colors.model,
+			rows: [["New adopters", figure(top.adopters)], ["Adopted by then", figure(top.cumulative)]]
+		}));
+		const words = [{
+			key: `title/${kind}`,
+			text: FrameworkText.fit(TITLES[kind], plot.width - 4, SIZE),
+			x: 2,
+			y: pane.top + 7,
+			size: SIZE,
+			weight: 600,
+			tone: "ink",
+			halo: true
+		}];
+		if (!bell) {
+			const text = `Market potential ${StrategyPane.compact(coefficients.m)}`;
+			if (FrameworkText.width(text, SIZE) + FrameworkText.width(TITLES[kind], SIZE) + 24 <= plot.width || pane.first) words.push({
+				key: `market/${kind}`,
+				text: FrameworkText.fit(text, plot.width - 4, SIZE),
+				x: plot.width - 2,
+				y: scale(coefficients.m) - 8,
+				anchor: "end",
+				size: SIZE,
+				halo: true
+			});
+		}
+		for (const level of crest) {
+			const text = `Peak ${name(level.t)}`, at = x(level.t), half = FrameworkText.width(text, SIZE) / 2;
+			if (bell) words.push({
+				key: `peak/${kind}`,
+				text,
+				x: StrategyRows.clamp(at, half, Math.max(half, plot.width - half)),
+				y: scale.range()[1] - 13,
+				anchor: "middle",
+				size: SIZE,
+				weight: 600,
+				tone: "ink",
+				halo: true
+			});
+			else if (pane.first && at + 10 + half * 2 <= plot.width) words.push({
+				key: `peak/${kind}`,
+				text,
+				x: at + 10,
+				y: scale(level.total) + 9,
+				size: SIZE,
+				weight: 600,
+				tone: "ink",
+				halo: true
+			});
+		}
+		return words;
+	}
+};
+export { BassDiffusionChart, BassDiffusionView };

package/dist/charts/strategycharts/BassModel.js

@@ -0,0 +1,96 @@
+// src/charts/strategycharts/BassModel.ts
+var LEAST = 3;
+var positive = (value) => Number.isFinite(value) && value > 0;
+/**
+* The Bass diffusion model (Bass, 1969) in discrete time: each period's adopters are (p + q N / m)(m - N), where N
+* have adopted already. The p part adopts unprompted and the q part follows those who went before.
+*/
+var BassModel = class BassModel {
+	/** Periods 1 to `count` of the model. */
+	static run({ p, q, m }, count) {
+		const periods = [];
+		let adopted = 0;
+		for (let t = 1; t <= count; t++) {
+			const left = Math.max(0, m - adopted), innovators = Math.min(left, p * left), imitators = Math.min(left - innovators, m > 0 ? q * (adopted / m) * left : 0);
+			adopted += innovators + imitators;
+			periods.push({
+				t,
+				innovators,
+				imitators,
+				adopters: innovators + imitators,
+				cumulative: adopted
+			});
+		}
+		return periods;
+	}
+	/**
+	* Bass's own estimate: least squares of each period's adopters on the total adopted before it and that total squared,
+	* solved for p, q and m. Null with fewer than three periods, or when the fit is not a diffusion: no positive
+	* coefficients, or a market smaller than what has already adopted.
+	*/
+	static fit(adopters) {
+		if (adopters.length < LEAST) return null;
+		const total = adopters.reduce((sum, value) => sum + value, 0);
+		if (!positive(total)) return null;
+		let before = 0;
+		const rows = adopters.map((value) => {
+			const x = before / total;
+			before += value;
+			return [
+				1,
+				x,
+				x * x,
+				value
+			];
+		});
+		const normal = [
+			0,
+			1,
+			2
+		].map((i) => [...[
+			0,
+			1,
+			2
+		].map((j) => rows.reduce((sum, row) => sum + row[i] * row[j], 0)), rows.reduce((sum, row) => sum + row[i] * row[3], 0)]);
+		const solved = BassModel.#solve(normal);
+		if (!solved) return null;
+		const a = solved[0], b = solved[1] / total, c = solved[2] / (total * total), root = b * b - 4 * a * c;
+		if (!(solved[2] < -1e-6 * Math.abs(a)) || !(a > 0) || root < 0) return null;
+		const m = (-b - Math.sqrt(root)) / (2 * c), p = a / m, q = -c * m;
+		return positive(m) && positive(p) && positive(q) && p < 1 && m >= total ? {
+			p,
+			q,
+			m
+		} : null;
+	}
+	/** Gaussian elimination with partial pivoting on an augmented matrix. Null when the rows are not independent. */
+	static #solve(matrix) {
+		const size = matrix.length;
+		for (let column = 0; column < size; column++) {
+			let pivot = column;
+			for (let row = column + 1; row < size; row++) if (Math.abs(matrix[row][column]) > Math.abs(matrix[pivot][column])) pivot = row;
+			if (Math.abs(matrix[pivot][column]) < 1e-12) return null;
+			[matrix[column], matrix[pivot]] = [matrix[pivot], matrix[column]];
+			for (let row = 0; row < size; row++) {
+				if (row === column) continue;
+				const factor = matrix[row][column] / matrix[column][column];
+				for (let k = column; k <= size; k++) matrix[row][k] -= factor * matrix[column][k];
+			}
+		}
+		return matrix.map((row, i) => row[size] / row[i]);
+	}
+	/** The market that makes the model with `p` and `q` reach `total` adopters by the end of period `count`. */
+	static market(p, q, total, count) {
+		const share = BassModel.run({
+			p,
+			q,
+			m: 1
+		}, count).at(-1)?.cumulative ?? 0;
+		return share > 0 ? total / share : total;
+	}
+	/** The period in which the model's new adopters peak, or null when it has no periods. */
+	static peak(periods) {
+		return periods.reduce((best, period) => best && best.adopters >= period.adopters ? best : period, null);
+	}
+};
+export { BassModel };