Appendix A — The kernel card

The whole grammar, on one page. The table below is the kernel, the list of every word in the grammar. Each word is an atom, and the operators join atoms into a sentence that describes a plot. The table is copied from The kernel each time the book is built, so it always matches that chapter. Functions you never write into a sentence, such as render_svg(), are in Functions around the grammar.

Kind	The words
Sources	data query
Marks	point line area bar step interval box ribbon text path rule zone surface edge
Channels	x y z color size shape pattern opacity group label play
Transforms	bin smooth straight count density proportion sum mean median max min quantile cumulative range confidence deviation smooth_band straight_band bounds partition flow layout cluster, and the four collision modifiers, dodge stack jitter repel
Operators	+ layers, * derives, | and / arrange
Scales	linear log time category order
Spaces	flat space polar nest map globe network
Settings	style theme palette
Labels	title subtitle caption x_label y_label z_label
Facets	facet
Selections	brush

The minimum sentence is a source, a mark, and the position channels that mark needs:

data(table) + mark + x(column) + y(column)

The order of + matters in a few places only. Each mark starts a layer: the mark, and the channels and settings that apply to it. In a plot with one mark, the mark and its channels may be written in any order. This book usually writes a sentence as data, mark, positions, refinements, where the refinements are the optional parts, such as color and title. Only two parts of the order are rules. A sentence must start with a source (data() or query()), and a style() needs a mark before it. The engine refuses a sentence that breaks either rule.

What the order does change is which marks each channel or table applies to, and which mark is drawn on top. A channel written before any mark applies to every layer that can accept it, and this book writes a channel there when every layer should use it. A channel such as color, written after a mark, belongs to that mark alone. Positions are the exception: a mark with no x or y of its own reads the first ones written. Each later data() applies to the mark written directly after it, and a style() styles the nearest mark before it. Two marks draw in the order you wrote them, so the second is drawn on top of the first. Which orders matter and Encoding scope have the rules in full.

Deriving is what * does: it joins a transform to a mark, and the mark is always on the left. More than one transform can follow one mark: bar * bin * mean cuts the x axis into bands, then averages y inside each band. Transforms on one mark must each do a different job, and each job is done at its own step. So the order you write them in does not change the picture, and writing them in the order they happen is the convention. Chaining transforms names the four jobs.

Precedence is the order in which a language groups its operators. In R and Python, * and / group first, then +, then |. Julia groups | together with +, from left to right. JavaScript spells the operators as words, so it has no precedence to remember. In every language, one plot needs no parentheses, even with a facet: data(table) + bar * bin + x(a) | facet(g).

Two whole plots joined by | or / make an arrangement. In an arrangement, put each plot inside its own parentheses: (…) / (…). Without them, / groups before + and joins the first plot’s last atom to the second plot’s data(), and gog refuses that sentence. Put parentheses around an arrangement inside an arrangement too: ((…) | (…)) / (…). Put them around a whole arrangement before you add a theme() to it. What groups first gives the order in each language, and Parentheses in an arrangement shows what that order does to an arrangement.

When gog refuses, the message names the rule, and says what to write instead. Illegal means the grammar forbids the sentence you wrote: rewrite it. Unsupported means the grammar allows it and this engine does not draw it: remove the atom the message names, or use one this engine draws. Illegal is not the same as unsupported has the rule, and a refusal of each kind, printed by the engine when the book is built.

When gog assumes instead of refusing, the plot still draws. The message is an Assumption: it says what gog decided for you. Read it, and check that the decision was what you meant.