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}))
sepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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))
weightheight123452345

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))
temperaturecityParisLondonBerlinRome0510152025

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)
Notestderr
[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.
1012345234567

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)
heightweight123452345

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}))
sepal widthsepal length4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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))
sepal widthsepal length4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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-panel
sepal widthsepal length56782.02.53.03.54.04.5petal widthpetal length2460.00.51.01.52.02.5

Each 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}))
sepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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}))
sepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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}))
sepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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 nil erases 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 that pj/pose writes into a pose that already has a mapping – see Scales.

  • Row filters: two :where maps 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 :theme and :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 :data in 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}))
sepal widthsepal length4.55.05.56.06.57.02.02.53.03.54.04.5

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))
sepal widthsepal length682.02.53.03.54.04.56868setosaversicolorvirginica

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))
sepal widthsepal length682.02.53.03.54.04.56868setosaversicolorvirginica

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))
cohortgrowth, taxgrowthtax024681012141618abc

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))
countsepal length4.55.05.56.06.57.07.58.00510152025

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}))
countdaymeallunchdinnerMonTue0102030405060

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)
weightheight1661681701721741761781806668707274767880

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))
sepal widthsepal length4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

A single numerical column produces a histogram:

(-> (rdatasets/datasets-iris)
    (pj/pose :sepal-length))
countsepal length4.55.05.56.06.57.07.58.00510152025

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}))
sepal widthsepal length4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

Or a LOESS smoother instead:

(-> scatter-base pj/lay-smooth)
sepal widthsepal length4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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-regression
Scatter with Regressionweightheightno data0101

Apply 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"]}))
Scatter with Regressionweightheightcohortab1234562345678

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"]}))
Scatter with Regressionweightheightcohortcd10203040506016182022242628

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}))
sepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

Numeric column – values map to a continuous gradient:

(-> (rdatasets/datasets-iris)
    (pj/lay-point :sepal-length :sepal-width {:color :petal-length}))
sepal widthsepal lengthpetal length2464.55.05.56.06.57.07.58.02.02.53.03.54.04.5

Fixed color string – all points colored uniformly:

(-> (rdatasets/datasets-iris)
    (pj/lay-point :sepal-length :sepal-width {:color "steelblue"}))
sepal widthsepal length4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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"}))
weightheightblueabc123123

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"}))
weightheight123123

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}))
densitysepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.00.00.20.40.60.81.01.2

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}))
sepal widthsepal lengthpetal length246petal width0.511.522.54.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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}))
sepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

: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}))
sepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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}))
sepal widthsepal length4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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}))
Iris Measurementssepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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}))
sepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

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))
sepal lengthsepal widthspeciessetosaversicolorvirginica2.02.53.03.54.04.54.55.05.56.06.57.07.58.0

: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))
northeast-101-101

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))
areapopulation1000100001000001000000101001000

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}))
sepal widthsepal length682.02.53.03.54.04.56868setosaversicolorvirginica

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:

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
source: notebooks/plotje_book/core_concepts.clj