plotto 0.1.0 → 0.3.0

package/README.md

@@ -86,6 +86,17 @@ draw(plot(rows, { x: "time", y: "value", color: "sensor" }).line().facet("indica
 
 Palettes: `pastel` (the default style), `sakura`, `aizome`, `momiji` (inspired by traditional Japanese colors), `wota`, `tableau`. Schemes: `ai`, `sakura`, `matcha`, `yuhi`, `sumi`, `aiaka` (diverging), and every d3 scheme (`viridis`, `magma`, …).
 
+### Info table
+
+Put facts about the data or the experiment in a table instead of a long subtitle:
+
+```python
+p.info({"data point": 15, "location": "hayama", "experiment": "cleaning with chlorine"})
+p.info(entries, position="bottom")   # "right" (default) or "bottom"
+```
+
+The table is a card on the right of the plot, or below it. A plot narrower than 560 px puts it below. `SPEC.md` §7 has the rules.
+
 ### Notebook
 
 - A plot shows at the width of the cell. The text keeps its size, and the height follows the aspect ratio of the format.
@@ -183,15 +194,28 @@ One-time setup:
 
 Each release:
 
-1. Set the same version in `package.json` and in `python/plotto/__init__.py` (a test verifies that they agree).
-2. Commit, then tag and push:
+`main` takes changes only through a reviewed pull request, so a release has two steps.
+
+1. On `main`, with no uncommitted changes and the Python environment of the repo active, prepare the release:
+
+   ```
+   scripts/release.sh 0.3.0
+   ```
+
+   The script:
+   - checks that `main` is up to date with `origin/main` and that the version is new and higher;
+   - runs `npm test`, `npm run browser-test`, `pytest python/tests`, `ruff` and `black`;
+   - on a new branch `release/v0.3.0`, sets the version in `package.json`, `package-lock.json` and `python/plotto/__init__.py`, and builds the site in `docs/`;
+   - commits "release 0.3.0", pushes the branch and opens the pull request page.
+2. Create the pull request, then have it reviewed and merged.
+3. Tag the merged `main`:
 
    ```
-   git tag v0.1.0
-   git push origin v0.1.0
+   scripts/release.sh tag
    ```
 
-3. The Actions tab shows the release. The packages are then at pypi.org/project/python-plotto and npmjs.com/package/plotto.
+   The script pulls `main` and reads the version. It asks before it tags and pushes `v0.3.0`, then deletes the release branch.
+4. The pushed tag starts the release in the Actions tab. The packages are then at pypi.org/project/python-plotto and npmjs.com/package/plotto.
 
 To upgrade Observable Plot or d3:
 

package/grammar.json

@@ -47,5 +47,7 @@
   "free": ["x", "y", "both"],
   "labels": ["title", "subtitle", "x", "y", "color", "caption"],
   "theme": ["format", "width", "height", "size", "legend"],
-  "legend": ["right", "bottom", "none"]
+  "legend": ["right", "bottom", "none"],
+  "info": ["position"],
+  "infoPosition": ["right", "bottom"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plotto",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Grammar-of-graphics plots for notebooks, web pages and slides with one renderer.",
   "license": "MIT",
   "homepage": "https://theoradusz.github.io/plotto/",

package/src/builder.js

@@ -13,7 +13,7 @@ export function plot(rows, mapping = {}) {
     if (!PLOT_CHANNELS.includes(ch)) fail("plot()", "channel", ch, PLOT_CHANNELS);
     needColumn(data[0], col, "plot()");
   }
-  return new Builder({ data, mapping, layers: [], facet: null, scales: {}, labels: {}, theme: { style: "pastel" } });
+  return new Builder({ data, mapping, layers: [], facet: null, scales: {}, labels: {}, info: null, theme: { style: "pastel" } });
 }
 
 class Builder {
@@ -106,6 +106,17 @@ class Builder {
     return this.#with({ labels: { ...this.#s.labels, ...options } });
   }
 
+  // A key/value table about the data or the experiment: info({ location: "hayama" }, { position: "right" }). null removes it.
+  info(entries, options = {}) {
+    checkKeys(options, GRAMMAR.info, "info()");
+    const position = options.position ?? "right";
+    if (!GRAMMAR.infoPosition.includes(position)) fail("info()", "position", position, GRAMMAR.infoPosition);
+    if (entries === null || entries === undefined) return this.#with({ info: null });
+    const pairs = Array.isArray(entries) ? entries : typeof entries === "object" ? Object.entries(entries) : null;
+    if (!pairs) throw new Error("info(): entries must be an object or a list of [key, value] pairs");
+    return this.#with({ info: { entries: pairs.map((pair) => infoEntry(pair)), position } });
+  }
+
   theme(style = "pastel", options = {}) {
     checkKeys(options, GRAMMAR.theme, "theme()");
     if (!(style in THEMES.styles)) fail("theme()", "style", style, Object.keys(THEMES.styles));
@@ -124,7 +135,7 @@ class Builder {
       if (col) used.forEach((set, i) => col in s.data[i].columns && set.add(col));
     }
     const data = s.data.map((t, i) => ({ columns: Object.fromEntries([...used[i]].map((c) => [c, t.columns[c]])) }));
-    return { version: 1, data, mapping: s.mapping, layers: s.layers, facet: s.facet, scales: s.scales, labels: s.labels, theme: s.theme };
+    return { version: 1, data, mapping: s.mapping, layers: s.layers, facet: s.facet, scales: s.scales, labels: s.labels, ...(s.info ? { info: s.info } : {}), theme: s.theme };
   }
 }
 
@@ -161,6 +172,15 @@ function constant(key, value, where, columns) {
   return toValue(value);
 }
 
+// One [key, value] entry of info(). Numbers keep 6 significant digits; the renderer writes the value as text.
+function infoEntry(pair) {
+  if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string") throw new Error("info(): each entry must be a [key, value] pair with a string key");
+  const [key, value] = pair;
+  if (value === null || value === undefined || (typeof value === "number" && Number.isNaN(value))) return [key, null];
+  if (!["string", "number", "boolean"].includes(typeof value)) throw new Error(`info(): the value of "${key}" must be a string, a number, a boolean or null. Format other values as a string`);
+  return [key, toValue(value)];
+}
+
 function needColumn(table, col, where) {
   if (!(col in table.columns)) throw new Error(`${where}: "${col}" is not a column. Columns: ${Object.keys(table.columns).join(", ")}`);
 }

package/src/figure.js

@@ -1,8 +1,9 @@
-// Figure: computes the views, scales and layout, then draws the title, strips, legend and panels as one SVG.
+// Figure: computes the views, scales and layout, then draws the title, info table, strips, legend and panels as one SVG.
 // Observable Plot draws each panel. drawPanels() draws them again after a zoom or a legend click.
 import * as Plot from "@observablehq/plot";
 import * as d3 from "d3";
 import { facetPanels } from "./facets.js";
+import { drawInfo, infoModel } from "./info.js";
 import { LAYERS } from "./layers.js";
 import { drawLegend, legendModel } from "./legend.js";
 import { place, TICK } from "./layout.js";
@@ -31,8 +32,10 @@ export function figure(spec, { document: doc = globalThis.document, width, domai
   for (const p of grid.panels) p.views = ns.layers.map((layer, li) => makeView(ctx, layer, p.rows[li], new Set()));
   const home = homeDomains(ns, grid, kind);
   const horizontal = theme.legend === "bottom";
-  const legend = legendModel(ns, color, fonts, { horizontal, maxWidth: W * 0.9, maxHeight: H * 0.8 });
-  const layout = place({ ns, grid, kind, home, legend, fonts, W, H });
+  const info = infoModel(ns, fonts, { W, H, narrow: W < NARROW });
+  const above = info?.position === "right" ? info.height + fonts.base : 0; // the info card sits above a right legend
+  const legend = legendModel(ns, color, fonts, { horizontal, maxWidth: W * 0.9, maxHeight: H * 0.8 - above });
+  const layout = place({ ns, grid, kind, home, legend, info, fonts, W, H });
 
   const svg = svgElement(doc, "svg", {
     xmlns: "http://www.w3.org/2000/svg",
@@ -45,8 +48,9 @@ export function figure(spec, { document: doc = globalThis.document, width, domai
   });
   svg.append(svgElement(doc, "rect", { width: W, height: H, fill: theme.background }));
   for (const t of layout.texts) svg.append(svgText(doc, t.text, t.attrs));
+  if (info) svg.append(drawInfo(doc, info, theme, layout.info));
   for (const s of layout.strips) svg.append(strip(doc, s, theme, fonts));
-  const state = { spec, ns, doc, svg, theme, fonts, grid, kind, color, ctx, legend, layout, home, W, H };
+  const state = { spec, ns, doc, svg, theme, fonts, grid, kind, color, ctx, legend, info, layout, home, W, H };
   state.domains = domains ?? home;
   state.hidden = hidden;
   state.panelLayer = svg.appendChild(svgElement(doc, "g", { class: "pt-panels" }));

package/src/info.js

@@ -0,0 +1,83 @@
+// Info table: the key/value entries of info(), as a card in the right column or below the plot.
+import * as d3 from "d3";
+import { svgElement, svgText } from "./svg.js";
+import { fitText, textWidth, wrapText } from "./text.js";
+
+const VALUE_LINES = 3; // a long value wraps to this many lines
+const KEY_SHARE = 0.45; // the key column takes at most this share of the table width
+const MAX_WIDTH = { right: 0.3, bottom: 0.9 }; // share of the figure width
+const MAX_HEIGHT = { right: 0.6, bottom: 0.3 }; // share of the figure height; the rest of the entries become "+N more"
+const MAX_COLUMNS = 3; // columns of entries in a bottom card
+
+// The info model with its position and size. narrow: a right placement moves to the bottom.
+export function infoModel(ns, fonts, { W, H, narrow }) {
+  if (!ns.info) return null;
+  const position = narrow ? "bottom" : ns.info.position;
+  return model(ns, fonts, ns.info.entries, position, W, H * MAX_HEIGHT[position]);
+}
+
+function model(ns, fonts, entries, position, W, maxHeight) {
+  const metrics = ns.theme.metrics;
+  const size = fonts.legend;
+  const pad = Math.round(size * 0.8);
+  const lineH = size * 1.35;
+  const keyGap = size;
+  const colGap = size * 2;
+  const all = entries.map(([key, value]) => ({ key: String(key), value: value === null ? "–" : String(value) }));
+  const width = (t) => textWidth(t, size, false, metrics);
+
+  // One column of rows, at most maxWidth wide: the keys on the left, the values wrapped on the right.
+  const column = (items, maxWidth) => {
+    const keyW = Math.min(d3.max(items, (r) => width(r.key)) ?? 0, maxWidth * KEY_SHARE);
+    const valueMax = Math.max(size * 3, maxWidth - keyW - keyGap);
+    let y = 0;
+    const laid = items.map((r) => {
+      const lines = wrapText(r.value, size, valueMax, false, metrics, VALUE_LINES);
+      const row = { key: fitText(r.key, size, keyW, false, metrics), full: r.key, lines, y };
+      y += lines.length * lineH;
+      return row;
+    });
+    const valueW = d3.max(laid, (r) => d3.max(r.lines, width)) ?? 0;
+    return { rows: laid, keyW, width: keyW + keyGap + valueW, height: y };
+  };
+
+  const inner = W * MAX_WIDTH[position] - 2 * pad;
+  const table = (rows) => {
+    let columns;
+    if (position === "bottom") {
+      const natural = d3.max(rows, (r) => width(r.key) + keyGap + width(r.value)) ?? 0;
+      const k = Math.max(1, Math.min(MAX_COLUMNS, rows.length, Math.floor((inner + colGap) / (natural + colGap))));
+      const perColumn = Math.ceil(rows.length / k);
+      const colW = (inner - colGap * (k - 1)) / k;
+      columns = d3.range(k).map((j) => column(rows.slice(j * perColumn, (j + 1) * perColumn), colW));
+    } else columns = [column(rows, inner)];
+    let x = pad;
+    for (const c of columns) (c.x = x), (x += c.width + colGap);
+    return { columns, width: x - colGap + pad, height: (d3.max(columns, (c) => c.height) ?? 0) + 2 * pad };
+  };
+  // Drop entries from the end until the table fits; the last row tells how many are not shown.
+  let kept = all.length;
+  let t = table(all);
+  while (t.height > maxHeight && kept > 1) {
+    kept--;
+    t = table([...all.slice(0, kept), { key: `+${all.length - kept} more`, value: "" }]);
+  }
+  return { position, size, pad, lineH, keyGap, ...t };
+}
+
+// The table as an SVG group at (x, y): keys in the muted color, values in the ink color, on a strip-colored card.
+export function drawInfo(doc, model, theme, { x, y }) {
+  const g = svgElement(doc, "g", { class: "pt-info", transform: `translate(${x},${y})`, "font-size": model.size });
+  g.append(svgElement(doc, "rect", { width: model.width, height: model.height, fill: theme.strip }));
+  const baseline = model.lineH * 0.75;
+  for (const c of model.columns) {
+    for (const r of c.rows) {
+      const top = model.pad + r.y + baseline;
+      const key = svgText(doc, r.key, { x: c.x, y: top, fill: theme.muted, "text-anchor": "start" });
+      if (r.key !== r.full) key.append(svgText(doc, r.full, {}, "title"));
+      g.append(key);
+      r.lines.forEach((line, i) => g.append(svgText(doc, line, { x: c.x + c.keyW + model.keyGap, y: top + i * model.lineH, fill: theme.ink, "text-anchor": "start" })));
+    }
+  }
+  return g;
+}

package/src/layout.js

@@ -1,4 +1,4 @@
-// Layout: the position and size of the title, panels, strips, axis titles, caption and legend, in px of the figure.
+// Layout: the position and size of the title, info table, panels, strips, axis titles, caption and legend, in px of the figure.
 // Text sizes come from text.js, so Node and the browser get the same layout.
 import * as d3 from "d3";
 import { ticks } from "./scales.js";
@@ -8,7 +8,7 @@ export const TICK = { size: 4, padding: 3 };
 const ROTATE = 40; // degrees of rotated category labels
 const TOOLBAR = 0.22; // share of the width kept free of the title, for the toolbar
 
-export function place({ ns, grid, kind, home, legend, fonts, W, H }) {
+export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
   const theme = ns.theme;
   const metrics = theme.metrics;
   const tw = (t, size, bold) => textWidth(t, size, bold, metrics);
@@ -16,6 +16,7 @@ export function place({ ns, grid, kind, home, legend, fonts, W, H }) {
   const pad = Math.round(s * 0.9);
   const gap = Math.round(s * 0.8);
   const { title, subtitle, caption, x: xTitle, y: yTitle } = ns.labels;
+  const at = (position) => (info?.position === position ? info : null);
   const headW = W - 2 * pad - Math.min(180, W * TOOLBAR);
   const titleLines = title ? wrapText(title, fonts.title, headW, true, metrics) : [];
   const subtitleLines = subtitle ? wrapText(subtitle, fonts.subtitle, headW, false, metrics) : [];
@@ -24,9 +25,11 @@ export function place({ ns, grid, kind, home, legend, fonts, W, H }) {
   const xt = xTitle ? fonts.axisTitle * 1.7 : 0;
   const yt = yTitle ? fonts.axisTitle * 1.7 : 0;
   const cap = caption ? fonts.tick * 1.8 : 0;
-  const right = legend && !legend.horizontal ? legend.width + s * 1.5 : 0;
+  const rightW = Math.max(legend && !legend.horizontal ? legend.width : 0, at("right")?.width ?? 0);
+  const right = rightW ? rightW + s * 1.5 : 0;
   const bottom = legend?.horizontal ? legend.height + s * 0.8 : 0;
-  const area = { x: pad + yt, y: top, w: W - 2 * pad - yt - right, h: H - top - pad - xt - bottom - cap };
+  const below = at("bottom") ? at("bottom").height + gap : 0;
+  const area = { x: pad + yt, y: top, w: W - 2 * pad - yt - right, h: H - top - pad - xt - bottom - cap - below };
 
   const strip = grid.kind === "none" ? 0 : Math.round(fonts.strip * 2);
   const wrapStrip = grid.kind === "wrap" ? strip : 0;
@@ -111,10 +114,17 @@ export function place({ ns, grid, kind, home, legend, fonts, W, H }) {
     texts.push({ text: yTitle, attrs: { transform: `translate(${pad + fonts.axisTitle * 0.85},${cy}) rotate(-90)`, "text-anchor": "middle", "font-size": fonts.axisTitle, fill: theme.muted } });
   }
   if (caption) texts.push({ text: fitText(caption, fonts.tick, W - 2 * pad, false, metrics), attrs: { x: innerLeft, y: H - pad - (bottom ? bottom : 0) + fonts.tick * 0.2, "font-size": fonts.tick, fill: theme.muted, "text-anchor": "start" } });
+  const rightX = W - pad - rightW;
+  const infoAt = !info
+    ? null
+    : info.position === "right"
+      ? { x: rightX, y: area.y }
+      : { x: Math.max(pad, Math.min(innerLeft, W - pad - info.width)), y: panelsBottom + xt + gap / 2 };
+  const above = at("right") ? info.height + s : 0;
   const legendAt = !legend
     ? null
     : legend.horizontal
       ? { x: Math.max(pad, (innerLeft + innerRight - legend.width) / 2), y: H - pad - legend.height }
-      : { x: W - pad - legend.width, y: area.y + Math.max(0, (area.h - d3.sum(mb) - legend.height) / 2) };
-  return { panels, strips, texts, legend: legendAt, area, rotateX };
+      : { x: rightX, y: area.y + above + Math.max(0, (area.h - d3.sum(mb) - above - legend.height) / 2) };
+  return { panels, strips, texts, legend: legendAt, info: infoAt, area, rotateX };
 }

package/src/spec.js

@@ -1,5 +1,5 @@
 // Validates a spec and adds the defaults. This is the only file that knows the defaults.
-// Output: tables, layers with resolved channels ({column} or {value}), facet, scales, labels and theme.
+// Output: tables, layers with resolved channels ({column} or {value}), facet, scales, labels, info and theme.
 import GRAMMAR from "../grammar.json" with { type: "json" };
 import { colorOf, colorTokens, resolveTheme } from "./theme.js";
 
@@ -12,7 +12,8 @@ export function normalize(spec, overrides = {}) {
   if (!layers.length) throw new Error("plotto: the plot has no layers. Add one, for example .line() or .point()");
   const facet = resolveFacet(spec.facet);
   const labels = { ...defaultLabels(layers), ...spec.labels };
-  return { tables, layers, facet, scales: spec.scales ?? {}, labels, theme };
+  const info = spec.info?.entries?.length ? { entries: spec.info.entries, position: spec.info.position ?? "right" } : null;
+  return { tables, layers, facet, scales: spec.scales ?? {}, labels, info, theme };
 }
 
 function toTable({ columns }) {