barX example with two quantitative values
Plot.barX(civilizations, {x1: "start", x2: "end", y: "civilization", sort: {y: "x1"}})
Observable Plot · all subjects
marks
512 notes in this subject, read out of this brain and free to use. This is page 3 of 9.
Axis mark composite structure
Plot's axis mark is a composite mark comprised of: a vector for ticks, a text mark for tick labels, and a text mark for an axis label. The stroke option affects the color of the tick vector, while the fill option affects the color of the text labels; both default to the color option, which defaults to currentColor.
Axis mark data and ticks options
By default, the data for an axis mark are tick values sampled from the associated scale's domain. Axis options for generating ticks: ticks (the approximate number of ticks to generate, or interval, or array of values), tickSpacing (the approximate number of pixels between ticks if ticks is not specified), interval (an interval or time interval).
Axis mark options
Axis mark options: anchor (the axis orientation: top or bottom for x or fx; left or right for y or fy), tickSize (the length of the tick vector in pixels; default 6 for x or y, or 0 for fx or fy), tickPadding (the separation between the tick vector and its label in pixels; default 3), tickFormat (either a function or specifier string to format tick values), tickRotate (whether to rotate tick labels, an angle in degrees clockwise; default 0), fontVariant (the ticks' font-variant; defaults to tabular-nums for quantitative axes), label (a string to label the axis; defaults to the scale's label, perhaps with an arrow), labelAnchor (the label anchor: top, right, bottom, left, or center), labelArrow (the label arrow: auto (default), up, right, down, left, none, or true), labelOffset (the label position offset in pixels; default depends on margins and orientation), color (the color of the ticks and labels; defaults to currentColor), textStroke (the color of the stroke around tick labels; defaults to none), textStrokeOpacity (the opacity of the stroke around tick labels), textStrokeWidth (the thickness of the stroke around tick labels in pixels).
axisFy function
Plot.axisFy(data, options) returns a new fy (facet y) axis with the given options. The default anchor is 'right' and the default label is null.
axisFx function
Plot.axisFx(data, options) returns a new fx (facet x) axis with the given options. The default anchor is 'top' and the default label is null.
axisY function
Plot.axisY(data, options) returns a new y axis with the given options. The default anchor is 'left' and default tickSpacing is 35 pixels.
axisX function
Plot.axisX(data, options) returns a new x axis with the given options. The default anchor is 'bottom' and default tickSpacing is 80 pixels.
Axis textAnchor option
The textAnchor option can be used to position tick labels, for example to extend the y-axis tick labels to the right and into the frame with the value 'start'.
labelAnchor option for y and fy axes
For the y and fy axis, the labelAnchor option controls the position of the axis label and may be top, center, or bottom. It defaults to center for ordinal scales and top for quantitative scales. When the label anchor is center, the label is rotated by 90° to fit, though you may need to adjust the margins to avoid overlap between the tick labels and the axis label.
Axis text stroke options
To draw an outline around the tick labels to improve legibility when drawing axes atop other marks, use the textStroke option (default none), textStrokeWidth option (default 3), and textStrokeOpacity option (default 1).
Axis color, stroke, and fill options
The color of an axis can be controlled with the color, stroke, and fill options, which affect the axis' component marks differently. The stroke option affects the tick vector; the fill option affects the label texts. The color option is shorthand for setting both fill and stroke. These options can be specified as channels to assign colors dynamically based on the associated tick value.
Time axis default format
Time axes default to a consistent multi-line tick format consisting of two fields (e.g., month and year, day and month, minutes and hours). When a tick has the same second field value as the previous tick, only the first field is shown for brevity. The format is inferred from the tick interval.
Scale ticks and tickSpacing not inherited by explicit axis marks
When an axis mark is declared explicitly (via the marks plot option, as opposed to an implicit axis), the corresponding scale's scale.ticks and scale.tickSpacing options are not automatically inherited by the axis mark; however, the scale.interval option is inherited, as is the scale.label option.
Axis label arrow option
The labelArrow option controls the arrow (↑, →, ↓, or ←) added to the axis label indicating the direction of ascending value. If auto (the default), the arrow will be added only if the scale is quantitative or temporal; if true, the arrow will also apply to ordinal scales, provided the domain is consistently ordered. Options are: auto (default), up, right, down, left, none, or true.
Axis default margins
The axis mark's default margins depend on its orientation (anchor) as follows, in order of marginTop, marginRight, marginBottom, and marginLeft, in pixels: top (30, 20, 0, 20), right (20, 40, 20, 0), bottom (0, 20, 30, 20), left (20, 0, 20, 40).
labelAnchor option for x and fx axes
For the x or fx axis, the labelAnchor option controls the position of the axis label and may be left, center, or right. It defaults to center for ordinal scales and right for quantitative scales.
Implicit axis behavior
If you don't declare an axis mark for a position scale, Plot will implicitly add one for you below (before) all other marks. To disable an implicit axis, set the scale.axis option to null for the corresponding scale, or set the top-level axis option to null to disable all implicit axes.
Axis lineWidth option for wrapping tick labels
The text mark's lineWidth option can be used to wrap long tick labels (and even soft hyphens). This option is expressed in ems, not pixels, and you may have to reserve additional marginBottom to make room for multiple lines.
bollingerX example: basic usage with aapl data
Plot.bollingerX(aapl, {y: "Date", x: "Close"}).plot()
bollingerY example: shorthand with array of numbers
Plot.bollingerY(aapl.map((d) => d.Close)).plot()
bollinger mark: composite mark structure
The bollinger mark is a composite mark consisting of two marks: an area mark representing volatility as a band, and a line mark representing a moving average. The band thickness is proportional to the deviation of nearby values.
bollinger mark: candlestick chart combination
Plot.plot({x: {domain: [new Date("2014-01-01"), new Date("2014-06-01")]}, y: {domain: [68, 92], grid: true}, color: {domain: [-1, 0, 1], range: ["red", "black", "green"]}, marks: [Plot.bollingerY(aapl, {x: "Date", y: "Close", stroke: "none", clip: true}), Plot.ruleX(aapl, {x: "Date", y1: "Low", y2: "High", strokeWidth: 1, clip: true}), Plot.ruleX(aapl, {x: "Date", y1: "Open", y2: "Close", strokeWidth: 3, stroke: (d) => Math.sign(d.Close - d.Open), clip: true})]})
bollingerY example: basic usage with aapl data
Plot.bollingerY(aapl, {x: "Date", y: "Close", n: 20, k: 2}).plot()
bollinger mark example: with line marks and map transform
Plot.lineY(data, Plot.mapY(Plot.bollinger({n: 20, k: -2}), {x: "Date", y: "Close", stroke: "red"}))
bollinger map method
Plot.bollinger(options) returns a bollinger map method for use with the map transform. The k option here defaults to zero instead of two.
bollingerY constructor
Plot.bollingerY(data, options) returns a bollinger mark for when time goes right (or left). If the y option is not specified, it defaults to the identity function, as when data is an array of numbers [y₀, y₁, y₂, …]. If the x option is not specified, it defaults to [0, 1, 2, …].
bollingerX constructor
Plot.bollingerX(data, options) returns a bollinger mark for when time goes up (or down). If the x option is not specified, it defaults to the identity function, as when data is an array of numbers [x₀, x₁, x₂, …]. If the y option is not specified, it defaults to [0, 1, 2, …].
bollinger mark options: window transform passthrough and defaults
Additional options are passed through to the underlying line mark, area mark, and window transform. Unlike the window transform, the strict option defaults to true, and the anchor option defaults to end, which assumes that the data is in chronological order.
bollinger mark options: fill, fillOpacity, stroke, strokeOpacity, strokeWidth
The bollinger mark supports the following special options: fill (fill color of the area; defaults to color), fillOpacity (fill opacity of the area; defaults to opacity), stroke (stroke color of the line; defaults to color), strokeOpacity (stroke opacity of the line; defaults to 1), strokeWidth (stroke width of the line in pixels; defaults to 1.5).
bollinger mark options: n, k, color, opacity
The bollinger mark supports the following special options: n (window size, the window transform's k option, an integer; defaults to 20), k (band radius, a number representing a multiple of standard deviations; defaults to 2), color (fill color of the area and stroke color of the line; defaults to currentColor), opacity (fill opacity of the area; defaults to 0.2).
Box mark with binned quantitative values using Math.floor
Plot.plot({ marginLeft: 60, y: { grid: true, label: "Price" }, x: { interval: 0.5, label: "Carats", labelAnchor: "right", tickFormat: (x) => x.toFixed(1) }, marks: [ Plot.ruleY([0]), Plot.boxY(diamonds, {x: (d) => Math.floor(d.carat * 2) / 2, y: "price"}) ] })
Binning quantitative values for box mark with faceting
To group quantitative values with a box mark, use faceting with the interval scale option on the fx scale. This is easier than manual binning with Math.floor. The scale interval transform is applied after the box mark applies the group transform, so this technique works better with faceting than with the x scale.
Box mark with binned quantitative values using faceting interval
Plot.plot({ marginLeft: 60, y: { grid: true, label: "Price" }, fx: { interval: 0.5, label: "Carats", labelAnchor: "right", tickFormat: (x) => x.toFixed(1) }, marks: [ Plot.ruleY([0]), Plot.boxY(diamonds, {fx: "carat", y: "price"}) ] })
Box mark with array of numbers shorthand
As shorthand, you can pass an array of numbers for a single boxplot without specifying data and options separately, such as Plot.boxX([0, 3, 4.4, 4.5, 4.6, 5, 7]).plot().
Box mark options for styling
The box mark accepts the following styling options: fill (fill color of the bar; defaults to #ccc), fillOpacity (fill opacity of the bar; defaults to 1), stroke (stroke color of the rule, tick, and dot; defaults to currentColor), strokeOpacity (stroke opacity of the rule, tick, and dot; defaults to 1), strokeWidth (stroke width of the tick; defaults to 1), and r (radius of the dot; defaults to 3). Other options are passed through to the underlying marks (rule, bar, tick, and dot).
boxX creates horizontal boxplots
Plot.boxX() returns a horizontal box mark. If the x option is not specified, it defaults to the identity function, as when data is an array of numbers. If the y option is not specified, it defaults to null; if specified, it should represent an ordinal (discrete) value.
boxY creates vertical boxplots
Plot.boxY() returns a vertical box mark. If the y option is not specified, it defaults to the identity function, as when data is an array of numbers. If the x option is not specified, it defaults to null; if specified, it should represent an ordinal (discrete) value.
Box mark uses group transform
The box mark uses the group transform to group and aggregate data. Because of this, the secondary dimension must be ordinal. To group quantitative values, bin manually (for example with Math.floor).
Box mark definition and composition
The box mark is a composite mark that summarizes one-dimensional distributions as boxplots. It consists of a rule to represent extreme values (not including outliers), a bar to represent the interquartile range (trimmed to the data), a tick to represent the median value, and a dot to represent any outliers.
Box mark example with horizontal boxplots
Plot.plot({ x: { grid: true, inset: 6 }, marks: [ Plot.boxX(morley, {x: "Speed", y: "Expt"}) ] })
Cell mark inset option
The cell mark supports the inset option as part of standard mark options. The inset option can be used to add spacing around cells, as seen in examples using inset: 0.5.
Cell mark Simpsons ratings heatmap example
Example: Plot.plot({ padding: 0, grid: true, x: {axis: "top", label: "Season"}, y: {label: "Episode"}, color: {type: "linear", scheme: "PiYG"}, marks: [Plot.cell(simpsons, {x: "season", y: "number_in_season", fill: "imdb_rating", inset: 0.5}), Plot.text(simpsons, {x: "season", y: "number_in_season", text: (d) => d.imdb_rating?.toFixed(1), fill: "black", title: "title"})] }) This creates a heatmap showing IMDb ratings across Simpsons episodes by season and episode number.
Plot.cellY() function signature
Plot.cellY(data, options) is equivalent to cell, except that if the y option is not specified, it defaults to [0, 1, 2, …], and if the fill option is not specified and stroke is not a channel, the fill defaults to the identity function and assumes that data = [y₀, y₁, y₂, …].
Cell mark with group transform example
Example: Plot.plot({ padding: 0, y: {tickFormat: Plot.formatMonth("en", "short")}, marks: [Plot.cell(seattle, Plot.group({fill: "max"}, { x: (d) => d.date.getUTCDate(), y: (d) => d.date.getUTCMonth(), fill: "temp_max", inset: 0.5 }))] }) This creates a heatmap showing the maximum observed temperature by month and date using the group transform.
Cell mark heatmap example with faceting
Example: Plot.plot({ padding: 0, x: {axis: null}, y: {tickFormat: Plot.formatWeekday("en", "narrow"), tickSize: 0}, fy: {tickFormat: ""}, color: {scheme: "PiYG"}, marks: [Plot.cell(dji, { x: (d) => d3.utcWeek.count(d3.utcYear(d.Date), d.Date), y: (d) => d.Date.getUTCDay(), fy: (d) => d.Date.getUTCFullYear(), fill: (d, i) => i > 0 ? (d.Close - dji[i - 1].Close) / dji[i - 1].Close : NaN, title: (d, i) => i > 0 ? ((d.Close - dji[i - 1].Close) / dji[i - 1].Close * 100).toFixed(1) : NaN, inset: 0.5 })] }) This creates a calendar view showing almost twenty years of daily changes of the Dow Jones Industrial Average, using fy for year-based faceting.
Cell mark ordinal scale ticks option
When an ordinal scale domain has high cardinality, the ticks scale option can be used to specify which ticks to label. Alternatively, consider using a quantitative or temporal scale instead, such as by switching to a bar mark.
Cell mark interval scale option
When ordinal data is regular, such as yearly observations, use the interval scale option to enforce uniformity and show gaps for missing data. It can be set to a named interval such as hour or day, a number for numeric intervals, a d3-time interval, or a custom implementation.
One-dimensional cell marks
A one-dimensional cell is produced by specifying only x or only y. One-dimensional cells can be a compact alternative to a bar chart, where the fill color of the cell replaces the length of the bar. However, position is a more salient encoding and should be preferred to color if space is available.
Cell mark with group transform
The cell mark can be combined with the group transform, which groups data by ordinal value. The bin transform, on the other hand, is intended for quantitative data and is typically paired with the rect mark.
Plot.cellX() function signature
Plot.cellX(data, options) is equivalent to cell, except that if the x option is not specified, it defaults to [0, 1, 2, …], and if the fill option is not specified and stroke is not a channel, the fill defaults to the identity function and assumes that data = [x₀, x₁, x₂, …].
Plot.cell() function signature
Plot.cell(data, options) returns a new cell with the given data and options. If neither the x nor y options are specified, data is assumed to be an array of pairs [[x₀, y₀], [x₁, y₁], [x₂, y₂], …] such that x = [x₀, x₁, x₂, …] and y = [y₀, y₁, y₂, …].
Cell mark stroke and fill defaults
The stroke defaults to none. The fill defaults to currentColor if the stroke is none, and to none otherwise.
Cell mark x and y channels
The cell mark supports x (horizontal position, bound to the x scale which must be band) and y (vertical position, bound to the y scale which must be band) channels. If x is not specified, the cell spans the full horizontal extent of the plot or facet. If y is not specified, the cell spans the full vertical extent of the plot or facet.
Cell mark overview
The cell mark draws rectangles positioned in two ordinal dimensions. It is a variant of the rect mark for use when both dimensions are ordinal. The plot's x and y scales must be band scales. Cells typically have a fill color encoding.
Contour filled vs stroked
The value option produces isolines suitable for stroking. The fill option produces filled contours. Setting fill to Plot.identity applies a color encoding to the contour values, allowing the contour values to be read via a color legend.
Contour mark overview
The contour mark draws isolines to delineate regions above and below a particular continuous value. Contours are computed by applying the marching squares algorithm to a discrete grid. The grid can be constructed either by interpolating spatial samples (arbitrary points in x and y) or by sampling a continuous function f(x,y) along the grid.
Contour drawing order and overlap
Contours are drawn in ascending value order, with the highest value on top. Filled contour polygons overlap. For isobands, see GitHub issue #1420.
Contour grid row-major order
The grid is a list of numbers in row-major order. The first number is the value of the bottom-left corner. Elevations of the first row are followed by the second row, then the third, and so on. Grid points represent the middle of each pixel rather than the corner.
Contour levels with interval or thresholds
Contour levels can be specified either with the interval option (a contour at each multiple of the specified value) or with the thresholds option (either a count of thresholds or an explicit array of values), similar to the bin transform.