line

A path through readings in the order written.

lineNode
Only withxyargandpolarxyzplane
On this page
A pink line through three points and a grey stepped line beside it.A pink line through three points and a grey stepped line beside it.

A line joins readings in the order written: x: and y: paired by position, numbers or dataset columns, line(x: #co2.year; y: #co2.ppm). On the argand plane the readings are z: or re: and im:, on the polar plane r: and theta:, and in space x:, y: and z:. The number line takes no line. A derived window leaves no room past a line's first and last x, so a series runs from edge to edge. A series read as an amount, filled down to the baseline, is an area.

interpolate is how it gets from one reading to the next. linear joins them with straight legs. bezier rounds the corners with a cubic through every reading, its handles at the middles of the legs either side, so it cannot overshoot; it draws the quantity as varying smoothly between readings. step holds each value until the next x and then jumps, with a dot at each jump, filled where the value is taken and hollow where it is left; !endpoints drops the dots and risers draws the vertical joins. polygon takes linear and bezier.

slice: draws long-format data, one row per thing per moment, as the rows a parameter over that column holds: between two numeric values the line is interpolated, and over a column of names it shows the rows carrying the name picked.

error is each reading's uncertainty in y, written as a scatter's is: a half-width per reading, or the interval's two ends, error: #growth.lo .. #growth.hi. error-style draws it as a capped bar at every reading (bars, the default) or as a band washed between the ends, which reads as an interval round the whole series where a bar at every reading would be a comb. A reading with no entry breaks the band.

An orange line of mean seedling height rising over eight weeks, inside a faint orange band from the low to the high end of its 95% interval, which widens as the weeks go on.An orange line of mean seedling height rising over eight weeks, inside a faint orange band from the low to the high end of its 95% interval, which widens as the weeks go on.
graph{
    @data#growth{
        week | height | lo   | hi
        0    | 1.0    | 0.9  | 1.1
        1    | 1.8    | 1.6  | 2.0
        2    | 3.1    | 2.7  | 3.5
        3    | 4.6    | 4.0  | 5.2
        4    | 6.4    | 5.5  | 7.3
        5    | 8.0    | 6.8  | 9.2
        6    | 9.3    | 7.8  | 10.8
        7    | 10.1   | 8.4  | 11.8
        8    | 10.6   | 8.7  | 12.5
    }

    line(x: #growth.week; y: #growth.height; error: #growth.lo .. #growth.hi; error-style: band; colour: orange)
}(
    x axis label: week
    y axis label: height (cm)
)

#Attributes

On any plane
slice
The column this mark is SLICED by — long-format data, one row per thing per slice, showing the one the scene's parameter over that column holds. A column with a number line interpolates, so a reader stopped between two values sees half way; a column of names selects the rows carrying the name they picked.
colour
Colour of the path.
colour-along
Also written: color
Defaultpink
width
Stroke width.
width-along
Default2
style
How the path is drawn: solid, dashed or dotted. A function of the point it is at, so it may change along the line: style: x -> (..8: solid; 8..: dashed) dashes it from x = 8 on.
stroke-along
Defaultsolid
interpolateAnimatable
How the path gets from one reading to the next: linear joins them straight; bezier rounds the corners with a cubic through every reading, its handles at the middles of the legs either side, so it cannot overshoot; step holds each value until the next x and then jumps.
linearstepbezier
Also written: interpolation
Defaultlinear
step-endpoints
On a step, the endpoints at each jump: filled where the value is taken, hollow where it is left.
Defaulttrue
markersAnimatable
A marker at every reading, drawn as a scatter draws its own, so the line and the readings it joins are one mark. Each marker's look is set by marker-shape, marker-size, marker-colour and marker-opacity.
Defaultfalse
marker-shape
Each marker's shape — circle, square, rectangle, triangle, star, diamond, hexagon, cross or tick — a list reading by reading, or a map applied to a column or #self.value: marker-shape: #wheat.kind -> (measured: circle; projected: diamond).
shape-style
Defaultcircle
marker-size
Each marker's size, in the units a scatter's markers take: one size, a list reading by reading, or an expression giving one per reading.
size-style
Default6
marker-colour
Each marker's colour: one colour, a list reading by reading, or a map applied to a column or #self.value. Unwritten, each marker takes the line's own colour at its reading.
colour-style
Also written: marker-color
marker-opacity
How solid each marker is, 0 to 1: one opacity, a list reading by reading, or an expression giving one per reading.
opacity-style
Default1
risers
On a step, the vertical joins between treads.
Also written: connect
Defaultfalse
label
Text drawn beside the line — rich text, so $maths$ sets.
hiddenAnimatable
Declared and framed, but not drawn.
Defaultfalse
lock
A reader may not edit it on an editable graph.
Also written: locked
Defaultfalse
text-sizeAnimatable
Size of the label.
Default20
layerAnimatable
Paint order among the marks: a higher layer is drawn later, on top; equal or omitted, the marks stack in document order, later on top.
group
The groups this mark belongs to, comma-separated: group: Early sown, Projected. It is drawn in the colour of the first that has one and the style of the first the graph's key: gives one, unless it writes its own colour: or style, and the footer's key names every group.
Only withxyplane
xImplicitAnimatable
The x readings: numbers (0, 1, 2 — entries may be expressions of parameters), or a dataset column (#co2.year). A column of names reads against a categorical axis (x format:, or the axis’s auto rule); an ISO date column reads as fractional years (2024-03-15 → ≈2024.2), and auto labels them in years. Paired with y by position.
Can be written as shorthand: line:value
yAnimatable
The y readings, paired with x by position.
by
The column that says which path each reading belongs to — long data, one row per thing per reading — so one line draws a path for every value in it, in the order each is first met: line(y: #scores.school; x: #scores.score; by: #scores.school; markers) is a dumbbell chart, and line(x: #scores.term; y: #scores.score; by: #scores.school) a slope chart. Each reading keeps its row, so a style applied to a column reads the right one.
fold
On a graph with one axis of names, each path's readings step across the band at its name instead of lying along one line: a run to the second reading, a turn, a run to the third. Where the path doubles back the turn is a U whose far side is the reading, so a value is read where the path turns. With heads: end and a colour along the value axis, it is the switchback chart of a margin moving from one election to the next.
Defaultfalse
heads
An arrowhead at the line's start, its end, or both — the notched head a vector and a curve draw, its tip on the reading and the stroke stopped where it begins. A reading under a head takes no marker, and a leg shorter than the head takes a smaller one.
nonestartendboth
Defaultnone
errorAnimatable
Each reading's uncertainty in y: a half-width per reading, or the interval's two ends — error: #fit.lo .. #fit.hi — as a scatter's error: takes. Drawn as error-style: says.
error-styleAnimatable
How a line's error: is drawn: a capped bar at every reading, or a band washed between the low and high ends — the confidence band round a dense series, where a bar at every reading would be a comb. A reading with no error breaks the band.
barsband
Defaultbars
Only withargandplane
zAnimatable
On the argand plane, the readings as complex numbers: written out (1 + i, 2 - i, -3i, a bare number a real), or a column of complex literals bound whole (#roots.z). Instead of re/im.
reAnimatable
On the argand plane, the readings' real parts, one per reading — numbers written out or a column — paired with im by position.
imAnimatable
On the argand plane, the readings' imaginary parts, paired with re by position.
errorAnimatable
Each reading's uncertainty in y: a half-width per reading, or the interval's two ends — error: #fit.lo .. #fit.hi — as a scatter's error: takes. Drawn as error-style: says.
error-styleAnimatable
How a line's error: is drawn: a capped bar at every reading, or a band washed between the low and high ends — the confidence band round a dense series, where a bar at every reading would be a comb. A reading with no error breaks the band.
barsband
Defaultbars
Only withpolarplane
rAnimatable
On the polar plane, the readings' distances from the origin, paired with theta by position.
thetaAnimatable
On the polar plane, the readings' angles in radians (60deg for degrees), paired with r by position; names on a categorical theta.
Only withxyzplane
xImplicitAnimatable
The x readings: numbers (0, 1, 2 — entries may be expressions of parameters), or a dataset column (#co2.year). A column of names reads against a categorical axis (x format:, or the axis’s auto rule); an ISO date column reads as fractional years (2024-03-15 → ≈2024.2), and auto labels them in years. Paired with y by position.
Can be written as shorthand: line:value
yAnimatable
The y readings, paired with x by position.
zAnimatable
On the argand plane, the readings as complex numbers: written out (1 + i, 2 - i, -3i, a bare number a real), or a column of complex literals bound whole (#roots.z). Instead of re/im.

#Derived attributes

Computed while the element renders — read one with #id.name in attribute position or {{#id.name}} in prose, never set.

On any plane
valueDerived
Each reading's y, one per reading, which a marker's style attributes follow as #self.value: marker-colour: #self.value -> (..<0: red; 0..: teal).
Only withxyplane
maxDerived
The highest y among the line's readings on the ordinary plane, and the highest z in space, following a slider or a slice; a dash with no readings.
minDerived
The lowest y among the line's readings, or the lowest z in space; a dash where max is.
max-xDerived
The x of the first reading that reaches max; a dash where max is, or where the x axis holds names.
min-xDerived
The x of the first reading that reaches min; a dash where min is, or where the x axis holds names.
Only withxyzplane
maxDerived
The highest y among the line's readings on the ordinary plane, and the highest z in space, following a slider or a slice; a dash with no readings.
minDerived
The lowest y among the line's readings, or the lowest z in space; a dash where max is.

#Allowed in

#Examples

A pink line joining three points.A pink line joining three points.
graph{
    line(x: 0, 2, 4; y: 0, 2, 1; colour: pink)
}
A line drawn as a staircase through three points, flat and then rising at each one.A line drawn as a staircase through three points, flat and then rising at each one.
graph{
    line(x: 0, 1, 2; y: 0, 0.5, 1; interpolate: step)
}
Atmospheric CO₂ in parts per million rising every decade from 1960 to 2020.Atmospheric CO₂ in parts per million rising every decade from 1960 to 2020.
graph{
    line(x: #co2.year; y: #co2.ppm)
}
A pink line through six readings with a marker at each: circles below zero and diamonds above it, the markers in the line’s own colour.A pink line through six readings with a marker at each: circles below zero and diamonds above it, the markers in the line’s own colour.
graph{
    line(
        x: 0, 1, 2, 3, 4, 5
        y: -2, -1, 1, 0.5, 2, 3
        markers
        marker-shape: #self.value -> (..<0: circle; otherwise: diamond)
        marker-size: 8
    )
}
In space: a path through six readings, climbing as it winds round the z axis.In space: a path through six readings, climbing as it winds round the z axis.
graph:xyz{
    line(x: 2, 0, -2, 0, 2, 0; y: 0, 2, 0, -2, 0, 2; z: 0, 1, 2, 3, 4, 5; markers)
}(
    x domain: [-3, 3]
    y domain: [-3, 3]
    z domain: [0, 5]
)

#Writing guidance

  • 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