scatter
A set of readings drawn as markers.
On this page


#Writing the readings
A scatter takes one series per axis, paired by position: scatter(x: 1.2, 1.8, 2.6; y: 4.5, 6.2, 4.0). A series is numbers written out or a column bound whole — scatter(x: #islands.area; y: #islands.species) — and the two may be one of each. A pair either series cannot read is dropped whole, so the columns stay aligned. A column of names reads against an axis ruled in names, which auto rules from the names themselves; a column of ISO dates reads as fractional years. Where the axis is ruled in numbers, a name in the series is refused (canvas/series-not-numeric).
The series are the plane's coordinates: x alone on the number line, where the mark is a dot plot and dotplot is the same mark by another name; r and theta on the polar plane; re and im, or one complex z, on the argand plane; x, y and z in space. A scatter with an id is a sample other marks work from: fit fits the one it names.
#Laying out the markers
A scatter stands when its markers share a line: the number line's lane, the place one sample stands at with on:, or every name of an axis ruled in names when both coordinates are written (the graph page covers standing). layout arranges the markers across that line:
stack— equal readings pile up, so a column's height is its count.swarm— each marker, in the order of the readings, takes the nearest place across the line where it touches no other, so close readings spread as well as equal ones and the outline is the shape of the distribution. A swarm needing more room thanbandgives it draws every marker smaller, down to half the size asked for, and only then overlaps at its edge.jitter— each marker at a settled pseudo-random offset withinband, taken from the graph'sseed.none— every marker on the line.auto, the default —stackon the number line,swarmwhere the scatter shares its place with aboxplotof the same readings or stands on a plane, andnoneon a scatter that does not stand.
graph{
scatter(y: #births.mass; on: control)
}A scatter over two numeric axes stands nowhere, and stack and swarm are refused on it. jitter there nudges both coordinates, each by at most half the smallest gap between the values on its axis, scaled by band, so tied readings come apart without any marker reaching the place of a different reading. On the polar plane only auto and none are accepted.
#Colour, shape and size from the data
colour, shape, size and opacity are style attributes: each takes a look, a list with one look per marker in written order, or a reading applied with -> to a map, a ramp or an expression — #trial.status -> (event: teal; censored: red), set out in Styling marks from data. The reading is a column, or #self.value: each marker's reading, measured along the axis the readings are — the line a standing scatter is laid out along, x on the number line, y on an ordinary cloud. It is read from the reading, so a swarmed or jittered marker keeps its band, and each error bar takes its marker's colour. Band ends take a parameter, so a slider can move one. None of the four is animatable.
graph{
axis.label(x: 0; label: no change; colour: grey; line)
boxplot(x: #studies.impact; y: #studies.change; colour: grey)
scatter(x: #studies.impact; y: #studies.change; colour: #self.value -> (..<0: purple; 0..: pink))
}(
x axis label: change in impact
)A column of categories applied to a map draws one dataset in several looks: here each subject's last reading is a teal circle where the event was seen and a red cross where it was censored, one key entry each.


@data#trial{
id | time | status
1 | 6 | event
2 | 9 | censored
3 | 10 | event
4 | 13 | event
5 | 17 | censored
6 | 22 | event
7 | 25 | censored
8 | 32 | censored
}
graph{
@for(n: #trial; as: row){
segment(start: (0, {{row.id}}); end: ({{row.time}}, {{row.id}}); colour: neutral)
}
scatter(
x: #trial.time
y: #trial.id
colour: #trial.status -> (event: teal; censored: red)
shape: #trial.status -> (event: circle; censored: cross)
)
}(
x axis label: weeks
y axis label: subject
)shape takes the scatter's nine shapes: circle, square, rectangle, triangle, star, diamond, hexagon, cross and tick. A column of numbers is applied to bands, since nothing lies between a circle and a cross: shape: #trial.dose -> (..<5: circle; 5..: cross). The column alone is refused:
scatter(x: #trial.time; y: #trial.id; shape: #trial.dose)[attribute]node `scatter`: attribute `shape`: `#trial.dose`, row 1: `2` is not one of the allowed values: circle, square, rectangle, triangle, star, diamond, hexagon, cross, tick
The statistics pack's effect-strip draws the banded chart above with its baseline and both named sides.
#Error bars
error draws a capped bar through each marker along the axis its reading is measured on: up y on an ordinary cloud, along the line on the number line or a standing strip. Each entry is a half-width — an error of 0.3 on a reading of 4.2 spans 3.9 to 4.5 — paired with the readings by data row, or a column bound whole: scatter(x: #runs.t; y: #runs.mean; error: #runs.sd). Nothing is drawn where an entry is missing, and the frame grows to hold the caps. Each bar takes its marker's colour.
An interval that is not symmetric is written as its two ends: two columns joined by .., error: #trials.lo .. #trials.hi, or every entry as low..high, error: 0.61..1.10, 0.48..0.94. A confidence interval on a ratio arrives this way, and on a log axis it is uneven either side of its estimate:


graph{
@data#trials{
trial | ratio | lo | hi
Leeds | 0.82 | 0.61 | 1.10
Otago | 0.67 | 0.48 | 0.94
Utrecht | 0.91 | 0.72 | 1.15
Bergen | 0.74 | 0.50 | 1.09
Pooled | 0.79 | 0.69 | 0.91
}
axis.label(x: 1; label: no effect; colour: grey; line)
scatter(x: #trials.ratio; y: #trials.trial; error: #trials.lo .. #trials.hi; shape: square)
}(
x scale: log
x axis label: odds ratio
)error-x adds a second bar across an ordinary cloud's marker, for a reading uncertain in both coordinates, and is refused on a scatter that stands. Both are refused on the polar plane and in space (canvas/plane-attribute). bar, lollipop and line take error the same way.
#Attributes
slicebandboxplot's band: is a share of, so a box and its markers are measured against one thing. A swarm that needs more draws its markers smaller until it fits, one size for the whole mark and never below half the size asked for, and only then overlaps at its edge rather than spilling into the next name. On an ordinary cloud, the share of the half-gap jitter may nudge a marker by. Nothing to stack or none.0.8shape#self.value, the marker's reading on the axis the readings are measured along: shape: #trial.status -> (event: circle; otherwise: cross). Numbers are keyed by intervals, since nothing lies between one shape and the next. A marker no key holds, in a map with no otherwise, takes the default.shape-stylecirclesize#self.value. size: #cities.people -> 0..6 -> 4 + 20_ places each reading along 0 to 6 and draws it at 4 plus 20 times that place, so the sizes run from 4 to 24 in step with the readings; a map with a size per interval bands them.size-style6colour#self.value, the marker's reading. A map keyed by names gives categories, #trial.status -> (event: teal; otherwise: grey); one keyed by intervals gives bands, #self.value -> (..<0: purple; 0..: pink), an end written < left out of its band and an end may read a slider's letter; an interval then a ramp's name is a ramp, #weather.temp -> 10..30 -> temperature. A marker no key holds, in a map with no otherwise, takes the default. Each error bar takes its marker's colour.colour-stylecolorredopacityopacity: #trial.dose -> 0..10 -> 0.2 + 0.8_.opacity-style1label$maths$ and inline formatting render. Fades and draws with the element.hiddenhidden: true !cue.to{false}(at: 2) reveals it — and unlike a cue, a hidden element still frames the plot, so the axes do not jump when it appears.falselockeditable: graph. Nothing at all on a graph that is not editable.lockedfalselayerz: before the argand plane took that letter for its coordinate.groupgroup: Treated, Projected. It is drawn in the colour of the first group that has one, over its own colour:, and the footer's key names every group. A stroke the graph's key: gives a group does not change it.xplanex#islands.area). A column of names reads against an axis ruled in names; an ISO date column reads as fractional years. Paired with y by position; a pair either axis cannot read is dropped whole.scatter:valuelayoutstack piles equal readings, so a column's height is its count. swarm puts each marker, in reading order, at the nearest place across the line where it touches no other. jitter gives each marker a settled offset within band:, from the graph's seed:; on a scatter that does not stand it nudges both coordinates instead, by at most half the smallest gap between the values on each axis. none puts every marker on the line. auto, the default, is stack on the number line, swarm beside a boxplot of the same readings or wherever the scatter stands on a plane, and none on a scatter that does not stand. stack and swarm are refused on a scatter that stands nowhere, and everything but auto and none on the polar plane.autononestackswarmjitterautoerrorerror: #trials.lo .. #trials.hi, or each entry written out, 0.7..1.1, 0.8..1.3. One entry per reading, paired by data row, or a column bound whole. Nothing is drawn where an entry is missing, and the frame grows to hold the caps. Refused on the polar plane and in space.xyplanex#islands.area). A column of names reads against an axis ruled in names; an ISO date column reads as fractional years. Paired with y by position; a pair either axis cannot read is dropped whole.scatter:valueyx by position.onboxplot's on: takes. scatter(y: #trial.control; on: control) is the readings up the y axis, all standing at the name control on x, and a name there joins the axis's names. A boxplot with the same readings and the same on: shares the strip's slot. Refused on the number line, which has no second axis, and on a scatter that writes both coordinates, whose markers stand where their readings put them.layoutstack piles equal readings, so a column's height is its count. swarm puts each marker, in reading order, at the nearest place across the line where it touches no other. jitter gives each marker a settled offset within band:, from the graph's seed:; on a scatter that does not stand it nudges both coordinates instead, by at most half the smallest gap between the values on each axis. none puts every marker on the line. auto, the default, is stack on the number line, swarm beside a boxplot of the same readings or wherever the scatter stands on a plane, and none on a scatter that does not stand. stack and swarm are refused on a scatter that stands nowhere, and everything but auto and none on the polar plane.autononestackswarmjitterautoerrorerror: #trials.lo .. #trials.hi, or each entry written out, 0.7..1.1, 0.8..1.3. One entry per reading, paired by data row, or a column bound whole. Nothing is drawn where an entry is missing, and the frame grows to hold the caps. Refused on the polar plane and in space.error-xerror: is. Refused on a scatter that stands, where error: already runs along the readings.argandplanez1 + i, 2 - i, -3i, a bare number a real), or a column of complex literals bound whole (#roots.z). Instead of re/im.reim by position.imre by position.onboxplot's on: takes. scatter(y: #trial.control; on: control) is the readings up the y axis, all standing at the name control on x, and a name there joins the axis's names. A boxplot with the same readings and the same on: shares the strip's slot. Refused on the number line, which has no second axis, and on a scatter that writes both coordinates, whose markers stand where their readings put them.layoutstack piles equal readings, so a column's height is its count. swarm puts each marker, in reading order, at the nearest place across the line where it touches no other. jitter gives each marker a settled offset within band:, from the graph's seed:; on a scatter that does not stand it nudges both coordinates instead, by at most half the smallest gap between the values on each axis. none puts every marker on the line. auto, the default, is stack on the number line, swarm beside a boxplot of the same readings or wherever the scatter stands on a plane, and none on a scatter that does not stand. stack and swarm are refused on a scatter that stands nowhere, and everything but auto and none on the polar plane.autononestackswarmjitterautoerrorerror: #trials.lo .. #trials.hi, or each entry written out, 0.7..1.1, 0.8..1.3. One entry per reading, paired by data row, or a column bound whole. Nothing is drawn where an entry is missing, and the frame grows to hold the caps. Refused on the polar plane and in space.error-xerror: is. Refused on a scatter that stands, where error: already runs along the readings.polarplanexyzplanex#islands.area). A column of names reads against an axis ruled in names; an ISO date column reads as fractional years. Paired with y by position; a pair either axis cannot read is dropped whole.scatter:valueyx by position.z1 + i, 2 - i, -3i, a bare number a real), or a column of complex literals bound whole (#roots.z). Instead of re/im.layoutstack piles equal readings, so a column's height is its count. swarm puts each marker, in reading order, at the nearest place across the line where it touches no other. jitter gives each marker a settled offset within band:, from the graph's seed:; on a scatter that does not stand it nudges both coordinates instead, by at most half the smallest gap between the values on each axis. none puts every marker on the line. auto, the default, is stack on the number line, swarm beside a boxplot of the same readings or wherever the scatter stands on a plane, and none on a scatter that does not stand. stack and swarm are refused on a scatter that stands nowhere, and everything but auto and none on the polar plane.autononestackswarmjitterauto#Derived attributes
Computed while the element renders — read one with #id.name in attribute position or {{#id.name}} in prose, never set.
value#self.value: colour: #self.value -> (..<0: purple; 0..: pink).countxplanemeanon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with no readings.medianon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with no readings.modesdon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with fewer than two readings.minmaxrangeq1q2q3iqrxyplanemeanon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with no readings.medianon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with no readings.modesdon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with fewer than two readings.minmaxrangeq1q2q3iqrx-meanx-medianx-modex-sdx-minx-maxx-rangex-q1x-q2x-q3x-iqry-meany-mediany-modey-sdy-miny-maxy-rangey-q1y-q2y-q3y-iqrcorrelationargandplanemeanon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with no readings.medianon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with no readings.modesdon:, or a column of names holding one name — and a dash at several names, on a cloud of pairs, or with fewer than two readings.minmaxrangeq1q2q3iqrre-meanre-medianre-modere-sdre-minre-maxre-rangere-q1re-q2re-q3re-iqrim-meanim-medianim-modeim-sdim-minim-maxim-rangeim-q1im-q2im-q3im-iqrcorrelationxyzplanex-meanx-medianx-modex-sdx-minx-maxx-rangex-q1x-q2x-q3x-iqry-meany-mediany-modey-sdy-miny-maxy-rangey-q1y-q2y-q3y-iqrz-meanz-medianz-modez-sdz-minz-maxz-rangez-q1z-q2z-q3z-iqr#Allowed in
#Examples


graph{
scatter(x: 0, 1, 2; y: 0, 2, 1)
}

graph{
scatter(x: #studies.change; y: #studies.impact; layout: swarm)
}

graph{
scatter(x: #studies.change; y: #studies.impact; colour: #self.value -> (..<0: purple; 0..: pink))
}

graph:xyz{
scatter(x: {{xs}}; y: {{ys}}; z: {{zs}})
surface(expression: 1 + 0.6x - 0.4y; colour: grey; opacity: 0.2)
}(
x domain: [-3, 3]
y domain: [-3, 3]
z domain: [-4, 6]
)