5 Core Concepts
The vocabulary you reach for daily: data, mappings, scope, layer types, and how they fit together. This chapter takes the mental model from Poses and turns it into a working reference you can scan while building a plot.
Read Poses first if you have not β this chapter builds on the pose vocabulary it introduces.
(ns plotje-book.core-concepts
(:require
;; Tablecloth -- dataset manipulation
[tablecloth.api :as tc]
;; Kindly -- notebook rendering protocol
[scicloj.kindly.v4.kind :as kind]
;; Plotje -- composable plotting
[scicloj.plotje.api :as pj]
;; Rdatasets -- standard datasets
[scicloj.metamorph.ml.rdatasets :as rdatasets]))Data
Plotje accepts plain Clojure data β maps, vectors of maps β or columnar datasets. No wrapping needed for simple cases. The Datasets chapter covers data formats and loading in detail.
We use the classic iris flower dataset throughout these examples. Each column has a name (a keyword like :sepal-length) and holds values of one type.
(rdatasets/datasets-iris)https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [150 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|---|---|---|---|---|---|
| 1 | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 2 | 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 3 | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4 | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 6 | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 7 | 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 8 | 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 9 | 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 10 | 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| β¦ | β¦ | β¦ | β¦ | β¦ | β¦ |
| 140 | 6.9 | 3.1 | 5.4 | 2.1 | virginica |
| 141 | 6.7 | 3.1 | 5.6 | 2.4 | virginica |
| 142 | 6.9 | 3.1 | 5.1 | 2.3 | virginica |
| 143 | 5.8 | 2.7 | 5.1 | 1.9 | virginica |
| 144 | 6.8 | 3.2 | 5.9 | 2.3 | virginica |
| 145 | 6.7 | 3.3 | 5.7 | 2.5 | virginica |
| 146 | 6.7 | 3.0 | 5.2 | 2.3 | virginica |
| 147 | 6.3 | 2.5 | 5.0 | 1.9 | virginica |
| 148 | 6.5 | 3.0 | 5.2 | 2.0 | virginica |
| 149 | 6.2 | 3.4 | 5.4 | 2.3 | virginica |
| 150 | 5.9 | 3.0 | 5.1 | 1.8 | virginica |
The dataset has 150 rows and 6 columns: a :rownames index plus four numerical measurements (in centimeters) and one categorical column (the species name β one of three strings).
Plotje treats numerical and categorical columns differently when choosing axes, colors, and statistical transforms.
Here is a scatter plot of sepal dimensions, colored by species:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
(pj/lay-point {:color :species}))Printed, the pose carries the data and the mapping of :x and :y at the top, and one point layer with its own layer-scoped :color:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
(pj/lay-point {:color :species})
kind/pprint){:mapping {:x :sepal-length, :y :sepal-width},
:layers [{:layer-type :point, :mapping {:color :species}}],
:data
https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [150 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|----------:|--------------:|-------------:|--------------:|-------------:|-----------|
| 1 | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 2 | 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 3 | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4 | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 6 | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 7 | 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 8 | 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 9 | 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 10 | 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| ... | ... | ... | ... | ... | ... |
| 140 | 6.9 | 3.1 | 5.4 | 2.1 | virginica |
| 141 | 6.7 | 3.1 | 5.6 | 2.4 | virginica |
| 142 | 6.9 | 3.1 | 5.1 | 2.3 | virginica |
| 143 | 5.8 | 2.7 | 5.1 | 1.9 | virginica |
| 144 | 6.8 | 3.2 | 5.9 | 2.3 | virginica |
| 145 | 6.7 | 3.3 | 5.7 | 2.5 | virginica |
| 146 | 6.7 | 3.0 | 5.2 | 2.3 | virginica |
| 147 | 6.3 | 2.5 | 5.0 | 1.9 | virginica |
| 148 | 6.5 | 3.0 | 5.2 | 2.0 | virginica |
| 149 | 6.2 | 3.4 | 5.4 | 2.3 | virginica |
| 150 | 5.9 | 3.0 | 5.1 | 1.8 | virginica |
}Input formats
Plotje accepts several common Clojure data shapes and coerces them into a dataset internally.
Map of columns β keys are column names, values are sequences:
(-> {:height [1 2 3 4 5]
:weight [2 4 3 5 4]}
(pj/lay-point :height :weight))Sequence of row maps β each map is one row:
(-> [{:city "Paris" :temperature 22}
{:city "London" :temperature 18}
{:city "Berlin" :temperature 20}
{:city "Rome" :temperature 28}]
(pj/lay-bar :city :temperature))Sequence of row vectors β each vector is one row, and the columns are named by their place: 0, 1 and so on. Nothing has to be wrapped first:
(-> [[1 2] [3 4] [5 7]]
pj/lay-point)[nREPL-session-c9b9fae5-165f-478a-a03b-662df66eca10] WARN tablecloth.api.dataset - Dataset creation behaviour changed for 2d 2-element arrays in v7.029. See https://github.com/scicloj/tablecloth/issues/142 for details.
Those integer names are what the axes are titled with, and they can be mapped like any other column name. (tc/rename-columns ds [:height :weight]) gives them words. A vector of vectors given to pj/arrange means something else β rows of cells, each cell a column, a mapping or a pose. Where the vector is written decides which it is: given as the data, it is rows of values, and in pj/arrangeβs list of cells, it is rows of cells. What the vector holds does not decide it.
When the dataset has 1, 2, or 3 columns, you can omit the column names entirely β they are inferred from the order of the columns: the first column becomes x, the second becomes y, the third becomes color. Here the first column is :weight, so :weight is on the x axis:
(-> {:weight [1 2 3 4 5] :height [2 4 3 5 4]}
pj/lay-point)With four or more columns no column is read by default: name the columns, in the pj/lay-* call or in pj/pose. See the Datasets chapter for loading from CSV, URLs, and other file formats.
Mappings and Layers
The Poses chapter introduced the split between mappings and layers: a mapping says what is drawn, and a layer says how. This section is the practical follow-up: how the split plays out across multi-layer plots, and in explicit and shorthand calls.
Declare a mapping once with pj/pose, then add layers with pj/lay-* β both layers share the same axes:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
pj/lay-point
(pj/lay-smooth {:stat :linear-model}))One mapping, two layers: points and a regression line.
When pj/lay-* is called with columns, it creates a pose and attaches a layer in one step:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width))We will revisit where mappings flow (to all layers or to a single one) in the Scope section below.
With multiple poses arranged side by side, use pj/arrange:
(def two-panel
(pj/arrange
[(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width))
(-> (rdatasets/datasets-iris)
(pj/lay-point :petal-length :petal-width))]))two-panelEach sub-pose has its own data and layers, and here each layer names its own columns. pj/arrange produces a composite pose that contains the two sub-poses as siblings.
Scope
A mapping maps a column (or a written value) to a visual property β like mapping :species to color. Where you write a mapping determines which layers read it. There are two levels:
| Where you write it | Which layers it reaches |
|---|---|
(pj/pose ... {:color :c}) |
All layers on this pose |
(pj/lay-point ... {:color :c}) |
This layer only |
This is lexical scope β the closest enclosing definition wins.
Pose-level mapping
pj/poseβs mapping flows to every layer attached to the pose:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width {:color :species})
pj/lay-point
(pj/lay-smooth {:stat :linear-model}))Both point and smooth layers read :color :species. Three regression lines β one per species.
Layer-level mapping
A mapping in pj/lay-* scopes to that layer alone:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
(pj/lay-point {:color :species})
(pj/lay-smooth {:stat :linear-model}))Printed, :color lives on the point layerβs own :mapping, not on the pose β so only the point layer reads it:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
(pj/lay-point {:color :species})
(pj/lay-smooth {:stat :linear-model})
kind/pprint){:mapping {:x :sepal-length, :y :sepal-width},
:layers
[{:layer-type :point, :mapping {:color :species}}
{:layer-type :smooth, :stat :linear-model}],
:data
https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [150 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|----------:|--------------:|-------------:|--------------:|-------------:|-----------|
| 1 | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 2 | 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 3 | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4 | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 6 | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 7 | 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 8 | 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 9 | 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 10 | 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| ... | ... | ... | ... | ... | ... |
| 140 | 6.9 | 3.1 | 5.4 | 2.1 | virginica |
| 141 | 6.7 | 3.1 | 5.6 | 2.4 | virginica |
| 142 | 6.9 | 3.1 | 5.1 | 2.3 | virginica |
| 143 | 5.8 | 2.7 | 5.1 | 1.9 | virginica |
| 144 | 6.8 | 3.2 | 5.9 | 2.3 | virginica |
| 145 | 6.7 | 3.3 | 5.7 | 2.5 | virginica |
| 146 | 6.7 | 3.0 | 5.2 | 2.3 | virginica |
| 147 | 6.3 | 2.5 | 5.0 | 1.9 | virginica |
| 148 | 6.5 | 3.0 | 5.2 | 2.0 | virginica |
| 149 | 6.2 | 3.4 | 5.4 | 2.3 | virginica |
| 150 | 5.9 | 3.0 | 5.1 | 1.8 | virginica |
}Color is on the point layer. The smooth layer does not read it β one overall regression line.
Override
Lower scopes override higher ones. A layer can cancel a mapping by setting it to nil:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width {:color :species})
(pj/lay-point {:color nil})
(pj/lay-smooth {:stat :linear-model}))Printed, the override appears as :color nil in the point layerβs own :mapping, erasing the pose-level color for that layer only:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width {:color :species})
(pj/lay-point {:color nil})
(pj/lay-smooth {:stat :linear-model})
kind/pprint){:mapping {:color :species, :x :sepal-length, :y :sepal-width},
:layers
[{:layer-type :point, :mapping {:color nil}}
{:layer-type :smooth, :stat :linear-model}],
:data
https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [150 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|----------:|--------------:|-------------:|--------------:|-------------:|-----------|
| 1 | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 2 | 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 3 | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4 | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 6 | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 7 | 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 8 | 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 9 | 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 10 | 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| ... | ... | ... | ... | ... | ... |
| 140 | 6.9 | 3.1 | 5.4 | 2.1 | virginica |
| 141 | 6.7 | 3.1 | 5.6 | 2.4 | virginica |
| 142 | 6.9 | 3.1 | 5.1 | 2.3 | virginica |
| 143 | 5.8 | 2.7 | 5.1 | 1.9 | virginica |
| 144 | 6.8 | 3.2 | 5.9 | 2.3 | virginica |
| 145 | 6.7 | 3.3 | 5.7 | 2.5 | virginica |
| 146 | 6.7 | 3.0 | 5.2 | 2.3 | virginica |
| 147 | 6.3 | 2.5 | 5.0 | 1.9 | virginica |
| 148 | 6.5 | 3.0 | 5.2 | 2.0 | virginica |
| 149 | 6.2 | 3.4 | 5.4 | 2.3 | virginica |
| 150 | 5.9 | 3.0 | 5.1 | 1.8 | virginica |
}The pose says :color :species. The point layer cancels it with nil β uncolored points. The smooth layer has no override, so it keeps the pose-level color β three lines.
How scope is applied
The same scoping principle governs mappings, layers, data, row filters and plot options. Where two values for one key meet β a later pj/pose on the same pose, a layer under its pose, a cell under its composite β they combine the same way at every level. A key holds either one value, which the later or inner value replaces, or a map of independent settings, which combines key by key:
Mappings: pose and layer mappings merge; the innermost wins on conflict, and an explicit
nilerases a mapping inherited from above. The one part that combines rather than being replaced is a mappingβs:scale: a scale set on a pose and a scale set on one of its layers combine key by key, and so do two scales thatpj/posewrites into a pose that already has a mapping β see Scales.Row filters: two
:wheremaps combine column by column; a column named in both takes the later or inner value. See Pose Rules.Plot options: the later or inner value wins, except
:themeand:config, whose settings combine key by key.Layers: every
pj/lay-*adds a new layer; layers do not override one another.Data: the first argument to
pj/pose/pj/lay-*sets the pose-level dataset; writing:datain a layerβs mapping overrides it for that layer alone (innermost non-nil wins).
A series is the one mapping that reaches past its layer. A vector of columns written where one column goes, as in (pj/lay-line data :month [:rain :snow]), is drawn by reshaping the poseβs dataset into one row per column and value, and every layer of the pose reads the reshaped rows β see Series.
Layer-level data
Write :data in the mapping of pj/lay-* to give that layer its own dataset:
(def setosa
(tc/select-rows (rdatasets/datasets-iris)
#(= "setosa" (:species %))))(def versicolor
(tc/select-rows (rdatasets/datasets-iris)
#(= "versicolor" (:species %))))(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
(pj/lay-point {:data setosa})
(pj/lay-smooth {:stat :linear-model :data versicolor}))Printed, each layer carries its own :data alongside its :mapping; the pose-level :data remains as a default for any layer that does not override it:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
(pj/lay-point {:data setosa})
(pj/lay-smooth {:stat :linear-model :data versicolor})
kind/pprint){:mapping {:x :sepal-length, :y :sepal-width},
:layers
[{:layer-type :point,
:data
https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [50 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|----------:|--------------:|-------------:|--------------:|-------------:|----------|
| 1 | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 2 | 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 3 | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4 | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 6 | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 7 | 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 8 | 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 9 | 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 10 | 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| ... | ... | ... | ... | ... | ... |
| 40 | 5.1 | 3.4 | 1.5 | 0.2 | setosa |
| 41 | 5.0 | 3.5 | 1.3 | 0.3 | setosa |
| 42 | 4.5 | 2.3 | 1.3 | 0.3 | setosa |
| 43 | 4.4 | 3.2 | 1.3 | 0.2 | setosa |
| 44 | 5.0 | 3.5 | 1.6 | 0.6 | setosa |
| 45 | 5.1 | 3.8 | 1.9 | 0.4 | setosa |
| 46 | 4.8 | 3.0 | 1.4 | 0.3 | setosa |
| 47 | 5.1 | 3.8 | 1.6 | 0.2 | setosa |
| 48 | 4.6 | 3.2 | 1.4 | 0.2 | setosa |
| 49 | 5.3 | 3.7 | 1.5 | 0.2 | setosa |
| 50 | 5.0 | 3.3 | 1.4 | 0.2 | setosa |
}
{:layer-type :smooth,
:stat :linear-model,
:data
https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [50 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|----------:|--------------:|-------------:|--------------:|-------------:|------------|
| 51 | 7.0 | 3.2 | 4.7 | 1.4 | versicolor |
| 52 | 6.4 | 3.2 | 4.5 | 1.5 | versicolor |
| 53 | 6.9 | 3.1 | 4.9 | 1.5 | versicolor |
| 54 | 5.5 | 2.3 | 4.0 | 1.3 | versicolor |
| 55 | 6.5 | 2.8 | 4.6 | 1.5 | versicolor |
| 56 | 5.7 | 2.8 | 4.5 | 1.3 | versicolor |
| 57 | 6.3 | 3.3 | 4.7 | 1.6 | versicolor |
| 58 | 4.9 | 2.4 | 3.3 | 1.0 | versicolor |
| 59 | 6.6 | 2.9 | 4.6 | 1.3 | versicolor |
| 60 | 5.2 | 2.7 | 3.9 | 1.4 | versicolor |
| ... | ... | ... | ... | ... | ... |
| 90 | 5.5 | 2.5 | 4.0 | 1.3 | versicolor |
| 91 | 5.5 | 2.6 | 4.4 | 1.2 | versicolor |
| 92 | 6.1 | 3.0 | 4.6 | 1.4 | versicolor |
| 93 | 5.8 | 2.6 | 4.0 | 1.2 | versicolor |
| 94 | 5.0 | 2.3 | 3.3 | 1.0 | versicolor |
| 95 | 5.6 | 2.7 | 4.2 | 1.3 | versicolor |
| 96 | 5.7 | 3.0 | 4.2 | 1.2 | versicolor |
| 97 | 5.7 | 2.9 | 4.2 | 1.3 | versicolor |
| 98 | 6.2 | 2.9 | 4.3 | 1.3 | versicolor |
| 99 | 5.1 | 2.5 | 3.0 | 1.1 | versicolor |
| 100 | 5.7 | 2.8 | 4.1 | 1.3 | versicolor |
}],
:data
https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [150 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|----------:|--------------:|-------------:|--------------:|-------------:|-----------|
| 1 | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 2 | 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 3 | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4 | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 6 | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 7 | 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 8 | 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 9 | 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 10 | 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| ... | ... | ... | ... | ... | ... |
| 140 | 6.9 | 3.1 | 5.4 | 2.1 | virginica |
| 141 | 6.7 | 3.1 | 5.6 | 2.4 | virginica |
| 142 | 6.9 | 3.1 | 5.1 | 2.3 | virginica |
| 143 | 5.8 | 2.7 | 5.1 | 1.9 | virginica |
| 144 | 6.8 | 3.2 | 5.9 | 2.3 | virginica |
| 145 | 6.7 | 3.3 | 5.7 | 2.5 | virginica |
| 146 | 6.7 | 3.0 | 5.2 | 2.3 | virginica |
| 147 | 6.3 | 2.5 | 5.0 | 1.9 | virginica |
| 148 | 6.5 | 3.0 | 5.2 | 2.0 | virginica |
| 149 | 6.2 | 3.4 | 5.4 | 2.3 | virginica |
| 150 | 5.9 | 3.0 | 5.1 | 1.8 | virginica |
}Points from setosa (50 rows), regression from versicolor. Same pose, different data per layer.
Faceting splits the poseβs dataset into panels automatically:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width)
(pj/facet :species))Three panels, each with its own data subset.
The facet divides the poseβs data only. A layer that carries :data of its own is drawn whole in every panel β in ggplot2 the facet divides a layerβs own data too. Here the regression fitted to the setosa rows is drawn in all three panels:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
pj/lay-point
(pj/lay-smooth {:stat :linear-model :data setosa})
(pj/facet :species))For layer data that differs per panel, build the panels with pj/arrange, so each cell is a pose with its own layer data β see Known Limitations.
Layer Placement
Scope determines which mappings each pose and layer reads. But how do layers find their pose? The rule depends on whether the pose is a leaf or a composite.
A panel is a part of the drawing: one set of axes and the marks drawn against them. A cell is a part of the pose: one of the sub-poses pj/arrange is given, or the part of a facet over columns that draws one column. A pose without a facet draws one panel, and an arrangement draws a panel for each of its cells.
On a leaf, pj/lay-* adds the layer to that leaf. A leaf draws one panel, and its layers share it, whatever columns they name:
(-> {:cohort [:a :b :c] :growth [12 19 15] :tax [3 5 4]}
(pj/lay-bar :growth :cohort)
(pj/lay-bar :tax :cohort))Each layer takes a color and a legend entry naming its column, the two layersβ bars are drawn side by side in each band, and the axis title names both columns. Separate panels come from pj/facet and pj/arrange β see Panels.
On a composite β several panels arranged together β the layer a pj/lay-* call adds is drawn in the cells it fits; Panels shows this once it has shown arrangements.
The Pose
The Poses chapter walked through the shape of a pose end to end. This is the per-field reference card β what each slot holds and which API call sets it:
| Field | Contains | Set by |
|---|---|---|
:data |
the dataset | pj/pose, pj/lay-*, or pj/with-data |
:mapping |
pose-level mappings, and their scales, and a facetβs categories under :col and :row |
pj/pose, pj/scale, pj/facet |
:layers |
layers attached to the pose | pj/lay-* |
:facet |
a facet over columns, when pj/facet is given them |
pj/facet |
:opts |
title, width, theme, coordinate system | pj/options, pj/coord |
A composite pose adds :poses (sub-poses) and optionally :layout and :share-scales; see the Composition chapter for that shape.
Mark, Stat, and Position
Each layer has a layer type β a rendering recipe with three parts:
- Mark β the visual shape (point, bar, line, area, tile, β¦)
- Stat β the computation before rendering (identity, bin, linear-model, density, β¦)
- Position β how overlapping groups share space (identity, dodge, stack, β¦)
A keyword like :histogram or :point names a layer type β look it up to see its parts:
(pj/layer-type-lookup :histogram){:mark :bar,
:stat :bin,
:x-only true,
:accepts [:normalize :bins :binwidth],
:doc "Histogram -- bins numerical data into bars.",
:column-counts #{1}}A histogram: stat :bin computes ranges, mark :bar shows them:
(-> (rdatasets/datasets-iris)
(pj/lay-histogram :sepal-length))A smoother: stat :loess fits a curve, mark :line draws it. (pj/lay-smooth {:stat :linear-model}) replaces the stat with a straight-line fit, as in the examples above:
(pj/layer-type-lookup :smooth){:mark :line,
:stat :loess,
:accepts
[:confidence-band
:level
:bootstrap-resamples
:bandwidth
:size
:stroke-dash
:dx
:dy],
:doc
"Smoothed trend line -- defaults to LOESS; pass {:stat :linear-model} for OLS.",
:column-counts #{2}}Position :stack places groups on top of each other:
(-> {:day ["Mon" "Mon" "Tue" "Tue"]
:count [30 20 45 15]
:meal ["lunch" "dinner" "lunch" "dinner"]}
(pj/lay-bar :day :count {:color :meal :position :stack}))See the Layer Types chapter for complete tables of every mark, stat, and position.
Inference
Plotje makes small poses work without you having to specify everything. You give it what you know β a dataset, perhaps a column or two β and it fills in the rest by inspecting the data.
Wherever you make a choice it wins; wherever you donβt, the library picks something sensible.
Column inference applies when a dataset has up to three columns and you call pj/pose (or a pj/lay-*) without naming any column. Plotje pairs the columns with aesthetics in dataset order:
| Columns in data | Inferred mapping |
|---|---|
| 1 | :x |
| 2 | :x, :y |
| 3 | :x, :y, :color |
With four or more columns the library does not guess β you have to name the columns you want, and a layer that names none reports an error. Column inference is most useful for quick sketches of small, focused datasets.
(-> {:height [170 180 165 175] :weight [70 80 65 75]}
pj/lay-point)Layer type inference happens when a pose has no explicit layer. The library inspects the types of the columns the mapping refers to and picks a chart type that fits. Two numerical columns produce a scatter plot:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width))A single numerical column produces a histogram:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length))In both cases the inferred plot is the same one you would get from pj/lay-point or pj/lay-histogram. Inference is a shorthand, not a separate rendering path. Every inferred choice can be overridden β see Inference Rules for the full decision logic and override settings, or Architecture for where in the pipeline each kind of inference happens.
Incremental Building
Because poses are plain data, you can save a partial plot and extend it later. Each call returns a new pose without changing the original.
(def scatter-base
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width)))Add a regression line:
(-> scatter-base (pj/lay-smooth {:stat :linear-model}))Or a LOESS smoother instead:
(-> scatter-base pj/lay-smooth)Reusable Pose Templates
A pose does not need to carry data. (pj/pose) creates an empty pose you can evolve like any other β adding layers, options β and then attach a dataset at the end with pj/with-data. The result is a reusable pose that can be applied to many datasets:
(def scatter-with-regression
(-> (pj/pose nil {:x :height :y :weight :color :cohort})
pj/lay-point
(pj/lay-smooth {:stat :linear-model})
(pj/options {:title "Scatter with Regression"})))Printed, the template has :data nil β a pose that carries mapping, layers, and options but no data yet:
(kind/pprint scatter-with-regression){:mapping {:x :height, :y :weight, :color :cohort},
:layers
[{:layer-type :point} {:layer-type :smooth, :stat :linear-model}],
:opts {:title "Scatter with Regression"}}Before it has data, the template draws an empty panel that reads βno dataβ, and prints a Note saying where to give the data:
scatter-with-regressionApply to one dataset:
(-> scatter-with-regression
(pj/with-data {:height [1 2 3 4 5 6]
:weight [2 4 3 5 6 8]
:cohort ["a" "a" "a" "b" "b" "b"]}))Apply the same template to a different dataset:
(-> scatter-with-regression
(pj/with-data {:height [10 20 30 40 50 60]
:weight [15 18 22 20 25 28]
:cohort ["c" "c" "c" "d" "d" "d"]}))pj/lay-* given nil in place of data also makes a template: (pj/lay-point nil :displ :hwy) is a pose with a point layer and no data. A template can also be a cell of an arrangement given data first β see Panels.
pj/with-data validates at attach time: if the dataset is missing a column the pose references, it reports an error naming the missing columns.
Color and Grouping
:color controls point and line colors. Its behavior depends on what you pass.
Categorical column β each unique value gets a distinct color. A legend maps labels to colors:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:color :species}))Numeric column β values map to a continuous gradient:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:color :petal-length}))Fixed color string β all points colored uniformly:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:color "steelblue"}))Coming from ggplot2. In ggplot2, colour="blue" is always a CSS color. In Plotje, {:color "blue"} is a column reference if a column with that exact name exists in the data, otherwise the CSS color. A keyword goes through the same two checks in the same order, so {:color :blue} is the column :blue where there is one and the color blue where there is not. Matching is strict: a string only matches a string column name, and a keyword only matches a keyword column name. Hex codes like "#0000ff" are practically unambiguous β the dataset is checked first for those too, but no dataset carries a column called #0000ff. To settle a genuine collision, say which you mean: {:color {:column "blue"}} or {:color {:value "blue"}}.
The disambiguation matters when the dataset uses string column names. With a string column named "blue", the column wins β three palette colors render, not a single blue:
(-> {"height" [1 2 3] "weight" [1 2 3] "blue" ["a" "b" "c"]}
(pj/lay-point "height" "weight" {:color "blue"}))Same string :color, dataset without a "blue" column β βblueβ parses as a CSS color:
(-> {"height" [1 2 3] "weight" [1 2 3]}
(pj/lay-point "height" "weight" {:color "blue"}))A categorical color also creates groups. Each group is processed independently: it gets its own regression line, density curve, or boxplot:
(-> (rdatasets/datasets-iris)
(pj/lay-density :sepal-length {:color :species}))Other visual properties include :alpha (transparency), :size, and :shape. Each accepts a value or a column the same way :color does β {:shape :square} draws every point square, and {:shape :species} gives each category its own symbol.
Bubble plot β :size mapped to a numeric column gives each point a radius reflecting the value:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width
{:color :petal-length :size :petal-width :alpha 0.7}))Shape by category β :shape mapped to a categorical column renders each group with a different marker, and a legend naming them. Useful for monochrome printing:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:shape :species})):color and :shape can take the same column at once. Each species then has its own color and its own marker, so a reader who cannot tell the colors apart can still tell the groups apart. The legend has one entry per species, and its key shows both:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:color :species
:shape :species}))The :group aesthetic creates groups without changing colors:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width {:group :species})
pj/lay-point
(pj/lay-smooth {:stat :linear-model}))Three regression lines but all the same color.
Plot Options and Reference Lines
The functions in this section set plot-level options: values that describe a plot rather than a layer. They are written on a pose and reach everything beneath it: written on the pose you are building they describe the whole plot, and written on one cell of a composite, that cell. See Options and Scopes for the full picture.
pj/options sets plot-level settings β title, axis labels, size, theme overrides:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:color :species})
(pj/options {:title "Iris Measurements"
:color-values :dark2}))Reference lines and shaded bands are themselves layers, added with pj/lay-rule-h, pj/lay-rule-v, pj/lay-band-h, pj/lay-band-v. Where each one draws comes from its mapping (:y-intercept / :x-intercept for rules; :y-min/:y-max or :x-min/:x-max for bands); appearance aesthetics like :color and :alpha work the same way they do on any other layer, and so does layer order β a rule added before the points is drawn under them.
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:color :species})
(pj/lay-rule-h {:y-intercept 3.0})
(pj/lay-band-v {:x-min 5.0 :x-max 6.0 :alpha 0.1}))Printed, the rule and the band hold the values they are drawn at (:y-intercept, :x-min, :x-max) and their appearance (:alpha) in their :mapping, the slot where the point layer holds its :color:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:color :species})
(pj/lay-rule-h {:y-intercept 3.0})
(pj/lay-band-v {:x-min 5.0 :x-max 6.0 :alpha 0.1})
kind/pprint){:layers
[{:layer-type :point,
:mapping {:x :sepal-length, :y :sepal-width, :color :species}}
{:layer-type :rule-h, :mapping {:y-intercept 3.0}}
{:layer-type :band-v,
:mapping {:x-min 5.0, :x-max 6.0, :alpha 0.1}}],
:data
https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [150 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|----------:|--------------:|-------------:|--------------:|-------------:|-----------|
| 1 | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 2 | 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 3 | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4 | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 6 | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 7 | 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 8 | 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 9 | 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 10 | 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| ... | ... | ... | ... | ... | ... |
| 140 | 6.9 | 3.1 | 5.4 | 2.1 | virginica |
| 141 | 6.7 | 3.1 | 5.6 | 2.4 | virginica |
| 142 | 6.9 | 3.1 | 5.1 | 2.3 | virginica |
| 143 | 5.8 | 2.7 | 5.1 | 1.9 | virginica |
| 144 | 6.8 | 3.2 | 5.9 | 2.3 | virginica |
| 145 | 6.7 | 3.3 | 5.7 | 2.5 | virginica |
| 146 | 6.7 | 3.0 | 5.2 | 2.3 | virginica |
| 147 | 6.3 | 2.5 | 5.0 | 1.9 | virginica |
| 148 | 6.5 | 3.0 | 5.2 | 2.0 | virginica |
| 149 | 6.2 | 3.4 | 5.4 | 2.3 | virginica |
| 150 | 5.9 | 3.0 | 5.1 | 1.8 | virginica |
}See the Customization chapter for the appearance of rules and bands (default opacity, color overrides), palettes, and themes. Temporal intercepts (LocalDate, Instant) are covered in Timelines.
Coordinates and Scales
pj/coord sets the coordinate system. :flip swaps the axes:
(-> (rdatasets/datasets-iris)
(pj/lay-point :sepal-length :sepal-width {:color :species})
(pj/coord :flip)):fixed locks the aspect ratio so one data unit on x equals one data unit on y β useful for spatial data or when distances on the two axes should read the same. The canvas is made narrower or shorter until the panel has that ratio, so here, where both columns run from -1 to 1, the panel is square:
(-> {:east [-1 1 -1 1] :north [-1 -1 1 1]}
(pj/lay-point :east :north)
(pj/coord :fixed))pj/scale changes how a numeric axis is shown. :log applies a logarithmic transformation:
(-> {:population [1000 5000 50000 200000 1000000 5000000]
:area [2 8 30 120 500 2100]}
(pj/lay-point :population :area)
(pj/scale :x :log)
(pj/scale :y :log))Both are written on the pose and reach every layer and panel beneath it. A mapping written out in full can name its own scale for one aesthetic, which takes precedence there.
Panels
Faceting splits a pose into panels by a columnβs values:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
(pj/facet :species)
pj/lay-point
(pj/lay-smooth {:stat :linear-model}))Printed, the facet column lives in the mapping under :col, beside :x and :y. A facet over categories is a mapping like any other β the pose itself is not split until render time:
(-> (rdatasets/datasets-iris)
(pj/pose :sepal-length :sepal-width)
(pj/facet :species)
pj/lay-point
(pj/lay-smooth {:stat :linear-model})
kind/pprint){:mapping {:x :sepal-length, :y :sepal-width, :col :species},
:layers
[{:layer-type :point} {:layer-type :smooth, :stat :linear-model}],
:data
https://vincentarelbundock.github.io/Rdatasets/csv/datasets/iris.csv [150 6]:
| :rownames | :sepal-length | :sepal-width | :petal-length | :petal-width | :species |
|----------:|--------------:|-------------:|--------------:|-------------:|-----------|
| 1 | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 2 | 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 3 | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4 | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5 | 5.0 | 3.6 | 1.4 | 0.2 | setosa |
| 6 | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
| 7 | 4.6 | 3.4 | 1.4 | 0.3 | setosa |
| 8 | 5.0 | 3.4 | 1.5 | 0.2 | setosa |
| 9 | 4.4 | 2.9 | 1.4 | 0.2 | setosa |
| 10 | 4.9 | 3.1 | 1.5 | 0.1 | setosa |
| ... | ... | ... | ... | ... | ... |
| 140 | 6.9 | 3.1 | 5.4 | 2.1 | virginica |
| 141 | 6.7 | 3.1 | 5.6 | 2.4 | virginica |
| 142 | 6.9 | 3.1 | 5.1 | 2.3 | virginica |
| 143 | 5.8 | 2.7 | 5.1 | 1.9 | virginica |
| 144 | 6.8 | 3.2 | 5.9 | 2.3 | virginica |
| 145 | 6.7 | 3.3 | 5.7 | 2.5 | virginica |
| 146 | 6.7 | 3.0 | 5.2 | 2.3 | virginica |
| 147 | 6.3 | 2.5 | 5.0 | 1.9 | virginica |
| 148 | 6.5 | 3.0 | 5.2 | 2.0 | virginica |
| 149 | 6.2 | 3.4 | 5.4 | 2.3 | virginica |
| 150 | 5.9 | 3.0 | 5.1 | 1.8 | virginica |
}A facet over columns, (pj/facet pose {:x [:sepal-length :sepal-width]}), draws a panel per column, and is kept under the poseβs :facet key rather than in its mapping. pj/arrange places whole poses side by side, each pose a cell of one composite. Panels shows each form, which form draws two columns or two categories inside one panel or across panels, and how the forms combine.
Whatβs Next
On a first read, the path through Foundations continues here:
- Panels β where panels come from, and which forms draw two things inside one panel or across panels
- Specifying Aesthetics β how to write what a mapping means, in full or in shorthand
To start making plots, the chart-type chapters follow:
- Distributions, Ranking, Change Over Time, and Relationships β recipes for common plotting goals
To go deeper into the model:
- Composition β composite poses, shared scales, and multi-panel patterns
- Options and Scopes β where options live and how scope determines what they reach
- Pose Rules β the formal rules, each with tested assertions; reference to return to, not required reading