12  Inference Rules

Plotje infers many parameters automatically so you can write less and get reasonable defaults. This notebook walks each rule with a worked example: a small pose, the rendered plot, and a description of what was inferred.

This chapter is a reference: each rule with its default and its override. For the conceptual overview, read Poses and Core Concepts first. On a first read through the book you can skim or skip it, and return when you need a specific default. The examples use small inline datasets so the relationships are easy to read at a glance.

(ns plotje-book.inference-rules
  (: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]))

A Worked Example

Before the rule-by-rule tour, here is what “inference” looks like in practice: a five-point scatter where Plotje filled in almost everything for us.

(def small-sample
  {:hours [1.0 2.0 3.0 4.0 5.0]
   :score [2.1 4.3 3.0 5.2 4.8]})
(def scatter-pose
  (-> small-sample
      (pj/lay-point :hours :score)))
scatter-pose
scorehours123452.02.53.03.54.04.55.0

Plotje inferred:

  • The x-axis label "hours" and y-axis label "score", taken from the column keywords

  • A linear scale on each axis, since both columns are numeric

  • The data extent [1.0, 5.0] widened to [0.8, 5.2] – a 5% padding so the extreme points do not sit on the panel edge

  • Round tick values: 1.0, 1.5, 2.0, ...

  • No legend, since no color mapping was given

  • A single point group rendered in the default color (dark gray, #333)

Each of those decisions is its own inference rule, with a default and an explicit override.

Overrides at a Glance

Every inference rule has an explicit override. The table below lists them all, and each row has a section below with worked examples.

What is inferred Default Override
Column selection one column fills x; two fill x, y; three fill x, y, color explicit column args in pj/pose or pj/lay-*
Column type dtype inspection :x-type, :y-type, :color-type in a pose’s or a layer’s mapping
Aesthetic classification the data decides: a name it carries is a column, anything else is a value {:color {:column "red"}} / {:color {:value "red"}}
Grouping categorical color column :group aesthetic
Layer type (mark + stat) column types (see Layer Type section) pj/lay-point, pj/lay-histogram, and the others
Domain extent the data’s extent plus 5% padding (pj/scale pose :x {:domain [0 10]})
Domain reach the axis spans what the data covers (pj/scale pose :y {:include 0})
Domain zero-anchor bar/stacked charts include zero (pj/scale pose :y {:domain [5 20]})
Fill domain [0.0, 1.0] for fill position (pj/scale pose :y {:domain [0 2]})
Tick values round intervals (linear), powers of 10 (log) (pj/scale pose :x {:breaks [1 2 3]})
Tick labels number formatting, calendar formatting (pj/scale pose :x {:breaks [...] :tick-labels [...]})
Axis labels column name, or every column drawn on the axis, with underscores and hyphens replaced by spaces (pj/options {:x-label "Custom"})
Color legend categorical = discrete, numerical = continuous, none = no legend, except layers naming different columns, which get an entry each :color on the layer or the pose
Size legend 5 graduated circles when :size maps to numerical column :size mapping controls presence
Alpha legend ~5 graduated opacity squares (count varies with range) when :alpha maps to numerical column :alpha mapping controls presence
Layout padding adjusts for title, labels, legend :width, :height in options
Layout type single panel, facet grid, or a composite for a facet over columns and for pj/arrange pj/facet, pj/arrange, pj/matrix
Coordinate system :cartesian (pj/coord :flip), (pj/coord :polar)

The sections follow roughly the order in which a pose is resolved into a plot – column selection, column types, aesthetics, grouping, layer type, domains, ticks, labels, legends, layout, coord flip – with two cross-cutting closing sections on how the rules combine in multi-layer plots and a diagram of the full resolution flow.

Column Selection

When column names are omitted, Plotje infers them from the dataset shape:

Number of columns Inferred mapping
1 first column becomes x
2 first becomes x, second becomes y
3 first becomes x, second becomes y, third becomes color
4+ no inference – see the note below

The same rule applies whether you start with pj/lay-* on raw data or pj/pose on raw data. Both read the first 1-3 columns of the dataset in the order they appear and build the mapping from there.

One column:

(-> {:values [1 2 3 4 5 6]}
    pj/lay-histogram)
countvalues123456012

Two columns – the first, :weight, goes on the x axis and the second, :height, on the y axis:

(-> {:weight [1 2 3 4 5] :height [2 4 3 5 4]}
    pj/lay-point)
heightweight123452345

Three columns – the third, :site, becomes :color:

(-> {:weight [1 2 3 4] :height [4 5 6 7] :site ["a" "a" "b" "b"]}
    pj/lay-point)
heightweightsiteab12344567

The mapping is inferred when the pose is drawn

A pose built from raw data with no column named – by pj/pose or by a pj/lay-* call – carries no mapping. The column-selection rule runs when the pose is drawn, and layer type inference (covered below) then supplies the mark.

(def two-col-pose
  (pj/pose {:side [1.0 2.0 3.0 4.0 5.0]
            :area [1.0 4.0 9.0 16.0 25.0]}))
two-col-pose
areaside123450510152025

pj/infer-mapping is the step the drawing functions run, and it shows the mapping the rule chooses:

(-> two-col-pose
    pj/infer-mapping
    (select-keys [:mapping :layers])
    kind/pprint)
{:mapping {:x :side, :y :area}, :layers []}

The inferred pose is one the reader could have written. Inferring from it again changes nothing, and it draws what the lean pose draws:

A later layer on a pose whose columns are read by default

A layer added to a pose leaves the layers before it as they were drawn. Below, the points come first and name no column, so they read the first three columns of the data. The trend line names the two columns the points are already drawn at. The default also maps the third column, :bed, to :color. Every layer of the pose reads that mapping, the trend line among them, so the points are colored by bed and there is one trend line per bed:

(def seedlings
  {:day [1 2 3 4 5 6 1 2 3 4 5 6]
   :height [2.0 3.1 3.9 5.2 6.1 6.8 1.5 2.1 2.4 3.3 3.6 4.4]
   :bed ["north" "north" "north" "north" "north" "north"
         "south" "south" "south" "south" "south" "south"]})
(-> seedlings
    pj/lay-point
    (pj/lay-smooth :day :height))
heightdaybednorthsouth123456234567

A later layer naming one of the two columns leaves the points as they were drawn too. Here a rug marks each :day along the x axis:

(-> seedlings
    pj/lay-point
    (pj/lay-rug :day))
heightdaybednorthsouth123456234567

A later layer naming other columns leaves the points where they were too: the trend line below names :height and :day the other way round, and the points stay at :day against :height, colored by bed. The trend line is drawn on the same panel, so each axis is titled by both of the columns drawn on it:

(-> seedlings
    pj/lay-point
    (pj/lay-smooth :height :day))
height, dayday, heightbednorthsouth12345671234567

Where the first layer names its columns, no column is read by default, and a layer added after it names no color either:

(-> seedlings
    (pj/lay-point :day :height)
    pj/lay-smooth)
heightday1.01.52.02.53.03.54.04.55.05.56.0234567

4+ columns

With four or more columns there is no unambiguous default, so no column is read from the data. (pj/lay-point data) and (pj/pose data) both build a pose with the data attached and no column named, and a later step may name the columns: (pj/pose pose :col-a :col-b) after either call, or (pj/lay-point pose :col-a :col-b) after (pj/pose data). After (pj/lay-point data), a second layer naming the columns also gives the first layer its columns (Rule LP6 in Pose Rules), so the points are drawn twice. A pose drawn while a layer still has no column reports an error that names the layer and lists the columns of the data:

(try
  (-> (rdatasets/datasets-iris)
      pj/lay-point
      pj/plan)
  (catch Exception e
    (ex-message e)))
"pj/lay-point draws from two columns, one on :x and one on :y, and this layer has no column on :x or :y. It names no column. Name both on the layer -- (pj/lay-point pose :x-column :y-column) -- or in the pose's mapping, which every layer of the pose reads. The data has 6 columns, so none is read by default. Available columns: [:petal-length :petal-width :rownames :sepal-length :sepal-width :species]"

When you provide explicit columns, inference is skipped:

(-> (rdatasets/datasets-iris)
    (pj/lay-point :petal-length :petal-width {:color :species}))
petal widthpetal lengthspeciessetosaversicolorvirginica12345670.00.51.01.52.02.5

Column Types

Once columns are selected, the next step is determining the type of each column – numerical, categorical, or temporal. This determines the scale type, domain, tick style, and the default mark.

Column dtype Inferred type
float, int :numerical
string, keyword, boolean, symbol, text :categorical
LocalDate, LocalDateTime, Instant, java.util.Date :temporal (numerical, with calendar-aware ticks)

A categorical column produces a band scale with string domain values. Compare:

(def animals
  {:animal ["cat" "dog" "bird" "fish"]
   :count [12 8 15 5]})
(def bar-pose
  (-> animals
      (pj/lay-bar :animal :count)))
bar-pose
countanimalcatdogbirdfish02468101214

The x-axis lays out the four animal names in order of appearance – strings, treated as a categorical band scale. The y-axis starts at zero because this is a bar chart.

Temporal columns

Plotje accepts java.util.Date (from Clojure’s #inst reader literal), LocalDate, LocalDateTime and Instant. Each is detected automatically and converted to epoch-milliseconds – one number per value – before any scale is built.

(def temporal-pose
  (-> {:date [#inst "2024-01-01" #inst "2024-06-01" #inst "2024-12-01"]
       :val [10 25 18]}
      (pj/lay-point :date :val)))
temporal-pose
valdateJan 2024Mar 2024May 2024Jul 2024Sep 2024Nov 20241012141618202224

The axis reads as dates. The plan underneath it holds none: the scale is an ordinary :linear one, the domain is a pair of epoch-millisecond numbers, and only the tick labels are calendar-aware. This is what the type table above means by “numerical, with calendar-aware ticks” – it describes the scaling, not the display.

A tick is labelled at the granularity of the calendar unit it steps by, and no finer: ticks a year apart carry the year alone, and ticks a month apart carry the month, with the year beside it once the axis covers about a year – the point past which the month alone stops saying which one. The same two-point layer over three spans gives clock time, weekday and hour, and year:

(pj/arrange
 [(-> {:when [#inst "2024-01-15T00:00" #inst "2024-01-15T06:00"] :level [1 2]}
      (pj/lay-point :when :level)
      (pj/options {:title "Six hours"}))
  (-> {:when [#inst "2024-01-15" #inst "2024-01-18"] :level [1 2]}
      (pj/lay-point :when :level)
      (pj/options {:title "Three days"}))
  (-> {:when [#inst "2015-01-15" #inst "2024-01-15"] :level [1 2]}
      (pj/lay-point :when :level)
      (pj/options {:title "Nine years"}))]
 {:cols 1})
Six hourslevelwhen00:0001:0002:0003:0004:0005:0006:0012Three dayslevelwhenMon 00:00Mon 12:00Tue 00:00Tue 12:00Wed 00:00Wed 12:00Thu 00:0012Nine yearslevelwhen20162017201820192020202120222023202412

The tick values sit on the calendar as well as the labels do, at every resolution. The step is a round number of years, months, weeks, days, hours, minutes or seconds, and each tick lands on a multiple of that step counted from the calendar rather than from the first value: the nine-year axis above carries one tick per year, and the twelve-month axis at the top of this section carries one every two months, beginning in January. A weekly axis lands on Mondays.

Overriding inferred types with :x-type / :y-type

Sometimes a numeric column holds categories – for example, hours of the day, years, or subject IDs. Inference treats a column of numbers as numerical, but you may want discrete categorical bands. Write :x-type :categorical (or :y-type) in the pose’s or the layer’s mapping to override:

(def hour-bar-pose
  (-> {:hour [9 10 11 12] :count [5 8 12 7]}
      (pj/lay-bar :hour :count {:x-type :categorical})))
hour-bar-pose
counthour9101112024681012

Four bars at discrete hour bands. Without the override the bars are drawn along a numerical axis, ticked at round numbers rather than once per hour; with the override, the column is read as categorical (values cast to strings for display). The same override exists for :y-type and for :color-type (see the Grouping section below for a :color-type example).

Aesthetic Resolution

The :color parameter does different things depending on what you pass. Each aesthetic (:color, :size, :alpha, :shape, :text) is classified as either a column reference or a written value.

Column reference – colored by palette

(def colored-pose
  (-> {:dose [1 2 3 4 5 6]
       :response [3 5 4 7 6 8]
       :g ["a" "a" "a" "b" "b" "b"]}
      (pj/lay-point :dose :response {:color :g})))
colored-pose
responsedosegab123456345678

The categorical column :g splits the data into two groups, each with its own color drawn from the palette. A legend appears on the right (100 drawing units wide) and the panel shrinks to make room.

Categorical color implies grouping below explains why a categorical color column creates groups while a numeric color column does not.

Fixed color string – single color, no legend

(def fixed-color-pose
  (-> small-sample
      (pj/lay-point :hours :score {:color "#E74C3C"})))
fixed-color-pose
scorehours123452.02.53.03.54.04.55.0

A written hex string maps every point to that single color: no grouping, no legend, no legend strip. The hex was parsed into the RGBA tuple [0.906 0.298 0.235 1.0].

Named colors and string disambiguation

CSS color names like "red" and "steelblue" also work as fixed colors:

(-> small-sample
    (pj/lay-point :hours :score {:color "steelblue"}))
scorehours123452.02.53.03.54.04.55.0

:color also accepts column names (like "species" or :species), so "red" could mean the column red or the color red.

The rule is: check the dataset first. If the value names a column of the layer’s data, it is a column reference. Otherwise it is read as a color, if it names one.

Here is the full resolution order for a :color value:

  1. If it names a dataset column, it is a column reference (grouping)
  2. If it starts with # and parses as hex, it is that color ("#E74C3C", "#F00")
  3. If it is a CSS color name, it is that color – as a string ("red", "steelblue") or as a keyword (:red, :steelblue)
  4. Otherwise, error. For a string the error names both readings, since a hex code written without its # arrives that way. For a keyword the error names only the missing column: a keyword naming a color would have been drawn at step 3, so the only reading left to name is the column.

A keyword and a string go through the same two checks, in the same order. Matching is strict: :species finds a keyword-named column and "species" finds a string-named one. The errors for the two differ in how much they say.

Hex without its # is not a color. Clojure2D reads a bare abc as #aabbcc, which would make "beef" and "fff" colors – far likelier mistyped column names. Write the #.

In practice, ambiguity is rare. Column names like "species" or "temperature" are not valid CSS colors, and color names like "red" are unlikely column names. When true ambiguity exists, say which you mean: {:color {:column "red"}} reads the column and {:color {:value "red"}} draws the color.

"red" is a fixed color when the dataset has no red column:

(def red-color-pose
  (-> small-sample
      (pj/lay-point :hours :score {:color "red"})))
red-color-pose
scorehours123452.02.53.03.54.04.55.0

No legend, points drawn red – treated as a fixed color, not a column.

No color – default gray

The Worked Example at the top of the chapter shows this case: with no :color mapping, all points render in the default dark gray (#333) and no legend appears.

Grouping

The colored examples above all rest on the same concept: grouping controls how data is split into independent subsets. Each group gets its own visual elements – its own set of points, its own regression line, its own density curve, its own bar in a dodged layout.

Grouping can be derived (from a categorical :color mapping) or explicit (via the :group aesthetic).

Categorical color implies grouping

When :color maps to a categorical column (as with colored-pose above), the data is split into one group per category. Each group gets a distinct palette color and a legend entry:

colored-pose
responsedosegab123456345678

Two groups, two legend entries – one per category in :g.

This is the column read through its scale. A column drawn as it stands – {:color {:column :hex :scale false}} – holds colors rather than data, so no categories come out of it and the rows are not split:

(-> {:dose [1 2 3] :response [4 5 6] :hex ["#EE7733" "#AA3377" "#000000"]}
    (pj/lay-point :dose :response {:color {:column :hex :scale false}}))
responsedose123456

One group, and three colors on it – one per row. See Specifying Aesthetics.

Numeric color does not create groups

When :color maps to a numerical column, data is NOT split. Instead, each mark drawn once per row takes its own color from a continuous gradient. There is one group, and the legend is continuous with 20 pre-computed color stops.

(def numeric-color-pose
  (-> {:dose [1 2 3 4 5]
       :response [2 4 3 5 4]
       :val [10 20 30 40 50]}
      (pj/lay-point :dose :response {:color :val})))
numeric-color-pose
responsedoseval1020304050123452345

A single group with a continuous legend of 20 color stops – the color is a visual encoding, not a grouping variable.

Overriding color type with :color-type

Sometimes a numeric column holds categorical identifiers – for example, subject IDs in a repeated-measures study. Inference treats numeric columns as continuous, but you want discrete groups. Setting :color-type :categorical overrides this so the column is treated as categorical despite its numeric dtype.

(def study-data
  {:subject [1 1 1 2 2 2 3 3 3]
   :day     [1 2 3 1 2 3 1 2 3]
   :score   [5 7 6 3 4 5 8 9 7]})

Without override – one group. A line is drawn once per group, so it takes one color and does not follow the column as a gradient, though the legend shows one; Plotje prints a warning saying so:

(def study-continuous-pose
  (-> study-data
      (pj/lay-line :day :score {:color :subject})))
study-continuous-pose
scoredaysubject1231233456789

With :color-type :categorical – three groups, one per subject:

(def study-categorical-pose
  (-> study-data
      (pj/lay-line :day :score {:color :subject
                                :color-type :categorical})))
study-categorical-pose
scoredaysubject1231233456789

The same data, the same columns – but :color-type :categorical changes inference from “one gradient” to “three distinct groups.” This affects grouping, line splitting, legend style, and palette assignment. The rendered plots differ:

(-> {:subject [1 1 1 2 2 2 3 3 3]
     :day     [1 2 3 1 2 3 1 2 3]
     :score   [5 7 6 3 4 5 8 9 7]}
    (pj/lay-line :day :score {:color :subject
                              :color-type :categorical})
    pj/lay-point
    (pj/options {:title "Scores by Subject (categorical override)"}))
Scores by Subject (categorical override)scoredaysubject1231233456789

Explicit grouping with :group

The :group aesthetic splits data into groups without assigning distinct colors or creating a legend. This is useful when you want per-group statistics but uniform appearance.

(def grouped-data
  {:dose [1 2 3 4 5 6]
   :response [3 5 4 7 6 8]
   :g ["a" "a" "a" "b" "b" "b"]})
(def explicit-group-pose
  (-> grouped-data
      (pj/lay-point :dose :response {:group :g})))
explicit-group-pose
responsedose123456345678

Two groups, but no legend and no color differentiation. Use :group when you need separate statistical fits but want a uniform visual style.

What grouping affects

Grouping determines how statistical transformations operate. Without grouping, (pj/lay-smooth {:stat :linear-model}) fits one regression line through all the data. With grouping, it fits one line per group.

One regression line – no grouping:

(-> grouped-data
    (pj/pose :dose :response)
    pj/lay-point
    (pj/lay-smooth {:stat :linear-model}))
responsedose123456345678

Two regression lines – grouped by color:

(-> grouped-data
    (pj/pose :dose :response {:color :g})
    pj/lay-point
    (pj/lay-smooth {:stat :linear-model}))
responsedosegab123456345678

The same applies to other statistics: density curves, LOESS smoothers, boxplots, and dodge/stack positioning all operate per group.

Layer Type

When you use pj/pose without an explicit pj/lay-* call, Plotje infers the layer type – a mark + stat bundle – from the column types of the referenced columns.

Single-column cases

Column type Inferred Mark + stat
numerical histogram :bar + :bin
temporal histogram (over epoch-ms, with calendar-aware ticks) :bar + :bin
categorical bar chart of category counts :rect + :count

Two-column cases

x type y type Inferred Mark + stat
numerical numerical scatter :point + :identity
temporal numerical time-series line :line + :identity
categorical numerical boxplot (vertical) :boxplot + :boxplot
numerical categorical boxplot (horizontal) :boxplot + :boxplot
the same column on both axes what the column draws alone: a histogram for a numerical or temporal column, a bar chart of counts for a categorical column as in the single-column table
any other pair scatter (fallback) :point + :identity

A temporal column is read as a numerical column here, so a categorical column against a temporal column is a boxplot too. The pairs that fall back to a scatter are categorical with categorical and temporal with temporal. These are rarer in practice, and giving them a dedicated inference is deferred. You can always override with an explicit pj/lay-* call; the inferred layer type is only a default.

When you use pj/lay-point, pj/lay-histogram or another layer function, the layer type’s stat takes precedence – column-type inference is bypassed.

One numerical column named on both axes draws its histogram:

(-> small-sample
    (pj/pose :hours :hours))
counthours12345012

An explicit pj/lay-point with one column on both axes still draws the points, and pj/lay-bar with one categorical column on both axes counts that column.

Under a facet over columns, as in pj/matrix, each panel that no layer draws takes the layer type inferred from its own columns. So the diagonal of a scatter plot matrix, where a column meets itself, draws that column’s histogram, and the other panels draw scatters:

(-> (rdatasets/datasets-iris)
    (pj/matrix [:sepal-length :sepal-width]))
567856782.02.53.03.54.04.5234sepal lengthsepal widthsepal lengthsepal width

A single numerical column produces a histogram:

(def hist-pose
  (-> small-sample
      (pj/pose :hours)))
hist-pose
counthours12345012

The inferred layer is a histogram – a :bar mark fed by the :bin stat, so the data is binned into rectangles before rendering.

A single temporal column also becomes a histogram, binned over epoch-milliseconds with calendar-aware tick labels:

(def temporal-hist-pose
  (-> {:date [#inst "2024-01-01" #inst "2024-02-01" #inst "2024-03-01"
              #inst "2024-04-01" #inst "2024-05-01"]}
      (pj/pose :date)))
temporal-hist-pose
countdateJan-01Jan-15Jan-29Feb-12Feb-26Mar-11Mar-25Apr-08Apr-22012

A single categorical column produces a bar chart of counts:

(def count-pose
  (-> animals
      (pj/pose :animal)))
count-pose
countanimalcatdogbirdfish01

The inferred layer uses a :rect mark fed by the :count stat, which tallied each of the 4 categories.

A single column written on :y rather than :x gets the same layer, drawn on its side: the categories run up the y axis and the counts along the x axis.

(def count-pose-on-y
  (-> animals
      (pj/pose {:y :animal})))
count-pose-on-y
animalcount01catdogbirdfish

A layer written with pj/lay-* on such a pose is drawn on its side too, where its layer type draws from one column – a histogram, a density, a rug or a bar. A layer type that draws only from two columns, such as a scatter, needs an :x: on data of two or three columns it takes the first column nothing names, so (pj/lay-point animals {:y :count}) draws :count against :animal, and on wider data it reports an error naming the missing :x. The Layer Types chapter lists how many columns each layer type draws from.

(-> animals
    (pj/lay-point {:y :count}))
countanimalcatdogbirdfish56789101112131415

The column can be named on the layer in place of the pose. Where every layer of the pose draws from one column and none names an :x, the pose is drawn on its side, as count-pose-on-y above is:

(-> animals
    (pj/lay-bar {:y :animal}))
animalcount01catdogbirdfish

Two numerical columns produce a scatter (the chapter’s opening scatter-pose is such a pose):

(def num-num-pose
  (-> small-sample (pj/pose :hours :score)))
num-num-pose
scorehours123452.02.53.03.54.04.55.0

A temporal x with a numerical y infers a time-series line. Row order is preserved, so pre-sort temporal data to avoid zigzag:

(def ts-line-pose
  (-> {:date [#inst "2024-01-01" #inst "2024-02-01" #inst "2024-03-01"]
       :val  [10 25 18]}
      (pj/pose :date :val)))
ts-line-pose
valdateJan-01Jan-08Jan-15Jan-22Jan-29Feb-05Feb-12Feb-19Feb-261012141618202224

A categorical x with a numerical y infers a boxplot – the default for summarizing a distribution across groups:

(def boxplot-pose
  (-> {:species ["a" "a" "a" "b" "b" "b" "c" "c" "c"]
       :val     [8  10  12  18  20  22  14  15  17]}
      (pj/pose :species :val)))
boxplot-pose
valspeciesabc810121416182022

A numerical x with a categorical y infers a horizontal boxplot – the same summary laid out with the category axis on y:

(def horizontal-boxplot-pose
  (-> {:val     [8  10  12  18  20  22  14  15  17]
       :species ["a" "a" "a" "b" "b" "b" "c" "c" "c"]}
      (pj/pose :val :species)))
horizontal-boxplot-pose
speciesval810121416182022abc

Domains

Numerical domains extend 5% beyond the data’s extent so points aren’t clipped at the edges.

scatter-pose
scorehours123452.02.53.03.54.04.55.0

The x-domain is [0.8, 5.2] – the data’s extent [1.0, 5.0] plus 0.2 padding on each side (5% of the data’s span, 4.0).

The domain follows the data, so an axis reaches zero only where the data does. Two settings say otherwise: :include names a value the axis has to reach, which is how zero gets onto it, and :domain replaces the extent outright. Scales works through the first and the second.

Special domain rules apply in certain contexts:

Bar charts always include zero on the value axis – for these vertical bars, that is the y-domain:

bar-pose
countanimalcatdogbirdfish02468101214

Percentage-filled layers normalize the y-domain to [0.0, 1.0]:

(def fill-pose
  (-> {:x ["a" "a" "b" "b"]
       :g ["m" "n" "m" "n"]}
      (pj/lay-bar :x {:position :fill :color :g})))
fill-pose
countxgmnab0.00.10.20.30.40.50.60.70.80.91.0

The y-domain is exactly [0.0, 1.0] – each category sums to 100%.

Multi-layer plots merge domains across layers – see “Multi-Layer Plots” below.

Ticks

Once domains are computed, Plotje selects “nice” round tick values. The logic depends on the scale type:

  • Linear – ticks at round intervals (1, 2, 2.5, 5, …). Where every value the axis reads is a whole number, so are the ticks: a column of 0, 1, 2 and 3 is ticked 0, 1, 2, 3 rather than at the halves the interval rule would otherwise reach for on so short a span

  • Log – 1-2-5 nice numbers: powers of 10 when at least three of them fall inside the domain, otherwise intermediates at 1-2-5 or 1-2-3-5 multiples per decade

  • Categorical – tick at each category, in order of appearance

  • Temporal – calendar-aware snapping (year, month, day, hour) with adaptive formatting

Linear ticks for the scatter example. Its :x is 1, 2, 3, 4, 5 and its :y runs 2.1 to 5.2, so the two axes are ticked differently from one another on almost the same span:

scatter-pose
scorehours123452.02.53.03.54.04.55.0

Five whole ticks along x, where the values are whole; seven ticks at half intervals along y, where they are not.

Log ticks for a multi-decade range:

(def log-scale-pose
  (-> {:x [0.1 1.0 10.0 100.0 1000.0]
       :y [5 10 15 20 25]}
      (pj/lay-point :x :y)
      (pj/scale :x :log)))
log-scale-pose
yx0.11101001000468101214161820222426

Five ticks at exact powers of 10 – no irrational intermediates. Whole numbers display without decimals, sub-1 values use minimal decimal places.

Categorical ticks match domain order:

bar-pose
countanimalcatdogbirdfish02468101214

All of this is what Plotje selects on its own. An axis scale also takes :breaks, :tick-labels, :n-ticks and :tick-spacing, which name the ticks rather than leaving them to the generator – :breaks takes dates on a temporal axis. All four are worked through in Scales.

Axis Labels

Labels come from column names. Underscores and hyphens become spaces.

(def iris-label-pose
  (-> (rdatasets/datasets-iris)
      (pj/lay-point :sepal-length :sepal-width)))
iris-label-pose
sepal widthsepal length4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

When only one column is specified, the y-axis shows computed counts. There is no column on :y to name, so the y-label names what the layer computes, count – or density for a density layer. {:y-label ""} in pj/options removes it:

(def x-only-pose
  (-> small-sample (pj/pose :hours)))
x-only-pose
counthours12345012

Explicit labels override inference:

(def explicit-label-pose
  (-> small-sample
      (pj/lay-point :hours :score)
      (pj/options {:x-label "Length (cm)" :y-label "Width (cm)"})))
explicit-label-pose
Width (cm)Length (cm)123452.02.53.03.54.04.55.0

Legends

A legend appears when a column is mapped to color. Three cases:

A categorical color mapping produces a discrete legend with one entry per category:

colored-pose
responsedosegab123456345678

The legend’s title is the column name; each entry has a :label and a palette color.

No color mapping, on a pose whose layers draw the same columns, means no legend:

scatter-pose
scorehours123452.02.53.03.54.04.55.0

A fixed color string also suppresses the legend:

fixed-color-pose
scorehours123452.02.53.03.54.04.55.0

A numeric color mapping produces a continuous legend (gradient bar):

(def continuous-color-pose
  (-> {:x [1 2 3] :y [4 5 6] :val [10 20 30]}
      (pj/lay-point :x :y {:color :val})))
continuous-color-pose
yxval1015202530123456

Size Legend

When :size maps to a numerical column, a size legend shows graduated circles spanning the data range. Each circle is drawn from the same scale as the marks, so the one beside a value is the size a mark of that value is drawn at.

(def size-legend-pose
  (-> {:x [1 2 3 4 5] :y [1 2 3 4 5] :s [10 20 30 40 50]}
      (pj/lay-point :x :y {:size :s})))
size-legend-pose
yxs10203040501234512345

The legend has 5 entries, each pairing a value with a circle of the corresponding radius. No size mapping means no size legend:

scatter-pose
scorehours123452.02.53.03.54.04.55.0

Alpha Legend

When :alpha maps to a numerical column, an alpha legend shows graduated opacity squares – about five nice 1/2/5 breaks; the exact count depends on the range (here [0.1, 0.9] yields four).

(def alpha-legend-pose
  (-> {:x [1 2 3 4 5] :y [1 2 3 4 5] :a [0.1 0.3 0.5 0.7 0.9]}
      (pj/lay-point :x :y {:alpha :a})))
alpha-legend-pose
yxa0.20.40.60.81234512345

As with size, a plot with no alpha mapping has no alpha legend.

Layout

Layout padding adjusts based on what elements are present – titles, axis labels, and legends each reserve their own space.

Compare a bare plot to one with title, labels, and legend:

scatter-pose
scorehours123452.02.53.03.54.04.55.0
(def full-layout-pose
  (-> {:x [1 2 3 4 5 6]
       :y [3 5 4 7 6 8]
       :g ["a" "a" "a" "b" "b" "b"]}
      (pj/lay-point :x :y {:color :g})
      (pj/options {:title "My Plot"})))
full-layout-pose
My Plotyxgab123456345678

The bare plot reserves no space for a title and no legend strip. The full plot adds padding above for the title and 100 drawing units on the right for the legend.

Layout type is also inferred from the pose structure:

  • A single panel is :single, also where its layers name different columns

  • A faceted pose – one mapping :col or :row – is :facet-grid

  • A facet over columns, a facet over categories wrapped into rows with {:cols n}, and a pose built with pj/arrange are planned as a composite: the plan holds one sub-plot per cell, and each sub-plot has a layout type of its own

scatter-pose
scorehours123452.02.53.03.54.04.55.0

Coordinate Flipping

Setting :coord :flip swaps the visual axes. The data stays the same – the categorical band that was on x ends up on y, with ticks and labels following along.

(def normal-pose
  (-> animals
      (pj/lay-bar :animal :count)))
normal-pose
countanimalcatdogbirdfish02468101214
(def flip-pose
  (-> animals
      (pj/lay-bar :animal :count)
      (pj/coord :flip)))
flip-pose
animalcount02468101214catdogbirdfish

The categorical axis moved from x to y.

Labels are also swapped – the x-label and y-label follow their visual axis, not the data axis:

(def flipped-labels-pose
  (-> small-sample
      (pj/lay-point :hours :score)
      (pj/coord :flip)))
flipped-labels-pose
hoursscore2.02.53.03.54.04.55.012345

After flipping, the visual x-axis shows “score” and the visual y-axis shows “hours” – labels track the visual axes.

Polar coordinates (:coord :polar) are covered separately – see the Polar Coordinates chapter for rose charts, radial bars, and related plots.

Multi-Layer Plots

When multiple layers share a panel, their domains are merged:

(def multi-pose
  (-> small-sample
      (pj/pose :hours :score)
      pj/lay-point
      (pj/lay-smooth {:stat :linear-model})))
multi-pose
scorehours123452.02.53.03.54.04.55.0

Two layers – one :point, one :line – sharing the same domain. The line carries the regression curve as a polyline.

When the layers of a pose name different columns, each axis is titled by every column drawn on it, and each layer with no :color specified takes a color and a legend entry naming its columns. Here both layers draw :sepal-length on :x, and each names its own :y:

(def two-columns-pose
  (-> (rdatasets/datasets-iris)
      (pj/pose :sepal-length)
      (pj/lay-point {:y :sepal-width})
      (pj/lay-point {:y :petal-width})))
two-columns-pose
sepal width, petal widthsepal lengthsepal widthpetal width4.55.05.56.06.57.07.58.00.00.51.01.52.02.53.03.54.04.5

A layer that specifies a color keeps that color and has no legend entry, and no layer takes a color by default on a panel where a layer is colored by a column.

(-> (rdatasets/datasets-iris)
    (pj/pose :sepal-length)
    (pj/lay-point {:y :sepal-width :color "#7f7f7f"})
    (pj/lay-point {:y :petal-width}))
sepal width, petal widthsepal lengthpetal width4.55.05.56.06.57.07.58.00.00.51.01.52.02.53.03.54.04.5

Resolution Overview

The diagram below sketches how the rules above combine – which inferences feed which others on the way from a pose to a rendered plot:

graph TD POSE["pose + options"] POSE --> CT["Column types"] POSE --> AE["Aesthetics"] CT --> GR["Grouping"] AE --> GR CT --> ME["Layer type"] GR --> STATS["Statistics"] ME --> STATS STATS --> DOM["Domains"] DOM --> TK["Ticks"] POSE --> LBL["Axis labels"] AE --> LEG["Color legend"] AE --> SLEG["Size legend"] AE --> ALEG["Alpha legend"] DOM --> LAYOUT["Layout"] LBL --> LAYOUT LEG --> LAYOUT SLEG --> LAYOUT ALEG --> LAYOUT DOM --> PLOT["Rendered plot"] TK --> PLOT LBL --> PLOT LEG --> PLOT SLEG --> PLOT ALEG --> PLOT LAYOUT --> PLOT STATS --> PLOT style POSE fill:#e8f5e9 style PLOT fill:#fff3e0 style STATS fill:#e3f2fd style DOM fill:#e3f2fd

Column types and aesthetic classification are the starting points; every other inference depends on them. Statistics and domains together set the geometry; labels, legends, and layout fill the plot around the panels.

What’s Next

  • Layer Types – the full registry of marks, stats, and positions that inference selects from
  • Relationships – inference applied to scatter, regression, and SPLOM
source: notebooks/plotje_book/inference_rules.clj