dodge (beeswarm)

Author: mbostock

package.json

@@ -35,6 +35,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
+    "@rollup/plugin-commonjs": "^21.0.1",
     "@rollup/plugin-json": "4",
     "@rollup/plugin-node-resolve": "13",
     "canvas": "2",
@@ -50,6 +51,7 @@
   },
   "dependencies": {
     "d3": "^7.3.0",
+    "interval-tree-1d": "1",
     "isoformat": "0.2"
   },
   "engines": {

rollup.config.js

@@ -1,5 +1,6 @@
 import fs from "fs";
 import {terser} from "rollup-plugin-terser";
+import commonjs from "@rollup/plugin-commonjs";
 import json from "@rollup/plugin-json";
 import node from "@rollup/plugin-node-resolve";
 import * as meta from "./package.json";
@@ -25,6 +26,7 @@ const config = {
     banner: `// ${meta.name} v${meta.version} Copyright ${copyrights.join(", ")}`
   },
   plugins: [
+    commonjs(),
     json(),
     node()
   ]

src/index.js

@@ -14,6 +14,7 @@ export {Text, text, textX, textY} from "./marks/text.js";
 export {TickX, TickY, tickX, tickY} from "./marks/tick.js";
 export {Vector, vector} from "./marks/vector.js";
 export {valueof} from "./options.js";
+export {dodgeX, dodgeY} from "./layouts/dodge.js";
 export {filter, reverse, sort, shuffle} from "./transforms/basic.js";
 export {bin, binX, binY} from "./transforms/bin.js";
 export {group, groupX, groupY, groupZ} from "./transforms/group.js";

src/layouts/dodge.js

@@ -0,0 +1,91 @@
+import {max} from "d3";
+import IntervalTree from "interval-tree-1d";
+import {maybeNumberChannel} from "../options.js";
+
+const anchorXLeft = ({marginLeft}) => [1, marginLeft];
+const anchorXRight = ({width, marginRight}) => [-1, width - marginRight];
+const anchorXMiddle = ({width, marginLeft, marginRight}) => [0, (marginLeft + width - marginRight) / 2];
+const anchorYTop = ({marginTop}) => [1, marginTop];
+const anchorYBottom = ({height, marginBottom}) => [-1, height - marginBottom];
+const anchorYMiddle = ({height, marginTop, marginBottom}) => [0, (marginTop + height - marginBottom) / 2];
+
+function maybeDodge(options) {
+  return typeof options === "string" ? {anchor: options} : options;
+}
+
+export function dodgeX(dodgeOptions = {}, options = {}) {
+  if (arguments.length === 1) [options, dodgeOptions] = [dodgeOptions, options];
+  let {anchor = "left", padding} = maybeDodge(dodgeOptions);
+  switch (`${anchor}`.toLowerCase()) {
+    case "left": anchor = anchorXLeft; break;
+    case "right": anchor = anchorXRight; break;
+    case "middle": anchor = anchorXMiddle; break;
+    default: throw new Error(`unknown dodge anchor: ${anchor}`);
+  }
+  return dodge("x", "y", anchor, padding, options);
+}
+
+export function dodgeY(dodgeOptions = {}, options = {}) {
+  if (arguments.length === 1) [options, dodgeOptions] = [dodgeOptions, options];
+  let {anchor = "bottom", padding} = maybeDodge(dodgeOptions);
+  switch (`${anchor}`.toLowerCase()) {
+    case "top": anchor = anchorYTop; break;
+    case "bottom": anchor = anchorYBottom; break;
+    case "middle": anchor = anchorYMiddle; break;
+    default: throw new Error(`unknown dodge anchor: ${anchor}`);
+  }
+  return dodge("y", "x", anchor, padding, options);
+}
+
+function dodge(y, x, anchor, padding = 1, options) {
+  const [, r] = maybeNumberChannel(options.r, 3);
+  if (options[x] == null) throw new Error(`missing channel: ${x}`);
+  return {
+    ...options,
+    layout(I, scales, values, dimensions) { // TODO wrap previous layout?
+      let {[x]: X, r: R} = values;
+      let [ky, ty] = anchor(dimensions);
+      const compare = ky ? compareAscending : compareSymmetric;
+      if (ky) ty += ky * ((R ? max(I, i => R[i]) : r) + padding); else ky = 1;
+      if (!R) R = new Float64Array(X.length).fill(r);
+      const Y = new Float64Array(X.length);
+      const tree = IntervalTree();
+      for (const i of I) {
+        const intervals = [];
+        const l = X[i] - R[i];
+        const r = X[i] + R[i];
+
+        // For any previously placed circles that may overlap this circle, compute
+        // the y-positions that place this circle tangent to these other circles.
+        // https://observablehq.com/@mbostock/circle-offset-along-line
+        tree.queryInterval(l - padding, r + padding, ([,, j]) => {
+          const yj = Y[j];
+          const dx = X[i] - X[j];
+          const dr = R[i] + padding + R[j];
+          const dy = Math.sqrt(dr * dr - dx * dx);
+          intervals.push([yj - dy, yj + dy]);
+        });
+
+        // Find the best y-value where this circle can fit.
+        for (let y of intervals.flat().sort(compare)) {
+          if (intervals.every(([lo, hi]) => y <= lo || y >= hi)) {
+            Y[i] = y;
+            break;
+          }
+        }
+
+        // Insert the placed circle into the interval tree.
+        tree.insert([l, r, i]);
+      }
+      return {...values, [y]: Y.map(y => y * ky + ty)};
+    }
+  };
+}
+
+function compareSymmetric(a, b) {
+  return Math.abs(a) - Math.abs(b);
+}
+
+function compareAscending(a, b) {
+  return (a < 0) - (b < 0) || (a - b);
+}

src/plot.js

@@ -95,8 +95,9 @@ export function plot(options = {}) {
 
   for (const mark of marks) {
     const channels = markChannels.get(mark) ?? [];
-    const values = applyScales(channels, scales);
+    let values = applyScales(channels, scales);
     const index = filter(markIndex.get(mark), channels, values);
+    if (mark.layout != null) values = mark.layout(index, scales, values, dimensions);
     const node = mark.render(index, scales, values, dimensions, axes);
     if (node != null) svg.appendChild(node);
   }
@@ -132,9 +133,10 @@ function filter(index, channels, values) {
 
 export class Mark {
   constructor(data, channels = [], options = {}, defaults) {
-    const {facet = "auto", sort, dx, dy} = options;
+    const {layout, facet = "auto", sort, dx, dy} = options;
     const names = new Set();
     this.data = data;
+    this.layout = layout;
     this.sort = isOptions(sort) ? sort : null;
     this.facet = facet == null || facet === false ? null : keyword(facet === true ? "include" : facet, "facet", ["auto", "include", "exclude"]);
     const {transform} = basic(options);