pass the bins' extent (x1, x2, y1, y2) to the reducer (#437)

* pass the bins' extent (x1, x2, y1, y2) to the reducer
* allow outputs to be suppressed
* remove unused maybeLabel

closes #435

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

Author: Fil

CHANGELOG.md

@@ -12,6 +12,27 @@ The constant *dx* and *dy* options have been extended to all marks, allowing to
 
 Quantitative scales, as well as identity position scales, now coerce channel values to numbers; both null and undefined are coerced to NaN. Similarly, time scales coerce channel values to dates; numbers are assumed to be milliseconds since UNIX epoch, while strings are assumed to be in [ISO 8601 format](https://github.com/mbostock/isoformat/blob/main/README.md#parsedate-fallback).
 
+### Transforms
+
+#### Plot.bin
+
+The reducers now receive the extent of the current bin as an argument after the data. For example, it allows to create meaningful titles:
+```js
+Plot.rect(
+  athletes,
+  Plot.bin(
+    {
+      fill: "count",
+      title: (bin, { x1, x2, y1, y2 }) =>
+        `${bin.length} athletes weighing between ${x1} and ${x2} and with a height between ${y1} and ${y2}`
+    },
+    { x: "weight", y: "height", inset: 0 }
+  )
+).plot()
+```
+
+The *x1* and *x2* outputs now default to undefined if *x* is explicitly defined; similary, the *y1* and *y2* outputs now default to undefined if *y* is explicitly defined.
+
 ## 0.2.0
 
 Released August 20, 2021.

README.md

@@ -1051,7 +1051,7 @@ While it is possible to compute channel values on the binned data by defining ch
 * **fill** - the first value of the *fill* channel, if any
 * **stroke** - the first value of the *stroke* channel, if any
 
-The **x1**, **x2**, and **x** output channels are only computed by the Plot.binX and Plot.bin transform; similarly the **y1**, **y2**, and **y** output channels are only computed by the Plot.binY and Plot.bin transform. The **x** and **y** output channels are lazy: they are only computed if needed by a downstream mark or transform.
+The **x1**, **x2**, and **x** output channels are only computed by the Plot.binX and Plot.bin transform; similarly the **y1**, **y2**, and **y** output channels are only computed by the Plot.binY and Plot.bin transform. The **x** and **y** output channels are lazy: they are only computed if needed by a downstream mark or transform. Conversely, the *x1* and *x2* outputs default to undefined if *x* is explicitly defined; and the *y1* and *y2* outputs default to undefined if *y* is explicitly defined.
 
 You can declare additional channels to aggregate by specifying the channel name and desired aggregation method in the *outputs* object which is the first argument to the transform. For example, to use [Plot.binX](#plotbinxoutputs-options) to generate a **y** channel of bin counts as in a frequency histogram:
 
@@ -1077,10 +1077,10 @@ The following aggregation methods are supported:
 * *deviation* - the standard deviation
 * *variance* - the variance per [Welford’s algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm)
 * *mode* - the value with the most occurrences
-* a function to be passed the array of values for each bin
+* a function to be passed the array of values for each bin and the extent of the bin
 * an object with a *reduce* method
 
-The *reduce* method is repeatedly passed the index for each bin (an array of integers) and the corresponding input channel’s array of values; it must then return the corresponding aggregate value for the bin.
+The *reduce* method is repeatedly passed the index for each bin (an array of integers), the corresponding input channel’s array of values, and the extent of the bin; it must then return the corresponding aggregate value for the bin.
 
 Most aggregation methods require binding the output channel to an input channel; for example, if you want the **y** output channel to be a *sum* (not merely a count), there should be a corresponding **y** input channel specifying which values to sum. If there is not, *sum* will be equivalent to *count*.
 

src/mark.js

@@ -151,16 +151,6 @@ export function maybeNumber(value, defaultValue) {
     : [value, undefined];
 }
 
-// If the channel value is specified as a string, indicating a named field, this
-// wraps the specified function f with another function with the corresponding
-// label property, such that the associated axis inherits the label by default.
-export function maybeLabel(f, value) {
-  const label = typeof value === "string" ? value
-    : typeof value === "function" ? value.label
-    : undefined;
-  return label === undefined ? f : Object.assign(d => f(d), {label});
-}
-
 // Validates the specified optional string against the allowed list of keywords.
 export function maybeKeyword(input, name, allowed) {
   if (input != null) return keyword(input, name, allowed);

src/transforms/bin.js

@@ -111,17 +111,18 @@ function binn(
             for (const [x1, x2, fx] of BX) {
               const bb = fx(g);
               for (const [y1, y2, fy] of BY) {
+                const extent = {x1, x2, y1, y2};
                 const b = fy(bb);
-                if (filter && !filter.reduce(b)) continue;
+                if (filter && !filter.reduce(b, extent)) continue;
                 groupFacet.push(i++);
-                groupData.push(reduceData.reduce(b, data));
+                groupData.push(reduceData.reduce(b, data, extent));
                 if (K) GK.push(k);
                 if (Z) GZ.push(G === Z ? f : Z[b[0]]);
                 if (F) GF.push(G === F ? f : F[b[0]]);
                 if (S) GS.push(G === S ? f : S[b[0]]);
                 if (BX1) BX1.push(x1), BX2.push(x2);
                 if (BY1) BY1.push(y1), BY2.push(y2);
-                for (const o of outputs) o.reduce(b);
+                for (const o of outputs) o.reduce(b, extent);
                 if (sort) sort.reduce(b);
               }
             }
@@ -132,8 +133,8 @@ function binn(
       maybeSort(groupFacets, sort, reverse);
       return {data: groupData, facets: groupFacets};
     }),
-    ...BX1 ? {x1: BX1, x2: BX2, x: mid(BX1, BX2)} : {x},
-    ...BY1 ? {y1: BY1, y2: BY2, y: mid(BY1, BY2)} : {y},
+    ...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},
     ...GK && {[gk]: GK},
     ...Object.fromEntries(outputs.map(({name, output}) => [name, output]))
   };

src/transforms/group.js

@@ -119,7 +119,11 @@ function groupn(
 }
 
 export function maybeOutputs(outputs, inputs) {
-  return Object.entries(outputs).map(([name, reduce]) => maybeOutput(name, reduce, inputs));
+  return Object.entries(outputs).map(([name, reduce]) => {
+    return reduce == null
+      ? {name, initialize() {}, scope() {}, reduce() {}}
+      : maybeOutput(name, reduce, inputs);
+  });
 }
 
 export function maybeOutput(name, reduce, inputs) {
@@ -136,8 +140,8 @@ export function maybeOutput(name, reduce, inputs) {
     scope(scope, I) {
       evaluator.scope(scope, I);
     },
-    reduce(I) {
-      O.push(evaluator.reduce(I));
+    reduce(I, extent) {
+      O.push(evaluator.reduce(I, extent));
     }
   };
 }
@@ -159,8 +163,10 @@ export function maybeEvaluator(name, reduce, inputs) {
         context = reducer.reduce(I, V);
       }
     },
-    reduce(I) {
-      return reducer.reduce(I, V, context);
+    reduce(I, extent) {
+      return reducer.scope == null
+        ? reducer.reduce(I, V, extent)
+        : reducer.reduce(I, V, context, extent);
     }
   };
 }
@@ -214,8 +220,8 @@ export function maybeSort(facets, sort, reverse) {
 
 function reduceFunction(f) {
   return {
-    reduce(I, X) {
-      return f(take(X, I));
+    reduce(I, X, extent) {
+      return f(take(X, I), extent);
     }
   };
 }