6 Panels
A plot can be one set of axes or a grid of them, and which you get is never chosen directly. A pose draws one panel, however many layers it holds and whatever columns they name. More panels come from pj/facet, which splits a pose’s one panel, and pj/arrange, which places poses side by side.
Two things to compare are either two columns or two categories of one column, and they are drawn either inside one panel or in panels of their own. The table names the form that draws each combination:
| inside one panel | across panels | |
|---|---|---|
| two columns | a series, {:x [:height :depth]} |
a facet over columns, (pj/facet pose {:x [...]}), or pj/arrange |
| two categories | an aesthetic, {:color :species} |
a facet over categories, (pj/facet pose :species) |
A series is drawn by pivoting its columns into a key column, :series, mapped to :color, so two columns on one panel are drawn as two categories are: a color and a legend entry each. Series teaches the series, and Color and Grouping the :color aesthetic. This chapter shows the forms in the across-panels column of the table, and how they combine. Faceting and Composition teach each in depth.
Read Poses first for what a leaf is.
(ns plotje-book.panels
(:require
;; Kindly -- notebook rendering protocol
[scicloj.kindly.v4.kind :as kind]
;; Plotje -- composable plotting
[scicloj.plotje.api :as pj]))(def measurements
{:height [1 2 3 4]
:weight [1 2 3 4]
:depth [1.6 2.3 3.4 4.7]
:species ["a" "a" "b" "b"]})The panel of a leaf pose
A pose built from one dataset with one mapping is a single leaf, and draws a single panel:
(-> measurements
(pj/lay-point :height :weight))Adding a layer does not add a panel. The layers of a pose share its axes and are drawn over one another:
(-> measurements
(pj/lay-point :height :weight)
(pj/lay-line :height :weight))A layer naming other columns adds no panel either. The layer’s columns are drawn against the axes the panel already has, each axis covers every column drawn on it and is titled by all of them, and each layer takes a color and a legend entry naming its columns:
(-> measurements
(pj/lay-point :height :weight)
(pj/lay-point :depth :weight))How the color of each layer is decided – a color it specifies, a :color on the pose, or a layer colored by a column – is in Pose Rules, and Inference Rules shows a color specified on each layer and a layer colored by a column.
The panel’s columns
A pj/lay-* call keeps its columns on its own layer, so a pose built by such calls has no mapping of its own. The panel still has columns: on each axis, the column the pose names, and where the pose names none there, the column of the first layer that names one. A layer that names no columns reads both of the panel’s columns:
(-> measurements
(pj/lay-point :height :weight)
pj/lay-smooth)The layer that names no columns may be written first. A pj/lay-* call does not read the data’s columns when it is called; the layer is given its columns when the pose is drawn, so a later call may name them:
(-> measurements
pj/lay-smooth
(pj/lay-point :height :weight))A layer that names one column reads the panel’s column on the other axis, where its layer type draws from two columns. The line below names :depth on :y and is drawn against the panel’s :height:
(-> measurements
(pj/lay-point :height :weight)
(pj/lay-line {:y :depth}))A layer type that can draw from one column is not given a second column. A rug draws from one column, so the rug below marks :depth along the :x axis and reads no :y:
(-> measurements
(pj/lay-point :height :weight)
(pj/lay-rug {:x :depth}))A panel per column
To draw the two columns apart, split the pose over them with pj/facet. Each layer naming one of the columns is drawn only in that column’s panel:
(-> measurements
(pj/lay-point :height :weight)
(pj/lay-point :depth :weight)
(pj/facet {:x [:height :depth]}))The cells of a facet over columns are made from the panel’s columns, and the facet replaces the column on the axis it names. Below, the line layer names :weight, so it is drawn in the :weight panel. The :depth panel keeps the panel’s :height on :x. No layer names :depth, so that panel draws the layer type inferred from :height and :depth, a scatter, and not the line:
(-> measurements
(pj/lay-line :height :weight)
(pj/facet {:y [:weight :depth]}))Where one layer is meant for every column, name the columns in the facet alone. The panels share the axis they agree about, :weight, and title it once:
(-> measurements
(pj/pose {:y :weight})
pj/lay-point
(pj/facet {:x [:height :depth]}))A matrix of columns
A facet over columns can cross a list of columns with itself: {:col {:x columns} :row {:y columns}} draws a panel for every pair of columns, the columns across drawn on :x and the same columns down drawn on :y. A layer naming no columns, added after it, is drawn in the panels that draw as many columns as its layer type reads – a point reads two, so it is drawn off the diagonal. A panel with the same column on both axes draws one column, and draws the layer type inferred for one column, a histogram:
(-> measurements
(pj/facet {:col {:x [:height :weight :depth]}
:row {:y [:height :weight :depth]}})
pj/lay-point)pj/matrix writes that facet from the list of columns:
(-> measurements
(pj/matrix [:height :weight :depth])
pj/lay-point)A panel per category
A facet over the categories of a column draws one panel per category, each drawing the rows of its category. Two species give two panels:
(-> measurements
(pj/lay-point :height :weight)
(pj/facet :species))The panels share both axes, so the categories can be read against each other: species “a” spans 1 to 2 on :height and species “b” 3 to 4, and both panels run from below 1 to above 4.
Many categories make a long row of panels. {:cols n} wraps them into rows of n panels, as in (pj/facet pose :class {:cols 4}) – see Wrapping the panels into rows.
Arranging poses side by side
pj/arrange takes finished poses and makes each one a cell of a single composite:
(pj/arrange [(pj/lay-point measurements :height :weight)
(pj/lay-point measurements :depth :weight)])Each pose above carries the dataset, so each cell computes its own axes and titles weight beside its own panel. Given the dataset first, pj/arrange makes its cells parts of one dataset. Cells that draw the same column on an axis then share that axis, titled once beside the grid, as the panels of a facet are:
(-> (pj/arrange measurements [{:x :height :y :weight}
{:x :depth :y :weight}])
pj/lay-point)Composition gives the rule for which cells share an axis, and how :share-scales changes it.
A pj/lay-* call on an arrangement adds its layer at the root of the composite. The layer is drawn in the cells it fits: the cells whose columns agree with the columns the layer names, and whose number of columns the layer type can draw – two for a scatter or a trend line, one for a histogram. Rule LP2 in Pose Rules states the rule exactly. In the arrangement above, pj/lay-point names no columns, and each cell draws two, so the points are drawn in every cell. Here the line of :weight against :depth is drawn in the second cell only:
(-> (pj/arrange measurements [{:x :height :y :weight}
{:x :depth :y :weight}])
pj/lay-point
(pj/lay-line :depth :weight))A call naming one column, of a layer type that draws from two columns, is drawn in every cell that draws the same column on that axis, or none, and reads the cell’s column on the other axis, as on a leaf.
Where no cell fits the layer, the layer is drawn in every cell, beside each cell’s own layers, as the layers of a single pose share its panel. A histogram reads one column, so beside cells that draw two columns it fits no cell, and it is drawn over the points of every cell. Each cell’s :y axis then reads a count beside a column, and drawing the plot prints a Note for each cell saying so:
(-> (pj/arrange measurements [{:x :height :y :weight}
{:x :depth :y :weight}])
pj/lay-point
(pj/lay-histogram :height))A pj/lay-* call never adds a cell. A histogram meant for a cell of its own is given that cell with pj/arrange, which adds the cells it is given to the arrangement’s list:
(-> (pj/arrange measurements [{:x :height :y :weight}
{:x :depth :y :weight}])
pj/lay-point
(pj/arrange [:height]))A cell may also be a template – a pose with layers and no data, as Reusable Pose Templates describes. When pj/arrange is given data first, the template cell draws from the arrangement’s data. Here a cell with layers of its own sits beside a cell drawn by inference:
(pj/arrange measurements [(-> (pj/lay-point nil :height :weight)
(pj/lay-smooth {:stat :linear-model}))
{:x :depth :y :weight}])A layer added at the root is drawn under a cell’s own layers, whatever order the calls come in. Below, the line added to the arrangement is drawn beneath the first cell’s points:
(-> (pj/arrange measurements [(pj/lay-point nil :height :weight)
{:x :depth :y :weight}])
pj/lay-line)A composite pose can also be written directly, which Composition covers. It is the same structure pj/arrange builds.
Cells that filter the data
A cell of pj/arrange may hold :where, a map from a column to a value, and draws only the rows that match. A cell is written as the argument after the data in pj/pose is written, so the cell {:where {:species "a"}} is read as it is read in (pj/pose nil {:where {:species "a"}}). Cells that split one dataset by the values of one column draw what pj/facet draws over that column:
(-> measurements
(pj/pose {:x :height :y :weight})
(pj/arrange [{:where {:species "a"}}
{:where {:species "b"}}])
pj/lay-point)A layer naming columns is drawn in every cell that splits the data, as it is drawn in every panel of the facet. A line of :weight against :height added to the cells above draws a line in each cell:
(-> measurements
(pj/pose {:x :height :y :weight})
(pj/arrange [{:where {:species "a"}}
{:where {:species "b"}}])
pj/lay-point
(pj/lay-line :height :weight))The Facet or Arrange section of Faceting compares a facet with cells that filter the data, and Pose Rules says how a filter on the pose combines with a cell’s.
Combining facets and arrangements
Columns and categories cross in one pj/facet call, the categories across and the columns down. Each entry under :col and :row is one of the two kinds of facet, as in the matrix above:
(-> measurements
(pj/pose {:x :height})
pj/lay-point
(pj/facet {:col :species :row {:y [:weight :depth]}}))Two pj/facet calls, one over the categories and one over the columns, write the same grid, in either order:
(-> measurements
(pj/pose {:x :height})
pj/lay-point
(pj/facet {:y [:weight :depth]})
(pj/facet :species)):col and :row are the panel aesthetics: they decide which panel a row is drawn in, rather than how a mark looks (see Aesthetic). A mapping on an arranged pose reaches every cell, so a facet written on an arranged pose reaches every cell:
(-> (pj/arrange [(pj/pose measurements :height :weight)
(pj/pose measurements :depth :weight)])
(pj/lay-point)
(pj/facet :species))What’s Next
- Specifying Aesthetics – the next chapter: how to write what a mapping means – where its values come from, and whether a scale reads them
See Also
Poses – leaf and composite poses
Composition – arranging poses, shared scales, and the patterns built from them
Faceting – faceting in practice, including grids of two columns
Pose Rules – the rules that decide where a
pj/lay-*call’s layer goes
source: notebooks/plotje_book/panels.clj