Area mark with fill channel creates implicit stack transform
If a fill channel is specified in an area mark, it is assumed to be ordinal or nominal; data is grouped into series and then implicitly stacked.
Observable Plot · all subjects
marks
512 notes in this subject, read out of this brain and free to use. This is page 2 of 9.
areaY three constructors overview
The area mark has three constructors: areaY for when baseline and topline share x values (time-series area chart where time goes right→ or ←left); areaX for when baseline and topline share y values (time-series area chart where time goes up↑ or down↓); and area for the rarely-used case where baseline and topline share neither x nor y values.
Area mark data ordering requirement
Points in areas are connected in input order: the first point is connected to the second, the second to the third, and so on. Area data is typically in chronological order. Unsorted data may produce gibberish. If data is not sorted, use the sort transform.
Area mark z=null disables implicit stack
To vary fill within a single series, set the z option to null. For areaY, z defaults to null if fill and y channels are strictly equal. For areaX, z defaults to null if fill and x are strictly equal.
areaY line option
If the line option is true in areaY, the stroke applies exclusively to the topline, and fillOpacity defaults to 0.3.
Area mark with single point segments
If an area segment consists of only a single point, it may appear invisible unless rendered with rounded or square line caps. Some curves such as cardinal-open only render a visible segment if it contains multiple points.
Area mark handling of invalid values
If any of x1, y1, x2, or y2 values are invalid (undefined, null, or NaN), the baseline and topline will be interrupted, resulting in a break that divides the area shape into multiple segments.
Area mark drawing order
Points along baseline and topline are connected in input order. If there are multiple series via z, fill, or stroke channel, series are drawn in input order such that the last series is drawn on top.
Area mark strokeLinecap, strokeLinejoin, and strokeMiterlimit defaults
The strokeLinecap defaults to round, strokeLinejoin defaults to round, and strokeMiterlimit defaults to 1.
Area mark channel behavior with varying values
The fillOpacity, stroke, strokeOpacity, strokeWidth, opacity, href, title, and ariaLabel channels behave like fill: when any of these channels are used with varying values, the area will be broken into contiguous segments. When any of these channels are used, setting an explicit z channel (possibly to null) is strongly recommended.
Area mark fill channel and segmentation
If fill is defined as a channel, the area will be broken into contiguous overlapping segments when the fill color changes. The fill color applies to the interval spanning the current data point and the following data point.
Area mark z channel and grouping defaults
By default, data is assumed to represent a single series. If z channel is specified, data is grouped by z to form separate series. If z is not specified, it defaults to fill if a channel, or stroke if a channel. The z channel determines how data is grouped.
Area mark optional channels
Optional channels for area marks are: x2 (horizontal position of topline, bound to x scale), y2 (vertical position of topline, bound to y scale), and z (categorical value to group data into series).
Area mark curve support
The area mark supports curve options to control interpolation between points. The default curve is linear, which draws straight line segments between adjacent points.
Area mark required channels
The area mark requires x1 (horizontal position of baseline, bound to x scale) and y1 (vertical position of baseline, bound to y scale). If x2 is not specified, it defaults to x1. If y2 is not specified, it defaults to y1.
area constructor for independent baseline and topline
Plot.area(data, options) returns a new area mark. This method is rarely used directly; it is only needed when the baseline and topline have neither common x nor y values. areaY is used in the common horizontal orientation where baseline and topline share x values, while areaX is used in the vertical orientation where baseline and topline share y values.
areaX constructor and shorthand
Plot.areaX(data, options) returns a new area mark. When neither x1 nor x2 option is specified, the x option may be specified as shorthand to apply an implicit stackX transform. This is the typical configuration for an area chart with a baseline at x = 0. If x is not specified, it defaults to the identity function. The y option specifies the y1 channel; y1 and y2 options are ignored.
areaX line option
If the line option is true in areaX, the stroke applies exclusively to the topline, and fillOpacity defaults to 0.3.
Arrow mark headLength option
The headLength option determines the scale of the arrowhead relative to the stroke width. It defaults to 8. Assuming the default stroke width of 1.5px, the headLength is the length of the arrowhead's side in pixels.
Arrow mark sweep option
The sweep option controls the bend orientation. It defaults to 1 indicating a positive (clockwise) bend angle. -1 indicates a negative (anticlockwise) bend angle. 0 effectively clears the bend angle. If -x, the bend angle is flipped when the ending point is to the left of the starting point, ensuring all arrows bulge up (or down if bend is negative). If -y, the bend angle is flipped when the ending point is above the starting point, ensuring all arrows bulge right (or left if bend is negative). The sign is negated for +x and +y.
Arrow mark inset options
The arrow mark supports insetStart (inset at the start of the arrow) and insetEnd (inset at the end of the arrow, useful if the arrow points to a dot). The inset option serves as shorthand for both insets.
Arrow mark similarity to link and vector marks
The arrow mark is similar to the link mark except it draws an arrowhead and is suitable for directed edges. The vector mark draws arrows of a given length and direction instead of between two points.
Arrow mark for directed graph edges
The arrow mark is useful for drawing directed graph edges, such as representing transition frequencies in a finite state machine or directed relationships between nodes.
Plot.arrow() signature
Plot.arrow(data, options) returns a new arrow with the given data and options. The data parameter provides the data source, and options specifies channels and settings like x1, y1, x2, y2, and additional arrow-specific options.
Arrow mark headAngle option
The headAngle option determines how pointy the arrowhead is, specified in degrees. It defaults to 60° and is typically between 0° and 180°.
Arrow mark bend option
The bend option sets the angle between the straight line connecting the two points and the outgoing direction of the arrow from the start point, specified in degrees. It defaults to 0°. The value true is shorthand for 22.5°. It must be within ±90°. A positive angle produces a clockwise curve; a negative angle produces a counterclockwise curve; zero produces a straight line.
Arrow mark default style options
The arrow mark has the following defaults: stroke defaults to currentColor, fill defaults to none, strokeWidth defaults to 1.5, and strokeMiterlimit defaults to 1.
Arrow mark shorthand options for vertical or horizontal arrows
For vertical or horizontal arrows, the x option can be specified as shorthand for x1 and x2, and the y option can be specified as shorthand for y1 and y2.
Arrow mark required channels
The arrow 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).
Plot.autoSpec() function
Plot.autoSpec(data, options) returns an auto mark options object with no option undefined; the mark type, reducers, and other options are all populated. Available since version 0.6.4. Example: Plot.autoSpec(olympians, {x: 'weight', y: 'height', color: 'count'}).
Auto mark option: mark
The mark option allows you to specify the desired mark type manually. Supported values are: area (areaY or areaX or sometimes area), bar (barY or barX; or rectY, rectX, or rect; or cell), dot (dot), line (lineY or lineX or sometimes line), rule (ruleY or ruleX). The chosen mark type depends on the provided options and the inferred data type.
Auto mark color field reference
To reference a field name as a variable color encoding instead of interpreting a string as a CSS color, specify the color option as an object with a value property. For example: color: {value: 'red'}.
Auto mark color as constant CSS color
If the color channel is specified as a string that is also a valid CSS color, it is interpreted as a constant color. For example, color: 'red' results in red bars. This is shorthand for color: {color: 'red'}.
Auto mark reducer behavior with x or y
Setting a reducer on x implicitly groups or bins on y, and likewise setting a reducer on y implicitly groups or bins on x. Setting a reducer on color or size groups or bins in both x and y. Setting a reducer on both x and y throws an error.
Auto mark supported facet channels
The auto mark supports fx (horizontal facet position/column) and fy (vertical facet position/row) for faceting.
Auto mark supported visual encoding channels
The auto mark supports color and size as visual encoding channels in addition to position channels.
Auto mark supported position channels
The auto mark requires at least one position channel: x (horizontal position) or y (vertical position).
Auto mark zero option
You can pass a zero option to indicate that zero is meaningful for either x or y. This adds a corresponding rule to the returned mark.
Auto mark size channel
The auto mark has a size channel, which currently always results in a dot and is an alias for the dot's r channel. In the future it will also represent a vector's length channel.
Auto mark color channel assignment
The auto mark has a single color channel which it assigns to either fill or stroke depending on the mark type. This enables seamless switching between different mark types when changing encodings.
Auto mark reducer syntax with value and reduce
To pass both a value and a reducer, or to disambiguate whether a string represents a field name or a reducer name, the x, y, color, and size options can be specified as an object with separate value and reduce properties. For example: {value: 'body_mass_g', reduce: 'sum'}.
Plot.auto() function
Plot.auto(data, options) returns an automatically-chosen mark with the given data and options, suitable for a quick view of the data. Example: Plot.auto(olympians, {x: 'weight', y: 'height', color: 'count'}).
Auto mark reduce option
The auto mark has special syntax that lets you specify a reducer without explicitly specifying a transform. Pass the reducer name as a string to the channel property, or pass a shorthand string like 'count'. You can also pass an object with separate value and reduce properties to specify both the input dimension and the reducer type.
Auto mark heuristics: single ordinal dimension
When given only one ordinal dimension, the auto mark creates a histogram using group and bar.
Auto mark heuristics: single quantitative dimension
When given only one quantitative dimension, the auto mark creates a histogram using bin and rect.
Auto mark heuristics: monotonic increasing dimension with numeric
When given a monotonically increasing dimension (such as Date ordered chronologically) paired with a numeric column, the auto mark creates a line chart.
Auto mark heuristics: two quantitative dimensions
When given two quantitative dimensions, the auto mark creates a scatterplot.
Auto mark overview and purpose
The auto mark automatically selects a mark type that best represents given data dimensions according to simple heuristics. It is intended to support fast exploratory analysis where the goal is to get a useful plot quickly. The auto mark powers Observable's chart cell.
Auto mark stability warning
While the auto mark will respect provided options, you should not rely on its behavior being stable over time. The auto mark may get smarter and take advantage of new features. The heuristics are not explicitly documented; see the source code for details.
Auto mark reduce null option
Setting reduce to null opts out of the reducer and creates a one-dimensional plot without grouping or binning the data.
Auto mark with other marks caution
You can combine the auto mark with other marks, but the combination may be brittle because the auto mark may pick encodings that don't play well with others.
barY required and optional channels
barY requires either y1 and y2 channels, or y as shorthand for implicit stackY transform. Optional channels: x (horizontal position, bound to x scale which must be band). If x is not specified, the bar spans the full horizontal extent of the plot or facet.
barY default options
If options is undefined for barY, it defaults to y2 as identity and x as the zero-based index [0, 1, 2, …]. This allows an array of numbers to be passed directly to barY to make a quick sequential bar chart.
barX interval option behavior
If an interval is specified for barX (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.
barY interval option behavior
If an interval is specified for barY (such as d3.utcDay), y1 and y2 can be derived from y: interval.floor(y) is invoked for each y to produce y1, and interval.offset(y1) is invoked for each y1 to produce y2. If the interval is specified as a number n, y1 and y2 are taken as the two consecutive multiples of n that bracket y. Named UTC intervals such as day are also supported.
Bar mark overview: barY and barX
The bar mark comes in two orientations: barY extends vertically and is used for vertical bar charts or column charts, while barX extends horizontally. The bar mark is a variant of the rect mark for use when one dimension is ordinal and the other is quantitative.
barX and barY implicit stack transforms
If only a single quantitative value is specified (e.g., only x for barX or only y for barY instead of x1 and x2 or y1 and y2), the bar applies an implicit stack transform. For barY this is stackY, and for barX this is stackX. This makes the bar span from zero to the given value.
Bar mark option: interval
The interval option enforces uniformity in ordinal bar charts and can 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.
Bar mark sort option
The mark sort option can be used to derive the scale domain from a channel. For example, sort: {x: "-y"} sorts x by descending y values.
barX example with two quantitative values
Plot.barX(civilizations, {x1: "start", x2: "end", y: "civilization", sort: {y: "x1"}})