graph

A plotting environment whose head names the plane the marks are drawn on.

graphNode
On this page
A graph of four grey readings with a teal line fitted through them, on axes labelled x and y.A graph of four grey readings with a teal line fitted through them, on axes labelled x and y.

#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 take x alone: point, text, segment, vector, brace, the axis marks, and the three that draw a sample in a lane above the line, scatter, boxplot and violin.
  • xy, the ordinary plane: x and y. Every mark except the four solids.
  • argand, the complex plane, with axes re and im. A position is one complex number, point(z: (3 + 2i)^2), where i is the unit and every expression is complex, or re and im given apart, which is how two columns bind. A curve is z(t), a surface is a function of z coloured by domain, and a field is the flow of z′ = f(z). Nothing here has an independent axis, so fit, integral, bar, lollipop, histogram, density, heatmap and axis.break are refused.
  • polar, with axes r and theta, the angle in radians unless written 60deg. A curve is r(θ), a surface or contour is a function of r and theta, and a bar or histogram stands round the turn as a rose. Refused: fit, integral, lollipop, density, boxplot, violin, heatmap, field and axis.break.
  • xyz, space: x, y and z in 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.

The complex plane: a vector to 3 + 2i, the point 5 + 12i, and a circle of radius √13 about the origin.The complex plane: a vector to 3 + 2i, the point 5 + 12i, and a circle of radius √13 about the origin.
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]
)
The polar plane: the cardioid r = 1 + cos θ, the point r = 2 at 60°, a band between r = 1 and r = 2, and a band from θ = 0 to π/4.The polar plane: the cardioid r = 1 + cos θ, the point r = 2 at 60°, a band between r = 1 and r = 2, and a band from θ = 0 to π/4.
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 line gets 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 written 30°.
  • dates: 2024, 2024-03, 2024-03-15 and date columns placed at their fractional years, ticked by the span.
  • months and weekdays: ticks Jan… and Mon…, 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').

Warning
The first name in a list is the lowest on a y axis.

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.

Revenue in £k for North, South, East and West: grey bars for 2023 and blue bars for 2024.Revenue in £k for North, South, East and West: grey bars for 2023 and blue bars for 2024.
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.

Warning
On a log scale, a column cell at or below zero drops its row.
Readings at x = 10, 100 and 1000 against y = 3, 9 and 27 on log–log axes, lying on their fitted straight line.Readings at x = 10, 100 and 1000 against y = 3, 9 and 27 on log–log axes, lying on their fitted straight line.
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.

Space: the surface z = 2x² + y² with its tangent plane z = 4x + 2y − 3 touching it at the point (1, 1, 3).Space: the surface z = 2x² + y² with its tangent plane z = 4x + 2y − 3 touching it at the point (1, 1, 3).
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 surface is 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 integral is the volume under a surface over a region written as its iterated bounds, x: [0, 2]; y: [0, 1 - x], and with n: the boxes of its Riemann sum.
  • A contour maps the levels on the floor, or on the surface with on: surface; a field is dx, dy and dz; a curve is a position in t; an angle is drawn in the plane its arms span.
  • bar, histogram and lollipop stand on the floor at (x, y) and rise up z; a fit is the regression plane of z on x and y.
  • An axis.label names a value on the box's edge, and with line rules it across the back of the box.
  • The solids, drawn nowhere else: polyhedron, revolution, section and shell.

Space refuses the shapes, brace, axis.brace, axis.band, axis.break, boxplot, violin, density and heatmap.

A bar chart in space: tea, coffee and juice sales for North, South and East as columns on a floor ruled in names both ways.A bar chart in space: tea, coffee and juice sales for North, South and East as columns on a floor ruled in names both ways.
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:

#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.

Tip
Another seed arranges the same sample differently, which is how a cloud that hides a point is fixed without touching the data.

#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.


#Attributes

On any plane
planeImplicit
Which kind of space the marks are drawn in.
Can be written as shorthand: graph:value
Defaultxy
title
The caption over the graph's top left, also its accessible name.
editable
Whether the reader may add marks of their own, and pan and zoom the frame.
Defaultfalse
interactive
Whether the reader may zoom, pan and reset the graph, with controls in the toolbar.
Defaultfalse
show-ticksAnimatable
The axes' tick numbers; the names an axis.label sets stay.
Defaulttrue
show-axesAnimatable
The axis lines and their arrowheads.
Also written: axes
Defaulttrue
show-backgroundAnimatable
Master switch for the grid, axes, their captions and the ticks.
Also written: background, show-bg, bg
Defaulttrue
show-gridAnimatable
The grid the marks are measured against.
Also written: grid
Defaulttrue
seed
The number a jittered scatter's offsets are drawn from.
Default0
key
A map from each group to how it is drawn: a colour, a stroke, or both.
map
legend
The footer's key to the groups.
Defaultfalse
continue
The earlier same-type environment whose state this one inherits.
Only withxplane
x-domainAnimatable
The range of the x axis, from its first grid line to its last.
Also written: domain
x-formatAnimatable
What the x axis holds: numbers, angles, dates, or names.
Also written: x-labels
Defaultauto
x-tick-labels
The text a categorical x axis shows for each of its names.
map
x-scaleAnimatable
How the x axis places a value.
Defaultlinear
x-grid-spacingAnimatable
The step between grid lines on x.
Also written: x-grid, x-spacing
Defaultauto
x-axis-label
The name of the x axis.
Also written: x-label
grid-styleAnimatable
What the grid is made of.
lineslines-minordotsdots-minor
Also written: grid-type
Defaultlines
Only withxyplane
x-domainAnimatable
The range of the x axis, from its first grid line to its last.
Also written: domain
y-domainAnimatable
The range of the y axis, as x-domain.
x-formatAnimatable
What the x axis holds: numbers, angles, dates, or names.
Also written: x-labels
Defaultauto
y-formatAnimatable
What the y axis holds, as x-format.
Also written: y-labels
Defaultauto
x-tick-labels
The text a categorical x axis shows for each of its names.
map
y-tick-labels
The text a categorical y axis shows for each of its names.
map
x-scaleAnimatable
How the x axis places a value.
Defaultlinear
y-scaleAnimatable
How the y axis places a value, as x-scale.
Defaultlinear
x-grid-spacingAnimatable
The step between grid lines on x.
Also written: x-grid, x-spacing
Defaultauto
y-grid-spacingAnimatable
The step between grid lines on y.
Also written: y-grid, y-spacing
Defaultauto
x-axis-label
The name of the x axis.
Also written: x-label
y-axis-label
The name of the y axis.
Also written: y-label
transformAnimatable
The map the plane is drawn through: a matrix on xy, a function of z on argand.
aspect
The shape of the plot and the length of its units.
autosquareequal
Defaultauto
axis-positionAnimatable
Where the axis lines are drawn.
autooriginedges
Defaultauto
grid-styleAnimatable
What the grid is made of.
lineslines-minordotsdots-minor
Also written: grid-type
Defaultlines
Only withargandplane
re-domainAnimatable
The range of the real axis.
im-domainAnimatable
The range of the imaginary axis.
re-grid-spacingAnimatable
The step between grid lines on the real axis.
Also written: re-grid, re-spacing
Defaultauto
im-grid-spacingAnimatable
The step between grid lines on the imaginary axis.
Also written: im-grid, im-spacing
Defaultauto
re-axis-label
The name of the real axis.
Also written: re-label
im-axis-label
The name of the imaginary axis.
Also written: im-label
transformAnimatable
The map the plane is drawn through: a matrix on xy, a function of z on argand.
aspect
The shape of the plot and the length of its units.
autosquareequal
Defaultauto
axis-positionAnimatable
Where the axis lines are drawn.
autooriginedges
Defaultauto
grid-styleAnimatable
What the grid is made of.
lineslines-minordotsdots-minor
Also written: grid-type
Defaultlines
Only withpolarplane
r-domainAnimatable
The radius of the polar plane, out to its outermost ring.
theta-domainAnimatable
The polar plane's sector, in radians.
theta-formatAnimatable
What the polar plane's angle axis holds: radians, degrees or names.
Also written: theta-labels
Defaultauto
r-scale
How the polar plane places a radius.
Defaultlinear
r-grid-spacingAnimatable
The spacing of the rings.
Also written: r-grid, r-spacing
Defaultauto
theta-grid-spacingAnimatable
The spacing of the rays, in radians.
Also written: theta-grid, theta-spacing
Defaultauto
grid-styleAnimatable
What the grid is made of.
lineslines-minordotsdots-minor
Also written: grid-type
Defaultlines
Only withxyzplane
x-domainAnimatable
The range of the x axis, from its first grid line to its last.
Also written: domain
y-domainAnimatable
The range of the y axis, as x-domain.
z-domainAnimatable
The range of the z axis.
x-formatAnimatable
What the x axis holds: numbers, angles, dates, or names.
Also written: x-labels
Defaultauto
y-formatAnimatable
What the y axis holds, as x-format.
Also written: y-labels
Defaultauto
x-tick-labels
The text a categorical x axis shows for each of its names.
map
y-tick-labels
The text a categorical y axis shows for each of its names.
map
x-grid-spacingAnimatable
The step between grid lines on x.
Also written: x-grid, x-spacing
Defaultauto
y-grid-spacingAnimatable
The step between grid lines on y.
Also written: y-grid, y-spacing
Defaultauto
z-grid-spacingAnimatable
The step of the z ticks and grid.
Also written: z-grid, z-spacing
Defaultauto
x-axis-label
The name of the x axis.
Also written: x-label
y-axis-label
The name of the y axis.
Also written: y-label
z-axis-label
The name of the z axis.
Also written: z-label
aspect
The shape of the plot and the length of its units.
autosquareequal
Defaultauto
axis-positionAnimatable
Where the axis lines are drawn.
autooriginedges
Defaultauto
viewAnimatable
Where the camera stands, as (azimuth, elevation) in degrees.
view-angles
Default(-60, 30)

#Allowed content

#Allowed in

#Examples

Three frames of the first step: four grey readings and a teal fitted line, then orange residuals fading in from each reading to the line.Three frames of the first step: four grey readings and a teal fitted line, then orange residuals fading in from each reading to the line.
@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
)
A number line with a teal box plot of nine readings, the readings themselves as grey markers swarmed through the same lane.A number line with a teal box plot of nine readings, the readings themselves as grey markers swarmed through the same lane.
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)
}
The polar plane: a rose of four petals and the unit circle, on a grid of rings and rays.The polar plane: a rose of four petals and the unit circle, on a grid of rings and rays.
graph:polar{
    curve(expression: 2 * cos(2 * theta); colour: blue)
    curve(expression: 1; colour: grey)
}(
    r-domain: [0, 2.2]
)
Revenue by region drawn as bars on a categorical x axis, with the y axis labelled. The title is the graph's accessible name and is not drawn.Revenue by region drawn as bars on a categorical x axis, with the y axis labelled. The title is the graph's accessible name and is not drawn.
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
)
The parabola y = x² − 2 as a boxed plot: with axis position: edges the axes run along the bottom and left of the frame rather than through the origin.The parabola y = x² − 2 as a boxed plot: with axis position: edges the axes run along the bottom and left of the frame rather than through the origin.
graph{
    curve(expression: x^2 - 2)
}(
    x-domain: [-3, 3]
    y-domain: [-3, 7]
    axis-position: edges
)
The argand plane with the points 2 + i and −1 + 2i, its axes on the edges of the frame.The argand plane with the points 2 + i and −1 + 2i, its axes on the edges of the frame.
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
)
A histogram of readings either side of zero: the vertical axis stands at the left edge, clear of the bars, rather than at x = 0 among them.A histogram of readings either side of zero: the vertical axis stands at the left edge, clear of the bars, rather than at x = 0 among them.
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{…} — and continue: 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{…}, and continue: 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.

Last updated