diff --git a/docs/features/scales.md b/docs/features/scales.md index 18aae3bbc0..b0e1075e39 100644 --- a/docs/features/scales.md +++ b/docs/features/scales.md @@ -638,6 +638,8 @@ Plot.plot({ As an added bonus, the **fontVariant** and **type** options are no longer needed because Plot now understands that the *x* scale, despite being *ordinal*, represents daily observations. ::: +While the example above relies on the **interval** being promoted to the scale’s **transform**, the [stack](../transforms/stack.md), [bin](../transforms/bin.md), and [group](../transforms/group.md) transforms are also interval-aware: they apply the scale’s **interval**, if any, *before* grouping values. (This results in the interval being applied twice, both before and after the mark transform, but the second application has no effect since interval application is idempotent.) + The **interval** option can also be used for quantitative and temporal scales. This enforces uniformity, say rounding timed observations down to the nearest hour, which may be helpful for the [stack transform](../transforms/stack.md) among other uses. ## Scale options diff --git a/docs/features/transforms.md b/docs/features/transforms.md index aea8fb4891..999d8b1728 100644 --- a/docs/features/transforms.md +++ b/docs/features/transforms.md @@ -175,7 +175,7 @@ Plot.plot({ ``` ::: -The **transform** function is passed two arguments, *data* and *facets*, representing the mark’s data and facet indexes; it must then return a {*data*, *facets*} object with the transformed data and facet indexes. The *facets* are represented as a nested array of arrays such as [[0, 1, 3, …], [2, 5, 10, …], …]; each element in *facets* specifies the zero-based indexes of elements in *data* that are in a given facet (*i.e.*, have a distinct value in the associated *fx* or *fy* dimension). +The **transform** function is passed three arguments, *data*, *facets*, and *options* representing the mark’s data and facet indexes, and the plot’s options; it must then return a {*data*, *facets*} object with the transformed data and facet indexes. The *facets* are represented as a nested array of arrays such as [[0, 1, 3, …], [2, 5, 10, …], …]; each element in *facets* specifies the zero-based indexes of elements in *data* that are in a given facet (*i.e.*, have a distinct value in the associated *fx* or *fy* dimension). If the **transform** option is specified, it supersedes any basic transforms (*i.e.*, the **filter**, **sort** and **reverse** options are ignored). However, the **transform** option is rarely used directly; instead one of Plot’s built-in transforms are used, and these transforms automatically compose with the basic **filter**, **sort** and **reverse** transforms. diff --git a/src/transforms/basic.d.ts b/src/transforms/basic.d.ts index 204acf39bc..3aee313b62 100644 --- a/src/transforms/basic.d.ts +++ b/src/transforms/basic.d.ts @@ -1,17 +1,22 @@ +import type {PlotOptions} from "../plot.js"; import type {ChannelName, Channels, ChannelValue} from "../channel.js"; import type {Context} from "../context.js"; import type {Dimensions} from "../dimensions.js"; import type {ScaleFunctions} from "../scales.js"; /** - * A mark transform function is passed the mark’s *data* and a nested index into - * the data, *facets*. The transform function returns new mark data and facets; - * the returned **data** defaults to the passed *data*, and the returned - * **facets** defaults to the passed *facets*. The mark is the *this* context. - * Transform functions can also trigger side-effects, say to populate - * lazily-derived columns; see also Plot.column. + * A mark transform function is passed the mark’s *data*, a nested index into + * the data, *facets*, and the plot’s *options*. The transform function returns + * new mark data and facets; the returned **data** defaults to the passed + * *data*, and the returned **facets** defaults to the passed *facets*. The mark + * is the *this* context. Transform functions can also trigger side-effects, say + * to populate lazily-derived columns; see also Plot.column. */ -export type TransformFunction = (data: any[], facets: number[][]) => {data?: any[]; facets?: number[][]}; +export type TransformFunction = ( + data: any[], + facets: number[][], + options?: PlotOptions +) => {data?: any[]; facets?: number[][]}; /** * A mark initializer function is passed the mark’s (possibly transformed)