Plotting

The tables below are generated from the interpreter's own builtin dispatch table (fn call_builtin and fn exec_plot_command in engine/crates/qu-interp/src/lib.rs), not written speculatively ahead of the implementation — every function and command listed here runs today and produces a real Figure/Panel state that savefig(...) can export to SVG, HTML, or TikZ. A browser-based interactive Playground (docs/ide.html) also exists separately for live plot rendering — see its own chapter in this book.

Most chart-type and annotation calls accept trailing named style arguments collected into a small key/value bag — commonly color=, label=, marker=; a few calls have their own extras (bins=, colormap=, values=, hatch=, align=, position=, outside=, radius=). These are noted per-row only when a call has something beyond the common trio. hold on (the default) overlays successive calls on the current panel; hold off gives each call its own panel.

Animation

animate(function_name, frames, path, [fps=24], [embed_fonts=])

Calls a function you wrote once per frame, with the frame number, and writes the sequence as one animated SVG.

function frame(i)
    t = 2 * pi * i / 60
    x = (0 to 200) / 20
    plot(x, sin(x - t), color = "royalblue")
    ylim(-1.2, 1.2)
    axis off
end function

animate("frame", 60, "wave.svg", fps = 24)

Why SVG and not GIF. A GIF needs an LZW encoder, caps the palette at 256 colours, and produces a raster that is wrong at any size but the one it was made at. An animated SVG is one file, opens in any browser, stays sharp at any size, and reuses the renderer that already exists — the frames *are* ordinary Qu figures.

It animates without JavaScript. Each frame becomes a <g> carrying a CSS animation that shows it for its own slot of the cycle. No SMIL, no script, so the file works opened from disk, embedded in a page, or dropped into a slide.

The cost is size: a hundred frames is a hundred figures in one file. That is the honest trade, and the frame count is yours to choose. A frame draws into a *fresh* figure, so it cannot inherit marks from the one before it, and the per-frame · plot chatter is suppressed — the animation reports itself once.

catalog/qu_starry_night.qu and catalog/qu_sea_waves.qu are the two worked examples. The sea is built from the deep-water dispersion relation rather than from a sine, which is why it never repeats its shape.

Layers

Describe a set of marks once, place it as many times as you like.

l = capture(function_name, [extra arguments...])
stamp(l, x, y, [scale=], [rotate=])

capture runs your function into a scratch panel and keeps what it drew. stamp puts a transformed copy on the real one.

function sensor()
    circle(0, 0, 0.28, fill = "#4169e1", alpha = 0.9)
    circle(0, 0, 0.44, color = "#4169e1", width = 1.2)
    plot([0, 0], [-0.44, -0.9], color = "#4169e1", width = 1.2)
end function

s = capture("sensor")
stamp(s, 2, 5)
stamp(s, 6, 5, scale = 0.7)
stamp(s, 10, 5, rotate = 180)

A layer is a value, not a mode. It can be passed to a function, returned from one, held in a list, and duplicated by ordinary assignment — where a recorder with a begin and an end is one more thing to forget to close. It separates *what* is drawn from *where*, which is the whole reason to want it: a sensor symbol, a leaf, a bolt described once and placed forty times.

Extra arguments go to the function, so one definition makes a family: capture("sensor", 0.8) if sensor takes a size.

The transform is translate, then scale, then rotate about the layer's own origin — the order that makes stamp(l, 3, 4, rotate = 30) mean "put it there, turned". A stamped copy scales its stroke widths with it, so a shrunk symbol does not read as a blob, and drops its legend label, so one thing is not keyed twice.

Two things do not rotate, and say so rather than pretending: vline and hline are defined as spanning the whole panel in one direction, so a turned one is not a line of that kind any more. They translate and scale. A rotated rule is a polygon or a two-point plot. A rotated rectangle becomes the polygon it actually is.

Error bars and contours inside a layer keep their own geometry rather than moving: both are measurements of specific data, and a copy of one somewhere else would be a claim about data that is not there.

Interactive export

explore(function_name, path, names=, from=, to=, steps=)

Writes a self-contained HTML page with one slider per parameter and the figure updating as they move.

function view(frequency, damping)
    ...draw...
end function

explore("view", "explorer.html",
        names = ("frequency [Hz]", "damping"),
        from  = (10, 0.02),
        to    = (400, 0.5),
        steps = (12, 8))

The limit is worth understanding before you reach it. There is no Qu in a browser, so the page computes nothing: every combination is rendered up front and the sliders *choose* among them. The cost is therefore the product of the step counts, and it is capped at 400 — two parameters at ten steps each is a hundred figures, three at ten is a thousand, which is not a web page. Within that limit the file needs no server, no network and no install.

ui_slider is the other half of this story. It *declares* a control for a host to render, which is right when Qu Studio is running the script and useless when you want to email someone a file. Both exist because both questions are real.

catalog/qu_signal_explorer.qu is the worked example: three sliders over a band-pass, with the time record, the spectrum and the pole positions all moving together.

Shapes

A shape given only fill= is filled and not outlined; give it color= to outline it. That matters more than it sounds: stroking a fill anyway put a hairline on every edge, which is invisible on one shape and reads as banding when twenty of them tile a gradient.

axis off removes the spines, ticks, tick labels and grid — for an inset, a sparkline, a schematic, or drawing that is not a plot at all, where the panel is simply a coordinate system. axis on restores them. The decoration is built and then dropped rather than skipped, so turning it off moves nothing else on the figure.

All take color=, fill=, alpha=, width= and dash=.

These are drawn in data coordinates, and that has a consequence worth knowing. The outline is sampled in data space and each sample is then mapped through the axis transform — so circle(0, 0, 1) on a panel whose x and y scales differ draws the correct *ellipse*, not a round blob. That is geometrically right and it is what every plotting library does.

To get a round circle you need the two axes at the same number of data units per pixel, and that is decided by the panel's shape as much as by its ranges. axis equal widens the narrower RANGE until both spans match; it does not reshape the panel, so on a panel wider than it is tall — the default — matching ranges still leave the x axis more spread out than the y, and the circle is still an ellipse. A square canvas is what actually does it, which is why the example below sets one.

The alternative — emitting an SVG <circle> at a pixel radius — would be simpler and would draw the wrong shape on any panel with unequal scales, which is most of them, and something that is not an ellipse at all on a log axis.

# A square canvas, so that equal ranges really are equal scales and the

# circle below comes out round. Without it the figure would render an

# ellipse while the paragraph above it explained how to avoid one.

figure_size(560, 560)
xlim(-2, 2)
ylim(-2, 2)
axis equal
circle(0, 0, 1, color = "royalblue", fill = "royalblue")
ellipse(0, 0, 1.6, 0.7, color = "crimson", rotate = 30)
arc(0, 0, 1.3, 0, 120, color = "seagreen", width = 2)
polygon([0.8, 1.6, 1.2], [-1.6, -1.6, -0.9], color = "purple", fill = "plum")
rectangle(-1.8, -1.8, -1.2, -1.2, color = "orange")
rect(1.0, -1.8, 1.8, -1.2, color = "teal")
point(0, 1.9)

Colours

Anywhere a colour is taken — color=, edgecolor=, background=, fill= — you may write:

Every one of these is resolved to #rrggbb at the moment the argument is read, before any renderer sees it, and a colour that does not resolve is an error naming the nearest real one:

qu: runtime error: plot: color=: `royalbleu` is not a colour -- did you mean `royalblue`?

Overloads: rgba

rgba(r, g, b, a) reads its fourth channel a two different ways depending on its own magnitude, so the same call can be written either the "raw byte" way or the CSS "opacity fraction" way and land on the same colour.

Case: byte alpha

Written as a whole number sharing the other three channels' 0–255 range, a is read as a raw alpha byte.

print(rgba(255, 0, 0, 128))   # "#ff000080" -- half-transparent red, byte alpha

#ff000080

Case: fractional alpha

Written as a number 0–1 instead, a is read as an opacity fraction — the CSS convention — so 0.5 here lands on the exact same byte as 128 above. The boundary sits at 1: rgba(r, g, b, 1) is read as the fraction (fully opaque), never as the barely-visible byte value 1.

print(rgba(255, 0, 0, 0.5))   # "#ff000080" -- the same colour, from the CSS-style opacity fraction

#ff000080

Colour spaces

RGB is what a screen takes and a poor space to think in. Each of these separates one perceptual question from the others, and hands back the #rrggbb every colour argument accepts — so they compose with everything without a colour type needing to exist.

HSV is the one that earns its place: fix saturation and value, walk the hue, and every colour in the set carries the same weight. That is what palette(n) does, and it is why a categorical palette picked by hand in RGB always has one colour that shouts.

print(palette(5))
print(to_hsv("royalblue"))
print(delta_e("royalblue", "crimson"))
print(hsv(210, 0.7, 0.9))
print(hsl(210, 0.7, 0.5))
print(lab(50, 20, -30))
print(cmyk(0.1, 0.2, 0, 0.05))
print(rgb(65, 105, 225))
print(rgba(255, 0, 0, 0.5))
print(to_rgb("royalblue"))
print(to_hsl("royalblue"))
print(to_lab("royalblue"))
print(to_cmyk("royalblue"))

("#4c7fc7", "#ac4cc7", "#c74c4e", "#b0c74c", "#4cc77b")
[225, 0.711111, 0.882353]
108.484687
#4595e6
#2680d9
#7f6daa
#dac2f2
#4169e1
#ff000080
[65, 105, 225]
[225, 0.727273, 0.568627]
[47.830074, 26.263097, -65.263665]
[0.711111, 0.533333, 0, 0.117647]

delta_e is the check to run before claiming two series can be told apart. Under 1 is invisible, 2–3 is where people start to notice, over 10 is plainly a different colour. Two RGB values differing is not the same question, and is often reassuring when it should not be.

The Lab conversions go through linear light rather than the gamma-encoded sRGB values. That step is what separates a correct conversion from the common wrong one: interpolating encoded values gives a colour that is visibly too dark, which is the classic fault in every hand-rolled gradient.

That check is not pedantry. Colour strings used to reach the backends untouched, and the backends disagree: an SVG viewer knows what royalblue means, and the PDF writer reads the first two characters as hex, fails, and falls back to zero. The same figure came out blue on screen and black in the paper, with nothing printed either time.

Handles: tying one mark to another

text, annotate, vline and hline return a handle to what they drew. Reading a property tells you what was set; assigning one changes the drawing.

lab  = text(120, 5.35, "6 dB = 1 bit", color = "#0E7C86")
rule = hline(6, dash = true, width = 1.4)
rule.color = lab.color        # one ink, stated once

print(rule.color)             # "#0e7c86" -- the rule really did pick up the label's colour

#0e7c86

The alternative is to quote the same colour at both call sites and trust they stay equal. They do not: a restated value drifts the first time one of the two is edited.

Reading a property the call never set gives none, because what it will actually be drawn in is the theme's choice, made at render time. Assigning that none onward is refused rather than accepted, since the two defaults are different inks and accepting it would produce exactly the mismatch the assignment was written to prevent — set an explicit value on the source first.

Handles are positions in the figure being built, so they stop being valid once figure() starts a new one.

Example data

Every example on this page runs against this, so you can paste any of them into a file and see the figure. Nothing here needs a data file.

t  = linspace(0, 1, 500)                  # one second at 500 Hz

y  = sin(2 * pi * 5 * t) + 0.2 * randn(500, seed = 1)
mag  = abs(rfft(y))                       # 251 bins for 500 samples

f    = linspace(0, 250, len(mag))         # the matching frequency axis

yhat = sin(2 * pi * 5 * t)                # a "model" to compare against

losses = 1 ./ (1 to 40)                   # a decaying training curve

Figure & Axes Control

Overloads: axis

axis is one verb with several keyword arguments that switch it to fundamentally different behavior, not variations on one theme — worth seeing side by side rather than picking one and assuming the rest are similar.

Case: equal

axis equal forces equal data units per pixel on both axes. Look for the circle actually looking round, not stretched to whatever aspect ratio the panel happens to have.

circle(0, 0, 1)
axis equal

Case: origin

axis origin moves the axis spines to cross through data (0, 0) instead of framing the panel in a box. Look for the spines meeting in the middle of the plot instead of at its edges.

plot([-2, -1, 0, 1, 2], [-1, 0, 1, 0, -1])
axis origin

· plot: figure 1 (5 points)

Case: scale log

axis scale y log switches only the named axis to a log scale, leaving the other one linear. Look for the exponential curve straightening into a line.

x = 1 to 50
plot(x, exp(0.1 * x))
axis scale y log

· plot: figure 2 (50 points)

Overloads: legend

legend is two unrelated builtins sharing one name: the bare command form controls the legend box itself (on/off/position), and the function-call form instead labels the panel's own series. Neither one does the other's job.

Case: function form — label series

legend("sin(x)", "cos(x)") labels the trailing two series of the current panel, in call order, and turns the legend on. Look for a legend box carrying those two exact strings.

t = linspace(0, 1, 50)
plot(t, sin(t))
plot(t, cos(t))
legend("sin(x)", "cos(x)")

· plot: figure 3 (50 points)
· plot: figure 4 (50 points)

Case: bare command — position/visibility

legend top left is unrelated to labeling — it only moves (or, with off, hides) whatever legend already exists, using whatever labels plot's own label= set. Look for the box relocating to the top-left corner.

t = linspace(0, 1, 50)
plot(t, sin(t), label = "sin(x)")
legend top left

· plot: figure 5 (50 points)

Overloads: grid

Case: bare command

grid off (bare) is the real toggle — it actually removes the panel's gridlines.

t = linspace(0, 1, 50)
plot(t, sin(t))
grid off

· plot: figure 6 (50 points)

Case: function call (no-op)

grid(...) called with parentheses, as a function, is accepted so a MATLAB-style script still parses — but it changes nothing. Calling it after grid off does not turn the grid back on; the gridlines stay off, exactly as grid off left them.

t = linspace(0, 1, 50)
plot(t, sin(t))
grid off
grid()   # no-op -- gridlines stay off, not re-enabled

· plot: figure 7 (50 points)

These figure/axes calls are meant to be composed, not used one at a time, so here is a single panel exercising most of the row above: it renames the tick positions to words instead of numbers on both axes, swaps the figure's font and background, turns on the (currently non-drawing) colormap/colorbar pair, and explicitly restates grid/box/scale even though they are already at their defaults, to show that calling them is always safe. Run it and look at the labels — "start"/"mid"/"end" and "low"/"zero"/"high" should sit exactly where 0, 0.5, 1 and -1, 0, 1 used to, against a warm off-white page instead of pure white:

figure()
t = linspace(0, 1, 200)
plot(t, sin(2 * pi * 5 * t))
xticks([0, 0.5, 1])
xticklabels("start", "mid", "end")
yticks([-1, 0, 1])
yticklabels("low", "zero", "high")
fontfamily("sans")
fontsize(tick = 10, label = 12, title = 14)
figure_background("#f7f7f7")
colormap("viridis")
colorbar()
grid()
box()
subplot(1, 1, 1)
xscale("linear")
yscale("linear")
title("Styled panel")

· plot: figure 8 (200 points)

Chart Types

Unless noted otherwise, each of these draws into the figure's *current panel* (self.figure.panel_for_new_series()), increments the figure/point counter, and accepts the common color=/label=/marker= style trio where relevant. plot_xy-style calls accept either f(y) (x defaults to 0, 1, 2, ...) or f(x, y).

Overloads: plot

plot's three call shapes are the most common overload in this chapter, and the marker-string form genuinely changes what gets drawn — a connected line versus discrete, unconnected points — not just its color or width.

Case: y only

Called with a single Vec, plot treats it as y and fills in x as 0, 1, 2, .... Look for a jagged line with no meaningful x-axis units.

plot([3, 1, 4, 1, 5])   # x defaults to 0, 1, 2, 3, 4

· plot: figure 9 (5 points)

Case: x and y (line)

With two equal-length Vecs it draws the default connected line. Look for a smooth curve with no dots at the sample points.

x = 0 to 9
plot(x, sin(x / 2))

· plot: figure 10 (10 points)

Case: marker string (scatter-style)

A third positional string like "o" (or marker="o") switches the exact same call to unconnected dots instead of a line. Look for discrete points with no line joining them.

x = 0 to 9
plot(x, sin(x / 2), "o")

· plot: figure 11 (10 points)

Overloads: boxplot

boxplot's argument count, not a keyword, decides how many groups are drawn side by side — the same pattern also used by spiderplot and raincloud, shown once here rather than three times.

Case: one group

A single Vec argument draws one box.

boxplot(randn(50, seed = 20))

Case: multiple groups

Each further Vec argument adds its own box at the next integer x position. Look for three boxes side by side instead of one.

boxplot(randn(50, seed = 20), randn(50, seed = 21) + 0.5, randn(50, seed = 22) - 0.3)

The line/scatter family covers continuous data; these five cover data that is naturally discrete or already summed. Reach for stem when each sample is its own event (a Kronecker-delta-like sequence, an impulse response) and a connecting line would misleadingly imply values in between; for stair when the value is genuinely constant between changes (a clock signal, a piecewise-constant control setpoint); for groupbar/stackbar when you have several numbers per category and want them either side-by-side (comparing magnitudes) or stacked (comparing a total and its composition); and for waterfall when you have several related traces (successive measurement passes, a parameter sweep) and want each to stay legible instead of drawing directly on top of the last. Six figures come out of this block — look for the stem's lollipops, the stair's right-angle corners, the two bar layouts' different use of the same three numbers, and the waterfall's traces climbing up and to the right of one another:

x = 0 to 9
y = sin(x / 2)
figure()
stem(x, y)
figure()
stair(x, y)
figure()
groupbar([1, 2, 3], [3, 5, 2])
figure()
stackbar([1, 2, 3], [3, 5, 2])
figure()
Z = [1, 2, 3, 4, 5; 2, 3, 4, 5, 6; 3, 4, 5, 6, 7]
waterfall(0 to 4, Z)

· stem: figure 14 (10 points)
· stair: figure 15 (10 points)
· groupbar: figure 16 (3 points)
· stackbar: figure 17 (3 points)

These four fit or summarize data rather than drawing it raw. splineplot and pwl both take a handful of control points and turn them into a smooth curve, but for different reasons: a spline is for when the points *are* the truth and you want a visually smooth curve through all of them exactly, while pwl is for when the underlying process is closer to piecewise-linear and you want a *fit* — its four segments won't pass through every point. spiderplot and raincloud are both about a shape rather than a fit: spiderplot compares several quantities on one radar chart, raincloud shows the full distribution (not just mean and spread) of two or more samples side by side, with the boxplot's summary, the KDE cloud's shape, and the individual jittered points all in one figure. Watch for the spline bending smoothly through the same five points pwl approximates with straight segments, and the raincloud's two "clouds" leaning the same direction as their generating distribution:

figure()
splineplot([0, 1, 2, 3, 4], [0, 2, 1, 3, 2])
figure()
pwl([0, 1, 2, 3, 4, 5, 6], [0, 1, 1.5, 3, 3.2, 3.5, 5])
figure()
spiderplot([3, 4, 2, 5, 4])
figure()
raincloud(randn(60, seed = 6), randn(60, seed = 7))

Two different kinds of "more than one number per point" live here. errorbar and fill_between both communicate uncertainty around a central curve — a whisker per sample versus a continuous shaded band — and bubble communicates a third *dimension* by encoding it as marker size rather than position. donut and pie are the odd ones out: they show how a whole splits into parts, which is a fundamentally different question ("what fraction is this?") from everything else on this page ("how does this vary against that?"), which is also why pie/donut charts are worth reaching for sparingly. In the rendered figures, check that the error whiskers and the fill_between band both widen and narrow with the same 0.1/±0.2 envelope around the same sine wave, and that the donut's hollow center is the only visual difference from the plain pie beside it:

x = 0 to 9
y = sin(x / 2)
figure()
errorbar(x, y, 0.1 * ones(10))
figure()
fill_between(x, y - 0.2, y + 0.2)
figure()
bubble(x, y, abs(y) * 20 + 5)
figure()
donut([30, 20, 50], "a", "b", "c")
figure()
pie([30, 20, 50], "a", "b", "c")

Four unrelated needs share this block only because they all involve a transform of the axes or the data before plotting. semilogx/semilogy/ loglog are for data that spans decades — a Bode magnitude, an exponential growth curve — where a linear axis would crush most of the interesting structure into a few pixels at one end. hist turns raw samples into a distribution shape. contour/contourf need a full 2-D field: note that meshgrid returns one Record with .x/.y fields (not two separate values), and that contour/contourf always take three arguments — (X, Y, Z) — never Z alone, because Qu has no notion of "the implicit grid a matrix was measured on". corr_heatmap/corrplot close the block by turning a table's numeric columns into a single correlation matrix. In the output, the semilog plot should look straight (or straighten a curve that was exponential), the log-log Bode-style curve should show a shallow slope rather than a hooked one, and the correlation heatmap's diagonal should read as the same colour throughout — a column is always perfectly correlated with itself:

f = logspace(0, 3, 200)
mag = 1 ./ sqrt(1 + (f / 100) .^ 2)
semilogx(f, mag)
figure()
x = 1 to 50
semilogy(x, exp(0.1 * x))
figure()
loglog(f, mag)
figure()
samples = randn(500, seed = 2)
hist(samples, bins = 15)
figure()
g = meshgrid(-3 to 3 step 0.2, -3 to 3 step 0.2)
Z = sin(sqrt(g.x .^ 2 + g.y .^ 2))
contour(g.x, g.y, Z)
figure()
contourf(g.x, g.y, Z)
figure()
tbl = table(a = randn(30, seed = 3), b = randn(30, seed = 4), c = randn(30, seed = 5))
corr_heatmap(tbl)
figure()
corrplot(tbl)

· hist: figure 31 (500 points, 15 bins)

If your data already lives in a table(...) (a data frame, in other languages' terms), the sns_* family saves you the step of pulling columns out into loose vectors by hand — you name the columns and Qu does the grouping. sns_scatter colours points by a categorical column, sns_box draws one boxplot group per category, and sns_bar aggregates a numeric column within each category before plotting the result. This example builds one small table with a numeric x, y and a two-level categorical grp column, then feeds it to all three; look for the scatter's two colours ("a" vs "b"), the two boxplot groups, and the two bars showing each group's mean y:

df = table(x = randn(30, seed = 1), y = randn(30, seed = 2),
           grp = ["a","b","a","b","a","b","a","b","a","b",
                  "a","b","a","b","a","b","a","b","a","b",
                  "a","b","a","b","a","b","a","b","a","b"])
sns_scatter(df, "x", "y", "grp")
figure()
sns_box(df, "grp", "y")
figure()
sns_bar(df, "grp", "y")
print("rows: " + str(rows(df)))

rows: 30

Annotations & Overlays

All of these attach shapes/callouts to the *current panel* (or, for blur_backdrop, to the whole figure).

These overlays exist for the moment a plain line/scatter isn't enough to make a point: xspan/yspan shade a region you want the reader to notice without drawing a whole extra series over it (a resonance band, a confidence window); arrow/arrowtext point at a specific feature instead of relying on the reader to find it; xbreak/ybreak compress a wide but uninteresting stretch of an axis so the parts that matter both get more room; and blur_backdrop throws everything except one rectangle out of focus, the way a camera would, to pull the eye toward it. The example below touches all of these across four figures — in the first, look for the two tinted rectangles and the labeled arrow pointing at "peak"; in the second and third, a straight y = x line should visibly bend at the "//" jag where the break swallows [0.3, 0.6]; in the fourth, only the rendered figure's own center square stays sharp. The trailing tex/printtex calls are unrelated to any of this — included here only to print something concrete for the block, not to demonstrate an overlay:

t = linspace(0, 1, 200)
y = sin(2 * pi * 5 * t)
plot(t, y)
xspan(0.2, 0.4, color = "orange")
yspan(-0.3, 0.3, color = "green")
arrow(0.6, 0, 0.8, 0.8)
arrowtext(0.85, -0.5, 0.95, 0.2, "peak")
figure()
plot(t, t)
xbreak(0.3, 0.6)
figure()
plot(t, t)
ybreak(0.3, 0.6)
figure()
plot(t, y)
blur_backdrop(0.2, 0.2, 0.8, 0.8, radius = 4)
print(tex([1, 2; 3, 4]))
printtex([1, 2; 3, 4])

· plot: figure 39 (200 points)
· plot: figure 40 (200 points)
· plot: figure 41 (200 points)
· plot: figure 42 (200 points)
$\begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}$
$\begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}$

Diagrams

Auto-laid-out box-and-arrow diagrams — the coordinates are computed, not placed by hand as rectangle/arrow/text above require. Both return the diagram as an SVG string (so it can be captured, printed, or embedded) and, given file=, also write it to disk. Format is chosen by extension the same way savefig chooses one: .svg and .html/.htm are implemented; .png is not (same whole-figure rasterizer gap savefig documents) and raises a clear error naming .svg/.html instead.

function classify(x)
  if x > 0
    y = 1
  else
    y = -1
  end if
  return y
end function
svg = algorigram("classify")
data = 0 to 99
print(diagram_pipeline(() := data |> lowpass(fc=1000) |> fft() |> abs()))

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 830.00 124.00" width="830.00" height="124.00" font-family="Inter, Helvetica, Arial, sans-serif">
<rect x="0" y="0" width="830.00" height="124.00" fill="#ffffff"/>
<line x1="191.00" y1="62.00" x2="233.60" y2="62.00" stroke="#333333" stroke-width="1.4"/>
<polygon points="239.00,62.00 230.00,65.60 230.00,58.40" fill="#333333" stroke="none" stroke-width="1.00" opacity="1"/>
<line x1="391.00" y1="62.00" x2="433.60" y2="62.00" stroke="#333333" stroke-width="1.4"/>
<polygon points="439.00,62.00 430.00,65.60 430.00,58.40" fill="#333333" stroke="none" stroke-width="1.00" opacity="1"/>
<line x1="591.00" y1="62.00" x2="633.60" y2="62.00" stroke="#333333" stroke-width="1.4"/>
<polygon points="639.00,62.00 630.00,65.60 630.00,58.40" fill="#333333" stroke="none" stroke-width="1.00" opacity="1"/>
<rect x="40.00" y="40.00" width="150.00" height="44.00" rx="22" fill="#e6f4ea" stroke="#333333" opacity="1"/>
<text x="115.00" y="66.55" font-size="13" text-anchor="middle" fill="#333333">data</text>
<rect x="240.00" y="40.00" width="150.00" height="44.00" rx="6" fill="#eef3fb" stroke="#333333" opacity="1"/>
<text x="315.00" y="66.55" font-size="13" text-anchor="middle" fill="#333333">lowpass(fc=1000)</text>
<rect x="440.00" y="40.00" width="150.00" height="44.00" rx="6" fill="#eef3fb" stroke="#333333" opacity="1"/>
<text x="515.00" y="66.55" font-size="13" text-anchor="middle" fill="#333333">fft()</text>
    ... 3 more lines

Interpolation for plotting

Overloads: interp1

The method string picks between three genuinely different curve shapes through the same six points — worth plotting side by side rather than trusting the names alone.

Case: linear

Straight segments between consecutive known points. Look for sharp corners at each of the six original samples (drawn as a separate scatter).

x = [0, 2, 4, 6, 8, 10]
y = [0, 1.8, 1.2, 3.5, 3.0, 4.8]
xq = 0 to 10 step 0.1
plot(xq, interp1(x, y, xq, "linear"))
scatter(x, y)

· plot: figure 43 (101 points)
· scatter: figure 44 (6 points)

Case: spline

A natural cubic spline through the same points. Look for a smooth curve with no corners, that can overshoot slightly between points the straight segments above would not.

x = [0, 2, 4, 6, 8, 10]
y = [0, 1.8, 1.2, 3.5, 3.0, 4.8]
xq = 0 to 10 step 0.1
plot(xq, interp1(x, y, xq, "spline"))
scatter(x, y)

· plot: figure 45 (101 points)
· scatter: figure 46 (6 points)

Case: nearest

Snaps each query point to whichever known sample is closest. Look for a blocky, staircase-like curve instead of anything smooth or straight.

x = [0, 2, 4, 6, 8, 10]
y = [0, 1.8, 1.2, 3.5, 3.0, 4.8]
xq = 0 to 10 step 0.1
plot(xq, interp1(x, y, xq, "nearest"))
scatter(x, y)

· plot: figure 47 (101 points)
· scatter: figure 48 (6 points)

Saving & Export

The actual figure-to-LaTeX export path is savefig("plot.tikz") or savefig("plot.tex") (see the savefig row above) — tex/printtex are a separate, value-level feature that happens to share the "LaTeX" theme, not alternate spellings of figure export.

Markers & Styling reference

Marker strings (passed as marker="..." or, for a few chart calls, as a bare positional string like plot(x, y, "o")):

• "line" — the default for plot/splineplot/pwl/waterfall/etc.
• "o" — circle marker (scatter-style).
• "x" / "+" — cross marker (both render identically).
• "s" / "square" — square marker.
• "stem" — vertical stem-and-marker (set automatically by stem(...)).
• "bar" / "stackbar" / "groupbar" — bar-family renderings (set automatically by the matching chart-type call).
• "step" — staircase line (set automatically by stair(...); not independently callable as a marker name since step is a reserved keyword).

A marker spec may also carry a line style suffix, and then the series is drawn as markers joined by that line: "o-" (circles, solid), "s--" (squares, dashed), "^:" (triangles, dotted), "D-." (diamonds, dash-dot). A spec that is all line and no glyph — "-", "--", ":", "-." — draws the line alone. Dash patterns scale with the line's weight, so a dash stays longer than the line is thick at any lw.

Keeping a marker readable on a busy background — a filled contour, a dense cloud, another series — has two answers, and they compose:

fill=true/false (alias mfc=) chooses filled or hollow; hollow is the default for most glyphs. Composite glyphs (boxplus, circletimes, crosshair, …) are a shape plus an overlay in the same ink, so filling them hides the mark that distinguishes them — draw those hollow.

See docs/design/figure-reference/svg/13_markers_and_lines.svg for every glyph, line style, weight and size on one sheet.

Named colormaps (colormap(name) or a chart's own colormap=), from plotting::PALETTES:

• "default" — Qu's own curated 8-color mix; used implicitly whenever no colormap(...) call has run.
• "kay" — the same 8 colors as "default", reordered.
• "qu" — the "Qu Best" palette: hues spaced 45° apart, reordered so consecutive entries sit roughly 180° apart (better for a cycling series palette than a plain hue sort).
• "tableau10" — the standard Tableau 10 / matplotlib tab10 cycle.
• "viridis", "plasma" — perceptually-uniform sequential scales; "viridis" is the default for corr_heatmap/corrplot/eda's correlation panel.
• "warm", "cool", "mono" — small curated sequential scales.
• "matlab" — MATLAB's own default ColorOrder (R2014b+), for porting a MATLAB figure's familiar blue/orange-red/yellow/purple line cycle.
• "blues" — ColorBrewer "Blues"; the default for plain heatmap(...).

An unrecognized colormap name is accepted and silently resolves to "default" rather than erroring the whole script over a typo.

Worked examples

The examples below are the smallest complete scripts each showing one common task end to end, rather than one call in isolation. Each is self-contained except where it says otherwise — it either defines its own data or reuses the vectors from the "Example data" section above (t, y, mag, f, yhat, losses), so pasting the Example data block once and then any one of these below it should reproduce exactly what's described.

A basic plot with labels, legend, and export — the shape almost every script starts from: two series on one panel, both axes labeled, a legend to tell them apart, and a save to disk. Look for two full sine/cosine periods sharing one set of axes, colour-coded and named in the legend box:

x = 0 to 2*pi step 0.05
plot(x, sin(x), label="sin(x)")
plot(x, cos(x), label="cos(x)")   # hold on (default) overlays on the same panel

xlabel("x")
ylabel("amplitude")
title("Two waves")
legend
grid on
show plot
savefig("waves.svg")

· plot: figure 49 (126 points)
· plot: figure 50 (126 points)
· show plot
· savefig waves.svg
  note: this figure uses screen styling and may not hold up in print -- call theme("publication") before saving for a paper (said once per session)
  note: fonts render using whatever is installed on the viewer's machine (none are embedded) -- pass embed_fonts=true (fontfamily preset only) or export .tikz for guaranteed appearance

A 2x2 subplot grid, for laying out several related views of the same dataset — here a signal's time-domain trace, its frequency spectrum, an actual-vs-predicted scatter, and a training-loss curve, the four views a typical signal-processing or model-fitting report wants side by side. Each panel(2, 2, k) call selects a cell before the plot call that fills it; expect four small, independent-looking charts sharing one figure, not one chart repeated four times:

panel(2, 2, 1)
plot(t, y)
panel(2, 2, 2)
plot(f, mag)
panel(2, 2, 3)
scatter(y, yhat)
panel(2, 2, 4)
plot(losses, color="orange")

· plot: figure 53 (6 points)
· plot: figure 54 (200 points)
· scatter: figure 55 (500 points)
· plot: figure 56 (40 points)

A scatter with a fitted trend line, for the everyday question "is there a relationship here, and if so, roughly what shape?" scatterfit draws the raw points and a polyfit curve through them in one call instead of two. Reusing the shared noisy sine t/y here is a deliberately awkward choice to make a point: a periodic signal has no real quadratic trend, so the fitted degree-2 curve should come out nearly flat while the scatter itself keeps oscillating around it — a reminder that scatterfit will always draw *a* line, whether or not a polynomial is the right model for the data:

scatterfit(t, y, 2)   # degree-2 polynomial fit through the scatter

xlabel("x")
ylabel("y")

A histogram plus boxplot side by side, for comparing a distribution's overall shape against a per-group five-number summary in one figure. The histogram (left) bins the shared noisy sine y into 20 buckets; the boxplot (right) compares three freshly generated groups so the two panels are visibly independent of each other:

group_a = randn(40, seed = 11)
group_b = randn(40, seed = 12) + 0.5
group_c = randn(40, seed = 13) - 0.3
panel(1, 2, 1)
histogram(y, 20)
panel(1, 2, 2)
boxplot(group_a, group_b, group_c)

· histogram: figure 57 (6 points, 20 bins)

An annotated series with a zoomed inset, for the common case of a feature — a transient, a peak, a glitch — that is too small on the full-range plot to read its value off directly. This example builds its own decaying oscillation (rather than reusing the shared data, since the reference point at x=3 needs an axis that actually reaches past 3), marks that point with a vertical rule and a text callout, and then magnifies the region right around it into an inset panel in the top-right corner. Look for the small dashed box around x=3 on the main curve, connector lines running to a zoomed-in copy of that same region, and the callout text sitting at the curve's value there:

xs = linspace(0, 5, 400)
ys = sin(2 * pi * 1.2 * xs) .* exp(-0.3 * xs)
y_at_3 = sin(2 * pi * 1.2 * 3) * exp(-0.3 * 3)
plot(xs, ys)
vline(3, color="red")
annotate(3, y_at_3, "transient")
zoom_inset(2.8, 3.2, -0.1, 0.1, position="top right", outside=true)
print(y_at_3)

· plot: figure 59 (400 points)
-0.238976

A heatmap, for any matrix where the *pattern* of values matters more than reading off individual numbers — a correlation matrix, a confusion matrix, a physical field. colorbar (the bare command; see the Figure & Axes Control table above) is accepted here for MATLAB-style familiarity, though today it doesn't change the rendered figure. Expect a 10x10 grid of cells shaded from the "viridis" scale according to each cell's own value:

m = randn(10, 10, seed = 4)
heatmap(m, colormap="viridis")
colorbar
title("Random field")
print("value range: [" + str(min(m)) + ", " + str(max(m)) + "]")

value range: [-2.270955, 2.7556]

A correlation overview of a table in one call, for the first-look pass over a new dataset before anything else — eda puts a correlation heatmap and one histogram per numeric column on a single auto-gridded figure, which is usually enough to spot an obviously skewed column or an unexpectedly strong pairwise correlation before writing any analysis code:

df = table(a = randn(30, seed = 3), b = randn(30, seed = 4), c = randn(30, seed = 5))
eda(df)   # correlation heatmap + one histogram per numeric column, auto-gridded

print("columns: " + str(cols(df)))

columns: 3

Interpolating between measured points before plotting, for the case where you have a handful of measurements and want a continuous curve to compare them against a model, or simply to make a sparse instrument reading look like a continuous signal. interp1 fills in the query points xq; the example then plots the smooth "spline" fit as a line with the original six measurements overlaid as a separate scatter series, so both the raw data and the interpolation are visible on the same axes:

x_measured = [0, 2, 4, 6, 8, 10]
y_measured = [0, 1.8, 1.2, 3.5, 3.0, 4.8]
xq = 0 to 10 step 0.1
yq = interp1(x_measured, y_measured, xq, "spline")
plot(xq, yq, label="spline fit")
scatter(x_measured, y_measured, label="measurements")
legend

· plot: figure 62 (101 points)
· scatter: figure 63 (6 points)

More functions