@mstone6969/graph 0.1.0 → 0.2.0

package/dist/charts/frameworks/PerceptualMap.js

@@ -0,0 +1,419 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { PerceptualMethod, PerceptualProjection } from "./PerceptualProjection.js";
+import { PositioningSamples } from "./PositioningSamples.js";
+import { max, min, scaleSqrt, symbol, symbolDiamond } from "d3";
+// src/charts/frameworks/PerceptualMap.ts
+var POLE_ROW = 16;
+var PLAIN_RADIUS = 6;
+var MIN_RADIUS = 4;
+var CHAR = 6.2;
+var GUTTER = 6;
+var IDEAL_AREA = 110;
+var clip = (text, room) => {
+	const fit = Math.max(1, Math.floor(room / CHAR));
+	return text.length <= fit ? text : `${text.slice(0, Math.max(1, fit - 1))}…`;
+};
+var spotBox = ({ x, y, anchor }, width) => {
+	const x0 = anchor === "start" ? x : anchor === "end" ? x - width : x - width / 2;
+	return {
+		x0,
+		y0: y - 7,
+		x1: x0 + width,
+		y1: y + 7
+	};
+};
+var hits = (a, b) => a.x0 < b.x1 && b.x0 < a.x1 && a.y0 < b.y1 && b.y0 < a.y1;
+/**
+* Shows where brands sit in customers' minds. Two attribute axes cross at the midpoint, with bubble area for share,
+* ideal rows as projected demand points, and attribute vectors. The direct map reads two rated attributes and fits the others
+* by regression (property fitting: Carroll and Chang's PROFIT). The biplots follow Gabriel (1971) on standardised ratings and keep
+* one unit on both axes: the form biplot favours distances between brands, the covariance biplot angles between attributes.
+*/
+var PerceptualMap = class extends Chart2D {
+	static meta = {
+		id: "perceptual-map",
+		name: "Perceptual map",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Positions brands on two attribute axes to reveal competitors, gaps and the distance to what customers want.",
+		tags: [
+			"positioning",
+			"brand map",
+			"biplot",
+			"marketing",
+			"ideal point"
+		],
+		sample: (seed) => PositioningSamples.perceptions(seed),
+		variants: {
+			method: [
+				PerceptualMethod.Direct,
+				PerceptualMethod.FormBiplot,
+				PerceptualMethod.CovarianceBiplot
+			],
+			sized: [true, false],
+			ideal: [false, true],
+			vectors: [false, true]
+		}
+	};
+	#dropped = false;
+	defaults() {
+		return {
+			name: "brand",
+			x: "Price",
+			y: "Quality",
+			size: "share",
+			role: "role",
+			method: PerceptualMethod.Direct,
+			sized: true,
+			ideal: false,
+			vectors: false
+		};
+	}
+	plotMargin() {
+		return {
+			top: 6,
+			right: 12,
+			bottom: 6,
+			left: 12
+		};
+	}
+	/** Labels name each brand, so the legend returns only when one had no room. */
+	legendItems() {
+		return this.#dropped ? super.legendItems() : [];
+	}
+	get #solution() {
+		const { data, name, x, y, size, role, attributes, method } = this.options;
+		return PerceptualProjection.solve(Array.isArray(data) ? data : [], {
+			name,
+			x,
+			y,
+			size,
+			role,
+			...attributes ? { attributes } : {}
+		}, method);
+	}
+	#direct(values, domain) {
+		const low = min(values) ?? 0, high = max(values) ?? 0;
+		const centre = domain ? (domain[0] + domain[1]) / 2 : (low + high) / 2;
+		return {
+			centre,
+			reach: Math.max(high - centre, centre - low, domain ? Math.abs(domain[1] - domain[0]) / 2 : 0) || 1
+		};
+	}
+	#frame(width, height, inset, places) {
+		const midX = width / 2, midY = height / 2, halfX = midX - inset, halfY = midY - inset - POLE_ROW;
+		if (this.options.method !== PerceptualMethod.Direct) {
+			const unit = Math.min(halfX / (max(places, (p) => Math.abs(p.x)) || 1), halfY / (max(places, (p) => Math.abs(p.y)) || 1));
+			return {
+				px: (x) => midX + x * unit,
+				py: (y) => midY - y * unit,
+				unitX: unit,
+				unitY: unit
+			};
+		}
+		const across = this.#direct(places.map((p) => p.x), this.options.xDomain), up = this.#direct(places.map((p) => p.y), this.options.yDomain);
+		const unitX = halfX / across.reach, unitY = halfY / up.reach;
+		return {
+			px: (x) => midX + (x - across.centre) * unitX,
+			py: (y) => midY - (y - up.centre) * unitY,
+			unitX,
+			unitY
+		};
+	}
+	#radius(solution, width, height) {
+		if (!this.options.sized) return () => PLAIN_RADIUS;
+		const top = max(solution.brands, (place) => place.size ?? 0) ?? 0;
+		if (top <= 0) return () => PLAIN_RADIUS;
+		const area = scaleSqrt().domain([0, top]).range([0, Math.max(12, Math.min(26, Math.min(width, height) * .08))]);
+		return (place) => Math.max(MIN_RADIUS, area(Math.max(0, place.size ?? 0)));
+	}
+	#poles(solution, width, height) {
+		const { method, x, y, xPoles, yPoles } = this.options;
+		const dimension = (axis) => solution.explained ? `Dim ${axis + 1} (${Math.round(solution.explained[axis] * 100)}%)` : "";
+		const [left, right] = xPoles ?? (method === PerceptualMethod.Direct ? [`Low ${x}`, `High ${x}`] : ["", dimension(0)]);
+		const [bottom, top] = yPoles ?? (method === PerceptualMethod.Direct ? [`Low ${y}`, `High ${y}`] : ["", dimension(1)]);
+		const across = width / 2 - GUTTER, up = width - 12;
+		return [
+			{
+				key: "left",
+				text: clip(left, across),
+				x: 0,
+				y: height / 2 - 9,
+				anchor: "start"
+			},
+			{
+				key: "right",
+				text: clip(right, across),
+				x: width,
+				y: height / 2 - 9,
+				anchor: "end"
+			},
+			{
+				key: "top",
+				text: clip(top, up),
+				x: width / 2,
+				y: 8,
+				anchor: "middle"
+			},
+			{
+				key: "bottom",
+				text: clip(bottom, up),
+				x: width / 2,
+				y: height - 7,
+				anchor: "middle"
+			}
+		].filter((pole) => pole.text);
+	}
+	/** Attribute vectors in pixels. Screen direction stays normal to the fitted contours even when the two axes have different units. */
+	#tips(arrows, frame, reach) {
+		const direct = this.options.method === PerceptualMethod.Direct;
+		const raw = arrows.map((arrow) => direct ? {
+			arrow,
+			x: arrow.x / frame.unitX,
+			y: -arrow.y / frame.unitY
+		} : {
+			arrow,
+			x: arrow.x * frame.unitX,
+			y: -arrow.y * frame.unitY
+		});
+		const longest = max(raw, (tip) => Math.hypot(tip.x, tip.y)) || 1;
+		return raw.map((tip) => {
+			const scale = direct ? reach * tip.arrow.strength / (Math.hypot(tip.x, tip.y) || 1) : reach / longest;
+			return {
+				arrow: tip.arrow,
+				x: tip.x * scale,
+				y: tip.y * scale
+			};
+		});
+	}
+	draw(ctx) {
+		const { width, height } = ctx.plot;
+		const { ideal, vectors, size, sized } = this.options;
+		const solution = this.#solution;
+		const shownIdeals = ideal ? solution.ideals : [];
+		const radius = this.#radius(solution, width, height);
+		const largest = max(solution.brands, radius) ?? PLAIN_RADIUS;
+		const frame = this.#frame(width, height, largest + 6, [...solution.brands, ...shownIdeals]);
+		const originX = width / 2, originY = height / 2;
+		const blocked = solution.brands.map((place) => {
+			const r = radius(place), x = frame.px(place.x), y = frame.py(place.y);
+			return {
+				x0: x - r,
+				y0: y - r,
+				x1: x + r,
+				y1: y + r
+			};
+		});
+		const poles = this.#poles(solution, width, height).map((pole) => {
+			if (pole.key !== "left" && pole.key !== "right") return pole;
+			const box = spotBox(pole, pole.text.length * CHAR);
+			return blocked.some((mark) => hits(box, mark)) ? {
+				...pole,
+				y: height / 2 + 11
+			} : pole;
+		});
+		blocked.push(...poles.map((pole) => spotBox(pole, pole.text.length * CHAR)));
+		const area = sized && solution.brands.some((place) => place.size !== null) ? `Area = ${size}` : "";
+		this.#drawAxes(ctx, originX, originY);
+		const tips = vectors ? this.#tips(solution.arrows, frame, Math.min(width / 2, height / 2 - POLE_ROW) * .78) : [];
+		this.#drawVectors(ctx, tips, originX, originY);
+		this.#drawBrands(ctx, solution.brands, frame, radius);
+		this.#drawIdeals(ctx, shownIdeals, frame);
+		const labels = [...this.#placeAll(shownIdeals.map((place) => ({
+			key: `ideal/${place.name}`,
+			text: place.name,
+			tone: "ink",
+			weight: 600,
+			spots: this.#around(frame.px(place.x), frame.py(place.y), 8)
+		})), width, height, blocked), ...this.#placeAll(tips.map((tip) => ({
+			key: `vector/${tip.arrow.name}`,
+			text: tip.arrow.name,
+			tone: "secondary",
+			weight: 600,
+			spots: this.#beyond(originX + tip.x, originY + tip.y, tip)
+		})), width, height, blocked)];
+		const brands = [...solution.brands].sort((a, b) => radius(b) - radius(a));
+		const placed = this.#placeAll(brands.map((place, i) => ({
+			key: `brand/${place.name}/${i}`,
+			text: place.name,
+			tone: "ink",
+			weight: 400,
+			spots: this.#around(frame.px(place.x), frame.py(place.y), radius(place))
+		})), width, height, blocked);
+		this.#dropped = placed.length < brands.length;
+		this.#drawPoles(ctx, poles);
+		this.#drawLabels(ctx, [...labels, ...placed]);
+		this.#drawAreaNote(ctx, area, width, height, blocked);
+	}
+	#around(x, y, r) {
+		return [
+			{
+				x: x + r + 4,
+				y,
+				anchor: "start"
+			},
+			{
+				x: x - r - 4,
+				y,
+				anchor: "end"
+			},
+			{
+				x,
+				y: y - r - 9,
+				anchor: "middle"
+			},
+			{
+				x,
+				y: y + r + 9,
+				anchor: "middle"
+			}
+		];
+	}
+	#beyond(x, y, tip) {
+		const anchor = tip.x >= 0 ? "start" : "end", side = tip.x >= 0 ? 6 : -6, lift = tip.y >= 0 ? 9 : -9;
+		return [
+			{
+				x: x + side,
+				y: y + lift / 3,
+				anchor
+			},
+			{
+				x,
+				y: y + lift,
+				anchor: "middle"
+			},
+			{
+				x: x - side,
+				y: y + lift,
+				anchor: tip.x >= 0 ? "end" : "start"
+			}
+		];
+	}
+	/** First free spot for each label in turn. Labels with no room are dropped, and stay readable in the tooltip. */
+	#placeAll(items, width, height, blocked) {
+		return items.flatMap(({ spots, ...item }) => {
+			const text = clip(item.text, Math.max(48, width * .34)), room = text.length * CHAR;
+			const spot = spots.find((candidate) => {
+				const box = spotBox(candidate, room);
+				return box.x0 >= 0 && box.x1 <= width && box.y0 >= 0 && box.y1 <= height && !blocked.some((mark) => hits(box, mark));
+			});
+			if (!spot) return [];
+			blocked.push(spotBox(spot, room));
+			return [{
+				...item,
+				...spot,
+				text
+			}];
+		});
+	}
+	#drawAxes(ctx, x, y) {
+		const { width, height } = ctx.plot;
+		const spans = [{
+			key: "x",
+			x1: 0,
+			y1: y,
+			x2: width,
+			y2: y
+		}, {
+			key: "y",
+			x1: x,
+			y1: POLE_ROW,
+			x2: x,
+			y2: height - POLE_ROW
+		}];
+		const lines = ctx.marks("axes", "line", spans, (d) => d.key).attr("stroke", ctx.theme.axis).attr("stroke-width", 1);
+		const place = {
+			x1: (d) => d.x1,
+			y1: (d) => d.y1,
+			x2: (d) => d.x2,
+			y2: (d) => d.y2
+		};
+		ctx.set(lines, place, place);
+	}
+	/** Above the marks with a halo, since a brand may sit at the end of an axis on both sides of it. */
+	#drawPoles(ctx, poles) {
+		const texts = ctx.text(ctx.marks("poles", "text", poles, (d) => d.key).attr("text-anchor", (d) => d.anchor).attr("dy", "0.32em").attr("font-weight", 600).text((d) => d.text)).attr("stroke", ctx.theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").attr("stroke-linejoin", "round");
+		ctx.set(texts, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		}, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		});
+	}
+	#drawVectors(ctx, tips, x, y) {
+		const path = ({ x: dx, y: dy }, scale) => {
+			const tx = x + dx * scale, ty = y + dy * scale, angle = Math.atan2(dy, dx), head = 7 * scale;
+			const wing = (turn) => `${tx - head * Math.cos(angle + turn)},${ty - head * Math.sin(angle + turn)}`;
+			return `M${x},${y}L${tx},${ty}M${wing(.45)}L${tx},${ty}L${wing(-.45)}`;
+		};
+		const lines = ctx.marks("vectors", "path", tips, (tip) => tip.arrow.name).attr("fill", "none").attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 2).attr("stroke-linecap", "round").attr("stroke-linejoin", "round");
+		ctx.set(lines, { d: (tip) => path(tip, 1) }, { d: (tip) => path(tip, 0) });
+		ctx.hover(lines, ({ arrow }) => ({
+			title: arrow.name,
+			rows: [["Fit with map (R)", +arrow.strength.toFixed(2)]]
+		}));
+	}
+	#drawBrands(ctx, brands, frame, radius) {
+		const { x, y, size, method } = this.options;
+		const direct = method === PerceptualMethod.Direct;
+		const ordered = [...brands].sort((a, b) => radius(b) - radius(a));
+		const dots = ctx.marks("brands", "circle", ordered, (d, i) => `${d.name}/${i}`).attr("fill", (d) => ctx.palette.color(d.name)).attr("fill-opacity", .9).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (d) => frame.px(d.x),
+			cy: (d) => frame.py(d.y),
+			r: radius
+		}, { r: 0 }, 30);
+		ctx.hover(dots, (d) => ({
+			title: d.name,
+			color: ctx.palette.color(d.name),
+			rows: [
+				[direct ? x : "Dim 1", +d.x.toFixed(2)],
+				[direct ? y : "Dim 2", +d.y.toFixed(2)],
+				...d.size === null ? [] : [[size, d.size]]
+			]
+		}));
+	}
+	#drawIdeals(ctx, ideals, frame) {
+		const diamond = symbol(symbolDiamond, IDEAL_AREA)();
+		const marks = ctx.marks("ideals", "path", ideals, (d, i) => `${d.name}/${i}`).attr("fill", ctx.theme.ink).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		const at = (d) => `translate(${frame.px(d.x)},${frame.py(d.y)})`;
+		ctx.set(marks, {
+			d: diamond,
+			transform: at
+		}, { transform: at });
+		ctx.hover(marks, (d) => ({
+			title: d.name,
+			rows: [["Map x", +d.x.toFixed(2)], ["Map y", +d.y.toFixed(2)]]
+		}));
+	}
+	#drawLabels(ctx, labels) {
+		const texts = ctx.marks("labels", "text", labels, (d) => d.key).attr("text-anchor", (d) => d.anchor).attr("dy", "0.32em").attr("font-size", 11).attr("font-family", ctx.theme.fontFamily).attr("font-weight", (d) => d.weight).attr("fill", (d) => d.tone === "ink" ? ctx.theme.ink : ctx.theme.inkSecondary).attr("stroke", ctx.theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").attr("stroke-linejoin", "round").text((d) => d.text);
+		ctx.set(texts, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		}, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		});
+	}
+	#drawAreaNote(ctx, text, width, height, blocked) {
+		const spot = {
+			x: width,
+			y: height - 7,
+			anchor: "end"
+		};
+		const free = text && !blocked.some((mark) => hits(spotBox(spot, text.length * CHAR), mark));
+		const notes = ctx.text(ctx.marks("area-note", "text", free ? [text] : [], (d) => d).attr("text-anchor", "end").attr("dy", "0.32em").text((d) => d), 10.5, "muted");
+		ctx.set(notes, {
+			x: spot.x,
+			y: spot.y
+		}, {
+			x: spot.x,
+			y: spot.y
+		});
+	}
+};
+export { PerceptualMap };

package/dist/charts/frameworks/PerceptualProjection.js

@@ -0,0 +1,142 @@
+import { MultivariateMath } from "../multivariate/MultivariateMath.js";
+import { deviation, mean, sum } from "d3";
+// src/charts/frameworks/PerceptualProjection.ts
+var PerceptualMethod = /* @__PURE__ */ function(PerceptualMethod) {
+	PerceptualMethod["Direct"] = "direct";
+	PerceptualMethod["FormBiplot"] = "form-biplot";
+	PerceptualMethod["CovarianceBiplot"] = "covariance-biplot";
+	return PerceptualMethod;
+}({});
+var PerceptualRole = /* @__PURE__ */ function(PerceptualRole) {
+	PerceptualRole["Brand"] = "brand";
+	PerceptualRole["Ideal"] = "ideal";
+	return PerceptualRole;
+}({});
+var MIN_FIT_ROWS = 4;
+var number = (value) => {
+	if (typeof value === "number") return Number.isFinite(value) ? value : NaN;
+	return typeof value === "string" && value.trim() ? Number(value) : NaN;
+};
+/** Turns brand rows into map coordinates: raw attribute pairs, or a two-dimensional biplot of standardised ratings. */
+var PerceptualProjection = class {
+	/** Places every row, keeping ideal rows out of the fit so that they are supplementary points. */
+	static solve(rows, columns, method) {
+		const clean = rows.filter((row) => row !== null && typeof row === "object");
+		const isIdeal = (row) => String(row[columns.role] ?? "").trim().toLowerCase() === "ideal";
+		const brands = clean.filter((row) => !isIdeal(row)), ideals = clean.filter(isIdeal);
+		return method === "direct" ? this.#direct(brands, ideals, columns) : this.#biplot(brands, ideals, columns, method);
+	}
+	/** Least-squares fit of `value` on map position, the property fitting of PROFIT (Carroll and Chang). Null when underdetermined. */
+	static fit(xs, ys, values) {
+		const kept = values.flatMap((value, i) => Number.isFinite(value) ? [i] : []);
+		if (kept.length < MIN_FIT_ROWS) return null;
+		const mx = mean(kept, (i) => xs[i]), my = mean(kept, (i) => ys[i]), mv = mean(kept, (i) => values[i]);
+		const cross = (a, b) => sum(kept, (i) => a(i) * b(i));
+		const dx = (i) => xs[i] - mx, dy = (i) => ys[i] - my, dv = (i) => values[i] - mv;
+		const xx = cross(dx, dx), yy = cross(dy, dy), xy = cross(dx, dy), xv = cross(dx, dv), yv = cross(dy, dv), vv = cross(dv, dv);
+		const determinant = xx * yy - xy * xy;
+		if (!vv || determinant <= 1e-12 * xx * yy) return null;
+		const x = (yy * xv - xy * yv) / determinant, y = (xx * yv - xy * xv) / determinant;
+		return {
+			x,
+			y,
+			strength: Math.sqrt(Math.max(0, Math.min(1, (x * xv + y * yv) / vv)))
+		};
+	}
+	static #place(row, x, y, columns) {
+		const size = number(row[columns.size]);
+		return {
+			name: String(row[columns.name] ?? "Unnamed"),
+			x,
+			y,
+			size: Number.isNaN(size) ? null : size,
+			row
+		};
+	}
+	/** Columns holding at least two distinct numbers across the brands. */
+	static #attributes(brands, columns, skip) {
+		return (columns.attributes ?? [...new Set(brands.flatMap((row) => Object.keys(row)))]).filter((name) => !skip.includes(name) && new Set(brands.map((row) => number(row[name])).filter(Number.isFinite)).size >= 2);
+	}
+	static #direct(brands, ideals, columns) {
+		const at = (row) => this.#place(row, number(row[columns.x]), number(row[columns.y]), columns);
+		const usable = ({ x, y }) => Number.isFinite(x) && Number.isFinite(y);
+		const placed = brands.map(at).filter(usable);
+		const xs = placed.map((place) => place.x), ys = placed.map((place) => place.y);
+		const arrows = this.#attributes(placed.map((place) => place.row), columns, [
+			columns.name,
+			columns.x,
+			columns.y,
+			columns.size,
+			columns.role
+		]).flatMap((name) => {
+			const fitted = this.fit(xs, ys, placed.map((place) => number(place.row[name])));
+			return fitted ? [{
+				name,
+				...fitted
+			}] : [];
+		});
+		return {
+			brands: placed,
+			ideals: ideals.map(at).filter(usable),
+			arrows,
+			explained: null
+		};
+	}
+	/** Gabriel's biplot of the brand-by-attribute table after standardising each attribute, from the correlation matrix. */
+	static #biplot(brands, ideals, columns, method) {
+		const empty = {
+			brands: [],
+			ideals: [],
+			arrows: [],
+			explained: null
+		};
+		const scored = this.#attributes(brands, columns, [
+			columns.name,
+			columns.size,
+			columns.role
+		]);
+		const vector = (row) => scored.map((name) => number(row[name]));
+		const complete = brands.filter((row) => vector(row).every(Number.isFinite));
+		const attributes = this.#attributes(complete, {
+			...columns,
+			attributes: scored
+		}, []);
+		if (complete.length < 2 || attributes.length < 2) return empty;
+		const matrix = complete.map((row) => attributes.map((name) => number(row[name])));
+		const { scores, loadings, eigenvalues, explained } = MultivariateMath.pca(matrix, true);
+		const stats = attributes.map((_, c) => {
+			const column = matrix.map((row) => row[c]);
+			return {
+				centre: mean(column),
+				spread: deviation(column) || 1
+			};
+		});
+		const root = [Math.sqrt(eigenvalues[0]), Math.sqrt(eigenvalues[1] ?? 0)];
+		const covariance = method === "covariance-biplot";
+		const rowScale = (axis) => covariance ? 1 / (root[axis] || 1) : 1;
+		const columnScale = (axis) => covariance ? root[axis] : 1;
+		const place = (row, score) => this.#place(row, score[0] * rowScale(0), (score[1] ?? 0) * rowScale(1), columns);
+		const supplementary = ideals.flatMap((row) => {
+			const values = attributes.map((name) => number(row[name]));
+			if (!values.every(Number.isFinite)) return [];
+			const z = values.map((value, c) => (value - stats[c].centre) / stats[c].spread);
+			return [place(row, loadings.slice(0, 2).map((axis) => sum(axis, (value, c) => value * z[c])))];
+		});
+		const arrows = attributes.map((name, c) => {
+			const a = loadings[0][c], b = loadings[1]?.[c] ?? 0;
+			return {
+				name,
+				x: a * columnScale(0),
+				y: b * columnScale(1),
+				strength: Math.min(1, Math.hypot(a * root[0], b * root[1]))
+			};
+		});
+		return {
+			brands: complete.map((row, i) => place(row, scores[i])),
+			ideals: supplementary,
+			arrows,
+			explained: [explained[0], explained[1] ?? 0]
+		};
+	}
+};
+export { PerceptualMethod, PerceptualProjection, PerceptualRole };