expose Plot.transform and Plot.column

Author: Fil

README.md

@@ -1331,6 +1331,7 @@ Plot’s transforms provide a convenient mechanism for transforming data as part
 * **filter** - filters data according to the specified accessor or values
 * **sort** - sorts data according to the specified comparator, accessor, or values
 * **reverse** - reverses the sorted (or if not sorted, the input) data order
+* **transform** - a function that returns transformed *data* and *facets*
 
 For example, to draw bars only for letters that commonly form vowels:
 
@@ -1346,10 +1347,6 @@ 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.
 
-For greater control, you can also implement a custom transform function:
-
-* **transform** - a function that returns transformed *data* and *index*
-
 The basic transforms are composable: the *filter* transform is applied first, then *sort*, then *reverse*. If a custom *transform* option is specified directly, it supersedes any basic transforms (*i.e.*, the *filter*, *sort* and *reverse* options are ignored). However, the *transform* option is rarely used directly; instead an option transform is used. These option transforms automatically compose with the basic *filter*, *sort* and *reverse* transforms.
 
 Plot’s option transforms, listed below, do more than populate the **transform** function: they derive new mark options and channels. These transforms take a mark’s *options* object (and possibly transform-specific options as the first argument) and return a new, transformed, *options*. Option transforms are composable: you can pass an *options* objects through more than one transform before passing it to a mark. You can also reuse the same transformed *options* on multiple marks.
@@ -1974,6 +1971,26 @@ If *marker* is true, it defaults to *circle*. If *marker* is a function, it will
 
 The primary color of a marker is inherited from the *stroke* of the associated mark. The *arrow* marker is [automatically oriented](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/orient) such that it points in the tangential direction of the path at the position the marker is placed. The *circle* markers are centered around the given vertex. Note that lines whose curve is not *linear* (the default), markers are not necessarily drawn at the data positions given by *x* and *y*; marker placement is determined by the (possibly Bézier) path segments generated by the curve. To ensure that symbols are drawn at a given *x* and *y* position, consider using a [dot](#dot).
 
+### Custom transforms
+
+For greater control, you can also implement a custom transform function, by defining the following option:
+
+* **transform** - a function that returns transformed *data* and *facets*
+
+The arguments of the *transform* function are *data* and *facets*. The incoming *facets* is an array of facets, each facet being an array of indices into the incoming *data* array. The transform must return an object with two properties *{data, facets}* with the same structure. (The new data and facets can, of course, be different from the incoming values.)
+
+A custom transform might also generate new channels (for example, the count of elements in a groupX transform might be returned as a new channel *y*). The following helpers are useful to build new custom transforms:
+
+#### Plot.transform(*options*, *transform*)
+
+Returns an options object with a new transform that corresponds to the specified *transform* function composed with any preceding transform.
+
+#### Plot.column(*x*)
+
+Returns [*X*, *setX*], a channel and a setter. *X* can be returned immediately as a new channel, and *setX* can be called to fill *X* when the transform is applied to the data. The resulting channel *X* is an object with a *transform* method that returns the materialized column of values instantiated by *setX*.
+
+If *x* is a string or has a label, a label is automatically created on the resulting channel.
+
 ## Formats
 
 These helper functions are provided for use as a *scale*.tickFormat [axis option](#position-options), as the text option for [Plot.text](#plottextdata-options), or for general use. See also [d3-format](https://github.com/d3/d3-format), [d3-time-format](https://github.com/d3/d3-time-format), and JavaScript’s built-in [date formatting](https://observablehq.com/@mbostock/date-formatting) and [number formatting](https://observablehq.com/@mbostock/number-formatting).

src/index.js

@@ -14,8 +14,8 @@ export {RuleX, RuleY, ruleX, ruleY} from "./marks/rule.js";
 export {Text, text, textX, textY} from "./marks/text.js";
 export {TickX, TickY, tickX, tickY} from "./marks/tick.js";
 export {Vector, vector, vectorX, vectorY} from "./marks/vector.js";
-export {valueof} from "./options.js";
-export {filter, reverse, sort, shuffle} from "./transforms/basic.js";
+export {valueof, lazyChannel as 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";
 export {normalize, normalizeX, normalizeY} from "./transforms/normalize.js";