Sort function signature: comparator vs accessor
In the function case for sort, if the sort function does not take exactly one argument, it is interpreted as a comparator function; otherwise it is interpreted as an accessor function.
Observable Plot · all subjects
transforms
239 notes in this subject, read out of this brain and free to use. This is page 4 of 4.
Sort transform changes z-order of overlapping marks
The sort transform sorts a mark's index to change the effective order of data, affecting the order in which a mark's graphical elements are drawn (z-order). This has a dramatic effect when elements overlap, as smaller elements can be hidden underneath larger ones when using null sort order for input order.
Sort can be applied as mark option or explicit transform
The sort transform can be applied either via the sort mark option, or as an explicit sort transform. The explicit sort transform is generally only needed when composing multiple transforms, or to disambiguate the sort transform from imputed ordinal scale domains (scale sorting).
Sort index order affects stack and dodge transforms
The index order produced by sort affects the behavior of certain transforms such as stack and dodge.
Dots sorted by descending r by default
Dots are sorted by descending r (radius) by default, so you may not need the sort option explicitly for dot marks.
sort() transform API
Plot.sort(order, options) sorts the data by the specified order parameter. The order parameter is one of: a comparator function, an accessor function, a field name, or a {channel, order} object.
reverse() transform reverses mark index order
Plot.reverse({x: 'culmen_length_mm', y: 'culmen_depth_mm'}) reverses the order of the data.
Sort order parameter options
The sort order parameter accepts: a comparator function (as with Array.sort), an accessor function, a field name string, or a {channel, order} object. In the object case, the channel option specifies the channel name (string), and the order option specifies 'ascending' (default) or 'descending'. The shorthand -name syntax sorts by descending order of the channel with that name, for example sort: {channel: '-r'} sorts by descending radius.
treeLink transform
treeLink populates x1, y1, x2, and y2 with the positions for each link in the tree, where x1 & y1 represents the position of the parent node and x2 & y2 the position of the child node. The default curve is 'bump-x', the default stroke is #555, the default strokeWidth is 1.5, and the default strokeOpacity is 0.5. This transform is often used with the link or arrow mark.
tree transform overview
The tree transform is rarely used directly. The two variants, treeNode and treeLink, are typically used internally by the composite tree mark. The tree transform arranges a tabular dataset into a hierarchy according to the given path channel, which is typically a slash-separated string. It then executes a tree layout algorithm to compute x and y coordinates; these channels can then be used to construct a node-link diagram.
tree transform path option
The path option specifies each node's hierarchy location and defaults to identity. The path column is typically slash-separated, as with UNIX-based file systems or URLs.
tree transform delimiter option
The delimiter option specifies the path separator as a single character and defaults to forward slash (/).
tree transform layout options
The following options control how the node-link diagram is laid out: treeLayout (a tree layout algorithm; defaults to d3.tree), treeAnchor (a tree layout orientation, either 'left' or 'right'; defaults to 'left'), treeSort (a node comparator, or null to preserve input order), and treeSeparation (a node separation function, or null for uniform separation).
tree transform default treeLayout
The default treeLayout implements the Reingold–Tilford 'tidy' algorithm based on Buchheim et al.'s linear time approach. Use d3.cluster instead to align leaf nodes.
treeAnchor left and right behavior
If treeAnchor is 'left', the root of the tree will be aligned with the left side of the frame. If treeAnchor is 'right', the root of the tree will be aligned with the right side of the frame. Use the insetLeft and insetRight scale options if horizontal padding is desired, for example to make room for labels.
treeSort option behavior
If the treeSort option is not null, it is typically a function that is passed two nodes in the hierarchy and compares them, similar to array.sort(). The treeSort option can also be specified as a string, in which case it refers either to a named column in data, or if it starts with 'node:', a node value.
treeSeparation option behavior
If the treeSeparation is not null, it is a function that is passed two nodes in the hierarchy and returns the desired relative amount of separation. By default, non-siblings are at least twice as far apart as siblings.
treeNode transform
treeNode populates x and y with the positions for each node in the tree. The default frameAnchor inherits the treeAnchor. This transform is often used with the dot or text mark.
treeNode node method support
If any treeNode option value is specified as an object with a node method, a derived output column will be generated by invoking the node method for each node in the tree.
treeLink named parent values
The treeLink transform will derive output columns for options that have the following named parent values: parent:name (the parent node's name, the last part of its path), parent:path (the parent node's full, normalized, slash-separated path), parent:depth (the distance from the parent node to the root), parent:height (the distance from the parent node to its deepest descendant).
treeLink node and link method support
If any treeLink option value is specified as an object with a node method, a derived output column will be generated by invoking the node method for each child node in the tree. If any option value is specified as an object with a link method, a derived output column will be generated by invoking the link method for each link in the tree, being passed two node arguments, the child and the parent.
tree mark construction example
The tree mark can be constructed using a link mark with Plot.treeLink(), a dot mark with Plot.treeNode(), and a text mark with Plot.treeNode({text: "node:name", dx: 6}). This example processes an array of slash-separated paths like "Chaos/Gaia/Mountains" where each path represents the hierarchical position of a node in the tree.
stackY2 returns y2 as y channel
stackY2 is like stackY, except that the y2 channel is returned as the y channel. This can be used, for example, to draw a line at the top of each stacked area, or to position stacked elements (such as dots) at their upper bound.
stackX diverging stacks with negative values
For stackX, negative values are stacked to the left of zero while positive values are stacked to the right (for null offset). The x1 channel contains the value of lesser magnitude (closer to zero) while the x2 channel contains the value of greater magnitude (farther from zero); the difference between them corresponds to the input x channel value.
stackY creates y1 and y2 from y channel
stackY transforms a single y channel into y1 and y2 channels by stacking values that share a common x (and possibly z) value. This replaces a length into lower and upper positions, where the upper position of each element equals the lower position of the next element in the stack. stackY also returns a lazy y channel that computes the midpoint of y1 and y2.
stackY implicit application in area, bar, and rect marks
The areaY, barY, and rectY marks apply the stackY transform implicitly if neither y1 nor y2 is specified. The stack transform can be invoked explicitly to produce identical results.
stackY and stackX reverse option
The reverse option is a boolean that reverses the effective order of layers. For the value order, stackY uses the y value while stackX uses the x value. For the appearance order, stackY uses the x position of the maximum y value while stackX uses the y position of the maximum x value.
stackY and stackX offset option values
The offset option controls the baseline of stacked layers. Supported offset methods are: null (default, zero baseline), normalize (rescale each stack to fill [0, 1]), center (align the centers of all stacks), wiggle (translate stacks to minimize apparent movement, and changes default order to inside-out), or a function to be passed a nested index, and start, end, and z values. If a stack has zero total value, the normalize offset will not adjust the stack's position. Both center and wiggle offsets ensure the lowest element across stacks starts at zero. The wiggle offset is recommended for streamgraphs.
stack offset function signature
An offset function receives four arguments: an index of stacks nested by facet and then stack, an array of start values (x1/y1), an array of end values (x2/y2), and an array of z values. The offset function is responsible for mutating the arrays of start and end values to apply the offset to each stack.
stackY diverging stacks with negative values
The stack transform supports diverging stacks: negative values are stacked below zero while positive values are stacked above zero (for null offset). For stackY, the y1 channel contains the value of lesser magnitude (closer to zero) while the y2 channel contains the value of greater magnitude (farther from zero); the difference between them corresponds to the input y channel value.
stackY and stackX order option values
The order option controls the sequence in which layers are stacked. Supported order methods are: null (default, input order), value (ascending value order, or descending with reverse), x (alias of value, for stackX only), y (alias of value, for stackY only), sum (order series by their total value), appearance (order series by the position of their maximum value), inside-out (default with wiggle offset, orders earliest-appearing series on the inside), a named field or function of data (order data by priority), or an array of z values (enumerate z values in desired order). The value and input order (null) can produce crossing paths and do not guarantee consistent series order across stacks.
stackX default x channel is constant 1
If x is not specified for stackX, it defaults to the constant 1, which is useful for constructing simple isotype charts.
stackY default y channel is constant 1
If y is not specified for stackY, it defaults to the constant 1, which is useful for constructing simple isotype charts or stacked dot charts where a count of data points is desired.
stackX creates x1 and x2 from x channel
stackX transforms a single x channel into x1 and x2 channels by stacking values that share a common y (and possibly z) value. This is the horizontal equivalent of stackY, replacing a length into lower and upper positions along the x axis. stackX also returns a lazy x channel that computes the midpoint of x1 and x2.
Stack transform two-argument form for chaining
If two arguments are passed to stack transform functions, the stack-specific options (offset, order, and reverse) are pulled exclusively from the first options argument, while any channels (x, y, z, etc.) are pulled from the second options argument. Options from the second argument not consumed by the stack transform are passed through. This form is necessary to disambiguate the option recipient when chaining transforms.
stackX2 returns x2 as x channel
stackX2 is like stackX, except that the x2 channel is returned as the x channel. This can be used to draw a line at the right edge of each stacked area.
stackX2 example with data
Plot.stackX2({y: "year", x: "revenue", z: "format", fill: "group"})
stackY1 returns y1 as y channel
stackY1 is like stackY, except that the y1 channel is returned as the y channel instead of y2. This can be used to draw a line at the bottom of each stacked area.
Stack transform output channels
In addition to y1 and y2 output channels, stackY computes a y output channel representing the midpoint of y1 and y2. stackX does the same for x. These channels are lazy and only computed if needed by a downstream mark or transform. The x and y channels can be used to position labels or dots in the center of a stacked layer.
Custom offset function for Likert scale survey results
A custom offset function can be implemented to position responses on a Likert scale such that negative (disagreeing) responses are on one side, positive (agreeing) responses are on the other side, and neutral responses are in the middle. The offset function receives the stacks, start values (x1/x2), end values, and z values, and mutates the start and end values to achieve the desired positioning.
Histogram with binX and implicit stack example
The following code creates a histogram showing weight frequency distribution, grouped by sex, using binX transform and implicit stack: Plot.rectY(olympians, Plot.binX({y: "count"}, {x: "weight", fill: "sex"})).plot()
Bin transform with rect mark example
The following code groups athletes by similar height and weight using a bin transform and encodes the count with fillOpacity: Plot.rect(olympians, Plot.bin({fillOpacity: "count"}, {x: "weight", y: "height", fill: "sex", inset: 0})).plot()
Window transform strict option
The strict option determines whether to output undefined if any window value is undefined. If strict is false (the default), the window size is effectively reduced at the start or end of each series or both, depending on the anchor, and undefined input values are ignored. If strict is true, the output start or end values or both (depending on anchor) of each series may be undefined since there are not enough elements to create a window of size k, and output values may also be undefined if some input values in the corresponding window are undefined. The strict option can have a dramatic effect if some data is missing: when strict, the reducer is skipped if any values in the current window are null, undefined, or NaN.
Window transform supports z channel
The window transform understands the z channel: each distinct z value is treated as a separate series, allowing independent windows to be computed per series.
Plot.window() function
Plot.window(k) returns a window map method for the given window size k, suitable for use with Plot.map. k can be a number, or replaced with an object with properties k, anchor, reduce, or strict for additional options to the window transform.
Plot.windowX() function
Plot.windowX(k, options) applies the window map method with the given window size k to the x channel (x, x1, and x2). k can be a number or an object with properties k, anchor, reduce, or strict. Similar to mapX from the map transform.
windowY example with multiple reducers
Plot.lineY(sftemp, Plot.windowY({k: 28, reduce: 'min'}, {x: 'date', y: 'low', stroke: 'blue'})) computes rolling minimum; similarly use reduce: 'max' for rolling maximum and reduce: 'median' for rolling median.
windowY example with rolling average
Plot.lineY(sftemp, Plot.windowY(k, {x: 'date', y: 'low', stroke: 'blue'})) computes a rolling average of the y values.
Window transform input order dependency
The window transform uses input order, not natural order by value, to determine the meaning of start and end. Use a sort transform to change the order as needed.
Window transform truncation behavior with strict false
When strict is false (the default), the window is automatically truncated as needed. For example, if k is 24 and anchor is middle, the initial 11 values have effective window sizes of 13, 14, 15, ..., 23, and the last 12 values have effective window sizes of 23, 22, 21, ..., 12. Undefined input values are ignored in truncated windows. Values computed with a truncated window may be noisy.
Window transform usage with map for custom channels
While windowY derives y (and y1 and y2), and windowX derives x (x1, and x2), you can use the map transform directly for other channels. For example, use Plot.map({stroke: Plot.window({k: 2, reduce: 'difference'})}, options) to compute a custom derived channel.
Window transform overview
The window transform is a specialized map transform that computes a moving window and derives summary statistics from the current window, such as rolling averages, rolling minimums, or rolling maximums.
Plot.windowY() function
Plot.windowY(k, options) applies the window map method with the given window size k to the y channel (y, y1, and y2). k can be a number or an object with properties k, anchor, reduce, or strict. Similar to mapY from the map transform.
Window transform k option
The k option specifies the window size: the number of consecutive elements in the rolling window. A larger window produces a smoother curve. k is required.
Window transform anchor option
The anchor option specifies how to align the rolling window with the data. Valid values are: start, middle (the default), and end. If middle, the window is centered around the current data point; for time-series data, this incorporates values from the future as well as the past. Setting anchor to end computes a trailing moving average. The window transform uses input order, not natural order by value, to determine the meaning of start and end; when data is in reverse chronological order, the meaning is effectively reversed.
Window transform reduce option
The reduce option specifies how to compute the output value for the current window. It defaults to mean for a rolling average. Named reducers supported are: min (minimum), max (maximum), mean (mean/average), median (median), mode (most common occurrence), pXX (percentile value where XX is 00-99), sum (sum of values), deviation (standard deviation), variance (variance per Welford's algorithm), difference (difference between last and first window value), ratio (ratio of last and first window value), first (first value), and last (last value). A reducer may also be specified as a function passed an index of size k and the corresponding input channel array, or if the function takes one argument, an array of k values.
Plot transforms work automatically with faceting
Transforms are integrated into Plot and work automatically with other Plot features such as faceting. For example, the fy (vertical facet) option can be added to break down grouped data by categories.
Plot includes built-in transforms for data aggregation
Plot's transforms let you aggregate and derive data within your plot specification, reducing time spent preparing data separately. Available transforms include: group, stack, normalize, window (moving averages), dodge, and hexbin (hexagonal binning).
Transforms are composable through options
To apply multiple transforms, you pass the options from one transform to the next. Mark options are plain JavaScript objects, allowing options to be shared across marks and inspected for debugging.