Plot.link() constructor
Plot.link(data, options) returns a new link with the given data and options.
Observable Plot · all subjects
marks
512 notes in this subject, read out of this brain and free to use. This is page 7 of 9.
Link mark definition and purpose
The link mark draws straight lines between two points [x1, y1] and [x2, y2] in quantitative dimensions. It is similar to the arrow mark, except it draws a straight line — or geodesic when used with a spherical projection.
Link mark required channels
The link mark requires four channels: x1 (starting horizontal position, bound to x scale), y1 (starting vertical position, bound to y scale), x2 (ending horizontal position, bound to x scale), and y2 (ending vertical position, bound to y scale).
Link mark shorthand options
For vertical or horizontal links, the x option can be specified as shorthand for both x1 and x2, and the y option can be specified as shorthand for both y1 and y2.
Link mark default styling
The stroke defaults to currentColor. The fill defaults to none. The strokeWidth and strokeMiterlimit default to one.
raster mark channels
When data is provided as discrete samples, the fill and fillOpacity channels specify abstract values (such as height in a topographic map) to be spatially interpolated to produce an image. These channels may alternatively be specified as continuous functions f(x, y).
raster mark spatial interpolators overview
Raster marks use spatial interpolators to populate a raster grid from discrete spatial samples. Built-in methods are: none (or null, assign each sample to the containing pixel), nearest (assign each pixel to the closest sample's value, Voronoi diagram), barycentric (apply barycentric interpolation over the Delaunay triangulation), and random-walk (apply a random walk from each pixel, stopping when near a sample).
raster mark basic usage with gridded data
The raster mark renders a raster image from discrete pixels in a grid. For gridded data, pass a flat array of values in row-major order and specify width and height. The first value represents the bottom-left corner, and the array is ordered row by row from bottom to top. Example: Plot.raster(volcano.values, {width: volcano.width, height: volcano.height})
raster grid coordinate system and pixel alignment
In raster marks, grid points represent the middle of each pixel, not the corner. The first row of data appears at the bottom of the image because y increases upward. Pixels are indexed in row-major order where the first number represents the bottom-left corner.
raster mark with function-based fill
The raster mark can accept fill as a continuous function f(x, y) that is evaluated at each pixel centroid of the raster grid without interpolation. When faceting, the function receives a third argument of facet values {fx, fy}. Example: Plot.raster({x1: -1, x2: 1, y1: -1, y2: 1, fill: (x, y) => Math.atan2(y, x)})
raster mark dimension options
Raster dimensions can be specified with: width (number of pixels on each horizontal line, positive integer), height (number of lines, positive integer), x1 (starting horizontal position, bound to x scale), x2 (ending horizontal position, bound to x scale), y1 (starting vertical position, bound to y scale), y2 (ending vertical position, bound to y scale), or pixelSize (screen size of a raster pixel, defaults to 1).
raster mark dimension defaults
If width is specified, x1 defaults to 0 and x2 defaults to width. If height is specified, y1 defaults to 0 and y2 defaults to height. If data is specified but width and height are not, x1, y1, x2, and y2 default to the frame's left, top, right, and bottom coordinates. If data is not specified, x1, x2, y1, and y2 must all be specified explicitly.
custom raster spatial interpolator function signature
The interpolate option can be specified as a function with arguments: index (array of numeric indexes into channels x, y, value), width (width of raster grid, positive integer), height (height of raster grid, positive integer), x (array of x-positions of samples), y (array of y-positions of samples), value (array of sample values). The expression x[index[0]] represents the x-position of the first sample, y[index[0]] its y-position, and value[index[0]] its value.
interpolateNearest function
Plot.interpolateNearest assigns each pixel in the raster grid the value of the closest sample, effectively creating a Voronoi diagram. Signature: interpolateNearest(index, width, height, x, y, value)
interpolateNone function
Plot.interpolateNone applies simple forward mapping of samples, binning them into pixels in the raster grid without blending or interpolation. If multiple samples map to the same pixel, the last one wins. This can introduce bias if points are not in random order, so use Plot.shuffle to randomize input if needed. Signature: interpolateNone(index, width, height, x, y, value)
interpolatorBarycentric function
Plot.interpolatorBarycentric() constructs a Delaunay triangulation of samples, then for each pixel determines the covering triangle and interpolates values at the triangle's vertices using barycentric coordinates. For ordinal or categorical values, one of the three values is picked randomly weighted by barycentric coordinates. Accepts options: random (number generator, defaults to linear congruential generator with fixed seed for deterministic results). Signature: interpolatorBarycentric(options)
interpolatorRandomWalk function
Plot.interpolatorRandomWalk() initiates a random walk from each pixel, stopping when the walk is within minDistance of a sample or maxSteps have been taken, then assigns the pixel the closest sample's value. Uses the 'walk on spheres' algorithm. Accepts options: random (number generator, defaults to linear congruential generator with fixed seed), minDistance (distance threshold to stop walk), maxSteps (maximum steps allowed). Signature: interpolatorRandomWalk(options)
raster mark with arbitrary spatial samples
The raster mark works with samples in arbitrary positions and arbitrary order, not just strictly gridded data. It requires x and y channel specifications for sample positions and a fill or fillOpacity channel for values. The interpolate option is used to spatially interpolate these scattered samples into a continuous image.
raster mark projection support
The raster mark supports Plot's projection system. When using projections, the raster can be clipped to a projection shape using the clip option, such as clip: 'sphere' for a spherical projection.
imageRendering Safari limitation
Safari does not currently support the imageRendering option for raster marks.
raster blur option for smoothing
The blur option accepts a non-negative pixel radius for smoothing the raster image. It defaults to 0. This is particularly useful with the random-walk interpolator to smooth the grainy output.
raster mark function signature
Plot.raster(data, options) returns a new raster mark with the given optional data and options. Data can be an array of values for gridded data or an array of objects with x, y, and fill properties for scattered samples.
raster mark constant options
Raster marks support the following constant options: colorSpace (the color space, may be set to 'display-p3' for Display P3 color space), interpolate (the spatial interpolation method), imageRendering (the image-rendering attribute, defaults to 'auto' for bilinear, may be set to 'pixelated' for sharper image), blur (non-negative pixel radius for smoothing, defaults to 0).
rect mark with bin transform produces histograms and heatmaps
The rect mark is often used with the bin transform to produce histograms or heatmaps. When paired with bin, it sets default inset options for a 1px gap separating adjacent rects. The bin transform can be used with the rect constructor to produce two-dimensional histograms (heatmaps) where density is represented by fill color encoding.
rect mark: axis-aligned rectangles defined by x1, y1, x2, y2
The rect mark draws axis-aligned rectangles defined by x1, y1, x2, and y2 coordinates. These four channels define the starting and ending horizontal and vertical positions of each rectangle.
rect mark channels: x1, y1, x2, y2
The rect mark supports the following optional channels: x1 (starting horizontal position, bound to x scale), y1 (starting vertical position, bound to y scale), x2 (ending horizontal position, bound to x scale), and y2 (ending vertical position, bound to y scale).
rect mark: band scale requirement for partial coordinates
If x1 is specified but x2 is not specified, then x must be a band scale. If y1 is specified but y2 is not specified, then y must be a band scale.
rect mark with interval option derives x1 and x2 from x
If an interval is specified such as d3.utcDay, x1 and x2 can be derived from x by calling interval.floor(x) to produce x1, and interval.offset(x1) to produce x2. The same process applies for y, y1, and y2. If the interval is specified as a number n, x1 and x2 are taken as the two consecutive multiples of n that bracket x. Named UTC intervals such as day are also supported.
rect mark standard options and defaults
The rect mark supports standard mark options including insets and rounded corners. The stroke option defaults to none. The fill option defaults to currentColor if the stroke is none, and to none otherwise.
rect mark rounded corners: r, rx1, ry1, rx2, ry2, rx1y1, rx2y1, rx2y2, rx1y2
The rect mark supports the following corner radius options: r (uniform radius on all corners), rx1 (radius on left side), ry1 (radius on top side), rx2 (radius on right side), ry2 (radius on bottom side), rx1y1 (radius on top-left corner), rx2y1 (radius on top-right corner), rx2y2 (radius on bottom-right corner), and rx1y2 (radius on bottom-left corner). When stacking rounded rects vertically, use positive ry2 and negative ry1. When stacking horizontally, use positive rx2 and negative rx1. If combined corner radii exceed width or height, radii are proportionally reduced to produce a pill shape.
rectX convenience constructor
rectX is equivalent to rect, except that if neither x1 nor x2 is specified, the x option can be used as shorthand to apply an implicit stackX transform. This is the typical configuration for a histogram with horizontal rectangles aligned at x = 0. If the x option is not specified, it defaults to the identity function.
rectY convenience constructor
rectY is equivalent to rect, except that if neither y1 nor y2 is specified, the y option can be used as shorthand to apply an implicit stackY transform. This is the typical configuration for a histogram with vertical rectangles aligned at y = 0. If the y option is not specified, it defaults to the identity function.
rect mark opts out of implicit stack when x1, x2, y1, or y2 specified
For overlapping rects, you can opt-out of the implicit stack transform by specifying either x1 or x2 for rectX, and likewise either y1 or y2 for rectY.
rect mark with interval transform for single values
The interval transform may be used to convert a single value in x or y (or both) into an extent. Unlike the bin transform, the interval transform produces overlapping rects if multiple points have the same position.
rect mark example: geographic bounding boxes
Plot.rect(countyboxes, {x1: "0", y1: "1", x2: "2", y2: "3", stroke: "currentColor"}) displays geographic bounding boxes as [x1, y1, x2, y2] tuples where x1 and x2 are degrees longitude and y1 and y2 are degrees latitude.
rectY example: basic histogram with bin transform
Plot.rectY(bins, {x1: "x0", x2: "x1", y: "length"}).plot({round: true}) produces a basic histogram from binned observations. Alternatively, Plot.rectY(d3.range(1000).map(d3.randomNormal()), Plot.binX()).plot() automatically bins quantitative values.
rectY example: vertical histogram with fill by category
Plot.rectY(olympians, Plot.binX({y: "count"}, {x: "weight", fill: "sex"})) with Plot.ruleY([0]) creates a vertical histogram with rects colored by the sex category.
rectY example: overlapping histogram with blendMode
Plot.rectY(olympians, Plot.binX({y2: "count"}, {x: "weight", fill: "sex", mixBlendMode: "multiply"})) with Plot.ruleY([0]) creates overlapping histograms where y2 avoids implicit stacking and mixBlendMode mitigates occlusion.
rect example: two-dimensional histogram heatmap
Plot.rect(diamonds, Plot.bin({fill: "count"}, {x: "carat", y: "price", thresholds: 100})) creates a heatmap where density is represented by fill color encoding.
rect example: interval transform for calendar heatmap
Plot.rect(seattle.filter((d) => d.date.getUTCFullYear() === 2015), {x: (d) => d.date.getUTCDate(), y: (d) => d.date.getUTCMonth(), interval: 1, fill: "temp_max", inset: 0.5}) creates a calendar heatmap showing daily maximum temperature where interval: 1 expands day-in-month and month-in-year numbers to unit intervals.
rect mark supports faceting
The rect mark and bin transform naturally support faceting. For example, Plot.rectY(olympians, Plot.binX({y: "count"}, {x: "weight", fy: "sex"})) creates faceted histograms separated by sex.
Rule mark opacity for dense overlaps
Reducing strokeOpacity on rules allows better perception of density when rules overlap.
Rule mark purpose: horizontal vs vertical lines
The rule mark draws either horizontal or vertical lines. ruleY draws a horizontal line with a given y value, while ruleX draws a vertical line with a given x value. Rules should be used when the secondary position dimension is quantitative; when it is ordinal, use a tick mark instead.
ruleY channels and defaults
ruleY has the following optional channels: y (vertical position, bound to y scale), x1 (starting horizontal position, bound to x scale), and x2 (ending horizontal position, bound to x scale). If y is not specified, it defaults to identity and assumes data = [y₀, y₁, y₂, …]. If y is null, the rule is centered vertically in the plot frame. If x is specified, it is shorthand for x2 with x1 equal to zero. If x1 is not specified, the rule starts at the left edge of the plot or facet. If x2 is not specified, the rule ends at the right edge of the plot or facet.
ruleY interval option for deriving x1 and x2
If an interval is specified for ruleY, such as d3.utcDay, x1 and x2 can be derived from x: interval.floor(x) is invoked for each x to produce x1, and interval.offset(x1) is invoked for each x1 to produce x2. If the interval is specified as a number n, x1 and x2 are taken as the two consecutive multiples of n that bracket x. Named UTC intervals such as 'day' are also supported and use the same scale options.
Rule mark stroke default
The stroke of a rule mark defaults to currentColor.
Rule mark options: standard mark options and markers
The rule mark supports the standard mark options, including insets along its secondary dimension, and marker options to add a marker such as a dot or an arrowhead to the start or end of the rule.
ruleX shorthand syntax
ruleX can be called as Plot.ruleX([0]) as an annotation with a simple array of values, or as Plot.ruleX(alphabet, {x: "letter", y: "frequency"}) to visualize data.
ruleY shorthand syntax
ruleY can be called as Plot.ruleY([0]) as an annotation with a simple array of values, or as Plot.ruleY(alphabet, {y: "letter", x: "frequency"}) to visualize data.
Rule mark x encoding shorthand in ruleY
In ruleY, if x is specified, it is shorthand for x2 with x1 equal to zero. This is the typical configuration for a horizontal lollipop chart with rules aligned at x = 0.
Rule mark use case: baseline annotation
Rules are commonly used as annotations to mark a baseline, such as y = 0 in a line chart, by passing a hard-coded array of literal values as data.
Rule mark use case: dense data visualization
Rules can serve as an alternative to an area mark in a band chart when data is sufficiently dense. You can limit the extent of a rule along the secondary dimension (y1 and y2 channels for ruleX, x1 and x2 channels for ruleY) rather than having it span the frame.
Rule mark lollipop chart example with markerEnd
In a lollipop chart, a rule can serve as a stylistic alternative to a bar, using markerEnd: "dot" to place a dot marker at the end of the rule.
Rule mark with stroke color encoding
Rules support a stroke color encoding channel to visualize data as color.
Rule mark with marker option for error bars
Rules can indicate uncertainty or error by setting the marker option to 'tick', which draws a small perpendicular line at the start and end of the rule.
Text mark draws text at x and y positions
The text mark draws text at the given position in x and y. It is often used to label other marks, such as to show the value of a bar. When space is available, direct labeling can allow faster and more accurate reading of values than an axis alone or a tooltip.
Text mark performance caveat for wrapping
For performance and simplicity, Plot does not measure text exactly and instead uses an approximate heuristic. If Plot's automatic wrapping is not doing what you want, consider hard wrapping with manual newlines (\n) instead.
Text mark textOverflow title channel behavior
If the mark does not have a title channel, a title with the non-truncated text is automatically added when textOverflow is used to truncate lines.
Labeled bars example with text mark
Plot.plot({ label: null, y: { grid: true, label: "Frequency (%)", percent: true }, marks: [ Plot.barY(alphabet, {x: "letter", y: "frequency"}), Plot.text(alphabet, {x: "letter", y: "frequency", text: (d) => (d.frequency * 100).toFixed(1), dy: -6, lineAnchor: "bottom"}), Plot.ruleY([0]) ] }) This example shows using text mark to label bar chart values positioned above each bar.
Text spiral example with default data format
Plot.plot({ aspectRatio: 1, inset: 10, grid: true, marks: [ Plot.text(d3.range(151).map((i) => [ Math.sqrt(i) * Math.sin(i / 10), Math.sqrt(i) * Math.cos(i / 10) ])) ] }) This example shows text mark with data as array of [x, y] pairs and no explicit x, y, or text options, demonstrating default behavior.