repelY initializer

docs/.vitepress/config.ts

@@ -133,6 +133,7 @@ export default defineConfig({
           {text: "Interval", link: "/transforms/interval"},
           {text: "Map", link: "/transforms/map"},
           {text: "Normalize", link: "/transforms/normalize"},
+          {text: "Repel", link: "/transforms/repel"},
           {text: "Select", link: "/transforms/select"},
           {text: "Shift", link: "/transforms/shift"},
           {text: "Sort", link: "/transforms/sort"},

docs/data/cancer.data.ts

@@ -0,0 +1,9 @@
+import fs from "node:fs";
+import {csvParse} from "d3";
+
+export default {
+  watch: ["../public/data/cancer.csv"],
+  load([file]) {
+    return csvParse(fs.readFileSync(file, "utf-8"));
+  }
+};

docs/data/cancer.ts

@@ -0,0 +1,4 @@
+import {data} from "./cancer.data";
+import {autoType} from "d3";
+
+export default data.map(({...d}) => autoType(d));

docs/public/data/cancer.csv

@@ -0,0 +1 @@
+../../../test/data/cancer.csv

docs/transforms/repel.md

@@ -0,0 +1,136 @@
+<script setup>
+
+import * as Plot from "@observablehq/plot";
+import * as d3 from "d3";
+import {ref} from "vue";
+import cancer from "../data/cancer.ts";
+
+const minDistance = ref(11);
+
+const points = (() => {
+  const random = d3.randomLcg(42);
+  const data = [];
+  const points = [];
+  let step;
+  for (step = 0; step < 31; ++step) {
+    data.push(random());
+    points.push(...data.map((y, node) => ({step, y, node})));
+  }
+  points.push(...data.map((y, node) => ({step, y, node})));
+  return points;
+})();
+</script>
+
+# Repel transform <VersionBadge pr="1957" />
+
+Given a position dimension (either **x** or **y**), the **repel** transform rearranges the values along that dimension in such a way that the distance between nodes is greater than or equal to the minimum distance, and their visual order preserved. The [repelX transform](#repelX) rearranges the **x** (horizontal) position of each series of nodes sharing a common **y** (vertical) position; likewise the [repelY transform](#repelY) rearranges nodes vertically.
+
+The repel transform is commonly used to prevent superposition of labels on line charts. The example below, per [Edward Tufte](https://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0003nk), represents estimates of survival rates per type of cancer after 5, 10, 15 and 20 years. Each data point is labelled with its actual value (rounded to the unit). Labels in the last column indicate the type.
+
+:::plot
+```js
+Plot.plot({
+  width: 400,
+  height: 600,
+  marginRight: 60,
+  marginBottom: 20,
+  x: {
+    axis: "top",
+    domain: ["5 Year", "10 Year", "15 Year", "20 Year"],
+    label: null,
+    padding: 0
+  },
+  y: { axis: null, insetTop: 20 },
+  marks: [
+    Plot.line(cancer, {x: "year", y: "survival", z: "name", strokeWidth: 1}),
+    Plot.text(cancer, Plot.repelY(
+      Plot.group({
+        text:"first"
+      }, {
+        text: "survival",
+        x: "year",
+        y: "survival",
+        textAnchor: "end",
+        dx: 5,
+        fontVariant: "tabular-nums",
+        stroke: "var(--plot-background)",
+        strokeWidth: 7,
+        fill: "currentColor"
+      })
+    )),
+    Plot.text(cancer, Plot.repelY({
+      filter: d => d.year === "20 Year",
+      text: "name",
+      textAnchor: "start",
+      frameAnchor: "right",
+      dx: 10,
+      y: "survival"
+    }))
+  ],
+  caption: "Estimates of survival rate (%), per type of cancer"
+})
+```
+
+Without this transform, some of these labels would otherwise be masking each other. (Note the use of the [group](group.md) transform so that, when several labels share an identical position and text contents, only the first one is retained—and the others filtered out; for example, value 62 in the first column.)
+
+The **minDistance** option is a constant indicating the minimum distance between nodes, in pixels. It defaults to 11, about the height of a line of text with the default font size. (If zero, the transform is not applied.)
+
+The chart below shows how the positions are transformed as we repeatedly inject nodes into a collection at a random vertical position, and apply the repelY transform at each step (horizontal axis). Adjust the range slider below to see how the positions change with the minimum distance option:
+
+<p>
+  <label class="label-input">
+    minDistance:
+    <input type="range" v-model.number="minDistance" min="0" max="30" step="0.1">
+    <span style="font-variant-numeric: tabular-nums;">{{minDistance.toLocaleString("en-US")}}</span>
+  </label>
+</p>
+
+:::plot
+```js
+Plot.plot({
+  y: {axis: null, inset: 25},
+  color: {type: "categorical"},
+  marks: [
+    Plot.line(points, Plot.repelY(minDistance, {
+      x: "step",
+      stroke: "node",
+      y: "y",
+      curve: "basis",
+      strokeWidth: 1
+    })),
+    Plot.dot(points, Plot.repelY(minDistance, {
+      x: "step",
+      fill: "node",
+      r: (d) => d.step === d.node,
+      y: "y"
+    })),
+  ]
+})
+```
+:::
+
+The repel transform differs from the [dodge transform](./dodge.md) in that it only adjusts the nodes’ existing positions.
+
+The repel transform can be used with any mark that supports **x** and **y** position.
+
+## Repel options
+
+The repel transforms accept the following option:
+
+* **minDistance** — the number of pixels separating the nodes’ positions
+
+## repelY(*repelOptions*, *options*) {#repelY}
+
+```js
+Plot.repelY(minDistance, {x: "date", y: "value"})
+```
+
+Given marks arranged along the *y* axis, the repelY transform adjusts their vertical positions in such a way that two nodes are separated by at least *minDistance* pixels, avoiding overlapping. The order of the nodes is preserved. The *x* position channel, if present, is used to determine series on which the transform is applied, and left unchanged.
+
+## repelX(*repelOptions*, *options*) {#repelX}
+
+```js
+Plot.repelX({x: "value"})
+```
+
+Equivalent to Plot.repelY, but arranging the marks horizontally by returning an updated *x* position channel that avoids overlapping. The *y* position channel, if present, is used to determine series and left unchanged.

src/index.d.ts

@@ -53,6 +53,7 @@ export * from "./transforms/group.js";
 export * from "./transforms/hexbin.js";
 export * from "./transforms/map.js";
 export * from "./transforms/normalize.js";
+export * from "./transforms/repel.js";
 export * from "./transforms/select.js";
 export * from "./transforms/shift.js";
 export * from "./transforms/stack.js";

src/index.js

@@ -48,6 +48,7 @@ export {find, group, groupX, groupY, groupZ} from "./transforms/group.js";
 export {hexbin} from "./transforms/hexbin.js";
 export {normalize, normalizeX, normalizeY} from "./transforms/normalize.js";
 export {map, mapX, mapY} from "./transforms/map.js";
+export {repelX, repelY} from "./transforms/repel.js";
 export {shiftX, shiftY} from "./transforms/shift.js";
 export {window, windowX, windowY} from "./transforms/window.js";
 export {select, selectFirst, selectLast, selectMaxX, selectMaxY, selectMinX, selectMinY} from "./transforms/select.js";

src/transforms/repel.d.ts

@@ -0,0 +1,53 @@
+import type {ChannelValueSpec} from "../channel.js";
+import type {Initialized} from "./basic.js";
+
+/** Options for the repel transform. */
+export interface RepelOptions {
+  /**
+   * A constant in pixels describing the minimum distance between two nodes.
+   * Defaults to 11.
+   */
+  minDistance?: number;
+}
+
+/** Options for the repelX transform. */
+export interface RepelXOptions extends RepelOptions {
+  /**
+   * The vertical position. Nodes sharing the same vertical position will be
+   * rearranged horizontally together.
+   */
+  y?: ChannelValueSpec;
+}
+
+/** Options for the repelY transform. */
+export interface RepelYOptions extends RepelOptions {
+  /**
+   * The horizontal position. Nodes sharing the same horizontal position will be
+   * rearranged vertically together.
+   */
+  x?: ChannelValueSpec;
+}
+
+/**
+ * Given an **x** position channel, rearranges the values in such a way that the
+ * horizontal distance between nodes is greater than or equal to the minimum
+ * distance, and their visual order preserved. Nodes that share the same
+ * position and text are fused together.
+ *
+ * If *repelOptions* is a number, it is shorthand for the repel
+ * **minDistance**.
+ */
+export function repelX<T>(options?: T & RepelXOptions): Initialized<T>;
+export function repelX<T>(repelOptions?: RepelXOptions | RepelXOptions["minDistance"], options?: T): Initialized<T>;
+
+/**
+ * Given a **y** position channel, rearranges the values in such a way that the
+ * vertical distance between nodes is greater than or equal to the minimum
+ * distance, and their visual order preserved. Nodes that share the same
+ * position and text are fused together.
+ *
+ * If *repelOptions* is a number, it is shorthand for the repel
+ * **minDistance**.
+ */
+export function repelY<T>(options?: T & RepelYOptions): Initialized<T>;
+export function repelY<T>(dodgeOptions?: RepelYOptions | RepelYOptions["minDistance"], options?: T): Initialized<T>;

src/transforms/repel.js

@@ -0,0 +1,69 @@
+import {bisector, group} from "d3";
+import {valueof} from "../options.js";
+import {initializer} from "./basic.js";
+
+export function repelX(repelOptions = {}, options = {}) {
+  if (arguments.length === 1) [repelOptions, options] = mergeOptions(repelOptions);
+  const {minDistance = 11} = maybeDistance(repelOptions);
+  return repel("x", "y", minDistance, options);
+}
+
+export function repelY(repelOptions = {}, options = {}) {
+  if (arguments.length === 1) [repelOptions, options] = mergeOptions(repelOptions);
+  const {minDistance = 11} = maybeDistance(repelOptions);
+  return repel("y", "x", minDistance, options);
+}
+
+function maybeDistance(minDistance) {
+  return typeof minDistance === "number" ? {minDistance} : minDistance;
+}
+function mergeOptions({minDistance, ...options}) {
+  return [{minDistance}, options];
+}
+
+function repel(k, h, minDistance, options) {
+  const sk = k[0]; // e.g., the scale for x1 is x
+  if (typeof minDistance !== "number" || !(minDistance >= 0)) throw new Error(`unsupported minDistance ${minDistance}`);
+  if (minDistance === 0) return options;
+  return initializer(options, function (data, facets, {[k]: channel}, {[sk]: s}) {
+    const {value, scale} = channel ?? {};
+    if (value === undefined) throw new Error(`missing channel ${k}`);
+    const K = value.slice();
+    const H = valueof(data, options[h]);
+    const bisect = bisector((d) => d.lo).left;
+
+    for (const facet of facets) {
+      for (const index of H ? group(facet, (i) => H[i]).values() : [facet]) {
+        const groups = [];
+        for (const i of index) {
+          if (scale === sk) K[i] = s(K[i]);
+          let j = bisect(groups, K[i]);
+          groups.splice(j, 0, {lo: K[i], hi: K[i], items: [i]});
+
+          // Merge overlapping groups.
+          while (
+            groups[j + 1]?.lo < groups[j].hi + minDistance ||
+            (groups[j - 1]?.hi > groups[j].lo - minDistance && (--j, true))
+          ) {
+            const items = groups[j].items.concat(groups[j + 1].items);
+            const mid = (Math.min(groups[j].lo, groups[j + 1].lo) + Math.max(groups[j].hi, groups[j + 1].hi)) / 2;
+            const w = (minDistance * (items.length - 1)) / 2;
+            groups.splice(j, 2, {lo: mid - w, hi: mid + w, items});
+          }
+        }
+
+        // Reposition elements within each group.
+        for (const {lo, hi, items} of groups) {
+          if (items.length > 1) {
+            const dist = (hi - lo) / (items.length - 1);
+            items.sort((i, j) => K[i] - K[j]);
+            let p = lo;
+            for (const i of items) (K[i] = p), (p += dist);
+          }
+        }
+      }
+    }
+
+    return {data, facets, channels: {[k]: {value: K, source: null}}};
+  });
+}

test/data/README.md

@@ -30,6 +30,10 @@ https://www.bls.gov/
 Great Britain aeromagnetic survey
 https://www.bgs.ac.uk/datasets/gb-aeromagnetic-survey/
 
+## cancer.csv
+Edward Tufte, Beautiful Evidence
+https://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0003nk
+
 ## cars.csv
 1983 ASA Data Exposition
 http://lib.stat.cmu.edu/datasets/