generalize Plot.select (#656)

* generalize Plot.select

closes #515

* Plot.select({x: "min"}, options) etc.

* select edits (#664)

* select edits

* update README

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

Author: Fil

README.md

@@ -1609,6 +1609,38 @@ Like [Plot.mapY](#plotmapymap-options), but applies the window map method with t
 
 The select transform derives a filtered mark index; it does not affect the mark’s data or channels. It is similar to the basic [filter transform](#transforms) except that provides convenient shorthand for pulling a single value out of each series. The data are grouped into series using the *z*, *fill*, or *stroke* channel in the same fashion as the [area](#area) and [line](#line) marks.
 
+#### Plot.select(*selector*, *options*)
+
+Selects the points of each series selected by the *selector*, which can be specified either as a function which receives as input the index of the series, or as a {key: value} object with exactly one key representing a channel and the value being a function which receives as inputs the index of the series and the channel or the shorthand “min” and “max” which respectively select the least and greatest points for the specified channel.
+
+For example, to select the point within each series that is the closest to the median of the *y* channel:
+
+```js
+Plot.select({
+  y: (I, V) => {
+    const median = d3.median(I, i => V[i]);
+    const i = d3.least(I, i => Math.abs(V[i] - median));
+    return [i];
+  }
+}, {
+  x: "year",
+  y: "revenue",
+  fill: "format"
+})
+```
+
+To pick three points at random in each series:
+
+```js
+Plot.select(I => d3.shuffle(I.slice()).slice(0, 3), {z: "year", ...})
+```
+
+To pick the point in each city with the highest temperature:
+
+```js
+Plot.select({fill: "max"}, {x: "date", y: "city", fill: "temperature", z: "city"})
+```
+
 #### Plot.selectFirst(*options*)
 
 Selects the first point of each series according to input order.

src/index.js

@@ -19,7 +19,7 @@ export {group, groupX, groupY, groupZ} from "./transforms/group.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";
-export {selectFirst, selectLast, selectMaxX, selectMaxY, selectMinX, selectMinY} from "./transforms/select.js";
+export {select, selectFirst, selectLast, selectMaxX, selectMaxY, selectMinX, selectMinY} from "./transforms/select.js";
 export {stackX, stackX1, stackX2, stackY, stackY1, stackY2} from "./transforms/stack.js";
 export {formatIsoDate, formatWeekday, formatMonth} from "./format.js";
 export {scale} from "./scales.js";

src/transforms/select.js

@@ -2,57 +2,84 @@ import {greatest, group, least} from "d3";
 import {maybeZ, valueof} from "../options.js";
 import {basic} from "./basic.js";
 
+export function select(selector, options = {}) {
+  // If specified selector is a string or function, it’s a selector without an
+  // input channel such as first or last.
+  if (typeof selector === "string") {
+    switch (selector.toLowerCase()) {
+      case "first": return selectFirst(options);
+      case "last": return selectLast(options);
+    }
+  }
+  if (typeof selector === "function") {
+    return selectChannel(null, selector, options);
+  }
+  // Otherwise the selector is an option {name: value} where name is a channel
+  // name and value is a selector definition that additionally takes the given
+  // channel values as input. The selector object must have exactly one key.
+  let key, value;
+  for (key in selector) {
+    if (value !== undefined) throw new Error("ambiguous select definition");
+    value = maybeSelector(selector[key]);
+  }
+  if (value === undefined) throw new Error("invalid select definition");
+  return selectChannel(key, value, options);
+}
+
+function maybeSelector(selector) {
+  if (typeof selector === "function") return selector;
+  switch (`${selector}`.toLowerCase()) {
+    case "min": return selectorMin;
+    case "max": return selectorMax;
+  }
+  throw new Error(`unknown selector: ${selector}`);
+}
+
 export function selectFirst(options) {
-  return select(first, undefined, options);
+  return selectChannel(null, selectorFirst, options);
 }
 
 export function selectLast(options) {
-  return select(last, undefined, options);
+  return selectChannel(null, selectorLast, options);
 }
 
-export function selectMinX(options = {}) {
-  const x = options.x;
-  if (x == null) throw new Error("missing channel: x");
-  return select(min, x, options);
+export function selectMinX(options) {
+  return selectChannel("x", selectorMin, options);
 }
 
-export function selectMinY(options = {}) {
-  const y = options.y;
-  if (y == null) throw new Error("missing channel: y");
-  return select(min, y, options);
+export function selectMinY(options) {
+  return selectChannel("y", selectorMin, options);
 }
 
-export function selectMaxX(options = {}) {
-  const x = options.x;
-  if (x == null) throw new Error("missing channel: x");
-  return select(max, x, options);
+export function selectMaxX(options) {
+  return selectChannel("x", selectorMax, options);
 }
 
-export function selectMaxY(options = {}) {
-  const y = options.y;
-  if (y == null) throw new Error("missing channel: y");
-  return select(max, y, options);
+export function selectMaxY(options) {
+  return selectChannel("y", selectorMax, options);
 }
 
-// TODO If the value (for some required channel) is undefined, scan forward?
-function* first(I) {
+function* selectorFirst(I) {
   yield I[0];
 }
 
-// TODO If the value (for some required channel) is undefined, scan backward?
-function* last(I) {
+function* selectorLast(I) {
   yield I[I.length - 1];
 }
 
-function* min(I, X) {
+function* selectorMin(I, X) {
   yield least(I, i => X[i]);
 }
 
-function* max(I, X) {
+function* selectorMax(I, X) {
   yield greatest(I, i => X[i]);
 }
 
-function select(selectIndex, v, options) {
+function selectChannel(v, selector, options) {
+  if (v != null) {
+    if (options[v] == null) throw new Error(`missing channel: ${v}`);
+    v = options[v];
+  }
   const z = maybeZ(options);
   return basic(options, (data, facets) => {
     const Z = valueof(data, z);
@@ -61,7 +88,7 @@ function select(selectIndex, v, options) {
     for (const facet of facets) {
       const selectFacet = [];
       for (const I of Z ? group(facet, i => Z[i]).values() : [facet]) {
-        for (const i of selectIndex(I, V)) {
+        for (const i of selector(I, V)) {
           selectFacet.push(i);
         }
       }