marks

512 notes in this subject, read out of this brain and free to use. This is page 8 of 9.

Text mark with line wrapping and textOverflow example

Plot.plot({ height: 320, x: {type: "point", align: 0, axis: "top", tickSize: 0}, marks: [ Plot.text( ["Call me Ishmael..."], { x: (d, i) => 1 + i, lineWidth: 20, frameAnchor: "top", textAnchor: "start" } ) ] }) This example demonstrates text mark with automatic line wrapping using lineWidth: 20 ems.

Text mark multiline support with newline characters

The text mark will generate multiple lines if the text contains newline characters (\n). This may be useful for longer annotations. If lineWidth is specified, input text values will be wrapped as needed while preserving existing newlines.

Text mark optional channels: x, y, fontSize, rotate

The optional channels for text mark are: x (horizontal position, bound to x scale), y (vertical position, bound to y scale), fontSize (font size in pixels), and rotate (rotation angle in degrees clockwise). If either x or y is not specified, the corresponding position is controlled by the frameAnchor option.

Text channel required for text mark

The text channel is required and contains the text contents as a string, possibly with multiple lines. If text contains newline characters (\n, \r\n, or \r), it will be rendered as multiple lines. If text is not specified, it defaults to identity for primitive data (such as numbers, dates, and strings), and to the zero-based index [0, 1, 2, …] for objects.

Text mark constant options: textAnchor, lineAnchor, lineHeight, lineWidth, textOverflow

Text-specific constant options include: textAnchor (start, end, or middle for horizontal position), lineAnchor (top, bottom, or middle for vertical position), lineHeight (in ems, defaults to 1), lineWidth (in ems for wrapping, defaults to Infinity), and textOverflow (how to wrap or clip lines longer than specified line width).

Text mark font options: fontFamily, fontSize, fontStyle, fontVariant, fontWeight, monospace

Font-related constant options for text mark: fontFamily (font name, defaults to system-ui), fontSize (font size in pixels, defaults to 10), fontStyle (normal by default), fontVariant (normal by default, defaults to tabular-nums when text is numbers or dates), fontWeight (normal by default), and monospace (if true, changes default fontFamily and metrics to monospace).

Text mark frameAnchor and rotate options

frameAnchor controls how to position the text within the frame and defaults to middle. rotate is the rotation angle in degrees clockwise and defaults to 0. Both fontSize and rotate can be specified as either channels or constants; when specified as a number, they are interpreted as a constant.

Text mark textAnchor and lineAnchor defaults with frameAnchor

If frameAnchor is not specified, textAnchor and lineAnchor default to middle. Otherwise, textAnchor defaults to start if frameAnchor is on the left, end if on the right, and middle otherwise. lineAnchor defaults to top if frameAnchor is on the top, bottom if on the bottom, and middle otherwise.

Text mark paintOrder and strokeWidth defaults

The paintOrder option defaults to stroke and the strokeWidth option defaults to 3. By setting fill to the foreground color and stroke to the background color (such as black and white), you can surround text with a halo which may improve legibility against a busy background.

Text mark textOverflow values

textOverflow values are: null (default, preserve overflowing characters), clip or clip-end (remove characters from the end), clip-start (remove characters from the start), ellipsis or ellipsis-end (replace characters from the end with ellipsis …), ellipsis-start (replace characters from the start with ellipsis …), or ellipsis-middle (replace characters from the middle with ellipsis …).

Text mark lineWidth for wrapping and monospace interpretation

If lineWidth is specified, input text values will be wrapped as needed to fit while preserving existing newlines. The implementation replaces the space before the word that overflows with a line feed. Lines may be split on soft-hyphens (\xad), replacing it with a hyphen. If monospace is truthy, lineWidth is interpreted as characters (ch) rather than ems.

Text formatting for numbers and dates

If text is specified as numbers or dates, a default formatter will automatically be applied, and fontVariant will default to tabular-nums instead of normal.

Plot.text() function signature and default data format

Plot.text(data, options) returns a new text mark with the given data and options. If neither x nor y nor frameAnchor 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₂, …].

Plot.textY() function defaults to identity for y

Plot.textY(data, options) is equivalent to text(), except y defaults to identity and assumes that data = [y₀, y₁, y₂, …]. If an interval is specified, x is transformed to (interval.floor(x) + interval.offset(interval.floor(x))) / 2. If interval is a number n, x will be the midpoint of two consecutive multiples of n that bracket x. Named UTC intervals such as day are also supported.

Text mark one-dimensional usage

The x and y channels are optional; a one-dimensional text mark can be produced by specifying only one position dimension. If both x and y are not defined, the text mark assumes that the data is an iterable of points [[x₁, y₁], [x₂, y₂], …], allowing for shorthand.

One-dimensional tick equivalence to rule

When there is no secondary position dimension, a tick behaves identically to a rule. While a one-dimensional rule and tick are equivalent, a one-dimensional rule is generally preferred because the name rule is more descriptive.

Tick mark options support

The tick mark supports the standard mark options, including insets, and marker options to add a marker (such as a dot or an arrowhead) to the start or end of the tick.

tickY channel requirements and options

tickY(data, options) returns a new horizontal tick. The y channel is required and is bound to the y scale. The x channel is optional and is bound to the x scale, which must be band. If the x channel is not specified, the tick will span the full horizontal extent of the frame.

Tick mark purpose and orientation

The tick mark is one of two marks in Plot for drawing horizontal or vertical lines. tickY draws a horizontal line with a given y value. tickX draws a vertical line with a given x value. Ticks should be used when the secondary position dimension is ordinal. When the secondary dimension is quantitative, use a rule mark instead.

Tick secondary dimension requirement

Ticks have an optional secondary position dimension (x for tickY and y for tickX). This second dimension is ordinal, unlike a rule, and requires a corresponding band scale.

Tick common use cases

Ticks are often used to show one-dimensional distributions, such as in barcode plots. Ticks and bars both have an ordinal secondary position dimension; a tick is convenient for stroking the upper bound of a bar for emphasis. Ticks are also used by the box mark to denote the median value for each group.

Tick default styling

The stroke of a tick defaults to currentColor.

Tick opacity for density visualization

Reducing opacity allows better perception of density when ticks overlap.

Tip mark title channel for text

The tip text is supplied via the title channel. If the tip mark's data is an array of strings, the title channel defaults to identity. When using the title channel, the tip mark wraps text to 20 ems by default, and preserves newlines in the provided text.

Tip mark displays text in floating box

The tip mark displays text, or several name-value pairs, in a floating box anchored to a given position in x and y. It is often paired with the pointer transform to reveal details on demand when hovering over a chart.

Tip mark pool option defaults to true

The tip mark defaults the pool option to true, such that if there are multiple tip marks and pointer transforms, at most one tip will be visible at a time. Setting the pool option to false allows multiple tips to be visible simultaneously.

Tip mark as mark option on other marks

The tip mark can be used as a mark option on other marks like lineY or dot. When tip: true is specified, it automatically pairs with a pointer transform using the appropriate defaults.

Tip mark text options

The tip mark supports text options to control text formatting: lineWidth (in ems, for wrapping; defaults to 20), lineHeight (in ems; defaults to 1), textOverflow, fontFamily (defaults to system-ui), fontSize (defaults to 10 pixels), fontStyle (defaults to normal), fontVariant (defaults to normal), fontWeight (defaults to normal), monospace (if true, changes default fontFamily and metrics to monospace), and textAnchor (start, end, or middle).

Tip mark channels option for additional name-value pairs

You can supply additional name-value pairs by registering extra channels using the channels mark option. This allows the tip to display data beyond the x and y channels.

Tip mark recognizes paired channels x1/x2 and y1/y2

The tip mark recognizes that x1 and x2 are paired channels, and y1 and y2 are paired channels. When both values in a pair are present, the tip displays them as a range. When y1 and y2 represent a length (indicated by a channel hint from transforms like stack), the tip shows the difference between them rather than both values.

Tip mark displays color or opacity swatches

If a channel is bound to the color or opacity scale, the tip mark displays a swatch to reinforce the encoding.

Tip mark format option

The format option accepts a key-value object mapping channel names to formats. Each format can be: a string (for number or time formats), a function that receives the value as input and returns a string, true to use the default format, or null or false to suppress. The order of channels in the tip follows their order in the format object followed by any additional channels. When using the title channel, the format option may be specified as a string or a function; the given format will then apply to the title channel.

Tip mark channel label specification

A channel's label can be specified alongside its value as a {value, label} object. If a channel label is not specified, the associated scale's label is used; if there is no associated scale or the scale has no label, the channel name is used instead.

Tip mark anchor option values

The tip mark supports nine different orientations specified by the anchor option: four sides (top, right, bottom, left), four corners (top-left, top-right, bottom-right, bottom-left), and middle. When middle is used, the tip will obscure its anchor point.

Tip mark automatic anchor selection

If you don't specify an explicit anchor, the tip mark will choose one automatically, using the preferredAnchor if it fits. The preferred anchor defaults to bottom, except when using the tip option and the pointerY pointing mode, in which case it defaults to left.

Tip mark position options and precedence

The tip mark supports position options x, x1, x2 (horizontal channels) and y, y1, y2 (vertical channels), plus frameAnchor as fallback position if x or y are unspecified. To resolve the anchor position, the tip applies this precedence: 1) the midpoint of x1 and x2 if both are present; 2) otherwise x if present; 3) otherwise x1 if present; 4) lastly the position given by frameAnchor. The same precedence applies to y, y1, and y2.

Tip mark appearance options

These tip-specific options control the tip appearance: anchor (nine values: top, right, bottom, left, top-left, top-right, bottom-right, bottom-left, middle), pointerSize (the size of the tip's pointer in pixels; defaults to 12), pathFilter (the image filter for the tip's box; defaults to a drop shadow), and textPadding (the padding around the text in pixels; defaults to 8).

Tip mark styling options

The tip mark does not support standard style channels such as varying fill or stroke; channels are used exclusively to control displayed values rather than the tip's appearance. You can use constant fill, fillOpacity, stroke, strokeOpacity, or strokeWidth on the path element surrounding the tip text.

Tip mark with transforms

The tip mark is compatible with transforms that derive x and y dynamically from data, such as the centroid transform which computes polygon centroids.

Plot.tip constructor

Plot.tip(data, options) returns a new tip mark with the given data and options.

Tip mark for static annotations

The tip mark can be used for static annotations to draw attention to elements of interest or to add context. This is done by specifying explicit x, y coordinates and the title channel with annotation text.

textLayout option values

The textLayout option controls how text labels are anchored to nodes. Two values are supported: 'mirrored' (leaf-node labels are left-anchored, and non-leaf nodes right-anchored) and 'normal' (all labels are left-anchored). If treeLayout is d3.tree or d3.cluster, textLayout defaults to 'mirrored'; otherwise it defaults to 'normal'.

Plot.tree() function signature

Plot.tree(data, options) returns a new tree mark with the given data and options.

Plot.cluster() function

Plot.cluster(data, options) is like Plot.tree(), except it sets the treeLayout option to d3.cluster (aligning leaf nodes) and defaults the textLayout option to 'mirrored'.

Tree mark layout requirements

The tree mark currently does not inform the default layout. It may be necessary to set the height and margin layout options for readability.

Tree mark example with slash-separated paths

Plot.tree(gods, {textStroke: "var(--vp-c-bg)"}) renders a tree where gods is an array of slash-separated paths like ['Chaos/Gaia/Mountains', 'Chaos/Gaia/Pontus', 'Chaos/Gaia/Uranus', 'Chaos/Eros', 'Chaos/Erebus', 'Chaos/Tartarus'].

Tree mark example with CSV data

Plot.plot({axis: null, margin: 10, marginLeft: 30, marginRight: 160, width: 688, height: 1800, marks: [Plot.tree(flare, {path: "name", delimiter: ".", textStroke: "var(--vp-c-bg)"})]}}) renders a tree from flare.csv data using the 'name' field as the path with '.' as the delimiter.

Custom tree layout example

A custom treeLayout function that produces an indented tree: function indent() { return (root) => { root.eachBefore((node, i) => { node.y = node.depth; node.x = i; }); }; }. This assigns each node's y coordinate to its depth and x coordinate to its order.

Cluster layout example

Plot.cluster(flare, {path: "name", treeSort: "node:height", delimiter: ".", textStroke: "var(--vp-c-bg)"}) renders a cluster layout that aligns leaf nodes, using node:height as the sort order.

Tree mark options reference

Tree mark options: fill (dot and text fill color; defaults to 'node:internal'), stroke (link stroke color; inherits fill by default), strokeWidth (link stroke width), strokeOpacity (link stroke opacity), strokeLinejoin (link stroke linejoin), strokeLinecap (link stroke linecap), strokeMiterlimit (link stroke miter limit), strokeDasharray (link stroke dash array), strokeDashoffset (link stroke dash offset), marker (link start and end marker), markerStart (link start marker), markerEnd (link end marker), dot (if true, whether to render a dot; defaults to false if no link marker), title (text and dot title; defaults to 'node:path'), text (text label; defaults to 'node:name'), textStroke (text stroke; defaults to 'white'), textLayout (text anchoring layout), dx (text horizontal offset; defaults to 6), dy (text vertical offset; defaults to 0). Any additional options are passed through to the constituent link, dot, and text marks and their corresponding treeLink or treeNode transform.

treeLayout option

The treeLayout option specifies the layout algorithm for the tree mark. The default is d3.tree (Reingold–Tilford 'tidy' tree algorithm). The treeLayout function should assign node.x and node.y coordinates.

Tree mark input format

The tree mark accepts data as an array of slash-separated paths, similar to paths in a file system. Each path represents the hierarchical position of a node in the tree. The path can be separated by a custom delimiter using the delimiter option.

Tree mark overview

The tree mark produces tree diagrams using the tree transform. It is a composite mark consisting of a link to render links from parent to child, an optional dot for nodes, and one or two text marks for node labels. The link mark uses the treeLink transform, while the dot and text marks use the treeNode transform.

Wind vector field example with atan2 and hypot

Plot.plot({inset: 10, aspectRatio: 1, color: {label: "Speed (m/s)", zero: true, legend: true}, marks: [Plot.vector(wind, {x: "longitude", y: "latitude", rotate: ({u, v}) => Math.atan2(u, v) * 180 / Math.PI, length: ({u, v}) => Math.hypot(u, v), stroke: ({u, v}) => Math.hypot(u, v)})]}) shows how to encode wind speed and direction using vector components u and v.

Vector mark draws arrows positioned by x,y with optional magnitude and direction

The vector mark draws little arrows, typically positioned in x and y quantitative dimensions, with an optional magnitude (length) and direction (rotate), as in a vector field.

Vector mark x channel

The x channel controls the horizontal position of a vector and is bound to the x scale.

Vector mark y channel

The y channel controls the vertical position of a vector and is bound to the y scale.

Vector mark length channel

The length channel controls the length in pixels of a vector mark and is bound to the length scale. It defaults to 12 pixels. Vectors with negative length will be drawn inverted.

Vector mark rotate channel

The rotate channel controls the rotation angle in degrees clockwise. It defaults to 0 degrees, which points up↑. Positive angles proceed clockwise from noon.

Vector mark shape option

The shape option controls the visual appearance (path geometry) of the vector and supports the following values: arrow (default) - an arrow with head size proportional to its length; spike - an isosceles triangle with open base; any object with a draw method receiving context, length, and radius.

Give your agent this brain