OptionaltitleOptionalnameWhat this layer is, when a subplot's layers are the same kind of thing.
Announced on a layer switch in place of the trace type. Without it, two layers of one type are indistinguishable — a hue-split error bar chart announces "Layer 1 of 2: error_bar plot" and then "Layer 2 of 2: error_bar plot", so a reader hears two different sets of numbers and is never told that the first is Male and the second Female, which is the whole content of the split and what a legend gives a sighted reader for free.
Distinct from title, which names the chart rather than the layer:
producers put the figure's title there for every layer of a figure, so it
cannot say which layer this is.
OptionalselectorsWhich element of the chart each point of the layer is drawn as.
A plain string leaves the pairing to document order; an array names one element per point; a grid names one per cell of a segmented layer.
A grid cell may be null, which says the chart drew no element for
that cell — a category a series has no bar at, or a position a heat grid
is not a rectangle at. That is different from a selector that fails to
resolve, which is a mistake and declines the whole grid: without a way to
tell the two apart, a producer whose layer has a gap has to choose between
losing the highlight everywhere and inferring the gaps from the values,
and a value of zero is not evidence that a bar was never drawn (#1002).
It is also not the same as a null in HeatmapData.points, which
says the chart drew no value. A calendar has both, at different cells:
a day inside the year with no row is drawn as a white square, so it has
an element and no value, while the slots outside the year have neither
(#1174).
OptionalorientationWhich way the layer is drawn. Defaults to Orientation.VERTICAL.
For one family of traces this key decides which field of a point holds the magnitude, so getting it wrong is not a cosmetic error — the trace reads a category name where it expects a number and sounds with no magnitude at all. For every other trace it changes only which axis label a reading is announced against, and the payload is written the same way whichever value is set.
What the two words name. Orientation is the direction the magnitude
runs, not which axis happens to be called x. That is the convention the
whole field uses: a horizontal bar chart is one whose bars run left to
right, with the categories down the y axis — and it is how the drawing
libraries name the same switch. Chart.js: indexAxis: 'y' gives
"horizontal bars", the y axis holding the categories and the x axis the
values. Highcharts: chart.inverted makes "the x axis vertical and y axis
horizontal". Matplotlib 3.10 replaced boxplot(vert=False) with
orientation='horizontal', which "plots the boxes horizontally". Plotly
states it outright: with 'h', "the value of each bar spans along the
horizontal".
A producer therefore reads its chart, not its API's vocabulary. Where a
library names the other direction — ECharts' and amCharts' funnel
orient/orientation name the way the stages progress, so their default
funnels encode the value as a band's width and are horz here — the
adapter translates, and says so where it does.
The rule is: the bar family swaps x and y; nothing else does.
| trace | vert |
horz |
|---|---|---|
| the bar family, listed below | x is the category, y the magnitude |
x is the magnitude, y the category |
error_bar, forest |
x is the category, y/yMin/yMax the magnitudes |
unchanged — only the axis labels swap |
box, boxen, violin_box |
quantile fields, no axis assignment | unchanged |
gantt, dumbbell |
— | unchanged; navigation and panning only |
The bar family is defined by what a type is built on rather than by what
it is called, because the exchange is inherited from AbstractBarPlot's
constructor: bar, histogram, stacked, dodged, normalized and
the traces built on those (diverging, mosaic) — and also dot and
lollipop, which the factory constructs as a BarTrace outright, and
funnel, whose trace extends BarTrace and never undoes the exchange.
Reading one model file at a time misses those last three, so
test/type/orientationContract.test.ts runs the list rather than
restating it.
Note that this is a different question from the one
resolveOrientation() in src/util/orientation.ts answers. Its
IS_ORIENTED record says whether a type has an orientation worth
announcing ("vertical bar plot"); a type can be oriented in that sense
and still not want its payload swapped, which is the trap this table
exists to close. Both r-maidr #184 and #186 were emitted against the
wrong half of it.
OptionaldomOptional DOM mapping hints. When provided, individual traces can opt-in to use these hints to map DOM elements to the internal row-major data grid without changing default behavior when omitted.
Optionalorder?: "row" | "column"Specify DOM flattening order for grid-like traces. 'row' => row-major, 'column' => column-major.
OptionalgroupDirection?: "reverse" | "forward"For segmented/dodged bars, control the per-column group/level iteration. 'forward' => iterate groups top-to-bottom (as previously domOrder='forward'). 'reverse' => iterate bottom-to-top (default).
OptionaliqrDirection?: "reverse" | "forward"For boxplots, control the Q1/Q3 edge mapping for IQR box. 'forward' => Q1=bottom, Q3=top (default for vertical) 'reverse' => Q1=top, Q3=bottom (for Base R vertical boxplots)
OptionalpointOrder?: "reverse" | "data"For a line-family layer, whether the chart draws the series' points in
the opposite order from the one data lists them in.
'data' (the default) => the r-th mark drawn is data[r].
'reverse' => the marks run the other way, so the last one drawn is
data[0].
A reversed category axis draws a series from its far end while the library goes on reporting its points in the order they were written, so a chart read in the written order is announced as its own mirror image: every value right, the shape backwards, and with it the stereo pan, the braille line and the direction autoplay sweeps (#1007).
A bar layer fixes that adapter-side, by reversing the rows and naming
each bar outright so the highlight follows (#995). A line cannot: it has
no per-point selector to permute -- LineTrace reads its points out of
one <path>'s geometry, in path order, which is the library's data
order whichever way the axis runs. Reversing the payload alone would
pair data[0] with the vertex at the other end of the chart, trading a
correct highlight for a wrong one (#988, #990). This is how an adapter
says it has reversed the payload, so the trace can pair the two halves
back up.
Read by LineTrace (and the traces built on it) and ignored by every
other type. Omit it unless the drawn direction is known: a layer that
declares 'reverse' and is not drawn that way outlines the wrong end
of the series, which is worse than the direction being wrong on its own.
OptionalaxesAxis configuration. Every axis (x, y, z) is specified as an AxisConfig
object with an optional label, optional grid navigation properties
(min, max, tickStep), and optional per-axis format.
OptionalforestDisplay configuration for a forest plot layer.
OptionalthresholdThreshold configuration for a volcano or Manhattan plot layer.
OptionalviolinOptional display configuration for violin plot layers (VIOLIN_KDE and VIOLIN_BOX). Controls which summary statistics are shown in the violin box overlay.
OptionalstepWhere a TraceType.STEP layer jumps between samples, and how a
stepped TraceType.AREA band moves between them. Read by
StepTrace and by AreaTrace -- line.shape and a fill are independent,
so a band can be a staircase -- and ignored by every other trace type.
Omit it when the producing library does not report one, rather than
guessing: the announcement names the convention, and naming the wrong one
is worse than staying silent.
Layer/trace definition containing plot type, data, and rendering configuration.