graph
A plotting environment whose head names the plane the marks are drawn on.
graphOn this page


#Planes
The head names the plane: graph:polar{…}. The plane decides what a coordinate on a mark is, which axes the frame draws, and which marks the body admits. graph{…} is graph:xy{…}.
x, the number line. One axis, and marks that takexalone:point,text,segment,vector,brace, the axis marks, and the three that draw a sample in a lane above the line,scatter,boxplotandviolin.xy, the ordinary plane:xandy. Every mark except the four solids.argand, the complex plane, with axesreandim. A position is one complex number,point(z: (3 + 2i)^2), whereiis the unit and every expression is complex, orreandimgiven apart, which is how two columns bind. A curve isz(t), a surface is a function ofzcoloured by domain, and a field is the flow ofz′ = f(z). Nothing here has an independent axis, sofit,integral,bar,lollipop,histogram,density,heatmapandaxis.breakare refused.polar, with axesrandtheta, the angle in radians unless written60deg. A curve isr(θ), a surface or contour is a function ofrandtheta, and a bar or histogram stands round the turn as a rose. Refused:fit,integral,lollipop,density,boxplot,violin,heatmap,fieldandaxis.break.xyz, space:x,yandzin a box the reader can turn. It has its own marks, the solids, and its own section below.
The Allowed content section of this page lists every plane's marks in full. A pair, such as a segment's ends or an angle's corner, is (a, b) on the ordinary, argand and polar planes, read in that plane's axes, and (a, b, c) in space.


graph:argand{
vector(z: 3 + 2i; label: $z$)
circle(z: 0; radius: abs(3 + 2i); fill-style: outlined)
curve(z: sqrt(13) * e^(i * t); t: [0, 2pi])
axis.label(im: 2; label: $2i$)
point(z: (3 + 2i)^2; label: $z^2$)
}(
re domain: [-4, 14]
im domain: [-6, 14]
)

graph:polar{
curve(expression: 1 + cos(theta))
point(r: 2; theta: 60deg)
axis.band(r: [1, 2])
axis.band(theta: [0, pi/4])
}(
r domain: [0, 3]
)A mark the plane cannot draw is a compile error. Written in the body, it is refused by the body's content policy; written inside a cue, the error names what the mark needs — a bar on the argand plane: 'bar' is not drawn on the argand plane — it needs a categorical axis and a value axis with a baseline.
Each axis attribute is spelled with its axis's name in front: re domain, r grid spacing, theta format. Another plane's is refused:
graph:polar{
curve(f: 1 + cos(theta))
}(
x domain: [0, 3]
)[attribute]node `graph`: `x-domain` is not declared on `graph` here — it is withdrawn when `plane: polar`
#The frame
#The window
x domain: [0, 10] sets the window on that axis exactly, its first and last grid lines on the edges. Its ends may be expressions of parameters (y domain: [0, 0.46 / s] reframes as s moves), and on an axis of names they are names, [Tue, Thu]. A domain is animatable: !cue.to moves the window, and !cue.zoom outlines the new window before moving to it.
An axis whose domain is left off frames what the graph draws, on its own:
- It reaches every mark: readings, curves sampled across the x the other marks span, bands, literal coordinates, a hidden mark, every keyframe's target, and a mark a parameter moves over the whole of that parameter's range. The frame is settled once and holds still while the reader drags.
- On a plain numeric axis it reaches to 0 when 0 is no further from the marks than their own span. Readings from 1 to 4 are framed from 0, and heights from 150 to 190 are not.
- Its grid step is 1, 2, 2.5 or 5 times a power of ten, whichever holds the extent with the least empty axis, and both ends go out to multiples of it, so every cell is one size. A written grid spacing is kept as written, and the ends then stay on the marks.
- An end that closes on a mark moves out one more step. An end at 0 stays where it is, so a series from the origin or bars standing on the axis sit on it, unless a point, a text or a lollipop's head is there and would be cut in half. A
linegets no room along x: a series runs from edge to edge. - Curves alone have no extent to frame. x is then about [−10, 10], and y is the same length in the same units, centred on the curve, or starting from the curve's end nearest 0 where the curve is taller than that. Beside other marks, each curve's turning and inflection points join the x extent, unless it has more than four of them.
A unit of x is drawn as long as a unit of y only where the two are one kind of thing: a geometry construction (a shape, a polygon, an angle or a vector), the argand plane, a transform:, or curves alone. The axis with less to show is grown to match, away from 0 where marks stand on it. aspect: equal asks for one unit length whatever is drawn; with both domains written, neither window can grow, so the plot narrows instead and is centred in its room. aspect: square draws the largest square plot the room holds and keeps each axis on its own scale: a square frame, not a square unit, which is what a quantile–quantile plot is read on. The number line and the polar plane take no aspect.
The number line's window is a band about its axis. The polar plane's is a square about the origin, out to the furthest mark or the end of r domain, its outermost ring a whole grid step.
#Axis formats and scales
x format: is what an axis holds. The options:
numbers.radians: ticks as fractions of π, and an automatic step taken from π/4, π/2, π, 2π.degrees: values in radians, ticks written30°.dates:2024,2024-03,2024-03-15and date columns placed at their fractional years, ticked by the span.monthsandweekdays: ticksJan… andMon…, where 1 is January or Monday.- A list of names,
x format: Red, Blue, Yellow, or a column of them,x format: #sales.region, its distinct cells in row order. discrete, below.auto, the default, decided from the marks.
Names make the axis categorical. They stand at 1…n from the origin end, left to right along x and bottom to top up y. Every mark on the axis speaks them, line(x: Mon, Tue, Wed; y: 12, 19, 15), and a column of names binds directly. A name the axis does not hold is a compile error, such as a point at x: Fri beside that line: 'point.x' is 'Fri', which is not on that axis ('Mon', 'Tue', 'Wed').
A mark that is continuous along the axis has nothing between two names to draw over, and is refused: curve, fit, integral, contour and surface.


graph{
@data#sales{
region | y2023 | y2024
North | 38.0 | 42.1
South | 33.5 | 31.4
East | 47.2 | 55.0
West | 26.1 | 27.8
}
bar(x: #sales.region; y: #sales.y2023; colour: grey; label: 2023)
bar(x: #sales.region; y: #sales.y2024; colour: blue; label: 2024)
}(
y axis label: revenue (£k)
)#Axes ruled in discrete numbers
x format: discrete is a categorical axis in numbers. The values the marks give are sorted, de-duplicated and stood at 1…n, evenly spaced however far apart the numbers are, and each tick writes the value it stands for. Speeds of 800, 1200, 1600 and 2000 rpm get four stops and no tick at a round thousand between them. A value the axis was not ruled at is a compile error, as an unknown name is — a point at x: 1000 on those four stops: 'point.x' is '1000', which is not on that axis ('800', '1200', '1600', '2000').
The stops are settings, not measurements: the levels of a factorial experiment, a die's faces, the years a census was taken. Where the gaps carry meaning, such as readings at uneven times, numbers keeps them and discrete throws them away.
Under auto an axis carrying a series of names is ruled in those names, in the order they first appear; a date column or literal makes it dates; an axis carrying nothing but heatmap cells is discrete at their values; anything else holds numbers. Writing the names out fixes their order and keeps a name with no data on the axis.
On the polar plane theta format is radians (rays every π/6, labelled in π), degrees (every 30°), or names, which stand as spokes at equal angles round the turn. The argand plane's axes take no format.
x scale: is how an axis places a value: linear, log (a value at its base-10 logarithm) or log2. Data is written as measured, scatter(x: 10, 100, 1000), and the axis places it. Curves are sampled in the scale, a fit on log–log axes has the exponent as its slope, domains and !cue.zoom windows stay in data units, and the ticks are the decades written as values. A written value at or below zero is a compile error. A scale on an axis of names, dates or angles is refused. The polar plane takes r scale, which rings at the decades from the start of r domain.


graph{
fit(of: #readings; degree: 1)
scatter#readings(x: 10, 100, 1000; y: 3, 9, 27)
}(
x scale: log
y scale: log
)#Axis lines, grid and frame
axis position places the axis lines on the ordinary and argand planes. Under auto, an axis runs through 0 where 0 is in the window and along the edge on 0's side where it is not. The vertical axis keeps to the left edge when either axis is ruled in names or the graph draws a bar or a histogram, and the horizontal axis keeps to the bottom when x is ruled in names. origin runs both through 0 whatever is drawn, and edges keeps both to the bottom and left, as a boxed plot. Space has rules of its own, below.
An axis carries an arrowhead at each end where it runs on, and none where it meets the other axis at the plot's edge. An axis of names runs on only where the window stops short of its first or last name.
show axes, show ticks and show grid switch those parts off, and show background switches off all three and the axes' captions; an axis label, brace or band the author writes stays. show ticks takes away the axis's own numbers only: the names an axis.label sets stay, and the margin shrinks to what is left in it. grid style is lines, lines-minor, dots or dots-minor; the minor forms add unlabelled divisions between the labelled ones. All of these are animatable.
interactive lets the reader scroll to zoom, drag to pan and double-click to reset, with zoom and reset controls in the toolbar. editable lets the reader change the graph itself (Editing by the reader).
title is set over the top-left of the graph, as every environment sets its caption, with a line of room left above the plot for it. It is also the graph's accessible name.
#Space and transforms
#Space
graph:xyz draws three axes in a box seen from view: (azimuth, elevation), in degrees, (-60, 30) unless written. A position is point(x: 1; y: 1; z: 3), a pair is (a, b, c), and a vector needs dx, dy and dz. On an interactive graph the reader turns the box by dragging, zooms with the wheel and double-clicks to return; !cue.to on view turns it for them.


graph:xyz{
surface(expression: 2 * x^2 + y^2)
surface(expression: 4x + 2y - 3)
point(x: 1; y: 1; z: 3; label: $P$)
}(
x domain: [-2, 2]
y domain: [-2, 2]
z domain: [0, 12]
view: (35, 25)
)Each domain left off is worked out from the marks at the parameters' resting values and rounded out to its ticks. Under aspect: auto the box is drawn as a cube whatever its units; aspect: equal gives the three axes one unit length, so a sphere is round.
The axes run through the origin, all three with arrowheads and numbers, where the box holds 0 on every axis and 0 is on the box's boundary for at most one of them: a floor at z = 0 has x and y across it and z rising from its middle. Otherwise all three are numbered along the box's edges, with no arrowheads, since each end of an edge is a corner other edges meet. auto also keeps to the edges when the floor is ruled in names, when a bar or histogram is drawn, and when the axes through 0 would run mostly inside a solid. axis position: origin runs them through 0 wherever the box holds it, and edges keeps them to the box.
The floor's two axes take a format, so either may be ruled in names; z holds numbers. No axis takes a scale, and space takes no transform. Its marks:
- A
surfaceis a height,surface(f: 16 - x^2 - y^2), or an equation,surface(f: x^2 + y^2 + z^2 = 9). One that is linear in x, y and z is a plane, drawn exactly where it crosses the box:surface(f: 4x + 2y - 3),surface(f: x = 1). - An
integralis the volume under a surface over a region written as its iterated bounds,x: [0, 2]; y: [0, 1 - x], and withn:the boxes of its Riemann sum. - A
contourmaps the levels on the floor, or on the surface withon: surface; afieldisdx,dyanddz; acurveis a position int; anangleis drawn in the plane its arms span. bar,histogramandlollipopstand on the floor at(x, y)and rise up z; afitis the regression plane of z on x and y.- An
axis.labelnames a value on the box's edge, and withlinerules it across the back of the box. - The solids, drawn nowhere else:
polyhedron,revolution,sectionandshell.
Space refuses the shapes, brace, axis.brace, axis.band, axis.break, boxplot, violin, density and heatmap.


graph:xyz{
bar(
x: North, South, East, North, South, East, North, South, East
y: Tea, Tea, Tea, Coffee, Coffee, Coffee, Juice, Juice, Juice
z: 12, 9, 14, 18, 15, 22, 7, 10, 6
colour: teal, teal, teal, orange, orange, orange, purple, purple, purple
)
}(
z axis label: sales
view: (-50, 25)
)#Transforms
transform: draws the plane through a map. On xy it is a 2×2 matrix written as its rows: (1, 1), (0, 1) sends (x, y) to (x + y, y), and its columns are where the basis vectors land. On argand it is a function of z: z^2, 1/z. Every position goes through the map and the grid is drawn as the image of the grid, while the window and its numbers stay where they are, measuring the space the picture is mapped into.
graph{
polygon(x: 0, 1, 1, 0; y: 0, 0, 1, 1; colour: teal)
vector(dx: 1; dy: 0; label: $\hat{\imath}$)
vector(dx: 0; dy: 1; colour: orange; label: $\hat{\jmath}$)
slider:k(range: [-1, 1]; default: 0.5; name: shear)
}(
transform: (1, k), (0, 1)
)Entries may be parameters, as k is here, and !cue.to moves from one map to the next along the straight line between them. A derived window covers the marks and their images under every map the graph passes through, so it holds still for the whole animation. A mark that reads an axis rather than a position is refused beside a transform, and so is editable. A bar is refused with 'bar' is not drawn through a 'transform:' — a bar stands on a baseline, and a bent plane has no baseline to stand on.
The others refused are histogram, lollipop, boxplot, violin, density, fit, integral, contour, surface, field and heatmap.
#Marks
Marks share colour, label (rich text, so $maths$ sets), hidden, lock and layer; each mark's attribute table says which it takes. A hidden mark is not drawn but still frames the plot, so revealing it with hidden: true !cue.to{false}(at: 2) does not move the axes. layer is paint order: higher is drawn later, and equal layers keep source order. A mark drawn only as a stroke takes style, one of solid, dashed or dotted: line, segment, vector, fit, contour, a lollipop's stems and an axis.label's rule. A mark drawn only as a shape takes style, one of solid, hatched, dotted or outlined: bar, histogram, boxplot, violin and integral. A mark with both an edge and an inside takes the two apart, stroke-style for the edge and fill-style for the inside: polygon, curve, density, area, angle and the shapes. outlined leaves the inside empty and draws the edge alone.
group: puts a mark in one or more named groups, and the graph's key: is a map from each group to how it is drawn: a colour, a style or both (Attributes). A style word goes to the part of a mark it styles: dashed to a stroke, hatched and outlined to a fill, solid and dotted to either. A mark takes its colour from one group and its style from another, group: Women, Projected, except where it writes its own colour or style, which wins. A group the key does not name takes its otherwise, key: (Projected: red dashed; otherwise: grey solid), and the footer names those groups once, as other; without one, a group with no colour in the key is dealt the next free hue. The footer names every group once legend is written on the graph; without it there is no key.
graph{
line(x: 2000, 2010, 2020; y: 4.1, 4.6, 5.2; group: Measured)
line(x: 2020, 2030, 2040; y: 5.2, 5.9, 6.5; group: Projected)
}(
key: (Measured: blue solid; Projected: blue dashed)
)The marks, by what they draw:
- Positions and figures:
point,line,segment,vector,polygonand theshapes. - Notation:
angle,braceandtext. - Functions and fields:
curve,integral,surface,contourandfield. - Data:
scatter,bar,lollipop,histogram,heatmap,boxplot,violin,densityandfit. Each binds a dataset column directly;declares them. - Axes:
axis.label,axis.brace,axis.bandandaxis.break, each speaking to the axis whose coordinate it gives. - Solids, in space only:
polyhedron,revolution,sectionandshell.
#Mark labels
A mark's label: is anchored at a point on the mark the words are about, and set just above it, or centred on it for a mark with room inside: a shape, a polygon, an integral's region, an angle. The anchor depends on the mark:
- a point or a shape: its position; a segment: its midpoint; a vector: its tip;
- a function curve: its value at the middle of the x it is drawn over; a path in t: its point half way along t;
- an integral: half way up the function at the middle of its limits;
- a line, a polygon, or a scatter on a plane: the centroid of its points;
- a scatter on the number line: the top marker of its tallest column;
- a bar or a histogram: the far end of the bar that reaches furthest;
- a density: its peak; a heatmap: the middle of the grid's top edge;
- an angle: out along the bisector, clear of the arc, with a hairline back to the corner.
Where two labels in a scene want the same place, each takes the best free position in a ring round its own mark, and a label moved far enough off its mark gets a hairline leader back to it. Positions are chosen once over the pictures a scene comes to rest at, so a mark moved by !cue.to carries its label with it. A label is never moved onto another mark's anchor or outside the picture; where every position is taken it overlaps at its first choice. It is not clipped by the plot, so a label on a mark at the edge stands whole in the margin, and it is not drawn when its anchor leaves the window.
#Where marks stand
A scatter, a boxplot and a violin draw a sample about a line, and stand. On the number line each takes a lane above the axis, in source order, the first on the axis itself.
On a plane a mark written with one coordinate stands at a place on the other axis: x: lies along x, y: stands up y, and on: says where. A number stands it at that value. A name stands it at that name and rules the axis in the names its marks stand at, so three samples side by side need no format. The room at a place is the band there: one unit on an axis of names, and on a numeric axis as much as keeps it clear of the nearest other place. Marks standing at one place split that room in source order, and band: is each mark's share of its slot.
graph{
boxplot(y: 41, 44, 45, 47, 48, 52; on: control; colour: blue)
scatter(y: 41, 44, 45, 47, 48, 52; on: control; colour: grey)
boxplot(y: 46, 50, 51, 53, 55, 61; on: treated; colour: orange)
scatter(y: 46, 50, 51, 53, 55, 61; on: treated; colour: grey)
}(
y axis label: mass (g)
)A box, a violin and a scatter of the same readings are one sample drawn several ways, and share one slot rather than splitting it, so the summary lands over the readings. Which is drawn over which is source order and layer. Written with both coordinates and one axis ruled in names, a mark stands at every name at once, each reading at the name in its own row, which is the shape data usually arrives in. An axis ruled in names never crosses at the origin, so the names stay clear of the marks.
A scatter(layout: jitter) takes its offsets from the graph's seed (0 unless written) and each reading's row, so the cloud is the same on every render.
#Editing by the reader
editable lets the reader add elements of their own from the footer, change the author's elements, take them off the plot and reorder them. Their changes are laid over what the author wrote, which is never rewritten, and are kept between visits; Reset graph in the toolbar clears everything they did. An editable graph can also be panned and zoomed, as interactive allows. A mark with lock stays listed among the elements but cannot be changed, moved or removed; on a graph that is not editable, lock does nothing.
#Derived attributes
Marks that compute something publish it: #f.slope in an attribute, {{#f.slope}} in prose, recomputed as parameters move. Derived attributes covers how they behave.
curve:max,min,max-x,min-x,length.line:max,min,max-x,min-x.segment,vector:length,anglein degrees.polygonand the shapes:area,perimeter.integral:area(volumein space),exact.surface,contour:min,maxover the window.angle:degrees,radians.section:area;revolution,shell:volume.polyhedron:volume,area,vertices,edges,faces.fit:slope,intercept,r2.density:mode,peak,current-bandwidth.boxplot:median,q1,q3,iqr,min,max, and for a box of paired readings the same under each axis's name,x-median.
#Attributes
planegraph:valuexytitleeditablefalseinteractivefalseshow-ticksaxis.label sets stay.trueshow-axesaxestrueshow-backgroundbackground, show-bg, bgtrueshow-gridgridtrueseedscatter's offsets are drawn from.0keymaplegendfalsecontinuexplanex-domaindomainx-formatx-labelsautox-tick-labelsmapx-scalelinearx-grid-spacingx-grid, x-spacingautox-axis-labelx-labelgrid-stylelineslines-minordotsdots-minorgrid-typelinesxyplanex-domaindomainy-domainx-domain.x-formatx-labelsautoy-formatx-format.y-labelsautox-tick-labelsmapy-tick-labelsmapx-scalelineary-scalex-scale.linearx-grid-spacingx-grid, x-spacingautoy-grid-spacingy-grid, y-spacingautox-axis-labelx-labely-axis-labely-labeltransformxy, a function of z on argand.aspectautosquareequalautoaxis-positionautooriginedgesautogrid-stylelineslines-minordotsdots-minorgrid-typelinesargandplanere-domainim-domainre-grid-spacingre-grid, re-spacingautoim-grid-spacingim-grid, im-spacingautore-axis-labelre-labelim-axis-labelim-labeltransformxy, a function of z on argand.aspectautosquareequalautoaxis-positionautooriginedgesautogrid-stylelineslines-minordotsdots-minorgrid-typelinespolarplaner-domaintheta-domaintheta-formattheta-labelsautor-scalelinearr-grid-spacingr-grid, r-spacingautotheta-grid-spacingtheta-grid, theta-spacingautogrid-stylelineslines-minordotsdots-minorgrid-typelinesxyzplanex-domaindomainy-domainx-domain.z-domainx-formatx-labelsautoy-formatx-format.y-labelsautox-tick-labelsmapy-tick-labelsmapx-grid-spacingx-grid, x-spacingautoy-grid-spacingy-grid, y-spacingautoz-grid-spacingz-grid, z-spacingautox-axis-labelx-labely-axis-labely-labelz-axis-labelz-labelaspectautosquareequalautoaxis-positionautooriginedgesautoview(azimuth, elevation) in degrees.view-angles(-60, 30)#Allowed content
plane decides which of these are drawnxplanexyplanepointtextaxis.labelaxis.braceaxis.bandsegmentbracevectorscatteraxis.breaklinepolygoncirclesquarerectangletrianglestardiamondhexagonanglecurvefitintegralbarpictographlollipopareahistogramdensityboxplotviolincontoursurfaceheatmapfieldcuecue.drawcue.tracecue.highlightcue.spotlightsliderselectorcue.slidercue.selectorargandplanepolarplane#Allowed in
#Examples


@use:statistics
graph#fit-graph{
fit#trend(of: #observations; degree: 1; colour: teal)
cue{
statistics.residuals(of: #trend; colour: orange)
}(
in: 1
)
scatter#observations(x: 1, 2, 3, 4; y: 2.0, 2.4, 3.1, 4.8; colour: grey)
}(
x-axis-label: x
y-axis-label: y
)

graph:x{
boxplot(x: 2, 3, 3, 4, 4, 5, 5, 7, 12; colour: teal)
scatter(x: 2, 3, 3, 4, 4, 5, 5, 7, 12; colour: grey)
}

graph:polar{
curve(expression: 2 * cos(2 * theta); colour: blue)
curve(expression: 1; colour: grey)
}(
r-domain: [0, 2.2]
)

graph{
bar(x: North, South, East, West; y: 42.1, 31.4, 55.0, 27.8; colour: blue)
}(
title: Revenue, 2024
y-axis-label: £k
)

graph{
curve(expression: x^2 - 2)
}(
x-domain: [-3, 3]
y-domain: [-3, 7]
axis-position: edges
)

graph:argand{
point(z: 2 + i; label: $2 + i$)
point(z: -1 + 2i; label: $-1 + 2i$)
}(
re-domain: [-3, 3]
im-domain: [-1, 3]
axis-position: edges
)

graph{
histogram(x: -2.1, -1.4, -0.8, -0.5, -0.2, 0.1, 0.3, 0.6, 0.9, 1.2, 1.8, 2.6; bins: 6)
}#Notes
- An environment's own id is written on the node —
graph#projectile{…}— andcontinue:points at it with#projectile. - The body holds marks and the parameters that drive them, each parameter a control in the footer.
- An environment's own id is written on the node,
graph#projectile{…}, andcontinue:points at it with#projectile.
#Writing guidance
- Selecting canvas content — A mark belongs on the canvas when seeing it changes what the reader understands, and the detail holds as a picture on its own.
- Framing a readable graph — When to write a domain, the defaults left alone, naming a series, the ticks the prose reads, and one meaning per hue.