Plot DSL
Plots in TukeySheets are described by a TOML document. A document has one [plot] section (title, axes, coords) and one or more [[layer]] blocks, each with a mark + the cell ranges it pulls from.
points
Draws individual data points as geometric shapes at (x, y) coordinates.
Use for scatter plots, comparing two continuous variables, or showing the distribution of data. Supports shape, size, color, and alpha aesthetics.
Parameters
Example
[plot]
x = "A1:A10"
y = "B1:B10"
[[layer]]
mark = "points"
[layer.params]
size = 5
beeswarm
Plots individual data points along an axis, spreading them to avoid overlap so every point is visible.
Use when you want to show all data points in a distribution without overlap. Works well for small-to-medium datasets where individual observations matter. Supports color, size, and grouping.
Parameters
Example
[plot]
x = "A1:A36"
y = "B1:B36"
[[layer]]
mark = "beeswarm"
[layer.params]
size = 4
spacing = 1.5
line
Connects data points in x order with straight line segments, or a smooth Catmull-Rom spline when smooth = true.
Use for time series, trends, or any ordered data. Set smooth = true to draw a curved spline through the points instead of straight segments. Map the color aesthetic to a column to draw multiple lines.
Parameters
Example
[plot]
x = "A1:A10"
y = "B1:B10"
[[layer]]
mark = "line"
[layer.params]
linewidth = 2
smooth = true
area
Fills the region between the data line and a baseline (default 0).
Use for cumulative totals, showing magnitude over time, or stacked area charts. The alpha aesthetic controls transparency. Combine with ribbon for confidence bands.
Parameters
Example
[plot]
x = "A1:A10"
y = "B1:B10"
[[layer]]
mark = "area"
[layer.params]
alpha = 0.6
bump
A bump chart shows how rankings change over time, using smooth curves between rank positions.
Use to visualize rank changes across categories or time periods. Each series is a smooth S-curve between rank positions. Map x to time, y to rank, color to the entity being ranked.
Parameters
Example
[plot]
legend = "none"
[[layer]]
mark = "bump"
[layer.aes]
x = "A1:A42"
y = "B1:B42"
stroke = "C1:C42"
[layer.params]
line_width = 2
point_size = 4
show_labels = "right"
ribbon
Fills the area between ymin and ymax across x values.
Use for confidence intervals, prediction bands, or any range display. Map ymin and ymax aesthetics to the lower and upper bounds. Combine with a line mark for the center.
Parameters
Example
[plot]
x = "A1:A10"
[[layer]]
mark = "ribbon"
[layer.aes]
ymin = "B1:B10"
ymax = "C1:C10"
[layer.params]
alpha = 0.3
smooth
Fits and draws a smoothed curve through the data with an optional confidence ribbon.
Use to show underlying trends without point-to-point noise. The method param controls the fitting approach. Combine with points for best results.
Parameters
Example
[plot]
x = "A1:A15"
y = "B1:B15"
[[layer]]
mark = "points"
[[layer]]
mark = "smooth"
[layer.params]
method = "lm"
se = true
color = "#e31a1c"
stream
A streamgraph — stacked area chart centered on a flowing baseline for a flowing, organic look.
Use to show how multiple categories contribute to a total over time. Requires x, y, and a group/fill aesthetic. The baseline param controls the stacking style.
Parameters
Example
[plot]
x = "A1:A50"
[[layer]]
mark = "stream"
[layer.aes]
y = "B1:B50"
fill = "C1:C50"
bars
Draws vertical bars from a baseline to the y value for each x position.
Use for comparing discrete categories or aggregate values. Supports fill, color, alpha, and width params. Use stat = "count" to auto-count categories.
Parameters
Example
[plot]
x = "A1:A7"
y = "B1:B7"
[[layer]]
mark = "bars"
[layer.params]
alpha = 0.9
stacked_bars
Stacks bars at each x position, grouped and colored by a categorical column.
Use to show part-to-whole relationships across categories. Map x to the category, y to the value, and color to the grouping column. Groups are stacked in first-appearance order.
Parameters
Example
[plot]
x = "A1:A12"
y = "B1:B12"
[[layer]]
mark = "stacked_bars"
color = "C1:C12"
dumbbell
Draws a horizontal line between two values per row, with dots at each end — showing the gap between two measures.
Use to compare before/after values, two groups, or the range between two related quantities per category. Map xmin to the first value, xmax to the second, and x to the row position.
Parameters
Example
[plot]
[[layer]]
mark = "dumbbell"
[layer.aes]
x = "C1:C40"
xmin = "A1:A40"
xmax = "B1:B40"
[layer.params]
size = 5
waterfall
Shows a running total with bars that go up or down, highlighting each increment or decrement.
Use for financial statements, budget breakdowns, or any cumulative contribution chart. Positive values go up, negative go down; a total bar is drawn at the end.
Parameters
Example
[plot]
x = "A1:A10"
y = "B1:B10"
[[layer]]
mark = "waterfall"
boxplot
Displays the five-number summary (min, Q1, median, Q3, max) and outliers as a box-and-whisker plot.
Use to compare distributions across categories. Map x to the grouping variable and y to the continuous measurement. Supports fill, alpha, and notch.
Parameters
Example
[plot]
x = "A1:A100"
y = "B1:B100"
[[layer]]
mark = "boxplot"
stat = "boxplot"
[layer.params]
alpha = 0.7
density
Draws a kernel density estimate (KDE) — a smoothed, continuous representation of a data distribution.
Use instead of a histogram when you want a smooth curve not dependent on bin width. Map x to the continuous variable. Use threshold_x with fill_below and fill_above to split the area into two differently-colored regions.
Parameters
Example
[plot]
x = "A1:A30"
[[layer]]
mark = "density"
stat = "density"
[layer.params]
alpha = 0.6
fill = "#4292c6"
fill_below = "#e07b39"
threshold_x = 33.4
histogram
Bins a continuous variable into intervals and draws bars showing the count or density in each bin.
Use to visualize the distribution of a single continuous variable. Adjust the bins param to control granularity. Supports fill, alpha, and bins.
Parameters
Example
[plot]
x = "A1:A150"
[coord_cartesian]
ylim = [0, 22]
[[layer]]
mark = "histogram"
[layer.params]
bins = 18
gap = 1
fill = "#4c8ecd"
alpha = 0.85
violin
A mirrored density plot that reveals the full shape and spread of the data distribution.
Use alongside boxplot for a richer view — violins show multimodality that boxplots hide. Map x to the group, y to the measurement. Supports fill, alpha, and scale.
Parameters
Example
[plot]
x = "A1:A50"
y = "B1:B50"
[[layer]]
mark = "violin"
[layer.params]
color = "#333333"
stroke_width = 1.0
alpha = 0.7
scale = "area"
show_quantiles = true
show_box = true
contour
Draws iso-contour lines over a 2D surface defined by x, y, and z values on a regular grid.
Use to visualize the topography of a z variable across x and y. Add filled = true to render a gradient fill behind the lines. Control the number of levels with levels.
Parameters
Example
[plot]
[[layer]]
mark = "contour"
[layer.aes]
x = "A1:A169"
y = "B1:B169"
z = "C1:C169"
[layer.params]
levels = 8
linewidth = 1.2
heatmap
Colors a grid of cells by a value, creating a color-encoded 2D matrix.
Use to visualize a third variable (fill) across a 2D grid of x and y combinations. Typical use: correlation matrices, gene expression, calendar heatmaps.
Parameters
Example
[plot]
[[layer]]
mark = "heatmap"
[layer.aes]
x = "A1:A25"
y = "B1:B25"
fill = "C1:C25"
hex
Bins 2D scatter data into hexagonal cells and colors them by point count or a summary statistic.
Use instead of scatter plots when overplotting hides data density. Great for large datasets. Adjust bins to control cell size.
Parameters
Example
[plot]
x = "A1:A180"
y = "B1:B180"
[[layer]]
mark = "hex"
[layer.params]
bins = 24
tile
Draws filled rectangles (tiles) at each (x, y) position, colored by a fill variable.
Like heatmap but with explicit tile positions and sizes. Use for raster maps, image-like data, or any regular grid visualization.
Parameters
Example
[plot]
[[layer]]
mark = "tile"
[layer.aes]
x = "A1:A9"
y = "B1:B9"
fill = "C1:C9"
candlestick
Draws OHLC candlestick bars showing open, high, low, and close prices for each time period.
Use for financial price data. Map x to the date/time, and the open, high, low, close aesthetics to the respective price columns. Green candles = close > open.
Parameters
Example
[plot]
x = "A1:A12"
[[layer]]
mark = "candlestick"
[layer.aes]
open = "B1:B12"
high = "C1:C12"
low = "D1:D12"
close = "E1:E12"
ohlc
Draws OHLC tick marks: a vertical line for the high-low range with left/right ticks for open and close.
A classic financial chart style, more compact than candlesticks. Map x to time, and open, high, low, close aesthetics to the respective price columns.
Parameters
Example
[plot]
x = "A1:A12"
[[layer]]
mark = "ohlc"
[layer.aes]
open = "B1:B12"
high = "C1:C12"
low = "D1:D12"
close = "E1:E12"
abline
Draws a straight line across the entire plot defined by slope and intercept: y = slope·x + intercept.
Use for regression reference lines, identity lines (slope=1, intercept=0), or any linear benchmark. Set slope and intercept in params — no data mapping needed.
Parameters
Example
[plot]
[coord_cartesian]
xlim = [0, 8]
ylim = [0, 12]
[[layer]]
mark = "abline"
[layer.params]
slope = 1
intercept = 0
color = "#aaaaaa"
linetype = "dashed"
[[layer]]
mark = "abline"
[layer.params]
slope = 1.5
intercept = 0
color = "#e31a1c"
linewidth = 2
annotate
Places a custom text annotation or shape at a specific plot coordinate.
Use to add callout labels, notes, or arrows at exact (x, y) positions. Unlike text mark, annotate works with fixed coordinates rather than data rows.
Parameters
Example
[plot]
x = "A1:A4"
y = "B1:B4"
[[layer]]
mark = "points"
[layer.params]
size = 6
[[layer]]
mark = "annotate"
[layer.params]
x = 2
y = 5.2
label = "Point 1"
[[layer]]
mark = "annotate"
[layer.params]
x = 4
y = 7.8
label = "Point 2"
[[layer]]
mark = "annotate"
[layer.params]
x = 6
y = 5.8
label = "Point 3"
[[layer]]
mark = "annotate"
[layer.params]
x = 8
y = 9.8
label = "Point 4"
highlight
Draws a filled rectangle to highlight a region of the plot.
Use to shade a range of x or y values — for example, a date range, a threshold band, or a reference region. Set xmin, xmax, ymin, ymax in params.
Parameters
Example
[plot]
x = "A1:A10"
y = "B1:B10"
[[layer]]
mark = "line"
[[layer]]
mark = "highlight"
[layer.params]
xmin = 3
xmax = 6
alpha = 0.2
hline
Draws one or more horizontal reference lines at fixed y values spanning the full width of the plot.
Use to mark thresholds, means, or target values. Set yintercept in params. No data mapping needed — the line spans the full x range automatically.
Parameters
Example
[plot]
x = "A1:A8"
y = "B1:B8"
[[layer]]
mark = "points"
[[layer]]
mark = "hline"
[layer.params]
yintercept = 7
color = "#e31a1c"
linewidth = 1
label
Places text labels at (x, y) positions, with an optional filled background box for readability.
Use when labels need to stand out against a busy background. Set background to a color to draw a box behind each label; omit it for transparent labels. Adjust padding to control box size.
Parameters
Example
[plot]
x = "A1:A5"
y = "B1:B5"
[[layer]]
mark = "points"
[layer.params]
size = 5
[[layer]]
mark = "label"
[layer.aes]
label = "C1:C5"
[layer.params]
size = 9
background = "#ffffffcc"
padding = 3
segment
Draws individual line segments from (x, y) to (xend, yend).
Use for connecting pairs of related points, drawing arrows between nodes, or showing directed changes. Each row defines one segment. Supports arrow, color, and linewidth.
Parameters
Example
[plot]
[[layer]]
mark = "segment"
[layer.aes]
x = "A1:A5"
y = "B1:B5"
xend = "C1:C5"
yend = "D1:D5"
text
Places text strings at (x, y) positions in the plot.
Use to annotate data points with their values or custom labels. Map the label aesthetic to a text column. Supports size, color, angle, hjust, vjust, and nudge_y.
Parameters
Example
[plot]
x = "A1:A5"
y = "B1:B5"
[[layer]]
mark = "points"
[layer.params]
size = 5
[[layer]]
mark = "text"
[layer.aes]
label = "C1:C5"
[layer.params]
size = 9
nudge_y = 0.6
vline
Draws one or more vertical reference lines at fixed x values spanning the full height of the plot.
Use to mark time points, category boundaries, or x-axis thresholds. Set xintercept in params. No data mapping needed — the line spans the full y range.
Parameters
Example
[plot]
x = "A1:A10"
y = "B1:B10"
[[layer]]
mark = "line"
[[layer]]
mark = "vline"
[layer.params]
xintercept = 5
color = "#e31a1c"
linewidth = 1
sankey
Flow diagram showing directed quantities between named nodes across multiple stages.
Ideal for multi-stage pipelines: supply chains, energy balances, budget allocations, or nutrient cycles. Each row is one directed edge; node positions and ribbon widths are computed automatically.
Parameters
Example
[[layer]]
mark = "sankey"
[layer.aes]
source = "D1:D11"
target = "E1:E11"
value = "C1:C11"
geo_region
Renders the panel's region outline (country, continent, or world) with optional subdivision boundaries — a data-free base layer for maps.
Use as the background layer inside a coord_geo plot to show the country/continent outline plus state or province subdivisions. No data mapping needed; geometry comes from the bundled geo datasets.
Parameters
Example
[plot]
[coord_geo]
region = "usa"
projection = "albers"
[[layer]]
mark = "geo_region"
[layer.params]
fill = "#f5f5f5"
stroke = "#888888"
show_subdivisions = true
geo_points
Plots a bubble/scatter layer at lon/lat positions, projected through the panel's geographic coordinate system.
Use inside a coord_geo plot to mark cities, events, or any point-located data. Map lon/lat to the longitude and latitude columns; size and fill aesthetics drive per-row dot radius and color.
Parameters
Example
[plot]
[coord_geo]
region = "world"
projection = "equirectangular"
[[layer]]
mark = "geo_region"
[[layer]]
mark = "geo_points"
[layer.aes]
lon = "A1:A20"
lat = "B1:B20"
size = "C1:C20"
[layer.params]
fill = "#1f77b4"
alpha = 0.8
geo_choropleth
Fills subdivision polygons (states, counties, countries) by an aggregated data value, producing a continuous color gradient.
Use inside a coord_geo plot to color regions by a numeric measure. Map id to the subdivision identifier column and value to the metric; the mark aggregates per id and trains a 2-color gradient on the result.
Parameters
Example
[plot]
[coord_geo]
region = "usa"
projection = "albers"
[[layer]]
mark = "geo_choropleth"
[layer.aes]
id = "A1:A50"
value = "B1:B50"
[layer.params]
agg = "sum"
scale_mode = "linear"
low_color = "#0d0887"
high_color = "#f0f921"
linerange
Vertical (or horizontal) line segments from ymin to ymax at each x.
Use for error bars, confidence intervals, or any per-point range. Pair with a points layer for the central estimate.
Parameters
Example
[plot]
x = "A1:A10"
[[layer]]
mark = "linerange"
[layer.aes]
ymin = "B1:B10"
ymax = "C1:C10"
spline
Smooth interpolating curve through ordered (x, y) points.
Like line but always smooth. Use when the data represents a continuous underlying signal you want emphasized.
Parameters
Example
[[layer]]
mark = "spline"
raster
Renders a regular grid of cells, one cell per (x, y) row, colored by a value.
Use for image-like dense grids — density maps, distance fields, anything precomputed to a regular lattice.
Parameters
Example
[[layer]]
mark = "raster"
rect
Filled rectangles defined by (xmin, xmax, ymin, ymax) per row.
Use for shaded regions, calendar heatmaps, or any axis-aligned rectangular highlight.
Parameters
Example
[[layer]]
mark = "rect"
[layer.aes]
xmin = "A:A"
xmax = "B:B"
ymin = "C:C"
ymax = "D:D"
spoke
Short line segments radiating from each (x, y) point in a given direction.
Use for vector fields, wind charts, or any directional data. Map angle and radius as aesthetics.
Parameters
Example
[[layer]]
mark = "spoke"
[layer.aes]
angle = "C:C"
radius = "D:D"
arrow
Directional arrow from one point to another, with an arrowhead at the destination.
Use for callouts, flow diagrams, or pointing at specific data points.
Parameters
Example
[[layer]]
mark = "arrow"
[layer.aes]
xend = "C:C"
yend = "D:D"