Framing a readable graph

#Authored and derived domains

An omitted domain is derived from the marks and then corrected: the tighter axis grows about its centre until one unit of x covers the same distance on screen as one unit of y. An authored domain is used exactly as written, aspect and all. The correction only ever grows an axis the graph derived, and it does not run at all where the units are not comparable — a categorical axis, a log axis, the number line.

#Shapes whose proportions carry meaning

A circle drawn on a frame whose axes are scaled differently is an oval, and the reader has no way to tell it from an oval the author meant. Where a shape carries meaning — a circle, a square, a right angle, any construction a reader is asked to see the geometry of — both domains are omitted, the correction runs, and the shape survives.

#Layouts that fill the frame

Where nothing turns on shape — annotated rows, labelled bands, a sequence laid out along an axis — both domains are authored, and the frame is exactly the window written. Authoring one and omitting the other is the case to avoid: the omitted axis is grown against the authored one, so the frame is neither the window asked for nor a corrected one.

#Padding a domain past the data

A domain is not widened to buy a margin. [-4, 54] for readings spanning 0 to 48 puts values the data never took into the axis gutter and crowds what is left. The honest bounds, or none at all. Room for a label at the end of a series is a different question, answered under Labels, clipping and the frame edge below.

#size and width as house style

The size and width defaults are the house style, and a mark that sets them stops matching every mark in the document that does not. The exception is where the attribute is the geometry rather than the weight: a square's size is half its side length and a circle's is its radius, so removing those removes the shape's dimensions.

#One declaration per mark

Each mark is declared once. To ring or dim around something a cue has already brought in, the cue.highlight or cue.spotlight nests inside that cue: neither changes whether its content is there, so the mark keeps the presence the outer cue gave it.

cue.draw{
    circle(x: 2; y: 3; colour: teal; label: P)

    cue.highlight{
        circle(x: 6; y: 1; colour: teal; label: Q)
    }(
        at: 2
        duration: 2s
    )
}(
    in: 1
    in duration: 1.2s
)

Two identical shapes — one drawn early, one faded in later beneath a highlight — is what this prevents: the same object is drawn twice, and the first copy stays under the second for the rest of the scene.

#Labels, clipping and the frame edge

A label is drawn beside or above its mark rather than inside it, and everything is clipped to the plot plus the clear air just outside it — enough for a marker standing on an edge, not enough for the words naming it. A mark on a domain boundary therefore has its label pushed into that margin, taking the position that escapes the picture by least. A labelled point at the end of a series wants the domain to run past the last reading rather than stop on it, which is room for a label rather than padding for its own sake.

Marks are spaced so that nothing overlaps, checked in the domain actually declared rather than the one the data suggests. Labels take the best free position in a ring around their mark, keeping off every other mark's ink as well as every other label, and step out to a second ring with a leader line back when the near positions are taken. Where nothing is free they overlap as little as they can — a label that is hard to read beats one that is not there, and a plot where that is happening is a plot with too much on it.

#Where a series label lands

A label is placed against its mark's anchor, and for line, polygon, scatter and bar that anchor is the mean of the readings, not a point on the mark. A series that runs flat and then jumps puts its mean in empty space; two series over the same x values put both means at the same x. The layout will move the words clear and draw a leader back to the nearest ink, but they still name the series from wherever the mean fell.

Where that reads badly, the series is named by a labelled point at a real vertex, chosen where the series are furthest apart, and the series itself carries no label:.

#Ticks the argument reads

!show background removes grid, axes and ticks together, and is the frame for a picture with no numeric axis to read. Short of that, ticks stay wherever a sentence asks the reader to read a value — comparing two rates, locating an intersection, introducing a function. A claim that it falls by the same amount each step cannot be checked without the scale, so the rule is audited against the paragraphs actually written rather than in the abstract.

Where the numbers are not part of the explanation, !show ticks drops them and axis.label names the values that are: it puts a name where the tick number would have gone, with line ruling it across the plot.

#One hue, one meaning

A hue means one thing for the length of a document. Teal as the standout reading in one environment cannot be the reference line in the next, and grey as the reference in one is grey as the reference in all of them. A colour is checked against every other environment in the document, not only against the plot being written.

An axis.label is chrome — it stands in for the tick it replaces — and keeps the neutral it defaults to unless its hue is doing semantic work, such as matching the one series it belongs to. A spare colour reached for so the name stands out puts a control into the register of the data, next to whatever the data hues already mean.