mark initializers (#801)

* mark initializers

scale hex radius so that when hexagons touch, circles also touch without overlapping (#803)

(supersedes #795)

simpler hexagon

hexgrid

fix for unscaled channels

reorder

hexbin

fix #806; handle missing hint

infer channel scales

pass data to initializer

offset hexagonal grid slightly

simpler without destructuring

reinitialize (#823)

* document layouts (as "scale-aware transforms")

* document binWidth

* document the initialize option after 42ac4f0

* sort hex bins by radius (descending)
group by z
inline hexbin
binWidth is the distance between two centers

(rebased on mbostock/reinitialize)

* dodge

rebased on mbostock/reinitialize

* compose intializers

* use composeInitialize to make dodge composable

* add new channels as you compose initializers

* darker transform, to demonstrate composition with dodgeY

(added as an example, but we could promote it to a transform)

* a more generic "remap"

* jiggle layout
(using the same remap intializer as in the darkerDodge plot)

composeInitialize

* update dependencies

* Update README

* Update README

* tweak error message

* Fix Plot.hexbin default reducer, and simplify (#884)

* sort tests

* revert inlined hexbin implementation

* simpler z

* simpler scale application

* re-inline d3-hexbin

* use descendingDefined to sort

* coerce X and Y to numbers

* populate radius hint

* fix hexbin z; implicit group on symbol

* update tests

* expose initialize; rewrite remap

* tweak tests

* tweak tests

* tweak tests

* tweak tests

* tweak tests

* tweak tests

* tweak tests

* tweak tests

* fix scale association, numeric coercion

* fix numeric coercion

* remove comment

* initializers

* Update README

* preserve this with composed transforms

* no default sort for hexbin

* channel sorting; default sort by descending r

* don’t consume null sort

* don’t consume null sort, strictly

* Update README

Co-authored-by: Philippe Rivière <[email protected]>

Author: mbostock

README.md

@@ -35,21 +35,23 @@
   },
   "sideEffects": false,
   "devDependencies": {
+    "@rollup/plugin-commonjs": "22",
     "@rollup/plugin-json": "4",
     "@rollup/plugin-node-resolve": "13",
     "canvas": "2",
     "eslint": "8",
     "htl": "0.3",
     "js-beautify": "1",
     "jsdom": "19",
-    "mocha": "9",
+    "mocha": "10",
     "module-alias": "2",
     "rollup": "2",
     "rollup-plugin-terser": "7",
     "vite": "2"
   },
   "dependencies": {
     "d3": "^7.3.0",
+    "interval-tree-1d": "1",
     "isoformat": "0.2"
   },
   "engines": {

package.json

@@ -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()
   ]

rollup.config.js

@@ -1,7 +1,9 @@
 import {ascending, descending, rollup, sort} from "d3";
+import {ascendingDefined, descendingDefined} from "./defined.js";
 import {first, labelof, map, maybeValue, range, valueof} from "./options.js";
 import {registry} from "./scales/index.js";
 import {maybeReduce} from "./transforms/group.js";
+import {composeInitializer} from "./transforms/initializer.js";
 
 // TODO Type coercion?
 export function Channel(data, {scale, type, value, filter, hint}) {
@@ -15,19 +17,41 @@ export function Channel(data, {scale, type, value, filter, hint}) {
   };
 }
 
-export function channelSort(channels, facetChannels, data, options) {
+export function channelObject(channelDescriptors, data) {
+  const channels = {};
+  for (const channel of channelDescriptors) {
+    channels[channel.name] = Channel(data, channel);
+  }
+  return channels;
+}
+
+// TODO Use Float64Array for scales with numeric ranges, e.g. position?
+export function valueObject(channels, scales) {
+  const values = {};
+  for (const channelName in channels) {
+    const {scale: scaleName, value} = channels[channelName];
+    const scale = scales[scaleName];
+    values[channelName] = scale === undefined ? value : Array.from(value, scale);
+  }
+  return values;
+}
+
+// Note: mutates channel.domain! This is set to a function so that it is lazily
+// computed; i.e., if the scale’s domain is set explicitly, that takes priority
+// over the sort option, and we don’t need to do additional work.
+export function channelDomain(channels, facetChannels, data, options) {
   const {reverse: defaultReverse, reduce: defaultReduce = true, limit: defaultLimit} = options;
   for (const x in options) {
-    if (!registry.has(x)) continue; // ignore unknown scale keys
+    if (!registry.has(x)) continue; // ignore unknown scale keys (including generic options)
     let {value: y, reverse = defaultReverse, reduce = defaultReduce, limit = defaultLimit} = maybeValue(options[x]);
     if (reverse === undefined) reverse = y === "width" || y === "height"; // default to descending for lengths
     if (reduce == null || reduce === false) continue; // disabled reducer
-    const X = channels.find(([, {scale}]) => scale === x) || facetChannels && facetChannels.find(([, {scale}]) => scale === x);
+    const X = findScaleChannel(channels, x) || facetChannels && findScaleChannel(facetChannels, x);
     if (!X) throw new Error(`missing channel for scale: ${x}`);
-    const XV = X[1].value;
+    const XV = X.value;
     const [lo = 0, hi = Infinity] = limit && typeof limit[Symbol.iterator] === "function" ? limit : limit < 0 ? [limit] : [0, limit];
     if (y == null) {
-      X[1].domain = () => {
+      X.domain = () => {
         let domain = XV;
         if (reverse) domain = domain.slice().reverse();
         if (lo !== 0 || hi !== Infinity) domain = domain.slice(lo, hi);
@@ -39,7 +63,7 @@ export function channelSort(channels, facetChannels, data, options) {
           : y === "width" ? difference(channels, "x1", "x2")
           : values(channels, y, y === "y" ? "y2" : y === "x" ? "x2" : undefined);
       const reducer = maybeReduce(reduce === true ? "max" : reduce, YV);
-      X[1].domain = () => {
+      X.domain = () => {
         let domain = rollup(range(XV), I => reducer.reduce(I, YV), i => XV[i]);
         domain = sort(domain, reverse ? descendingGroup : ascendingGroup);
         if (lo !== 0 || hi !== Infinity) domain = domain.slice(lo, hi);
@@ -49,16 +73,36 @@ export function channelSort(channels, facetChannels, data, options) {
   }
 }
 
+function sortInitializer(name, compare = ascendingDefined) {
+  return (data, facets, {[name]: V}) => {
+    if (!V) throw new Error(`missing channel: ${name}`);
+    V = V.value;
+    const compareValue = (i, j) => compare(V[i], V[j]);
+    return {facets: facets.map(I => I.slice().sort(compareValue))};
+  };
+}
+
+export function channelSort(initializer, {channel, reverse}) {
+  return composeInitializer(initializer, sortInitializer(channel, reverse ? descendingDefined : ascendingDefined));
+}
+
+function findScaleChannel(channels, scale) {
+  for (const name in channels) {
+    const channel = channels[name];
+    if (channel.scale === scale) return channel;
+  }
+}
+
 function difference(channels, k1, k2) {
   const X1 = values(channels, k1);
   const X2 = values(channels, k2);
   return map(X2, (x2, i) => Math.abs(x2 - X1[i]), Float64Array);
 }
 
 function values(channels, name, alias) {
-  let channel = channels.find(([n]) => n === name);
-  if (!channel && alias !== undefined) channel = channels.find(([n]) => n === alias);
-  if (channel) return channel[1].value;
+  let channel = channels[name];
+  if (!channel && alias !== undefined) channel = channels[alias];
+  if (channel) return channel.value;
   throw new Error(`missing channel: ${name}`);
 }
 

src/channel.js

@@ -27,11 +27,3 @@ export function positive(x) {
 export function negative(x) {
   return x < 0 && isFinite(x) ? x : NaN;
 }
-
-export function firstof(...values) {
-  for (const v of values) {
-    if (v !== undefined) {
-      return v;
-    }
-  }
-}

src/defined.js

@@ -4,8 +4,9 @@ export {Arrow, arrow} from "./marks/arrow.js";
 export {BarX, BarY, barX, barY} from "./marks/bar.js";
 export {boxX, boxY} from "./marks/box.js";
 export {Cell, cell, cellX, cellY} from "./marks/cell.js";
-export {Dot, dot, dotX, dotY} from "./marks/dot.js";
+export {Dot, dot, dotX, dotY, circle, hexagon} from "./marks/dot.js";
 export {Frame, frame} from "./marks/frame.js";
+export {Hexgrid, hexgrid} from "./marks/hexgrid.js";
 export {Image, image} from "./marks/image.js";
 export {Line, line, lineX, lineY} from "./marks/line.js";
 export {Link, link} from "./marks/link.js";
@@ -18,7 +19,10 @@ export {Vector, vector, vectorX, vectorY} from "./marks/vector.js";
 export {valueof, column} from "./options.js";
 export {filter, reverse, sort, shuffle, basic as transform} from "./transforms/basic.js";
 export {bin, binX, binY} from "./transforms/bin.js";
+export {dodgeX, dodgeY} from "./transforms/dodge.js";
 export {group, groupX, groupY, groupZ} from "./transforms/group.js";
+export {hexbin} from "./transforms/hexbin.js";
+export {initializer} from "./transforms/initializer.js";
 export {normalize, normalizeX, normalizeY} from "./transforms/normalize.js";
 export {map, mapX, mapY} from "./transforms/map.js";
 export {window, windowX, windowY} from "./transforms/window.js";

src/index.js

@@ -1,8 +1,9 @@
 import {create, path, symbolCircle} from "d3";
 import {positive} from "../defined.js";
-import {identity, maybeFrameAnchor, maybeNumberChannel, maybeSymbolChannel, maybeTuple} from "../options.js";
+import {identity, maybeFrameAnchor, maybeNumberChannel, maybeTuple} from "../options.js";
 import {Mark} from "../plot.js";
 import {applyChannelStyles, applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, offset} from "../style.js";
+import {maybeSymbolChannel} from "../symbols.js";
 
 const defaults = {
   ariaLabel: "dot",
@@ -26,7 +27,7 @@ export class Dot extends Mark {
         {name: "rotate", value: vrotate, optional: true},
         {name: "symbol", value: vsymbol, scale: "symbol", optional: true}
       ],
-      options,
+      vr === undefined || options.sort !== undefined ? options : {...options, sort: {channel: "r", reverse: true}},
       defaults
     );
     this.r = cr;
@@ -100,3 +101,11 @@ export function dotX(data, {x = identity, ...options} = {}) {
 export function dotY(data, {y = identity, ...options} = {}) {
   return new Dot(data, {...options, y});
 }
+
+export function circle(data, options) {
+  return dot(data, {...options, symbol: "circle"});
+}
+
+export function hexagon(data, options) {
+  return dot(data, {...options, symbol: "hexagon"});
+}

src/marks/dot.js

@@ -0,0 +1,46 @@
+import {create} from "d3";
+import {Mark} from "../plot.js";
+import {number} from "../options.js";
+import {applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
+import {sqrt4_3} from "../symbols.js";
+import {ox, oy} from "../transforms/hexbin.js";
+
+const defaults = {
+  ariaLabel: "hexgrid",
+  fill: "none",
+  stroke: "currentColor",
+  strokeOpacity: 0.1
+};
+
+export function hexgrid(options) {
+  return new Hexgrid(options);
+}
+
+export class Hexgrid extends Mark {
+  constructor({binWidth = 20, clip = true, ...options} = {}) {
+    super(undefined, undefined, {clip, ...options}, defaults);
+    this.binWidth = number(binWidth);
+  }
+  render(index, scales, channels, dimensions) {
+    const {dx, dy, binWidth} = this;
+    const {marginTop, marginRight, marginBottom, marginLeft, width, height} = dimensions;
+    const x0 = marginLeft - ox, x1 = width - marginRight - ox, y0 = marginTop - oy, y1 = height - marginBottom - oy;
+    const rx = binWidth / 2, ry = rx * sqrt4_3, hy = ry / 2, wx = rx * 2, wy = ry * 1.5;
+    const path = `m0,${-ry}l${rx},${hy}v${ry}l${-rx},${hy}`;
+    const i0 = Math.floor(x0 / wx), i1 = Math.ceil(x1 / wx);
+    const j0 = Math.floor((y0 + hy) / wy), j1 = Math.ceil((y1 - hy) / wy) + 1;
+    const m = [];
+    for (let j = j0; j < j1; ++j) {
+      for (let i = i0; i < i1; ++i) {
+        m.push(`M${i * wx + (j & 1) * rx},${j * wy}${path}`);
+      }
+    }
+    return create("svg:g")
+        .call(applyIndirectStyles, this, dimensions)
+        .call(g => g.append("path")
+          .call(applyDirectStyles, this)
+          .call(applyTransform, null, null, offset + dx + ox, offset + dy + oy)
+          .attr("d", m.join("")))
+      .node();
+  }
+}

src/marks/hexgrid.js

@@ -1,7 +1,5 @@
 import {parse as isoParse} from "isoformat";
 import {color, descending, quantile} from "d3";
-import {symbolAsterisk, symbolDiamond2, symbolPlus, symbolSquare2, symbolTriangle2, symbolX as symbolTimes} from "d3";
-import {symbolCircle, symbolCross, symbolDiamond, symbolSquare, symbolStar, symbolTriangle, symbolWye} from "d3";
 
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
 const TypedArray = Object.getPrototypeOf(Uint8Array);
@@ -23,6 +21,7 @@ export const indexOf = (d, i) => i;
 export const identity = {transform: d => d};
 export const zero = () => 0;
 export const one = () => 1;
+export const yes = () => true;
 export const string = x => x == null ? x : `${x}`;
 export const number = x => x == null ? x : +x;
 export const boolean = x => x == null ? x : !!x;
@@ -319,48 +318,6 @@ export function isRound(value) {
   return /^\s*round\s*$/i.test(value);
 }
 
-const symbols = new Map([
-  ["asterisk", symbolAsterisk],
-  ["circle", symbolCircle],
-  ["cross", symbolCross],
-  ["diamond", symbolDiamond],
-  ["diamond2", symbolDiamond2],
-  ["plus", symbolPlus],
-  ["square", symbolSquare],
-  ["square2", symbolSquare2],
-  ["star", symbolStar],
-  ["times", symbolTimes],
-  ["triangle", symbolTriangle],
-  ["triangle2", symbolTriangle2],
-  ["wye", symbolWye]
-]);
-
-function isSymbolObject(value) {
-  return value && typeof value.draw === "function";
-}
-
-export function isSymbol(value) {
-  if (isSymbolObject(value)) return true;
-  if (typeof value !== "string") return false;
-  return symbols.has(value.toLowerCase());
-}
-
-export function maybeSymbol(symbol) {
-  if (symbol == null || isSymbolObject(symbol)) return symbol;
-  const value = symbols.get(`${symbol}`.toLowerCase());
-  if (value) return value;
-  throw new Error(`invalid symbol: ${symbol}`);
-}
-
-export function maybeSymbolChannel(symbol) {
-  if (symbol == null || isSymbolObject(symbol)) return [undefined, symbol];
-  if (typeof symbol === "string") {
-    const value = symbols.get(`${symbol}`.toLowerCase());
-    if (value) return [undefined, value];
-  }
-  return [symbol, undefined];
-}
-
 export function maybeFrameAnchor(value = "middle") {
   return keyword(value, "frameAnchor", ["middle", "top-left", "top", "top-right", "right", "bottom-right", "bottom", "bottom-left", "left"]);
 }