group transform orientation
The group transform groups on both x and y, and often outputs to fill or r as in a heatmap. It also groups on the first channel of z, fill, or stroke, if any.
Observable Plot · all subjects
transforms
239 notes in this subject, read out of this brain and free to use. This is page 3 of 4.
groupZ transform orientation
The groupZ transform groups on neither x nor y, combining everything into one group. It groups on the first channel of z, fill, or stroke, if any. If none of z, fill, or stroke are channels, then all data within each facet is placed into a single group.
groupY transform orientation
The groupY transform groups on y, and often outputs x as in a horizontal bar chart. groupY also groups on the first channel of z, fill, or stroke, if any.
Group transform automatic output channels
In addition to data, the following channels are automatically output by the group transform: x (the horizontal position of the group, only computed by groupX and group transform), y (the vertical position of the group, only computed by groupY and group transform), z (the first value of the z channel, if any), fill (the first value of the fill channel, if any), and stroke (the first value of the stroke channel, if any).
Custom reducer function for group transform
A reducer may be specified as a function to be passed the array of values for each group and the extent of the group, or as an object with a reduceIndex method and optionally a scope property. When using the object form, the reduceIndex method is repeatedly passed three arguments: the index for each group (an array of integers), the input channel's array of values, and the extent of the group (an object {data, x, y}); it must then return the corresponding aggregate value for the group.
Group transform reducer scope option
If the reducer object's scope is data, then the reduceIndex method is first invoked for the full data; the return value of the reduceIndex method is then made available as a third argument, making the extent the fourth argument. Similarly if the scope is facet, then the reduceIndex method is invoked for each facet, and the resulting reduce value is made available while reducing the facet's groups. This optional scope is used by the proportion and proportion-facet reducers.
Group transform channel binding to input channels
Most reducers 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.
Group transform channel computation timing
You can control whether a channel is computed before or after grouping. If a channel is declared only in options (and it is not a special group-eligible channel such as x, y, z, fill, or stroke), it will be computed after grouping and be passed the grouped data: each datum is the array of input data corresponding to the current group. If a channel is declared in both outputs and options, then the channel in options is computed before grouping and can be aggregated using any built-in reducer or custom reducer function during the group transform.
Group transform z dimension priority
If any of z, fill, or stroke is a channel, the first of these channels is considered the z dimension and will be used to subdivide groups.
Group transform default grouping order
By default, empty groups are omitted, and non-empty groups are generated in ascending (natural) order. You can reverse this order using a reverse option or control which groups are included using filter and sort options specified as reducers.
Named reducers for group transform
The group transform supports the following named reducers: first (the first value, in input order), last (the last value, in input order), count (the number of elements, frequency), sum (the sum of values), proportion (the sum proportional to the overall total, weighted frequency), proportion-facet (the sum proportional to the facet total), min (the minimum value), min-index (the zero-based index of the minimum value), max (the maximum value), max-index (the zero-based index of the maximum value), mean (the mean value, average), median (the median value), mode (the value with the most occurrences), pXX (the percentile value, where XX is a number in [00,99]), deviation (the standard deviation), variance (the variance per Welford's algorithm), identity (the array of values), x (the group's x value when grouping on x, added in version 0.6.12), y (the group's y value when grouping on y, added in version 0.6.12), and z (the group's z value: z, fill, or stroke, added in version 0.6.14).
interval transform: converts quantitative or temporal values into continuous extents
The interval transform turns a quantitative or temporal value into a continuous extent [start, stop]. For example, if value is an instant in time, the interval transform could return a start of UTC midnight and a stop of the UTC midnight the following day.
interval mark option for temporal data creates UTC scale and meaningful tick intervals
When using a rectY mark with the interval option and a time interval like 'day', Plot computes a temporal (utc) x scale with ticks at meaningful intervals such as weekly boundaries. This differs from a band scale which would require every distinct value to have its own label.
interval mark option converts singular values into intervals
For marks like barY, the interval option affects the associated channel by converting a singular value into an interval [y1, y2]. For example, specifying interval: 5e6 makes each bar's vertical extent span an interval of 5 million instead of extending to y = 0.
interval option accepts named time intervals, numbers, D3 time intervals, or objects
The interval option can be specified as a named time interval (such as 'day'), a number, a D3 time interval, or any object that implements interval.floor and interval.offset methods.
interval is not a standalone transform but a mark and scale option
The interval transform is not implemented as a standalone transform, but as an option on marks and scales.
interval transform example: rectY with temporal data
Plot.plot({ y: { grid: true, transform: (d) => d / 1e6, label: "Daily trade volume (millions)" }, marks: [ Plot.rectY(aapl.slice(-40), {x: "Date", interval: "day", y: "Volume"}), Plot.ruleY([0]) ] }) This example shows using the interval option with 'day' on a rectY mark to create a temporal UTC x scale instead of an ordinal band scale, allowing meaningful tick placement at weekly boundaries.
interval transform example: barY with numeric interval
Plot.plot({ marginBottom: 80, x: {type: "band"}, y: { grid: true, transform: (d) => d / 1e6, label: "Daily trade volume (millions)" }, marks: [ Plot.barY(aapl.slice(-40), {x: "Date", y: "Volume", interval: 5e6}), Plot.ruleY([0]) ] }) This example shows using a numeric interval on barY where each bar's vertical extent spans an interval of 5 million instead of extending to y = 0.
mapY shorthand for cumsum example
Plot.mapY("cumsum", {y: d3.randomNormal()}) is shorthand for Plot.map({y: "cumsum"}, {y: d3.randomNormal()}).
bollinger map method implementation
The bollinger map method is implemented atop the window map method, computing the mean of values within the rolling window, and then offsetting the mean by a multiple of the rolling deviation.
Bollinger bands with map transform example
Plot.plot({ y: { grid: true }, marks: [ Plot.areaY(aapl, Plot.map({y1: Plot.bollinger({n, k: -k}), y2: Plot.bollinger({n, k})}, {x: "Date", y: "Close", fillOpacity: 0.2})), Plot.lineY(aapl, Plot.map({y: Plot.bollinger({n})}, {x: "Date", y: "Close", stroke: "blue"})), Plot.lineY(aapl, {x: "Date", y: "Close", strokeWidth: 1}) ] }) uses the map transform to construct Bollinger bands, showing both the price and volatility of Apple stock.
Quantile map with window example
Plot.plot({ marks: [ Plot.ruleY([0, 1]), Plot.lineY(aapl, Plot.mapY("quantile", {x: "Date", y: "Volume", strokeOpacity: 0.2})), Plot.lineY(aapl, Plot.windowY(30, Plot.mapY("quantile", {x: "Date", y: "Volume"}))) ] }) maps daily trading volume to a p-quantile in [0, 1] using the quantile map method, then applies a 30-day rolling mean with the window transform to smooth out the noise.
map transform overview
The map transform groups data into series and then transforms each series' values, for example to normalize them relative to a basis or to apply a moving average. It is series-aware: data are first grouped into series using the z, fill, or stroke channel in the same fashion as the area and line marks so that series are processed independently.
Map options supported
The following map methods are supported: cumsum (cumulative sum), rank (the rank of each value in the sorted array), quantile (the rank, normalized between 0 and 1), a function to be passed an array of values returning new values, a function to be passed an index and array of channel values returning new values, or an object that implements the mapIndex method. If a function is used, it must return an array of the same length as the given input. If a mapIndex method is used, it is repeatedly passed the index for each series (an array of integers), the corresponding input channel's array of values, and the output channel's array of values; it must populate the slots specified by the index in the output array.
Plot.map() signature and behavior
Plot.map(outputs, options) groups on the first channel of z, fill, or stroke if any, and then for each channel declared in the specified outputs object, applies the corresponding map method. Each channel in outputs must have a corresponding input channel in options.
Plot.mapX() signature and behavior
Plot.mapX(map, options) is equivalent to Plot.map({x: map, x1: map, x2: map}, options), but ignores any of x, x1, and x2 not present in options. If none of x, x1, or x2 are specified, then x defaults to identity.
Plot.mapY() signature and behavior
Plot.mapY(map, options) is equivalent to Plot.map({y: map, y1: map, y2: map}, options), but ignores any of y, y1, and y2 not present in options. If none of y, y1, or y2 are specified, then y defaults to identity.
Random walk cumsum example
Plot.plot({ marks: [ Plot.ruleY([0]), Plot.lineY({length: 600}, Plot.mapY("cumsum", {y: d3.randomNormal()})) ] }) shows a random walk computed as a cumulative sum of random numbers sampled from a normal distribution.
normalizeX basis options
The basis option for normalizeX specifies how to normalize series values. Valid options are: first (the first value, default), last (the last value), min (the minimum value), max (the maximum value), mean (the mean value), median (the median value), pXX (the percentile value, where XX is a number in [00,99]), sum (the sum of values), extent (the minimum is mapped to zero and the maximum to one), deviation (subtract the mean then divide by the standard deviation), a function passed an array of values returning the desired basis, or a function passed an index and channel value array returning the desired basis.
Plot.normalize() method
Plot.normalize(basis) returns a normalize map method for the given basis, suitable for use with the map transform. The basis parameter is required.
Plot.normalizeY() method signature and options
Plot.normalizeY(basis, options) works like mapY but applies the normalize map method with the given basis. The basis parameter can be a string specifying the normalization type. Alternatively, normalizeY can accept a single options object with the basis property mixed in, like Plot.normalizeY({basis: "first", x: "Date", y: "Close", stroke: "Symbol"}). If not specified, the basis defaults to first.
Index chart example with normalizeY
An index chart shows the return of several stocks relative to their closing price on a particular date. This is created by using Plot.normalizeY with the y: "Close" and stroke: "Symbol" channels to show how each stock's price has changed relative to its starting value.
Proportional demographics example with normalizeX
The normalize transform can compute proportional demographics from absolute populations. Using Plot.normalizeX("sum", {z: "state", x: "population", y: "state"}) normalizes population values by the sum, so x represents the proportion of each state's population in each age group.
Normalize transform overview
The normalize transform is a specialized map transform that normalizes series values relative to some basis, converting absolute values into relative values. It groups y by z, fill, or stroke into separate series before normalizing.
shiftY example
Plot.shiftY("7 days", {y: "Date", x: "Close"}) shifts the y channel by 7 days.
shift transform overview
The shift transform is a specialized map transform that derives an output x1 channel by shifting the x channel. It can be used with the difference mark to show change over time.
shiftX function signature and interval specification
shiftX takes an interval and options object: Plot.shiftX(interval, options). The interval may be specified as: a name (second, minute, hour, day, week, month, quarter, half, year, monday, tuesday, wednesday, thursday, friday, saturday, sunday) with an optional number and sign (e.g., +3 days or -1 year); or as a number; or as an implementation such as d3.utcMonth with interval.floor(value), interval.offset(value), and interval.range(start, stop) methods.
shiftX channel aliases and domain behavior
The shiftX transform aliases the x channel to x2 and derives an x1 channel from the x channel by shifting values by the given interval. It applies a domain hint to the x2 channel such that by default the plot shows only the intersection of x1 and x2. For example, if the interval is +1 year, the first year of the data is not shown.
shiftY function signature and behavior
shiftY takes an interval and options object: Plot.shiftY(interval, options). It derives a y1 channel from the input y channel by shifting values by the given interval. The shiftY transform also aliases the y channel to y2 and applies a domain hint to the y2 channel such that by default the plot shows only the intersection of y1 and y2. For example, if the interval is +1 year, the first year of the data is not shown.
shiftX with differenceY example
Plot.differenceY(aapl, Plot.shiftX("365 days", {x: "Date", y: "Close"})).plot({y: {grid: true}}) shows Apple stock price changes over a one-year interval using the shiftX transform with differenceY mark.
select example: selectFirst implemented with function
Plot.select((I) => [I[0]], {x: "Date", y: "Close"}) This shows how to implement selectFirst using a selector function that returns the first element of the series index.
select example: selectMinY implemented with function
Plot.select({y: (I, Y) => [d3.least(I, (i) => Y[i])]}, {x: "Date", y: "Close"}) This shows how to implement selectMinY using a value selector function that uses d3.least to find the index with minimum channel value.
select example: selecting point closest to median
function selectorMedian(I, V) { const median = d3.median(I, (i) => V[i]); const i = d3.least(I, (i) => Math.abs(V[i] - median)); return [i]; } Plot.select({y: selectorMedian}, {x: "year", y: "revenue", fill: "format"}) This example selects the point within each series that is closest to the median of y.
select example: sampling 10% of data
function selectorSample(I) { return I.filter((i, j) => j % 10 === 0); } Plot.select({y: selectorSample}, {x: "Date", y: "Close"}) This example selects a sample of 10% of the data by filtering every tenth element.
select determines first/last by input order, not value order
The select transform uses input order, not natural order by value, to determine the meaning of first and last.
select transform: filters data to show subset per series
The select transform filters a mark's index to show a subset of the data. It is a specialized filter transform that pulls a single value or a sample subset out of each series.
selectLast(options) selects last point of each series
Plot.selectLast(options) selects the last point of each series according to input order.
selectMinX(options) selects leftmost point of each series
Plot.selectMinX(options) selects the leftmost point of each series.
selectMinY(options) selects lowest point of each series
Plot.selectMinY(options) selects the lowest point of each series.
selectMaxX(options) selects rightmost point of each series
Plot.selectMaxX(options) selects the rightmost point of each series.
selectMaxY(options) selects highest point of each series
Plot.selectMaxY(options) selects the highest point of each series.
select example: labeling last value in line chart
Plot.plot({ y: {grid: true}, marks: [ Plot.ruleY([0]), Plot.line(aapl, {x: "Date", y: "Close"}), Plot.text(aapl, Plot.selectLast({x: "Date", y: "Close", text: "Close", frameAnchor: "bottom", dy: -6})) ] }) This example uses selectLast to label the last value in a line chart.
select example: labeling extreme values in line chart
Plot.plot({ y: {grid: true}, marks: [ Plot.ruleY([0]), Plot.line(aapl, {x: "Date", y: "Close"}), Plot.text(aapl, Plot.selectMinY({x: "Date", y: "Close", text: "Close", frameAnchor: "top", dy: 6})), Plot.text(aapl, Plot.selectMaxY({x: "Date", y: "Close", text: "Close", frameAnchor: "bottom", dy: -6})) ] }) This example uses selectMinY and selectMaxY to label the lowest and highest values.
select(selector, options) syntax and selector types
The select function signature is Plot.select(selector, options). The selector parameter can be: a named selector (either 'first' or 'last'), a function which receives the series index as input, or a {name: value} object with exactly one name. In the object form, name is the name of a channel and value is a value selector, which can be a named selector ('min' or 'max') or a function which receives the series index and the channel values.
select selector function returns subset of passed-in series index
A selector function must return the selected index as a subset of the passed-in series index.
selectFirst(options) selects first point of each series
Plot.selectFirst(options) selects the first point of each series according to input order.
select uses z, fill, or stroke channel to group data into series
The select transform groups data into series using the z, fill, or stroke channel in the same fashion as the area and line marks.
select example: labeling last point in multi-series line chart
Plot.plot({ y: {grid: true}, marks: [ Plot.ruleY([0]), Plot.line(stocks, {x: "Date", y: "Close", stroke: "Symbol"}), Plot.text(stocks, Plot.selectLast({x: "Date", y: "Close", z: "Symbol", text: "Symbol", textAnchor: "start", dx: 3})) ] }) This example uses selectLast with z channel to label the last point in each series of a multi-series line chart.
select example: selecting point with highest channel value
Plot.select({fill: "max"}, {x: "date", y: "city", z: "city", fill: "temperature"}) This example selects the point in each city with the highest temperature (selectMaxFill).
shuffle() transform randomizes mark index order
Plot.shuffle({x: 'culmen_length_mm', y: 'culmen_depth_mm'}) shuffles the data randomly. If a seed option is specified, a linear congruential generator with the given seed is used to generate random numbers; otherwise Math.random is used.