Merge branch 'main' into fil/daspect

Author: Fil

CHANGELOG.md

@@ -1,5 +1,41 @@
 # Observable Plot - Changelog
 
+## 0.5.0
+
+*Not yet released. These are forthcoming changes in the main branch.*
+
+Plot now supports mark initializers via the **initializer** option. Initializers can transform data, channels, and indexes. Unlike data transforms which operate in abstract data space, initializers can operate in screen space such as pixel coordinates and colors. For example, initializers can modify a marks’ positions to avoid occlusion. The new hexbin and dodge transforms are implemented as mark initializers.
+
+The new hexbin transform functions similarly to the bin transform, except it aggregates both *x* and *y* into hexagonal bins before reducing. The size of the hexagons can be specified with the **binWidth** option, which controls the width of the (pointy-topped) hexagons.
+
+The new hexgrid decoration mark draws a hexagonal grid. It is intended to be used with the hexbin transform as an alternative to the default horizontal and vertical axis grid.
+
+The dot mark now supports the *hexagon* symbol type for pointy-topped hexagons. The new circle and hexagon marks are convenience shorthand for dot marks with the *circle* and *hexagon* symbol, respectively. The dotX, dotY, textX, and textY marks now support the **interval** option.
+
+The new dodge transform can be used to produce beeswarm plots. Given an *x* channel representing the desired horizontal position of circles, the dodgeY transform derives a new *y* (vertical position) channel such that the circles do not overlap; the dodgeX transform similarly derives a new *x* channel given a *y* channel. If an *r* channel is specified, the circles may have varying radius.
+
+The mark **sort** option now supports index sorting. For example, to sort dots by ascending radius:
+
+~~~js
+Plot.dot(earthquakes, {x: "longitude", y: "latitude", r: "intensity", sort: {channel: "r"}})
+~~~
+
+The dot mark now sorts by descending radius by default to reduce occlusion.
+
+The **zero** scale option (like the **nice** and **clamp** options) may now be specified as a top-level option, applying to all quantitative scales.
+
+The rule mark now correctly respects the **dx** and **dy** options.
+
+Fix crash when using area mark shorthand.
+
+Marks can now define a channel hint to set the default range of the *r* scale. This is used by the hexbin transform when producing an *r* output channel.
+
+Improve performance of internal array operations, including type coercion.
+
+[breaking] Color scales with diverging color schemes now default to the *diverging* scale type instead of the *linear* scale type.
+
+[breaking] *mark*.initialize return signature.
+
 ## 0.4.3
 
 [Released April 12, 2022.](https://github.com/observablehq/plot/releases/tag/v0.4.3)

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 : map(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,39 @@ export function channelSort(channels, facetChannels, data, options) {
   }
 }
 
+function sortInitializer(name, optional, compare = ascendingDefined) {
+  return (data, facets, {[name]: V}) => {
+    if (!V) {
+      if (optional) return {}; // do nothing if given channel does not exist
+      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, optional, reverse}) {
+  return composeInitializer(initializer, sortInitializer(channel, optional, 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,5 +1,6 @@
 import {create, quantize, interpolateNumber, piecewise, format, scaleBand, scaleLinear, axisBottom} from "d3";
 import {inferFontVariant} from "../axes.js";
+import {map} from "../options.js";
 import {interpolatePiecewise} from "../scales/quantitative.js";
 import {applyInlineStyles, impliedString, maybeClassName} from "../style.js";
 
@@ -115,7 +116,7 @@ export function legendRamp(color, {
         .attr("height", height - marginTop - marginBottom)
         .attr("fill", d => d);
 
-    ticks = Array.from(thresholds, (_, i) => i);
+    ticks = map(thresholds, (_, i) => i);
     tickFormat = i => thresholdFormat(thresholds[i], i);
   }
 

src/legends/ramp.js

@@ -1,8 +1,10 @@
 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";
+import {maybeIntervalMidX, maybeIntervalMidY} from "../transforms/interval.js";
 
 const defaults = {
   ariaLabel: "dot",
@@ -26,7 +28,7 @@ export class Dot extends Mark {
         {name: "rotate", value: vrotate, optional: true},
         {name: "symbol", value: vsymbol, scale: "symbol", optional: true}
       ],
-      options,
+      options.sort === undefined ? {...options, sort: {channel: "r", optional: true, reverse: true}} : options,
       defaults
     );
     this.r = cr;
@@ -94,9 +96,17 @@ export function dot(data, {x, y, ...options} = {}) {
 }
 
 export function dotX(data, {x = identity, ...options} = {}) {
-  return new Dot(data, {...options, x});
+  return new Dot(data, maybeIntervalMidY({...options, x}));
 }
 
 export function dotY(data, {y = identity, ...options} = {}) {
-  return new Dot(data, {...options, y});
+  return new Dot(data, maybeIntervalMidX({...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();
+  }
+}