sort, reverse and shuffle can be applied as initializers (#908)

* sort, reverse and shuffle can be applied as initialzers

if sort is applied on a string such as "y" and a (possibly derived) y channel exists, it is preferred to sorting on data[i]["y"]; which allows to sort("y", dodgeY()).

closes #907

* apply helper; filter initializer

* basic transforms for initializers

* avoid circular import

* prefer basic initializer

* generalize channel sorting

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

README.md

@@ -424,8 +424,6 @@ Plot.plot({
 
 ### Sort options
 
-#### Ordinal domain sorting
-
 If an ordinal scale’s domain is not set, it defaults to natural ascending order; to order the domain by associated values in another dimension, either compute the domain manually (consider [d3.groupSort](https://github.com/d3/d3-array/blob/main/README.md#groupSort)) or use an associated mark’s **sort** option. For example, to sort bars by ascending frequency rather than alphabetically by letter:
 
 ```js
@@ -464,20 +462,6 @@ If the input channel is *data*, then the reducer is passed groups of the mark’
 
 Note: when the value of the sort option is a string or a function, it is interpreted as a [basic sort transform](#transforms). To use both sort options and a sort transform, use [Plot.sort](#plotsortorder-options).
 
-#### Index sorting
-
-In addition to the [sort transform](#transforms) which allow sorting by data, you can use the **sort** option to sort marks by some other channel value. For example, to sort dots by descending radius:
-
-```js
-Plot.dot(earthquakes, {x: "longitude", y: "latitude", r: "intensity", sort: {channel: "r", reverse: true}})
-```
-
-In fact, sorting by descending radius is the default behavior of the dot mark when an *r* channel is specified. You can disable this by setting the sort explicitly to null:
-
-```js
-Plot.dot(earthquakes, {x: "longitude", y: "latitude", r: "intensity", sort: null})
-```
-
 ### Facet options
 
 The *facet* option enables [faceting](https://observablehq.com/@observablehq/plot-facets). When faceting, two additional band scales may be configured:
@@ -1475,6 +1459,18 @@ Plot.barY(alphabet.filter(d => /[aeiou]/i.test(d.letter)), {x: "letter", y: "fre
 
 Together the **sort** and **reverse** transforms allow control over *z* order, which can be important when addressing overplotting. If the sort option is a function but does not take exactly one argument, it is assumed to be a [comparator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description); otherwise, the sort option is interpreted as a channel value definition and thus may be either as a column name, accessor function, or array of values.
 
+The sort transform can also be used to sort on channel values, including those derived by [initializers](#initializers). For example, to sort dots by descending radius:
+
+```js
+Plot.dot(earthquakes, {x: "longitude", y: "latitude", r: "intensity", sort: {channel: "r", order: "descending}})
+```
+
+In fact, sorting by descending radius is the default behavior of the dot mark when an *r* channel is specified. You can disable this by setting the sort explicitly to null:
+
+```js
+Plot.dot(earthquakes, {x: "longitude", y: "latitude", r: "intensity", sort: null})
+```
+
 For greater control, you can also implement a [custom transform function](#custom-transforms):
 
 * **transform** - a function that returns transformed *data* and *index*

src/channel.js

@@ -1,9 +1,7 @@
 import {ascending, descending, rollup, sort} from "d3";
-import {ascendingDefined, descendingDefined} from "./defined.js";
 import {first, isIterable, 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}) {
@@ -73,22 +71,6 @@ export function channelDomain(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];

src/index.js

@@ -17,12 +17,11 @@ export {TickX, TickY, tickX, tickY} from "./marks/tick.js";
 export {tree, cluster} from "./marks/tree.js";
 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 {filter, reverse, sort, shuffle, basic as transform, initializer} 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/marks/dot.js

@@ -4,6 +4,7 @@ import {identity, maybeFrameAnchor, maybeNumberChannel, maybeTuple} from "../opt
 import {Mark} from "../plot.js";
 import {applyChannelStyles, applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, offset} from "../style.js";
 import {maybeSymbolChannel} from "../symbols.js";
+import {sort} from "../transforms/basic.js";
 import {maybeIntervalMidX, maybeIntervalMidY} from "../transforms/interval.js";
 
 const defaults = {
@@ -28,7 +29,7 @@ export class Dot extends Mark {
         {name: "rotate", value: vrotate, optional: true},
         {name: "symbol", value: vsymbol, scale: "symbol", optional: true}
       ],
-      options.sort === undefined ? {...options, sort: {channel: "r", optional: true, reverse: true}} : options,
+      options.sort === undefined && options.reverse === undefined ? sort({channel: "r", order: "descending"}, options) : options,
       defaults
     );
     this.r = cr;

src/options.js

@@ -114,6 +114,12 @@ export function isOptions(option) {
   return isObject(option) && typeof option.transform !== "function";
 }
 
+// Disambiguates a sort transform (e.g., {sort: "date"}) from a channel domain
+// sort definition (e.g., {sort: {y: "x"}}).
+export function isDomainSort(sort) {
+  return isOptions(sort) && sort.value === undefined && sort.channel === undefined;
+}
+
 // For marks specified either as [0, x] or [x1, x2], such as areas and bars.
 export function maybeZero(x, x1, x2, x3 = identity) {
   if (x1 === undefined && x2 === undefined) { // {x} or {}

src/plot.js

@@ -1,14 +1,14 @@
 import {create, cross, difference, groups, InternMap, select} from "d3";
 import {Axes, autoAxisTicks, autoScaleLabels} from "./axes.js";
-import {Channel, channelObject, channelDomain, channelSort, valueObject} from "./channel.js";
+import {Channel, channelObject, channelDomain, valueObject} from "./channel.js";
 import {defined} from "./defined.js";
 import {Dimensions} from "./dimensions.js";
 import {Legends, exposeLegends} from "./legends.js";
-import {arrayify, isOptions, isScaleOptions, keyword, map, range, second, where, yes} from "./options.js";
+import {arrayify, isDomainSort, isScaleOptions, keyword, map, range, second, where, yes} from "./options.js";
 import {Scales, ScaleFunctions, autoScaleRange, exposeScales} from "./scales.js";
 import {registry as scaleRegistry} from "./scales/index.js";
 import {applyInlineStyles, maybeClassName, maybeClip, styles} from "./style.js";
-import {basic} from "./transforms/basic.js";
+import {basic, initializer} from "./transforms/basic.js";
 import {consumeWarnings} from "./warnings.js";
 
 export function plot(options = {}) {
@@ -248,14 +248,13 @@ export function plot(options = {}) {
 
 export class Mark {
   constructor(data, channels = [], options = {}, defaults) {
-    const {facet = "auto", sort, dx, dy, clip, initializer, channels: extraChannels} = options;
+    const {facet = "auto", sort, dx, dy, clip, channels: extraChannels} = options;
     const names = new Set();
     this.data = data;
-    this.sort = isOptions(sort) ? sort : null;
-    this.initializer = this.sort?.channel == null ? initializer : channelSort(initializer, this.sort);
+    this.sort = isDomainSort(sort) ? sort : null;
+    this.initializer = initializer(options).initializer;
+    this.transform = this.initializer ? options.transform : basic(options).transform;
     this.facet = facet == null || facet === false ? null : keyword(facet === true ? "include" : facet, "facet", ["auto", "include", "exclude"]);
-    const {transform} = basic(options);
-    this.transform = transform;
     if (extraChannels !== undefined) channels = [...channels, ...extraChannels.filter(e => !channels.some(c => c.name === e.name))];
     if (defaults !== undefined) channels = [...channels, ...styles(this, options, defaults)];
     this.channels = channels.filter(channel => {

src/scales/ordinal.js

@@ -106,7 +106,7 @@ function maybeRound(scale, channels, options) {
 function inferDomain(channels) {
   const values = new InternSet();
   for (const {value, domain} of channels) {
-    if (domain !== undefined) return domain(); // see channelSort
+    if (domain !== undefined) return domain(); // see channelDomain
     if (value === undefined) continue;
     for (const v of value) values.add(v);
   }

src/transforms/basic.js

@@ -1,6 +1,6 @@
 import {randomLcg} from "d3";
-import {ascendingDefined} from "../defined.js";
-import {arrayify, isOptions, valueof} from "../options.js";
+import {ascendingDefined, descendingDefined} from "../defined.js";
+import {arrayify, isDomainSort, isOptions, maybeValue, valueof} from "../options.js";
 
 // If both t1 and t2 are defined, returns a composite transform that first
 // applies t1 and then applies t2.
@@ -14,17 +14,37 @@ export function basic({
 } = {}, t2) {
   if (t1 === undefined) { // explicit transform overrides filter, sort, and reverse
     if (f1 != null) t1 = filterTransform(f1);
-    if (s1 != null && !isOptions(s1)) t1 = composeTransform(t1, sortTransform(s1));
+    if (s1 != null && !isDomainSort(s1)) t1 = composeTransform(t1, sortTransform(s1));
     if (r1) t1 = composeTransform(t1, reverseTransform);
   }
   if (t2 != null && i1 != null) throw new Error("transforms cannot be applied after initializers");
   return {
     ...options,
-    ...(s1 === null || isOptions(s1)) && {sort: s1},
+    ...(s1 === null || isDomainSort(s1)) && {sort: s1},
     transform: composeTransform(t1, t2)
   };
 }
 
+// If both i1 and i2 are defined, returns a composite initializer that first
+// applies i1 and then applies i2.
+export function initializer({
+  filter: f1,
+  sort: s1,
+  reverse: r1,
+  initializer: i1,
+  ...options
+} = {}, i2) {
+  if (i1 === undefined) { // explicit initializer overrides filter, sort, and reverse
+    if (f1 != null) i1 = filterTransform(f1);
+    if (s1 != null && !isDomainSort(s1)) i1 = composeInitializer(i1, sortTransform(s1));
+    if (r1) i1 = composeInitializer(i1, reverseTransform);
+  }
+  return {
+    ...options,
+    initializer: composeInitializer(i1, i2)
+  };
+}
+
 function composeTransform(t1, t2) {
   if (t1 == null) return t2 === null ? undefined : t2;
   if (t2 == null) return t1 === null ? undefined : t1;
@@ -34,8 +54,23 @@ function composeTransform(t1, t2) {
   };
 }
 
+function composeInitializer(i1, i2) {
+  if (i1 == null) return i2 === null ? undefined : i2;
+  if (i2 == null) return i1 === null ? undefined : i1;
+  return function(data, facets, channels, scales, dimensions) {
+    let c1, d1, f1, c2, d2, f2;
+    ({data: d1 = data, facets: f1 = facets, channels: c1} = i1.call(this, data, facets, channels, scales, dimensions));
+    ({data: d2 = d1, facets: f2 = f1, channels: c2} = i2.call(this, d1, f1, {...channels, ...c1}, scales, dimensions));
+    return {data: d2, facets: f2, channels: {...c1, ...c2}};
+  };
+}
+
+function apply(options, t) {
+  return (options.initializer != null ? initializer : basic)(options, t);
+}
+
 export function filter(value, options) {
-  return basic(options, filterTransform(value));
+  return apply(options, filterTransform(value));
 }
 
 function filterTransform(value) {
@@ -46,36 +81,53 @@ function filterTransform(value) {
 }
 
 export function reverse(options) {
-  return {...basic(options, reverseTransform), sort: null};
+  return {...apply(options, reverseTransform), sort: null};
 }
 
 function reverseTransform(data, facets) {
   return {data, facets: facets.map(I => I.slice().reverse())};
 }
 
 export function shuffle({seed, ...options} = {}) {
-  return {...basic(options, sortValue(seed == null ? Math.random : randomLcg(seed))), sort: null};
+  return {...apply(options, sortValue(seed == null ? Math.random : randomLcg(seed))), sort: null};
 }
 
 export function sort(value, options) {
-  return {...basic(options, sortTransform(value)), sort: null};
+  return {...(isOptions(value) && value.channel !== undefined ? initializer : apply)(options, sortTransform(value)), sort: null};
 }
 
 function sortTransform(value) {
-  return (typeof value === "function" && value.length !== 1 ? sortCompare : sortValue)(value);
+  return (typeof value === "function" && value.length !== 1 ? sortData : sortValue)(value);
 }
 
-function sortCompare(compare) {
+function sortData(compare) {
   return (data, facets) => {
     const compareData = (i, j) => compare(data[i], data[j]);
     return {data, facets: facets.map(I => I.slice().sort(compareData))};
   };
 }
 
 function sortValue(value) {
-  return (data, facets) => {
-    const V = valueof(data, value);
-    const compareValue = (i, j) => ascendingDefined(V[i], V[j]);
+  let channel, order;
+  ({channel, value, order = ascendingDefined} = {...maybeValue(value)});
+  if (typeof order !== "function") {
+    switch (`${order}`.toLowerCase()) {
+      case "ascending": order = ascendingDefined; break;
+      case "descending": order = descendingDefined; break;
+      default: throw new Error(`invalid order: ${order}`);
+    }
+  }
+  return (data, facets, channels) => {
+    let V;
+    if (channel === undefined) {
+      V = valueof(data, value);
+    } else {
+      if (channels === undefined) throw new Error("channel sort requires an initializer");
+      V = channels[channel];
+      if (!V) return {}; // ignore missing channel
+      V = V.value;
+    }
+    const compareValue = (i, j) => order(V[i], V[j]);
     return {data, facets: facets.map(I => I.slice().sort(compareValue))};
   };
 }

src/transforms/dodge.js

@@ -3,7 +3,7 @@ import IntervalTree from "interval-tree-1d";
 import {finite, positive} from "../defined.js";
 import {identity, number, valueof} from "../options.js";
 import {coerceNumbers} from "../scales.js";
-import {initializer} from "./initializer.js";
+import {initializer} from "./basic.js";
 
 const anchorXLeft = ({marginLeft}) => [1, marginLeft];
 const anchorXRight = ({width, marginRight}) => [-1, width - marginRight];
@@ -50,7 +50,7 @@ function dodge(y, x, anchor, padding, options) {
   if (r != null && typeof r !== "number") {
     const {channels, sort, reverse} = options;
     options = {...options, channels: [...channels ?? [], {name: "r", value: r, scale: "r"}]};
-    if (sort === undefined && reverse === undefined) options.sort = r, options.reverse = true;
+    if (sort === undefined && reverse === undefined) options.sort = {channel: "r", order: "descending"};
   }
   return initializer(options, function(data, facets, {[x]: X, r: R}, scales, dimensions) {
     if (!X) throw new Error(`missing channel: ${x}`);

src/transforms/hexbin.js

@@ -1,8 +1,8 @@
 import {coerceNumbers} from "../scales.js";
 import {sqrt3} from "../symbols.js";
 import {identity, isNoneish, number, valueof} from "../options.js";
+import {initializer} from "./basic.js";
 import {hasOutput, maybeGroup, maybeOutputs, maybeSubgroup} from "./group.js";
-import {initializer} from "./initializer.js";
 
 // We don’t want the hexagons to align with the edges of the plot frame, as that
 // would cause extreme x-values (the upper bound of the default x-scale domain)