Rule Documentation has not yet been reviewed by a human.
A rule series adds reference lines that give context to the data, such as
a target, a threshold, or the time of an event. Supply x for a vertical line
or y for a horizontal line. Add the rule alongside the series it annotates.
A single reference line can use a constant value without a data array.
Horizontal reference values
Use numeric y values for reference lines without a data array. A thin dashed target and a thick solid upper limit show how width and dash patterns distinguish reference values.
const data = Array.from({ length: 97 }, (_, i) => ({ x: i / 4, y: 44 + 15 * Math.sin(i / 9) + 5 * Math.cos(i * 0.8) + 38 * Math.exp(-(((i - 62) / 10) ** 2)), }))
const reference_values = plot({ series: [ plot.line({ data, color: { light: '#0891b2', dark: '#67e8f9' }, width: 2, }), plot.rule({ y: 60, color: { light: '#7c3aed', dark: '#c4b5fd' }, width: 1, dash: [7, 4], tooltip: pure(() => h("span", {}, 'Target: 60 ms')), }), plot.rule({ y: 90, color: { light: '#c2410c', dark: '#fdba74' }, width: 4, tooltip: pure(() => h("span", {}, 'Upper limit: 90 ms')), }), ], height: 260, margin: { top: 5, right: 8, bottom: 20, left: 30 }, axis: { x: { min: 0, max: 24, label: '' }, y: { min: 0, max: 110, label: '' } }, background: { light: '#ffffff', dark: '#151b28' }, chrome_color: { light: '#e2e8f0', dark: '#334155' }, grid: false, border: false, zoom_pan: false, })
// In Antithesis notebook, plot() returns a Printable. Uncomment below to display it: // print(reference_values) // presentation.blank("Reference values").print(reference_values)Vertical event markers
Read x positions from data to mark events along a signal. A solid rule marks deployment; thinner dashed rules mark recovery events. Tooltips identify each event.
const data = Array.from({ length: 97 }, (_, i) => ({ x: i / 4, y: 35 + 12 * Math.sin(i / 11) + 4 * Math.cos(i * 0.7) + (i >= 28 && i < 64 ? 30 : 0), }))
const events = [ { hour: 7, name: 'Deploy', recovery: false }, { hour: 16, name: 'Rollback', recovery: true }, { hour: 21, name: 'Verified', recovery: true }, ]
const event_markers = plot({ series: [ plot.line({ data, color: { light: '#6366f1', dark: '#a5b4fc' }, width: 2, }), plot.rule({ data: events.filter(event => !event.recovery), x: 'hour', color: { light: '#c2410c', dark: '#fdba74' }, width: 3, tooltip: pure(({ row }) => h("span", {}, row?.name + ' at hour ' + row?.hour)), }), plot.rule({ data: events.filter(event => event.recovery), x: 'hour', color: { light: '#0d9488', dark: '#5eead4' }, width: 2, dash: [5, 4], tooltip: pure(({ row }) => h("span", {}, row?.name + ' at hour ' + row?.hour)), }), ], height: 260, margin: { top: 5, right: 8, bottom: 20, left: 30 }, axis: { x: { min: 0, max: 24, label: '' }, y: { min: 0, max: 110, label: '' } }, background: { light: '#ffffff', dark: '#151b28' }, chrome_color: { light: '#e2e8f0', dark: '#334155' }, grid: false, border: false, zoom_pan: false, })
// In Antithesis notebook, plot() returns a Printable. Uncomment below to display it: // print(event_markers) // presentation.blank("Event markers").print(event_markers)Rule arguments
| Field | Type | Default | Description |
|---|---|---|---|
data? |
{[key: string]: any}[] |
None | Data for multiple reference lines. Omit it to draw a single line by setting either x or y to a constant number or category name. Exactly one of x and y is required. |
x? |
number | FieldArg |
None | Vertical rule position, or a field/accessor when data is supplied. Set exactly one of x and y. |
y? |
number | FieldArg |
None | Horizontal rule position, or a field/accessor when data is supplied. |
color? |
ColorArg |
Black | Series color. Theme pairs provide separate light and dark colors. |
width? |
number |
1 |
Rule width in pixels. |
dash? |
number[] |
Solid | Alternating dash and gap lengths in pixels. |
tooltip? |
TooltipArg |
None | Use true for the default tooltip, or a callback for custom content. |
on_select? |
SelectFn |
None | Callback receiving the selected point and its source data. |
hoverable? |
boolean |
true |
Enable tooltips, selection callbacks, and hover highlights for this series. |
highlight? |
boolean |
true |
Highlight a data point when you hover over it. |
highlight_color? |
ColorArg |
Automatic | Exact hover color, including opacity. |
This example draws dashed horizontal lines at two thresholds, colors them by value, and adds tooltips and a selection callback.
const selected_data = new reactive.StateVar('Select a point to inspect its data.')
const series = [plot.rule({ data: [{ threshold: 5 }, { threshold: 8 }], y: 'threshold', color: pure((row) => Number(row.threshold) >= 8 ? 'tomato' : 'steelblue'), width: 2, dash: [6, 4], tooltip: pure(({ x, y }) => h("span", {}, `(${x}, ${y})`)), on_select: pure(({ row }) => selected_data.set(JSON.stringify(row)), { selected_data }), hoverable: true, highlight: true, })]
const threshold_lines_plot = plot({ series, height: 260 })
const threshold_lines = h( 'div', {}, threshold_lines_plot, h( pure(({ selected_data }) => h('output', { 'aria-live': 'polite', style: { display: 'block' } }, selected_data.get()), ), { selected_data }, ), )
// In Antithesis notebook, plot() returns a Printable. Uncomment below to display it: // print(threshold_lines) // presentation.blank("Threshold lines").print(threshold_lines)For a single vertical reference line, supply a numeric x without data:
const series = [plot.rule({ x: 3, color: 'tomato', width: 2, hoverable: false, highlight: false, })]
const vertical_reference = plot({ series, height: 260 })
// In Antithesis notebook, plot() returns a Printable. Uncomment below to display it: // print(vertical_reference) // presentation.blank("Vertical reference").print(vertical_reference)Shared configuration
See Install and configure to set up Plot. The argument tables describe omitted fields; examples may override these defaults. See Data fields, Series colors, Strokes, and Mark shapes for shared options. For callbacks, see Tooltips and Selection.