column, not channel (#842)

Author: mbostock

README.md

@@ -2139,11 +2139,11 @@ Plot provides a few helpers for implementing transforms.
 
 Given an *options* object that may specify some basic transforms (*filter*, *sort*, or *reverse*) or a custom *transform* function, composes those transforms if any with the given *transform* function, returning a new *options* object. If a custom *transform* function is present on the given *options*, any basic transforms are ignored. Any additional input *options* are passed through in the returned *options* object. This method facilitates applying the basic transforms prior to applying the given custom *transform* and is used internally by Plot’s built-in transforms.
 
-#### Plot.channel([*source*])
+#### Plot.column([*source*])
 
-This helper for constructing derived channels returns a [*channel*, *setChannel*] array. The *channel* object implements *channel*.transform, returning whatever value was most recently passed to *setChannel*. If *setChannel* is not called, then *channel*.transform returns undefined. If a *source* is specified, then *channel*.label exposes the given *source*’s label, if any: if *source* is a string as when representing a named field of data, then *channel*.label is *source*; otherwise *channel*.label propagates *source*.label. This allows derived channels to propagate a human-readable axis or legend label.
+This helper for constructing derived columns returns a [*column*, *setColumn*] array. The *column* object implements *column*.transform, returning whatever value was most recently passed to *setColumn*. If *setColumn* is not called, then *column*.transform returns undefined. If a *source* is specified, then *column*.label exposes the given *source*’s label, if any: if *source* is a string as when representing a named field of data, then *column*.label is *source*; otherwise *column*.label propagates *source*.label. This allows derived columns to propagate a human-readable axis or legend label.
 
-Plot.channel is typically used by options transforms to define new channels; these channels are populated (derived) when the custom *transform* function is invoked.
+Plot.column is typically used by options transforms to define new channels; the associated columns are populated (derived) when the **transform** option function is invoked.
 
 ## Curves
 

src/index.js

@@ -15,7 +15,7 @@ export {Text, text, textX, textY} from "./marks/text.js";
 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, channel} from "./options.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 {group, groupX, groupY, groupZ} from "./transforms/group.js";

src/options.js

@@ -154,10 +154,10 @@ export function maybeInput(key, options) {
   return options[key];
 }
 
-// Defines a channel whose values are lazily populated by calling the returned
+// Defines a column whose values are lazily populated by calling the returned
 // setter. If the given source is labeled, the label is propagated to the
-// returned channel definition.
-export function channel(source) {
+// returned column definition.
+export function column(source) {
   let value;
   return [
     {
@@ -168,9 +168,9 @@ export function channel(source) {
   ];
 }
 
-// Like channel, but allows the source to be null.
-export function maybeChannel(source) {
-  return source == null ? [source] : channel(source);
+// Like column, but allows the source to be null.
+export function maybeColumn(source) {
+  return source == null ? [source] : column(source);
 }
 
 export function labelof(value, defaultValue) {
@@ -179,10 +179,10 @@ export function labelof(value, defaultValue) {
     : defaultValue;
 }
 
-// Assuming that both x1 and x2 and lazy channels (per above), this derives a
-// new a channel that’s the average of the two, and which inherits the channel
-// label (if any). Both input channels are assumed to be quantitative. If either
-// channel is temporal, the returned channel is also temporal.
+// Assuming that both x1 and x2 and lazy columns (per above), this derives a new
+// a column that’s the average of the two, and which inherits the column label
+// (if any). Both input columns are assumed to be quantitative. If either column
+// is temporal, the returned column is also temporal.
 export function mid(x1, x2) {
   return {
     transform(data) {

src/transforms/bin.js

@@ -1,5 +1,5 @@
 import {bin as binner, extent, thresholdFreedmanDiaconis, thresholdScott, thresholdSturges, utcTickInterval} from "d3";
-import {valueof, range, identity, maybeChannel, maybeTuple, maybeColorChannel, maybeValue, mid, labelof, isTemporal} from "../options.js";
+import {valueof, range, identity, maybeColumn, maybeTuple, maybeColorChannel, maybeValue, mid, labelof, isTemporal} from "../options.js";
 import {coerceDate, coerceNumber} from "../scales.js";
 import {basic} from "./basic.js";
 import {hasOutput, maybeEvaluator, maybeGroup, maybeOutput, maybeOutputs, maybeReduce, maybeSort, maybeSubgroup, reduceCount, reduceFirst, reduceIdentity} from "./group.js";
@@ -67,14 +67,14 @@ function binn(
   if (gy != null && hasOutput(outputs, "y", "y1", "y2")) gy = null;
 
   // Produce x1, x2, y1, and y2 output channels as appropriate (when binning).
-  const [BX1, setBX1] = maybeChannel(bx);
-  const [BX2, setBX2] = maybeChannel(bx);
-  const [BY1, setBY1] = maybeChannel(by);
-  const [BY2, setBY2] = maybeChannel(by);
+  const [BX1, setBX1] = maybeColumn(bx);
+  const [BX2, setBX2] = maybeColumn(bx);
+  const [BY1, setBY1] = maybeColumn(by);
+  const [BY2, setBY2] = maybeColumn(by);
 
   // Produce x or y output channels as appropriate (when grouping).
   const [k, gk] = gx != null ? [gx, "x"] : gy != null ? [gy, "y"] : [];
-  const [GK, setGK] = maybeChannel(k);
+  const [GK, setGK] = maybeColumn(k);
 
   // Greedily materialize the z, fill, and stroke channels (if channels and not
   // constants) so that we can reference them for subdividing groups without
@@ -94,11 +94,11 @@ function binn(
     interval, // eslint-disable-line no-unused-vars
     ...options
   } = inputs;
-  const [GZ, setGZ] = maybeChannel(z);
+  const [GZ, setGZ] = maybeColumn(z);
   const [vfill] = maybeColorChannel(fill);
   const [vstroke] = maybeColorChannel(stroke);
-  const [GF = fill, setGF] = maybeChannel(vfill);
-  const [GS = stroke, setGS] = maybeChannel(vstroke);
+  const [GF = fill, setGF] = maybeColumn(vfill);
+  const [GS = stroke, setGS] = maybeColumn(vstroke);
 
   return {
     ..."z" in inputs && {z: GZ || z},

src/transforms/group.js

@@ -1,6 +1,6 @@
 import {group as grouper, sort, sum, deviation, min, max, mean, median, mode, variance, InternSet, minIndex, maxIndex, rollup} from "d3";
 import {ascendingDefined, firstof} from "../defined.js";
-import {valueof, maybeColorChannel, maybeInput, maybeTuple, maybeChannel, channel, first, identity, take, labelof, range, second, percentile} from "../options.js";
+import {valueof, maybeColorChannel, maybeInput, maybeTuple, maybeColumn, column, first, identity, take, labelof, range, second, percentile} from "../options.js";
 import {basic} from "./basic.js";
 
 // Group on {z, fill, stroke}.
@@ -51,8 +51,8 @@ function groupn(
   filter = filter == null ? undefined : maybeEvaluator("filter", filter, inputs);
 
   // Produce x and y output channels as appropriate.
-  const [GX, setGX] = maybeChannel(x);
-  const [GY, setGY] = maybeChannel(y);
+  const [GX, setGX] = maybeColumn(x);
+  const [GY, setGY] = maybeColumn(y);
 
   // Greedily materialize the z, fill, and stroke channels (if channels and not
   // constants) so that we can reference them for subdividing groups without
@@ -65,11 +65,11 @@ function groupn(
     y1, y2, // consumed if y is an output
     ...options
   } = inputs;
-  const [GZ, setGZ] = maybeChannel(z);
+  const [GZ, setGZ] = maybeColumn(z);
   const [vfill] = maybeColorChannel(fill);
   const [vstroke] = maybeColorChannel(stroke);
-  const [GF = fill, setGF] = maybeChannel(vfill);
-  const [GS = stroke, setGS] = maybeChannel(vstroke);
+  const [GF = fill, setGF] = maybeColumn(vfill);
+  const [GS = stroke, setGS] = maybeColumn(vstroke);
 
   return {
     ..."z" in inputs && {z: GZ || z},
@@ -148,7 +148,7 @@ export function maybeOutputs(outputs, inputs) {
 
 export function maybeOutput(name, reduce, inputs) {
   const evaluator = maybeEvaluator(name, reduce, inputs);
-  const [output, setOutput] = channel(evaluator.label);
+  const [output, setOutput] = column(evaluator.label);
   let O;
   return {
     name,

src/transforms/map.js

@@ -1,5 +1,5 @@
 import {count, group, rank} from "d3";
-import {maybeZ, take, valueof, maybeInput, channel} from "../options.js";
+import {maybeZ, take, valueof, maybeInput, column} from "../options.js";
 import {basic} from "./basic.js";
 
 export function mapX(m, options = {}) {
@@ -19,7 +19,7 @@ export function map(outputs = {}, options = {}) {
   const channels = Object.entries(outputs).map(([key, map]) => {
     const input = maybeInput(key, options);
     if (input == null) throw new Error(`missing channel: ${key}`);
-    const [output, setOutput] = channel(input);
+    const [output, setOutput] = column(input);
     return {key, input, output, setOutput, map: maybeMap(map)};
   });
   return {

src/transforms/stack.js

@@ -1,6 +1,6 @@
 import {InternMap, cumsum, group, groupSort, greatest, max, min, rollup, sum} from "d3";
 import {ascendingDefined} from "../defined.js";
-import {field, channel, maybeChannel, maybeZ, mid, range, valueof, maybeZero, one} from "../options.js";
+import {field, column, maybeColumn, maybeZ, mid, range, valueof, maybeZero, one} from "../options.js";
 import {basic} from "./basic.js";
 
 export function stackX(stackOptions = {}, options = {}) {
@@ -67,9 +67,9 @@ function mergeOptions(options) {
 
 function stack(x, y = one, ky, {offset, order, reverse}, options) {
   const z = maybeZ(options);
-  const [X, setX] = maybeChannel(x);
-  const [Y1, setY1] = channel(y);
-  const [Y2, setY2] = channel(y);
+  const [X, setX] = maybeColumn(x);
+  const [Y1, setY1] = column(y);
+  const [Y2, setY2] = column(y);
   offset = maybeOffset(offset);
   order = maybeOrder(order, offset, ky);
   return [

src/transforms/tree.js

@@ -1,6 +1,6 @@
 import {stratify, tree} from "d3";
 import {ascendingDefined} from "../defined.js";
-import {channel, identity, isObject, one, valueof} from "../options.js";
+import {column, identity, isObject, one, valueof} from "../options.js";
 import {basic} from "./basic.js";
 
 export function treeNode({
@@ -18,8 +18,8 @@ export function treeNode({
   if (frameAnchor === undefined) frameAnchor = treeAnchor.frameAnchor;
   const normalize = normalizer(delimiter);
   const outputs = treeOutputs(options, maybeNodeValue);
-  const [X, setX] = channel();
-  const [Y, setY] = channel();
+  const [X, setX] = column();
+  const [Y, setY] = column();
   return {
     x: X,
     y: Y,
@@ -73,10 +73,10 @@ export function treeLink({
   options = {curve, stroke, strokeWidth, strokeOpacity, ...options};
   const normalize = normalizer(delimiter);
   const outputs = treeOutputs(options, maybeLinkValue);
-  const [X1, setX1] = channel();
-  const [X2, setX2] = channel();
-  const [Y1, setY1] = channel();
-  const [Y2, setY2] = channel();
+  const [X1, setX1] = column();
+  const [X2, setX2] = column();
+  const [Y1, setY1] = column();
+  const [Y2, setY2] = column();
   return {
     x1: X1,
     x2: X2,
@@ -256,7 +256,7 @@ function slash(path, i) {
 }
 
 // These indexes match the array returned by nodeOutputs. The first two elements
-// are always the name of the output and its channel value definition so that
+// are always the name of the output and its column value definition so that
 // the outputs can be passed directly to Object.fromEntries.
 const output_setValues = 2;
 const output_evaluate = 3;
@@ -268,7 +268,7 @@ function treeOutputs(options, maybeTreeValue) {
     const value = options[name];
     const treeValue = maybeTreeValue(value);
     if (treeValue !== undefined) {
-      outputs.push([name, ...channel(value), treeValue]);
+      outputs.push([name, ...column(value), treeValue]);
     }
   }
   return outputs;