@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/financial/ProjectionCone.js

@@ -0,0 +1,134 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { ConeBands, ConeModel } from "./financeEnums.js";
+import { FinanceInk } from "./FinanceInk.js";
+import { PriceMarks } from "./PriceMarks.js";
+import { Quotes } from "./Quotes.js";
+import { SessionChart } from "./SessionChart.js";
+import { deviation, mean, quantile } from "d3";
+// src/charts/financial/ProjectionCone.ts
+/** Standard-normal quantiles for the band edges used here. */
+var Z = {
+	.05: -1.645,
+	.1: -1.282,
+	.25: -.674,
+	.75: .674,
+	.9: 1.282,
+	.95: 1.645
+};
+var PAIRS = {
+	[ConeBands.Fifty]: [[.25, .75]],
+	[ConeBands.Ninety]: [[.05, .95]],
+	[ConeBands.Graded]: [
+		[.05, .95],
+		[.1, .9],
+		[.25, .75]
+	]
+};
+/** History with a widening range of outcomes: use it to communicate forecast uncertainty honestly. */
+var ProjectionCone = class extends SessionChart {
+	static meta = {
+		id: "projection-cone",
+		name: "Projection cone",
+		family: ChartFamily.Financial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Extends a price forward as nested probability bands that widen with time, showing the range of plausible outcomes.",
+		tags: [
+			"fan chart",
+			"forecast",
+			"scenario",
+			"percentile",
+			"risk"
+		],
+		sample: (seed) => SampleData.ohlc(seed, 90),
+		variants: {
+			model: [
+				ConeModel.Lognormal,
+				ConeModel.Normal,
+				ConeModel.Empirical
+			],
+			bands: [
+				ConeBands.Graded,
+				ConeBands.Fifty,
+				ConeBands.Ninety
+			],
+			horizon: [
+				30,
+				60,
+				90
+			],
+			drift: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			model: ConeModel.Lognormal,
+			bands: ConeBands.Graded,
+			horizon: 30,
+			drift: false
+		};
+	}
+	futureSessions() {
+		return this.options.horizon;
+	}
+	twoTone() {
+		return false;
+	}
+	level(bars, probability, step) {
+		const last = bars.at(-1).close;
+		const returns = bars.slice(1).map((bar, i) => Math.log(Math.abs(bar.close / bars[i].close) || 1));
+		const average = mean(returns) ?? 0, spread = deviation(returns) ?? 0;
+		const drift = this.options.drift ? average * step : 0;
+		const root = Math.sqrt(step);
+		switch (this.options.model) {
+			case ConeModel.Normal: return last * (1 + drift + Z[probability] * spread * root);
+			case ConeModel.Empirical: return last * Math.exp(drift + ((quantile(returns, probability) ?? 0) - average) * root);
+			default: return last * Math.exp(drift + Z[probability] * spread * root);
+		}
+	}
+	/** Aligned with the axis: nulls through history, values from the last close onward. */
+	forward(bars, probability) {
+		const last = bars.length - 1;
+		return Array.from({ length: bars.length + this.options.horizon }, (_, i) => i < last ? null : i === last ? bars[last].close : this.level(bars, probability, i - last));
+	}
+	valueDomain(bars) {
+		const edges = PAIRS[this.options.bands].flat().flatMap((p) => this.forward(bars, p).filter((v) => v !== null));
+		const values = [...bars.map((bar) => bar.close), ...edges];
+		const low = Math.min(...values), high = Math.max(...values);
+		const pad = (high - low || 1) * .05;
+		return [low - pad, high + pad];
+	}
+	plotMarks(ctx, view) {
+		const color = this.tones(ctx).up;
+		const { bars } = view;
+		const pairs = PAIRS[this.options.bands];
+		for (const slot of [
+			0,
+			1,
+			2
+		]) {
+			const pair = bars.length > 1 ? pairs[slot] : void 0;
+			PriceMarks.band(ctx, view, `cone-${slot}`, pair ? this.forward(bars, pair[1]) : [], pair ? this.forward(bars, pair[0]) : [], color, .16);
+		}
+		PriceMarks.line(ctx, view, "median", bars.length > 1 ? this.forward(bars, .75).map((high, i) => high === null ? null : (high + this.forward(bars, .25)[i]) / 2) : [], color, 1.5, "4 3");
+		PriceMarks.line(ctx, view, "history", bars.map((bar) => bar.close), color);
+		const outer = pairs[0];
+		const edge = bars.length > 1 ? outer.map((p) => ({
+			p,
+			value: this.forward(bars, p).at(-1)
+		})) : [];
+		FinanceInk.note(ctx, "cone-labels", edge, ({ p, value }) => ({
+			x: ctx.plot.width - 3,
+			y: view.y(value) + (p < .5 ? 13 : -5),
+			text: `${Math.round(p * 100)}% ${Quotes.money(value)}`,
+			anchor: "end"
+		}), 10, "secondary");
+		this.sessions(ctx, view, (bar) => ({
+			title: bar.label,
+			rows: [["Close", Quotes.money(bar.close)]]
+		}));
+	}
+};
+export { ProjectionCone };

package/dist/charts/financial/Quotes.js

@@ -0,0 +1,74 @@
+import { utcFormat } from "d3";
+// src/charts/financial/Quotes.ts
+var dayLabel = utcFormat("%b %-d, %Y");
+/** Reads user rows into clean bars, tolerating strings, nulls and missing open/high/low columns. */
+var Quotes = class {
+	static number(value) {
+		if (value === null || value === void 0 || value === "") return NaN;
+		return value instanceof Date ? value.getTime() : Number(value);
+	}
+	static date(value) {
+		if (value === null || value === void 0 || value === "") return null;
+		const date = value instanceof Date ? value : new Date(value);
+		return Number.isNaN(date.getTime()) ? null : date;
+	}
+	static read(rows, fields) {
+		const bars = [];
+		for (const row of rows ?? []) {
+			const close = this.number(row[fields.close]);
+			if (!Number.isFinite(close)) continue;
+			const previous = bars.at(-1)?.close ?? close;
+			const finite = (value, fallback) => Number.isFinite(value) ? value : fallback;
+			const open = finite(this.number(row[fields.open]), previous);
+			const high = Math.max(finite(this.number(row[fields.high]), close), open, close);
+			const low = Math.min(finite(this.number(row[fields.low]), close), open, close);
+			const date = this.date(row[fields.date]);
+			bars.push({
+				index: bars.length,
+				date,
+				label: date ? dayLabel(date) : String(row[fields.date] ?? bars.length + 1),
+				open,
+				high,
+				low,
+				close,
+				volume: Math.max(0, finite(this.number(row[fields.volume]), 0)),
+				source: {
+					open,
+					high,
+					low,
+					close
+				}
+			});
+		}
+		return bars;
+	}
+	/** Expresses prices as percent change from the first close. */
+	static rebased(bars) {
+		const base = bars[0]?.close;
+		if (!base) return bars;
+		const move = (price) => (price - base) / Math.abs(base) * 100;
+		return bars.map((bar) => ({
+			...bar,
+			open: move(bar.open),
+			high: move(bar.high),
+			low: move(bar.low),
+			close: move(bar.close)
+		}));
+	}
+	static money(value) {
+		return value.toLocaleString("en", {
+			minimumFractionDigits: 2,
+			maximumFractionDigits: 2
+		});
+	}
+	static compact(value) {
+		return Intl.NumberFormat("en", {
+			notation: "compact",
+			maximumFractionDigits: 1
+		}).format(value);
+	}
+	static signed(value, digits = 2) {
+		return `${value >= 0 ? "+" : ""}${value.toFixed(digits)}`;
+	}
+};
+export { Quotes };

package/dist/charts/financial/RSIChart.js

@@ -0,0 +1,74 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MovingAverageKind, RsiForm } from "./financeEnums.js";
+import { FinanceMath } from "./FinanceMath.js";
+import { OscillatorChart } from "./OscillatorChart.js";
+import { PriceMarks } from "./PriceMarks.js";
+// src/charts/financial/RSIChart.ts
+/** Bounded momentum gauge: use it to find overbought and oversold extremes. */
+var RSIChart = class extends OscillatorChart {
+	static meta = {
+		id: "rsi",
+		name: "Relative Strength Index",
+		family: ChartFamily.Financial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Scores recent gains against losses from 0 to 100, flagging moves that have run too far too fast.",
+		tags: [
+			"momentum",
+			"oscillator",
+			"overbought",
+			"stochastic rsi",
+			"cutler"
+		],
+		sample: (seed) => SampleData.ohlc(seed, 110),
+		variants: {
+			period: [
+				14,
+				7,
+				21
+			],
+			smoothing: [
+				MovingAverageKind.Wilder,
+				MovingAverageKind.Simple,
+				MovingAverageKind.Exponential
+			],
+			form: [RsiForm.Classic, RsiForm.Stochastic],
+			upper: [70, 80],
+			shade: [true, false],
+			pricePane: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			period: 14,
+			smoothing: MovingAverageKind.Wilder,
+			form: RsiForm.Classic,
+			upper: 70,
+			shade: true
+		};
+	}
+	values(bars) {
+		const { period, smoothing, form } = this.options;
+		const rsi = FinanceMath.rsi(bars.map((bar) => bar.close), period, smoothing);
+		return form === RsiForm.Stochastic ? FinanceMath.sma(FinanceMath.stochastic(rsi, rsi, rsi, period), 3) : rsi;
+	}
+	valueDomain() {
+		return [0, 100];
+	}
+	oscillator(ctx, view, tones) {
+		const values = this.values(view.bars);
+		const { upper, shade } = this.options;
+		this.zones(ctx, view, tones, values, upper, 100 - upper, shade);
+		PriceMarks.line(ctx, view, "rsi-line", values, ctx.theme.categorical[0]);
+	}
+	tooltip(bar) {
+		const value = this.values(this.bars())[bar.index];
+		return {
+			title: bar.label,
+			rows: [[this.options.form === RsiForm.Stochastic ? "Stoch RSI" : "RSI", value == null ? "–" : value.toFixed(1)], ["Close", bar.close.toFixed(2)]]
+		};
+	}
+};
+export { RSIChart };

package/dist/charts/financial/RenkoChart.js

@@ -0,0 +1,58 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { BoxMethod, PriceSource } from "./financeEnums.js";
+import { BrickChart } from "./BrickChart.js";
+import { FinanceMath } from "./FinanceMath.js";
+import { PriceMarks } from "./PriceMarks.js";
+import { PriceTransforms } from "./PriceTransforms.js";
+// src/charts/financial/RenkoChart.ts
+/** Equal bricks printed only when price moves a set amount: use it to read trend and levels with time removed. */
+var RenkoChart = class extends BrickChart {
+	static meta = {
+		id: "renko",
+		name: "Renko chart",
+		family: ChartFamily.Financial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Stacks fixed-size bricks as price moves, stripping out time and small fluctuations to expose trend.",
+		tags: [
+			"bricks",
+			"price action",
+			"atr"
+		],
+		sample: (seed) => SampleData.ohlc(seed, 240),
+		variants: {
+			method: [
+				BoxMethod.ATR,
+				BoxMethod.Range,
+				BoxMethod.Percent
+			],
+			source: [PriceSource.Close, PriceSource.HighLow],
+			reversal: [
+				2,
+				1,
+				3
+			],
+			wicks: [false, true],
+			average: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			reversal: 2,
+			wicks: false,
+			average: false
+		};
+	}
+	construct(bars, box) {
+		return PriceTransforms.renko(bars, box, this.options.reversal, this.options.source).map((brick) => this.column(brick.index, brick.up ? brick.bottom : brick.top, brick.up ? brick.top : brick.bottom, brick.bar, this.options.wicks ? brick.wick : void 0));
+	}
+	columnMarks(ctx, view, tones) {
+		PriceMarks.candles(ctx, view, tones, view.bars, { wicks: this.options.wicks });
+		const closes = view.bars.map((bar) => bar.close);
+		const window = Math.min(10, Math.max(2, Math.floor(closes.length / 4)));
+		PriceMarks.line(ctx, view, "brick-average", this.options.average ? FinanceMath.ema(closes, window) : [], ctx.palette.color(this.options.average ? `EMA ${window}` : "Up"));
+	}
+};
+export { RenkoChart };

package/dist/charts/financial/ReturnCalendar.js

@@ -0,0 +1,196 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { CalendarCell, CalendarGrain, CalendarMeasure, CalendarTotals } from "./financeEnums.js";
+import { Quotes } from "./Quotes.js";
+import { color, mean, quantile, scaleBand, utcFormat } from "d3";
+// src/charts/financial/ReturnCalendar.ts
+var MONTHS = Array.from({ length: 12 }, (_, month) => utcFormat("%b")(new Date(Date.UTC(2024, month, 1))));
+var QUARTERS = [
+	"Q1",
+	"Q2",
+	"Q3",
+	"Q4"
+];
+var TOTAL = "Year";
+var AVERAGE = "Mean";
+/** Period returns laid out by year: use it to report performance and to spot seasonal patterns. */
+var ReturnCalendar = class extends Chart2D {
+	static meta = {
+		id: "return-calendar",
+		name: "Return calendar",
+		family: ChartFamily.Financial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Arranges monthly or quarterly returns in a year-by-period table, with polarity colour for gains and losses.",
+		tags: [
+			"monthly returns",
+			"seasonality",
+			"heatmap",
+			"tearsheet"
+		],
+		sample: (seed) => SampleData.ohlc(seed, 1095),
+		variants: {
+			measure: [CalendarMeasure.Return, CalendarMeasure.Excess],
+			grain: [CalendarGrain.Month, CalendarGrain.Quarter],
+			totals: [
+				CalendarTotals.Year,
+				CalendarTotals.None,
+				CalendarTotals.Both
+			],
+			cell: [CalendarCell.Tile, CalendarCell.Bubble],
+			orientation: [Orientation.Horizontal, Orientation.Vertical]
+		},
+		valid: (values) => values.measure === CalendarMeasure.Return || values.cell === CalendarCell.Bubble
+	};
+	defaults() {
+		return {
+			date: "date",
+			close: "close",
+			measure: CalendarMeasure.Return,
+			grain: CalendarGrain.Month,
+			totals: CalendarTotals.Year,
+			cell: CalendarCell.Tile,
+			orientation: Orientation.Horizontal
+		};
+	}
+	cells() {
+		const { data, date, close, measure, grain, totals } = this.options;
+		const quarterly = grain === CalendarGrain.Quarter;
+		const periods = quarterly ? QUARTERS : MONTHS;
+		const closes = /* @__PURE__ */ new Map();
+		for (const row of data ?? []) {
+			const when = Quotes.date(row[date]), price = Quotes.number(row[close]);
+			if (!when || !Number.isFinite(price)) continue;
+			const year = when.getUTCFullYear(), slot = quarterly ? Math.floor(when.getUTCMonth() / 3) : when.getUTCMonth();
+			const key = `${year}/${slot}`, hit = closes.get(key);
+			if (!hit) closes.set(key, {
+				year,
+				slot,
+				time: +when,
+				first: price,
+				last: price
+			});
+			else if (+when >= hit.time) {
+				hit.time = +when;
+				hit.last = price;
+			}
+		}
+		const ordered = [...closes.values()].sort((a, b) => a.year - b.year || a.slot - b.slot);
+		const raw = ordered.flatMap((period, i) => {
+			const base = ordered[i - 1]?.last ?? period.first;
+			return base ? [{
+				year: period.year,
+				slot: period.slot,
+				value: (period.last - base) / Math.abs(base) * 100
+			}] : [];
+		});
+		const years = [...new Set(raw.map((item) => item.year))];
+		const cells = [];
+		for (const year of years) {
+			const items = raw.filter((item) => item.year === year);
+			const average = measure === CalendarMeasure.Excess ? mean(items, (item) => item.value) ?? 0 : 0;
+			items.forEach((item) => cells.push({
+				row: String(year),
+				column: periods[item.slot],
+				value: item.value - average,
+				total: false
+			}));
+			if (totals !== CalendarTotals.None) {
+				const compound = (items.reduce((growth, item) => growth * (1 + item.value / 100), 1) - 1) * 100;
+				cells.push({
+					row: String(year),
+					column: TOTAL,
+					value: measure === CalendarMeasure.Excess ? compound - average * items.length : compound,
+					total: true
+				});
+			}
+		}
+		const rows = years.map(String);
+		if (totals === CalendarTotals.Both) {
+			for (const column of periods) {
+				const hits = cells.filter((cell) => cell.column === column);
+				if (hits.length) cells.push({
+					row: AVERAGE,
+					column,
+					value: mean(hits, (cell) => cell.value),
+					total: true
+				});
+			}
+			rows.push(AVERAGE);
+		}
+		return {
+			cells,
+			rows,
+			columns: totals === CalendarTotals.None ? periods : [...periods, TOTAL]
+		};
+	}
+	plotMargin() {
+		return {
+			top: 20,
+			right: 12,
+			bottom: 8,
+			left: 44
+		};
+	}
+	legendItems() {
+		return [];
+	}
+	draw(ctx) {
+		const { cells, rows, columns } = this.cells();
+		const { width, height } = ctx.plot;
+		const flipped = this.options.orientation === Orientation.Vertical;
+		const across = flipped ? rows : columns, down = flipped ? columns : rows;
+		const x = scaleBand(across, [0, width]).paddingInner(.06), y = scaleBand(down, [0, height]).paddingInner(.08);
+		const wide = x.bandwidth(), deep = y.bandwidth();
+		const left = (cell) => x(flipped ? cell.row : cell.column);
+		const top = (cell) => y(flipped ? cell.column : cell.row);
+		const reach = Math.max(quantile(cells.filter((cell) => !cell.total).map((cell) => Math.abs(cell.value)), .9) ?? 0, .01);
+		const paint = (cell) => ctx.palette.diverging(Math.max(-1, Math.min(1, -cell.value / reach)));
+		const key = (cell) => `${cell.row}/${cell.column}`;
+		const tile = this.options.cell === CalendarCell.Tile;
+		const tips = (cell) => ({
+			title: `${cell.column} ${cell.row}`,
+			color: paint(cell),
+			rows: [[this.options.measure === CalendarMeasure.Excess ? "Excess" : "Return", `${Quotes.signed(cell.value)}%`]]
+		});
+		const rects = ctx.marks("tiles", "rect", tile ? cells : [], key).attr("fill", paint).attr("rx", 3);
+		ctx.set(rects, {
+			x: left,
+			y: top,
+			width: wide,
+			height: deep
+		}, {
+			x: left,
+			y: top,
+			width: wide,
+			height: 0
+		}, 3);
+		ctx.hover(rects, tips);
+		const room = Math.min(wide, deep) / 2 - 1;
+		const radius = (cell) => Math.max(1.5, room * Math.sqrt(Math.min(1, Math.abs(cell.value) / reach)));
+		const dots = ctx.marks("bubbles", "circle", tile ? [] : cells, key).attr("fill", paint);
+		const cx = (cell) => left(cell) + wide / 2, cy = (cell) => top(cell) + deep / 2;
+		ctx.set(dots, {
+			cx,
+			cy,
+			r: radius
+		}, {
+			cx,
+			cy,
+			r: 0
+		}, 3);
+		ctx.hover(dots, tips);
+		const fits = tile && wide >= 22 && deep >= 13;
+		const labels = ctx.text(ctx.marks("values", "text", fits ? cells : [], key), wide >= 34 ? 10 : 9).attr("text-anchor", "middle").attr("dy", "0.34em").attr("pointer-events", "none").attr("fill", (cell) => ctx.palette.inkOn(color(paint(cell))?.formatHex() ?? ctx.theme.surface)).attr("font-weight", (cell) => cell.total ? 600 : 400).text((cell) => cell.value.toFixed(wide >= 34 ? 1 : 0).replace(/^-(0(\.0)?)$/, "$1"));
+		ctx.set(labels, {
+			x: cx,
+			y: cy
+		});
+		const header = across.filter((_, i) => wide >= 20 || i % 2 === 0);
+		ctx.text(ctx.marks("column-names", "text", header)).attr("text-anchor", "middle").attr("x", (name) => x(name) + wide / 2).attr("y", -7).text((name) => name);
+		const side = down.filter((_, i) => deep >= 12 || i % 2 === 0);
+		ctx.text(ctx.marks("row-names", "text", side)).attr("text-anchor", "end").attr("x", -7).attr("y", (name) => y(name) + deep / 2).attr("dy", "0.34em").text((name) => name);
+	}
+};
+export { ReturnCalendar };