// stdlib/charts: histogram and CDF of one numeric column (ROADMAP 6.34, D-214; the "Latency Histogram & CDF" of the block-authoring design). // Sent: its declared values (column, bins, mode, title) and the tables of the blocks the author named. The bin count and the mode are // controls in the view; a change is written back as one body line (api.set), so it saves with the document. const SVGNS = "http://www.w3.org/2000/svg"; const put = (n, a, kids) => { for (const k in a || {}) { const v = a[k]; if (v === false || v == null) continue; n.setAttribute(k, v === true ? "" : String(v)); } for (const c of kids) if (c != null) n.append(c); return n; }; const h = (t, a, ...k) => put(document.createElement(t), a, k); const sv = (t, a, ...k) => put(document.createElementNS(SVGNS, t), a, k); const tok = (n, fb) => `var(--wmn-color-${n}, ${fb})`; const num = (v) => (typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : Number.NaN); const fmt = (v) => { if (typeof v !== "number" || !Number.isFinite(v)) return String(v ?? ""); const a = Math.abs(v); if (a !== 0 && (a >= 1e6 || a < 1e-3)) return v.toExponential(2).replace(/\.?0+e/, "e"); return String(+v.toPrecision(4)); }; const MAX_ROWS = 5000; function readTable(api) { for (const name of api.dataNames()) { const d = api.data(name); const t = d?.value; if (!t || !Array.isArray(t.columns) || !Array.isArray(t.rows)) continue; const cols = t.columns.map((c) => (typeof c === "string" ? c : c && typeof c.name === "string" ? c.name : "")); const rows = t.rows.slice(0, MAX_ROWS).map((r) => (Array.isArray(r) ? r : cols.map((c) => (r ? r[c] : null)))); return { name, cols, rows, total: t.rows.length }; } return null; } const isNumeric = (t, i) => { let seen = 0; for (const r of t.rows) { if (r[i] === null || r[i] === undefined || r[i] === "") continue; if (!Number.isFinite(num(r[i]))) return false; seen++; } return seen > 0; }; function niceTicks(lo, hi, n) { if (!Number.isFinite(lo) || !Number.isFinite(hi)) return [0, 1]; // a span too big for a float is worked out in halves if (!Number.isFinite(hi - lo)) return niceTicks(lo / 2, hi / 2, n).map((v) => v * 2); if (!(hi > lo)) { lo -= 1; hi += 1; } const raw = (hi - lo) / Math.max(1, n); // values so large that one unit is below their spacing have no ticks between them if (!(raw > 0)) return [lo, hi]; const mag = 10 ** Math.floor(Math.log10(raw)); const r = raw / mag; const step = (r < 1.5 ? 1 : r < 3 ? 2 : r < 7 ? 5 : 10) * mag; const out = []; const top = Math.ceil(hi / step) * step + step / 2; // ends when the step no longer moves the value (below float spacing), and never makes more than 60 ticks for (let v = Math.floor(lo / step) * step; v <= top && out.length < 60; ) { out.push(+v.toFixed(12)); const next = v + step; if (next === v) break; v = next; } return out.length >= 2 ? out : [lo, hi]; } // where v lies between a and b (0 to 1), without overflowing when b - a is beyond a float const frac = (v, a, b) => (v / 2 - a / 2) / (b / 2 - a / 2 || 1); const STYLE = ` .sl{font:14px/1.4 var(--wmn-font-text,system-ui,sans-serif);color:var(--wmn-color-on-surface,#1c1b1a);padding:8px 4px} .sl-title{font:500 16px/1.3 var(--wmn-font-display,serif);margin:0 0 4px;color:var(--wmn-color-chart-title,#1c1b1a)} .sl-note{color:var(--wmn-color-on-surface-variant,#57423c);margin:4px 0;font-size:13px} .sl-cursor{display:block;border-radius:4px;touch-action:pan-y} .sl-cursor:focus-visible,.sl button:focus-visible,.sl input:focus-visible,.sl select:focus-visible{outline:2px solid var(--wmn-color-primary,#a03a19);outline-offset:2px} .sl-read{min-height:20px;margin:4px 0;font-size:13px;font-variant-numeric:tabular-nums} .sl-controls{display:flex;flex-wrap:wrap;gap:8px 18px;align-items:center;margin:6px 0;font-size:13px} .sl-controls label{display:inline-flex;gap:8px;align-items:center} .sl-controls input[type=range]{width:150px;accent-color:var(--wmn-color-primary,#a03a19)} .sl select{font:inherit;font-size:13px;min-height:28px;border-radius:var(--wmn-radius,4px);border:1px solid var(--wmn-color-outline,#8b716a);background:var(--wmn-color-surface-container,#f2edeb);color:var(--wmn-color-on-surface,#1c1b1a)} .sl-stats{display:flex;flex-wrap:wrap;gap:4px 18px;margin:4px 0;padding:0;list-style:none;font-size:13px;font-variant-numeric:tabular-nums} .sl-stats b{font-weight:500;color:var(--wmn-color-on-surface-variant,#57423c);margin-right:4px} `; const quantile = (sorted, q) => { if (sorted.length === 0) return Number.NaN; const at = (sorted.length - 1) * q; const lo = Math.floor(at); const hi = Math.ceil(at); return sorted[lo] + (sorted[hi] - sorted[lo]) * (at - lo); }; export default function view(api) { document.head.append(h("style", {}, STYLE)); const root = api.root; const box = h("div", { class: "sl" }); const plot = h("div", {}); const range = h("input", { type: "range", min: 1, max: 100, step: 1, value: 12, "data-k": "bins", "aria-label": "Bins", }); const shown = h("output", {}, "12"); const pick = h( "select", { "data-k": "mode", "aria-label": "Show" }, ...[ ["both", "Histogram and CDF"], ["histogram", "Histogram"], ["cdf", "CDF"], ].map(([v, l]) => h("option", { value: v }, l)), ); const controls = h( "div", { class: "sl-controls" }, h("label", {}, "Bins", range, shown), h("label", {}, "Show", pick), ); controls.hidden = true; box.append(controls, plot); root.append(box); let values = api.values(); let width = 0; let cursor = 0; let timer = 0; let sendTimer = 0; const send = (key, value) => { clearTimeout(sendTimer); sendTimer = setTimeout(() => api.set(key, value), 80); }; function bin(sorted, count) { const lo = sorted[0]; const hi = sorted[sorted.length - 1]; // (mixed, not lo + span * k: the span of -1e308 to 1e308 is beyond a float) const at = (k) => lo * (1 - k) + hi * k; const bins = Array.from({ length: count }, (_, i) => ({ a: at(i / count), b: at((i + 1) / count), n: 0 })); for (const v of sorted) bins[Math.max(0, Math.min(count - 1, Math.floor(frac(v, lo, hi) * count)))].n++; let run = 0; for (const b of bins) { run += b.n; b.cum = run / sorted.length; } return bins; } range.addEventListener("input", () => { const n = Number(range.value); values = { ...values, bins: n }; shown.textContent = String(n); send("bins", n); redraw(); }); pick.addEventListener("change", () => { values = { ...values, mode: pick.value }; send("mode", pick.value); redraw(); }); function draw() { const hadFocus = plot.contains(document.activeElement); plot.replaceChildren(); controls.hidden = true; if (values.title) plot.append(h("p", { class: "sl-title" }, String(values.title))); const t = readTable(api); if (!t) { plot.append( h( "p", { class: "sl-note" }, "No table yet. Add source: and the id of a block that prints a table, then run that block.", ), ); api.status(JSON.stringify({ state: "empty" })); return; } const ci = t.cols.includes(values.column) ? t.cols.indexOf(values.column) : t.cols.findIndex((_, i) => isNumeric(t, i)); if (ci < 0) { plot.append(h("p", { class: "sl-note", role: "status" }, "The table has no numeric column to count.")); api.status(JSON.stringify({ state: "problem" })); return; } const col = t.cols[ci]; const data = t.rows .map((r) => num(r[ci])) .filter(Number.isFinite) .sort((a, b) => a - b); if (data.length === 0) { plot.append(h("p", { class: "sl-note", role: "status" }, `Column ${col} has no numbers.`)); return; } const mode = ["histogram", "cdf", "both"].includes(values.mode) ? values.mode : "both"; const count = Math.max(1, Math.min(100, Math.round(Number(values.bins) || 12))); const bins = bin(data, count); cursor = Math.min(cursor, count - 1); const mean = data.reduce((s, v) => s + v, 0) / data.length; plot.append( h( "ul", { class: "sl-stats", "aria-label": `Summary of ${col}` }, ...[ ["n", String(data.length)], ["mean", fmt(mean)], ["median", fmt(quantile(data, 0.5))], ["p95", fmt(quantile(data, 0.95))], ["p99", fmt(quantile(data, 0.99))], ["max", fmt(data[data.length - 1])], ].map(([k, v]) => h("li", {}, h("b", {}, k), v)), ), ); const W = Math.max(200, Math.floor(width || root.clientWidth || 600)); const H = 260; const m = { l: 52, r: mode === "histogram" ? 14 : 48, t: 10, b: 42 }; const iw = W - m.l - m.r; const ih = H - m.t - m.b; const axis = tok("chart-axis", "#8b716a"); const grid = tok("chart-grid", "#dec0b8"); const label = tok("chart-label", "#57423c"); const lo = bins[0].a; const hi = bins[bins.length - 1].b; const X = (v) => m.l + frac(v, lo, hi) * iw; const maxN = Math.max(...bins.map((b) => b.n)); const nt = niceTicks(0, maxN, 5); const topN = nt[nt.length - 1] || 1; const Yn = (n) => m.t + ih - (n / topN) * ih; const Yp = (p) => m.t + ih - p * ih; const svg = sv("svg", { width: W, height: H, viewBox: `0 0 ${W} ${H}`, "aria-hidden": "true", focusable: "false" }); if (mode === "cdf") { for (const p of [0, 0.25, 0.5, 0.75, 1]) { svg.append(sv("line", { x1: m.l, x2: W - m.r, y1: Yp(p), y2: Yp(p), stroke: grid })); svg.append( sv( "text", { x: m.l - 6, y: Yp(p) + 4, "text-anchor": "end", fill: label, "font-size": 12 }, `${Math.round(p * 100)}%`, ), ); } } else { for (const v of nt) { svg.append(sv("line", { x1: m.l, x2: W - m.r, y1: Yn(v), y2: Yn(v), stroke: v === 0 ? axis : grid })); svg.append( sv("text", { x: m.l - 6, y: Yn(v) + 4, "text-anchor": "end", fill: label, "font-size": 12 }, fmt(v)), ); } } if (mode === "both") for (const p of [0, 0.5, 1]) svg.append( sv("text", { x: W - m.r + 6, y: Yp(p) + 4, fill: label, "font-size": 12 }, `${Math.round(p * 100)}%`), ); for (const v of niceTicks(lo, hi, Math.max(2, Math.floor(iw / 90))).filter((v) => v >= lo && v <= hi)) svg.append( sv("text", { x: X(v), y: H - m.b + 18, "text-anchor": "middle", fill: label, "font-size": 12 }, fmt(v)), ); svg.append(sv("text", { x: m.l + iw / 2, y: H - 6, "text-anchor": "middle", fill: label, "font-size": 12 }, col)); if (mode !== "cdf") for (const b of bins) svg.append( sv("rect", { x: X(b.a) + 0.5, y: Yn(b.n), width: Math.max(1, X(b.b) - X(b.a) - 1), height: Yn(0) - Yn(b.n), fill: tok("chart-1", "#a03a19"), "fill-opacity": mode === "both" ? 0.75 : 1, }), ); if (mode !== "histogram") { // the empirical CDF as a step line, at most 300 steps const stride = Math.max(1, Math.floor(data.length / 300)); let d = `M${X(data[0]).toFixed(1)} ${Yp(0).toFixed(1)}`; for (let i = 0; i < data.length; i += stride) d += `L${X(data[i]).toFixed(1)} ${Yp(i / data.length).toFixed(1)}L${X(data[i]).toFixed(1)} ${Yp((i + 1) / data.length).toFixed(1)}`; d += `L${X(data[data.length - 1]).toFixed(1)} ${Yp(1).toFixed(1)}`; svg.append(sv("path", { d, fill: "none", stroke: tok("chart-2", "#0051d5"), "stroke-width": 2 })); } const cur = sv("g", {}); svg.append(cur); const readout = h("div", { class: "sl-read" }); const textOf = (b) => `${fmt(b.a)} to ${fmt(b.b)}: ${b.n} values (${Math.round((b.n / data.length) * 1000) / 10}%), ${Math.round(b.cum * 1000) / 10}% at or below ${fmt(b.b)}`; const slider = h( "div", { class: "sl-cursor", role: "slider", tabindex: 0, "aria-label": `${values.title ? `${values.title}, ` : ""}Histogram of ${col}. Arrow keys move between bins`, "aria-valuemin": 1, "aria-valuemax": count, "aria-valuenow": 1, }, svg, ); const place = () => { const b = bins[cursor]; cur.replaceChildren( sv("rect", { x: X(b.a), y: m.t, width: Math.max(1, X(b.b) - X(b.a)), height: ih, fill: "none", stroke: tok("on-surface", "#1c1b1a"), "stroke-dasharray": "3 3", }), ); readout.textContent = textOf(b); slider.setAttribute("aria-valuenow", String(cursor + 1)); slider.setAttribute("aria-valuetext", textOf(b)); }; slider.addEventListener("keydown", (e) => { const step = e.key === "ArrowRight" || e.key === "ArrowUp" ? 1 : e.key === "ArrowLeft" || e.key === "ArrowDown" ? -1 : e.key === "Home" ? -1e9 : e.key === "End" ? 1e9 : 0; if (!step) return; e.preventDefault(); cursor = Math.max(0, Math.min(count - 1, cursor + step)); place(); }); slider.addEventListener("pointermove", (e) => { const r = svg.getBoundingClientRect(); const k = (e.clientX - r.left - m.l) / (iw || 1); const v = lo * (1 - k) + hi * k; const idx = Math.max( 0, Math.min(count - 1, bins.findIndex((b) => v < b.b) < 0 ? count - 1 : bins.findIndex((b) => v < b.b)), ); if (idx !== cursor) { cursor = idx; place(); } }); controls.hidden = false; range.value = String(count); shown.textContent = String(count); pick.value = mode; plot.append(slider, readout); place(); if (hadFocus) plot.querySelector("[role=slider]")?.focus(); api.status(JSON.stringify({ state: "drawn", column: col, n: data.length, bins: count, mode, width: W })); } const redraw = () => { if (timer) return; timer = setTimeout(() => { timer = 0; draw(); }, 16); }; api.onValues((v) => { values = v; redraw(); }); api.onData(redraw); if (typeof ResizeObserver !== "undefined") new ResizeObserver(() => { const w = Math.floor(root.clientWidth); if (Math.abs(w - width) > 1) { width = w; redraw(); } }).observe(root); width = Math.floor(root.clientWidth); draw(); api.done({ lib: "stdlib/charts", block: "histogram" }); }