consume bin options; allow bin options on output (#565)

* consume options

* Update bin.js

* don’t propagate count input label

* remove trailing comma

* all bin options on outputs

* rename test

* regenerate test output

* consume stack options, too

* lift default

* same with groups (#569)

* same with groups

* utc

* prettier

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

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

Author: mbostock

README.md

@@ -1152,7 +1152,7 @@ To control how the quantitative dimensions *x* and *y* are divided into bins, th
 * **domain** - values outside the domain will be omitted
 * **cumulative** - if positive, each bin will contain all lesser bins
 
-If the **domain** option is not specified, it defaults to the minimum and maximum of the corresponding dimension (*x* or *y*), possibly niced to match the threshold interval to ensure that the first and last bin have the same width as other bins. If **cumulative** is negative (-1 by convention), each bin will contain all *greater* bins rather than all *lesser* bins, representing the [complementary cumulative distribution](https://en.wikipedia.org/wiki/Cumulative_distribution_function#Complementary_cumulative_distribution_function_.28tail_distribution.29).
+These options may be specified either on the *options* or *outputs* object. If the **domain** option is not specified, it defaults to the minimum and maximum of the corresponding dimension (*x* or *y*), possibly niced to match the threshold interval to ensure that the first and last bin have the same width as other bins. If **cumulative** is negative (-1 by convention), each bin will contain all *greater* bins rather than all *lesser* bins, representing the [complementary cumulative distribution](https://en.wikipedia.org/wiki/Cumulative_distribution_function#Complementary_cumulative_distribution_function_.28tail_distribution.29).
 
 To pass separate binning options for *x* and *y*, the **x** and **y** input channels can be specified as an object with the options above and a **value** option to specify the input channel values.
 

src/transforms/bin.js

@@ -1,23 +1,26 @@
 import {bin as binner, extent, thresholdFreedmanDiaconis, thresholdScott, thresholdSturges, utcTickInterval} from "d3";
 import {valueof, range, identity, maybeLazyChannel, maybeTuple, maybeColor, maybeValue, mid, labelof, isTemporal} from "../mark.js";
 import {basic} from "./basic.js";
-import {maybeEvaluator, maybeGroup, maybeOutput, maybeOutputs, maybeReduce, maybeSort, maybeSubgroup, reduceCount, reduceIdentity} from "./group.js";
+import {hasOutput, maybeEvaluator, maybeGroup, maybeOutput, maybeOutputs, maybeReduce, maybeSort, maybeSubgroup, reduceCount, reduceIdentity} from "./group.js";
 import {maybeInsetX, maybeInsetY} from "./inset.js";
 
 // Group on {z, fill, stroke}, then optionally on y, then bin x.
 export function binX(outputs = {y: "count"}, options = {}) {
+  ([outputs, options] = mergeOptions(outputs, options));
   const {x, y} = options;
   return binn(maybeBinValue(x, options, identity), null, null, y, outputs, maybeInsetX(options));
 }
 
 // Group on {z, fill, stroke}, then optionally on x, then bin y.
 export function binY(outputs = {x: "count"}, options = {}) {
+  ([outputs, options] = mergeOptions(outputs, options));
   const {x, y} = options;
   return binn(null, maybeBinValue(y, options, identity), x, null, outputs, maybeInsetY(options));
 }
 
 // Group on {z, fill, stroke}, then bin on x and y.
 export function bin(outputs = {fill: "count"}, options = {}) {
+  ([outputs, options] = mergeOptions(outputs, options));
   const {x, y} = maybeBinValueTuple(options);
   return binn(x, y, null, null, outputs, maybeInsetX(maybeInsetY(options)));
 }
@@ -61,8 +64,21 @@ function binn(
 
   // Greedily materialize the z, fill, and stroke channels (if channels and not
   // constants) so that we can reference them for subdividing groups without
-  // computing them more than once.
-  const {x, y, z, fill, stroke, ...options} = inputs;
+  // computing them more than once. We also want to consume options that should
+  // only apply to this transform rather than passing them through to the next.
+  const {
+    x,
+    y,
+    z,
+    fill,
+    stroke,
+    x1, x2, // consumed if x is an output
+    y1, y2, // consumed if y is an output
+    domain, // eslint-disable-line no-unused-vars
+    cumulative, // eslint-disable-line no-unused-vars
+    thresholds, // eslint-disable-line no-unused-vars
+    ...options
+  } = inputs;
   const [GZ, setGZ] = maybeLazyChannel(z);
   const [vfill] = maybeColor(fill);
   const [vstroke] = maybeColor(stroke);
@@ -127,14 +143,19 @@ function binn(
       maybeSort(groupFacets, sort, reverse);
       return {data: groupData, facets: groupFacets};
     }),
-    ...BX1 && !hasOutput(outputs, "x") ? {x1: BX1, x2: BX2, x: mid(BX1, BX2)} : {x},
-    ...BY1 && !hasOutput(outputs, "y") ? {y1: BY1, y2: BY2, y: mid(BY1, BY2)} : {y},
+    ...!hasOutput(outputs, "x") && (BX1 ? {x1: BX1, x2: BX2, x: mid(BX1, BX2)} : {x, x1, x2}),
+    ...!hasOutput(outputs, "y") && (BY1 ? {y1: BY1, y2: BY2, y: mid(BY1, BY2)} : {y, y1, y2}),
     ...GK && {[gk]: GK},
     ...Object.fromEntries(outputs.map(({name, output}) => [name, output]))
   };
 }
 
-function maybeBinValue(value, {cumulative, domain, thresholds} = {}, defaultValue) {
+// Allow bin options to be specified as part of outputs; merge them into options.
+function mergeOptions({cumulative, domain, thresholds, ...outputs}, options) {
+  return [outputs, {cumulative, domain, thresholds, ...options}];
+}
+
+function maybeBinValue(value, {cumulative, domain, thresholds}, defaultValue) {
   value = {...maybeValue(value)};
   if (value.domain === undefined) value.domain = domain;
   if (value.cumulative === undefined) value.cumulative = cumulative;
@@ -144,7 +165,7 @@ function maybeBinValue(value, {cumulative, domain, thresholds} = {}, defaultValu
   return value;
 }
 
-function maybeBinValueTuple(options = {}) {
+function maybeBinValueTuple(options) {
   let {x, y} = options;
   x = maybeBinValue(x, options);
   y = maybeBinValue(y, options);
@@ -202,15 +223,6 @@ function isTimeInterval(t) {
   return t ? typeof t.range === "function" : false;
 }
 
-function hasOutput(outputs, ...names) {
-  for (const {name} of outputs) {
-    if (names.includes(name)) {
-      return true;
-    }
-  }
-  return false;
-}
-
 function binset(bin) {
   return [bin, new Set(bin)];
 }

src/transforms/group.js

@@ -57,7 +57,14 @@ function groupn(
   // Greedily materialize the z, fill, and stroke channels (if channels and not
   // constants) so that we can reference them for subdividing groups without
   // computing them more than once.
-  const {z, fill, stroke, ...options} = inputs;
+  const {
+    z,
+    fill,
+    stroke,
+    x1, x2, // consumed if x is an output
+    y1, y2, // consumed if y is an output
+    ...options
+  } = inputs;
   const [GZ, setGZ] = maybeLazyChannel(z);
   const [vfill] = maybeColor(fill);
   const [vstroke] = maybeColor(stroke);
@@ -112,12 +119,21 @@ function groupn(
       maybeSort(groupFacets, sort, reverse);
       return {data: groupData, facets: groupFacets};
     }),
-    ...GX && {x: GX},
-    ...GY && {y: GY},
+    ...!hasOutput(outputs, "x") && (GX ? {x: GX} : {x1, x2}),
+    ...!hasOutput(outputs, "y") && (GY ? {y: GY} : {y1, y2}),
     ...Object.fromEntries(outputs.map(({name, output}) => [name, output]))
   };
 }
 
+export function hasOutput(outputs, ...names) {
+  for (const {name} of outputs) {
+    if (names.includes(name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export function maybeOutputs(outputs, inputs) {
   return Object.entries(outputs).map(([name, reduce]) => {
     return reduce == null
@@ -151,7 +167,7 @@ export function maybeEvaluator(name, reduce, inputs) {
   const reducer = maybeReduce(reduce, input);
   let V, context;
   return {
-    label: labelof(input, reducer.label),
+    label: labelof(reducer === reduceCount ? null : input, reducer.label),
     initialize(data) {
       V = input === undefined ? data : valueof(data, input);
       if (reducer.scope === "data") {

src/transforms/interval.js

@@ -17,13 +17,13 @@ function maybeInterval(interval) {
 
 // The interval may be specified either as x: {value, interval} or as {x,
 // interval}. The former is used, for example, for Plot.rect.
-function maybeIntervalValue(value, {interval} = {}) {
+function maybeIntervalValue(value, {interval}) {
   value = {...maybeValue(value)};
   value.interval = maybeInterval(value.interval === undefined ? interval : value.interval);
   return value;
 }
 
-function maybeIntervalK(k, maybeInsetK, options = {}) {
+function maybeIntervalK(k, maybeInsetK, options) {
   const {[k]: v, [`${k}1`]: v1, [`${k}2`]: v2} = options;
   const {value, interval} = maybeIntervalValue(v, options);
   if (value == null || interval == null) return options;
@@ -38,7 +38,7 @@ function maybeIntervalK(k, maybeInsetK, options = {}) {
   });
 }
 
-export function maybeIntervalX(options) {
+export function maybeIntervalX(options = {}) {
   return maybeIntervalK("x", maybeInsetX, options);
 }
 

src/transforms/stack.js

@@ -4,42 +4,42 @@ import {field, lazyChannel, maybeLazyChannel, maybeZ, mid, range, valueof, maybe
 import {basic} from "./basic.js";
 
 export function stackX(stackOptions = {}, options = {}) {
-  if (arguments.length === 1) options = mergeOptions(stackOptions);
+  if (arguments.length === 1) ([stackOptions, options] = mergeOptions(stackOptions));
   const {y1, y = y1, x, ...rest} = options; // note: consumes x!
   const [transform, Y, x1, x2] = stack(y, x, "x", stackOptions, rest);
   return {...transform, y1, y: Y, x1, x2, x: mid(x1, x2)};
 }
 
 export function stackX1(stackOptions = {}, options = {}) {
-  if (arguments.length === 1) options = mergeOptions(stackOptions);
+  if (arguments.length === 1) ([stackOptions, options] = mergeOptions(stackOptions));
   const {y1, y = y1, x} = options;
   const [transform, Y, X] = stack(y, x, "x", stackOptions, options);
   return {...transform, y1, y: Y, x: X};
 }
 
 export function stackX2(stackOptions = {}, options = {}) {
-  if (arguments.length === 1) options = mergeOptions(stackOptions);
+  if (arguments.length === 1) ([stackOptions, options] = mergeOptions(stackOptions));
   const {y1, y = y1, x} = options;
   const [transform, Y,, X] = stack(y, x, "x", stackOptions, options);
   return {...transform, y1, y: Y, x: X};
 }
 
 export function stackY(stackOptions = {}, options = {}) {
-  if (arguments.length === 1) options = mergeOptions(stackOptions);
+  if (arguments.length === 1) ([stackOptions, options] = mergeOptions(stackOptions));
   const {x1, x = x1, y, ...rest} = options; // note: consumes y!
   const [transform, X, y1, y2] = stack(x, y, "y", stackOptions, rest);
   return {...transform, x1, x: X, y1, y2, y: mid(y1, y2)};
 }
 
 export function stackY1(stackOptions = {}, options = {}) {
-  if (arguments.length === 1) options = mergeOptions(stackOptions);
+  if (arguments.length === 1) ([stackOptions, options] = mergeOptions(stackOptions));
   const {x1, x = x1, y} = options;
   const [transform, X, Y] = stack(x, y, "y", stackOptions, options);
   return {...transform, x1, x: X, y: Y};
 }
 
 export function stackY2(stackOptions = {}, options = {}) {
-  if (arguments.length === 1) options = mergeOptions(stackOptions);
+  if (arguments.length === 1) ([stackOptions, options] = mergeOptions(stackOptions));
   const {x1, x = x1, y} = options;
   const [transform, X,, Y] = stack(x, y, "y", stackOptions, options);
   return {...transform, x1, x: X, y: Y};
@@ -73,8 +73,8 @@ function aliasSort(options, name) {
 // transform. If only one options object is specified, we interpret it as a
 // stack option, and therefore must remove it from the propagated options.
 function mergeOptions(options) {
-  const {reverse} = options;
-  return reverse ? {...options, reverse: false} : options;
+  const {offset, order, reverse, ...rest} = options;
+  return [{offset, order, reverse}, rest];
 }
 
 function stack(x, y = () => 1, ky, {offset, order, reverse}, options) {