Plot objects and methods#

Workflow#

There are three levels of physical sizing. Content never expands the page or outer plot frame automatically:

Internal padding is named margins=(left,top,right,bottom): data width equals frame width minus left and right margins, and height works the same way. margins and plot_area are mutually exclusive; omitting both enables automatic margins.

plot(size=(width,height), x=axis(...), y=axis(...), style=plot_style(...), margins=(left,top,right,bottom)) creates a reusable definition. Size includes axes, labels and any colorbar. Omit margins for measured automatic padding. Insufficient fixed margins produce a located W_PLOT_LAYOUT warning while retaining the settings and continuing output. For precise multi-panel placement, specify each plot_area and its data-area anchor explicitly. There is no automatic alignment, equalization of widths, or adjustment across panels.

axis accepts label="", scale="linear"|"log"|"symlog", an increasing numeric range=(min,max), increasing ticks=[...], and D3 number format, such as .2f, .1e, or .0%. Log coordinates and error endpoints must be positive. Automatic ranges pad ordinary data by 5%; heatmaps use outer cell bounds; constant data is expanded.

axis(label_offset=(dx,dy)) shifts only that axis title. Both values are finite physical lengths, including negatives; the default is (0 mm,0 mm). It works with every notation mode.

plot_style accepts font_family (family or file), font_size=8 pt, line_width=0.6 pt, axis/text color="#222222", and a nonempty colors=[...] cycle. Data values are unitless numbers; scientific units belong in labels. Lengths use existing mm/cm/in/pt/px syntax.

page.add(p,size=(..., auto)) recomputes plot layout while preserving physical font, stroke and marker sizes. An omitted height retains its definition value. First placement seals the definition; later placements can have other sizes, but layers and decorations can no longer be changed. Scaling a containing group still scales all of its contents. New constructor names can be shadowed; existing plot = image(...) remains valid.

Long labels, unresolved tick overlaps and oversized legends or colorbars produce W_PLOT_LAYOUT warnings and retain their complete content. Automatic ticks still try a lower count; explicit ticks, fonts and fixed data rectangles remain unchanged. Warnings identify the placement location and, for insufficient margins, the approximate additional space needed on each side in mm. CLI validation and rendering print warnings to stderr and can still exit successfully; Rust exposes scene.warnings and Notebook displays Python warnings. Content may extend beyond a plot frame, but anything outside the page is clipped on export. Nonpositive data rectangles, invalid domains and invalid data remain errors.

Common options: hexadecimal color, physical line_width, opacity, and legend label. Band opacity defaults to 0.2; other layers to 1.

Grids draw first, followed by layers in order; both are separately clipped to the data rectangle. Axes and labels are outside that clip; legends draw last. Input arrays are snapshotted when adding layers. Paths are generated in batches, without the DSL's 10,000-command limit, simplification or sampling.

line, scatter, and errorbar share the options below. Lines and error bars default to marker="none"; scatter defaults to circle. Omitting the new options retains solid markers.

Data and legend symbols share geometry, paint, and per-point opacity. A marked line combines its line and marker in the legend. Error bars show the stems and caps for the actual xerr/yerr directions, plus any marker. Legend entries retain layer order; matching labels are never merged.

1p.line(x=[0,1,2], y=[1,3,2], marker="diamond", marker_size=2 mm,2       marker_fill="none", marker_border_color="#222222", marker_border_width=0.5 pt,3       label="Measured")

Editable source · SVG · PDF. Edit each series' symbol, fill, line style, and uncertainty direction independently.

Axis, layer legend, and colorbar label values accept strings, text(...), or formula(...). Strings inherit the plot color and the relevant font size. Text/formula materials retain their own styling, explicit sizes, widths, and wrapping, without automatic scaling. Use existing text(spans=[...]) for mixed content. Relative font paths still resolve against the material's defining .lay file.

1label = text(spans=[span("Energy "), formula(source=r"E_f", font_size=9 pt), span(" (eV)")],2             font_family="DejaVu Sans", font_size=9 pt)3p = plot(size=(100 mm,80 mm), x=axis(label=label),4         y=axis(label=formula(source=r"I-I_0", font_size=10 pt), notation="offset"))

Axes and colorbar(...) share these options:

The x-axis multiplier sits below the ticks at the right; the y-axis multiplier sits above the axis at the left. tick_labels=false hides the multiplier too. Measured labels and multipliers contribute to surrounding space requirements. Notation changes only display: data and chart.data(...) use original values, with unchanged linear/log mappings. Insufficient fixed margins or plot_area space produce warnings while retaining the data rectangle and all manually placed neighboring panels.

The centered x-axis title normally shares the row below the ticks with the right-aligned multiplier. Only an overlap between their measured default bounds places the title below the multiplier, separated by 1.2 mm. Formula superscripts/subscripts, text widths and line breaks participate in measurement. Without an x-axis multiplier, the previous default title placement is retained.

axis(label_offset=(dx,dy)) shifts the title independently; exponent_offset shifts the multiplier independently. Offsets are applied after default placement and collision handling, so moving either decoration does not reposition the other. Both use chart-local physical coordinates, with x right and y down, followed by chart rotation or containing-group scaling. Even the rotated y-axis title translates along those two local directions. Offset-induced title/multiplier overlaps and insufficient space produce W_PLOT_LAYOUT while retaining the requested settings. Automatic margins measure required space; a legacy title positioned at the frame edge can still be shifted outside that frame, in which case its position is retained with a warning. Use plot_area to reserve explicit surrounding space. Colorbars also accept independent label_offset, retaining their existing layout rules.

1x = axis(label="Time (s)", notation="offset", exponent=-6,2         exponent_offset=(0 mm, -0.5 mm),3         label_offset=(0 mm, 0.5 mm))

For more complex title layouts, use independent page.add(text(...)) or group.add(text(...)) placements targeting data-rectangle anchors.

Editable source · SVG · PDF. Both data rectangles are explicitly 76 × 52 mm, with page top-left positions (30,32) mm and (134,32) mm. The right panel shifts its x-axis title down 0.5 mm and its multiplier up 0.5 mm while preserving the data rectangle.

1h = plot(size=(80 mm,65 mm))2heat = h.heatmap(z=[[1,2,3],[4,5,6]], extent=(0,3,0,2),3                origin="lower", cmap="viridis", vmin=0, vmax=6)4h.colorbar(heat, label="Intensity", format=".1f")5page.add(h)

Rectangular matrices support uniform or explicit nonuniform x_edges/y_edges, named axes and independent breaks. extent=(xmin,xmax,ymin,ymax) gives outer cell edges; the default is (0,columns,0,rows). origin="lower" places row zero at the bottom; "upper" places it at the top. Palettes: viridis/magma/inferno/plasma/cividis/rdbu/gray. vmin/vmax default to finite extrema and expand constant data; values outside the range clamp to endpoint colors.

Default mode="raster" stores one source pixel per cell and displays it without interpolation. Nonuniform cells and advanced spatial axes use vector geometry to preserve mapping. Axes and text stay vector. mode="vector" emits one rectangle per valid cell, useful for small matrices. Each plot accepts one colorbar bound to one of its own heatmap or color-mapped layer handles; right is the default position. Legacy normalization is linear; color_scale enables shared nonlinear mappings. Export DPI does not change the underlying values or color normalization.

p.colorbar(heat, ...) binds a heatmap or color-mapped layer from the same plot, with at most one colorbar per plot. Omitting the new options retains the default right-hand appearance.

1p.colorbar(heat, position="bottom", length=45 mm, thickness=3 mm,2           ticks=[0,2500,5000], notation="offset", exponent=3, format=".1f",3           label=formula(source=r"I", font_size=9 pt))4# Manual alternative (only one colorbar call per plot):5# p.colorbar(heat, position=(3.5 mm,51 mm), orientation="horizontal", length=45 mm)

Vertical values increase from bottom to top; horizontal values increase from left to right. Colors share the layer's normalization. Side ticks face outward; manual vertical ticks face right and manual horizontal ticks face down. Colorbar multipliers sit above vertical strips at the left, or beyond horizontal ticks at the right; adjust with exponent_offset.

Automatic margins measure side colorbars. Fixed margins and fixed data rectangles retain the requested geometry. Manual colorbars never change margins. Out-of-frame content, long labels, and overlapping ticks produce W_PLOT_LAYOUT while preserving length, thickness, fonts, positions, and explicit ticks. A local p.colorbar(...) binds a layer in its own plot. To share one across plots, give those layers the same color_scale and place a standalone colorbar(scale=..., length=...) asset; see Cartesian plots. Neither form automatically avoids other panels or manual decorations.

Editable source · SVG · PDF. All four independently placed heatmaps have 52 × 36 mm data rectangles; the source also includes alternative manual horizontal coordinates.

table(src="results.csv") reads a CSV with unique nonempty headers, or column-oriented JSON such as {"x":[0,1],"y":[2,3],"sample":["A","B"]}. Columns must be nonempty and equally long. String columns are retained, but plotting requires numeric columns. Use d["column"] to select a column. CSV quoting and UTF-8 BOM are supported; empty cells are missing, literal NaN strings are not.

array(src="matrix.json") reads a nonempty numeric vector or rectangular matrix. JSON null represents missing values. Booleans, non-finite values and integers outside the JavaScript safe-integer range are rejected. Paths resolve against the defining .lay file, including modules. Data is cached within one compilation and read again on the next compilation.

Missing rows break lines/bands, skip scatter/error bars, or become transparent heatmap cells, with a counted W_PLOT_MISSING. Length mismatches, empty valid data, negative uncertainty, invalid log values, ragged matrices and impossible layouts are located errors. Ordinary layers preserve data order without imputation or sampling; statistical methods explicitly calculate the documented summaries.

Limits and related topics#

dsl-reference · Rust/WASM API · Python API · CLI options

Fixed layout and scientific style#

Use plot_area=box(offset=(left,top), size=(width,height)) to lock the data rectangle relative to the outer plot frame. All four values are physical lengths: left/top must be nonnegative, width/height positive, and boundaries finite. Extending beyond size produces a warning and retains the rectangle. This option is mutually exclusive with margins. Placement width/height overrides change the surrounding space while preserving the data rectangle. Changes to fonts, ticks, labels, legends or colorbars also preserve it; insufficient space produces a located W_PLOT_LAYOUT warning and output continues. In this mode axis and colorbar labels stay next to their respective axes when the outer frame grows.

1page = canvas(size=(120 mm, 90 mm), background="#ffffff")2p = plot(size=(100 mm, 70 mm), plot_area=box(offset=(20 mm, 10 mm), size=(60 mm, 40 mm)),3         x=axis(label="Time (s)", range=(0, 2)),4         y=axis(label="Signal", range=(0, 4)))5p.line(x=[0, 1, 2], y=[0, 3, 1])6chart = page.add(p, anchor="plot_top_left", offset=(30 mm, 20 mm))7peak = chart.data(x=1, y=3)8pointer = page.add(line(end_head=head(), dx=-10 mm, dy=8 mm, line_width=0.5 pt),9                   anchor="end", target=peak)10page.add(text(content="Peak", font_size=8 pt), anchor=bottom_left,11         target=pointer.start, offset=(1 mm, -1 mm))

• chart.data(x=...,y=...) returns an anchor on a placed plot instance. Values must be finite, unitless numbers within the resolved domains, including endpoints; log coordinates must be positive. It uses that instance's final layout and does not change the domains. Recompiling after an axis-range change keeps the annotation at the same data value. Out-of-range anchors raise an error.
• Annotation offset values are physical displacements in the shared container. Text and arrows remain independent elements: they may extend outside the data clip, have no automatic collision avoidance, and do not expand the plot's outer frame.
• Nine data-rectangle anchors are available: plot_top_left/plot_top_center/plot_top_right, plot_middle_left/plot_center/plot_middle_right, and plot_bottom_left/plot_bottom_center/plot_bottom_right. Use target=chart.plot_top_left or the quoted placement option anchor="plot_top_left" to position the data rectangle directly on the page.
• Lines and arrows support anchor="start"/"end" as well as pointer.start/end targets. Plot and endpoint anchors rotate with their instances; the original nine outer anchors still use the rotated axis-aligned bounding box. New placement anchor names require quotes and add no reserved words.
• An annotation and its target must belong to the same canvas or group. Place both inside a group to scale or rotate the whole annotated figure together; the usual group rules scale physical dimensions too. Each plot remains independently positionable and editable.

Data coordinates, data-rectangle anchors and physical offsets can be combined directly. anchor selects the placed element's own alignment point; target supplies its destination. The following offsets follow the page coordinates, rather than the rotated chart's local coordinates:

1page.add(text(content="Peak", font_size=8 pt), anchor=bottom_left,2         target=chart.data(x=1, y=3), offset=(2 mm, -2 mm))3page.add(text(content="(a)", font_size=9 pt),4         target=chart.plot_top_left, offset=(2 mm, 2 mm))

Editable source · SVG · PDF. The example fixes an 88 × 55 mm data area with its top-left at (26, 20) mm on the page. The peak arrow, threshold label and title are separate placements.

These options are opt-in and retain the previous appearance when omitted. They do not change plot_area, data domains, placement anchors, or other panels. Automatic margins still respond to measured axis text; use plot_area when the data rectangle must remain fixed. Insufficient fixed margins or space around a fixed rectangle produce W_PLOT_LAYOUT without reducing font sizes, moving, or compressing the data rectangle.

Manual legends may sit outside the data rectangle. They never reserve margins or resize the outer frame. Extending beyond the outer frame produces a warning and retains the specified coordinates. Legends do not detect collisions with labels or data; leave the required space explicitly. Grids draw behind data and may be hidden by opaque heatmaps. Scaling a containing group still scales its text, ticks, and legends under the existing group rules.

Editable source · SVG · PDF. Both data rectangles are explicitly 64 × 45 mm, with top-left positions set by the author to (20, 26) mm and (115, 26) mm on the page. This example does not use automatic alignment.

Extended layers and projections#

Multiple axes and breaks · Bars and steps · Histograms and ECDF · Boxplots and violins · Heatmaps and contours · Polar projection · Polar layers · Radar charts