13 Layer Types
A layer type is the bundle that determines how data becomes a visual element. It combines three concepts:
- mark – what shape to show (points, bars, lines, …)
- stat – what computation to apply first (pass through, bin, count, regress, …)
- position – how overlapping groups share space (identity, dodge, stack, fill)
Layer functions (pj/lay-point, pj/lay-histogram, pj/lay-bar, (pj/lay-smooth {:stat :linear-model}), and the others) each add a layer with the corresponding layer type. When no layer is added, Plotje infers a layer type from the column types.
All built-in layer types are registered in a data registry. The tables below are generated from that registry – they stay in sync with the code.
On a first read through the book you can skim or skip this chapter, and return when you need to look up what a layer type draws and computes.
(ns plotje-book.layer-types
(:require
;; Kindly -- notebook rendering protocol
[scicloj.kindly.v4.kind :as kind]
;; Plotje -- composable plotting
[scicloj.plotje.api :as pj]
;; Layer-type registry -- for inspecting layer-type data
[scicloj.plotje.layer-type :as layer-type]
;; String utilities
[clojure.string :as str]))Reading the Registry
The tables below are generated directly from the layer-type registry, so they track whatever is currently registered. Two small helpers query the registry: used-by returns the comma-separated list of layer types whose given field equals a value, and distinct-in-order returns each distinct field value in the order layer types were registered. Both are used to populate the Mark, Stat, and Position tables further down.
(defn used-by
"Sorted comma-separated layer-type names whose `field` equals `value`."
[field value]
(->> (layer-type/registered)
(filter (fn [[_ m]] (= value (or (get m field) :identity))))
(map (comp name key))
sort
(str/join ", ")))(defn distinct-in-order
"Distinct values of `field` across layer types, in first-seen order."
[field]
(let [seen (volatile! #{})]
(reduce (fn [acc k]
(let [v (get (layer-type/lookup k) field)]
(if (@seen v) acc
(do (vswap! seen conj v) (conj acc v)))))
[] layer-type/layer-type-order)))Layer Types
Each row is a registered layer type showing its mark, stat, position, and the layer settings it presets. Two layer types can share a mark and differ only in the stat or the presets: :histogram is the :bar mark with a binning stat, and :label is the :text mark with a background box preset.
(kind/table
{:column-names ["Layer type" "Mark" "Stat" "Position" "Columns" "Presets"]
:row-maps
(for [k layer-type/layer-type-order
:let [m (layer-type/lookup k)]]
{"Layer type" (kind/code (pr-str k))
"Mark" (kind/code (pr-str (:mark m)))
"Stat" (kind/code (pr-str (:stat m)))
"Position" (kind/code (pr-str (or (:position m) :identity)))
"Columns" (kind/code (pr-str (layer-type/column-counts k)))
"Presets" (if-let [d (:defaults m)] (kind/code (pr-str d)) "")})})| Layer type | Mark | Stat | Position | Columns | Presets |
|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Columns a layer type draws from
The “Columns” entry is the layer type’s :column-counts: the set of numbers of columns it draws from. #{1} draws from an x column alone, as a histogram does; #{2} draws from an x column and a y column, as a scatter does; #{1 2} draws from either, as a bar does – it counts the categories of one column, and takes a second column as the heights of its bars:
(layer-type/column-counts :bar)#{1 2}Among the places that read it:
A layer added to a composite, or after a facet crossing two lists of columns, is drawn in the panels it fits. The number of columns the layer type draws from is one of the two things that decide whether a panel fits the layer; Rule LP2 in Pose Rules states both. Where no panel fits, the layer is drawn in every panel. The scatter plot matrix is the case where the panels differ: a point layer is drawn off the diagonal, and the diagonal keeps its histograms.
A pose that names a column on
:yalone, with no:x, is drawn with a layer type that draws from one column, turned on its side – a numerical column gives a horizontal histogram.A layer that names one column is given the panel’s column on the other axis only where its layer type cannot draw from one column: after
(pj/lay-point data :a :b),(pj/lay-line {:y :c})draws:cagainst:a, and(pj/lay-rug {:x :c})draws:calone.
A layer type registered without :column-counts draws from two columns, or from one where it is registered :x-only true.
A layer type carries one more field the table leaves out, because only one built-in layer type has it. :varies names the appearance aesthetics its mark varies from row to row, and the quantity it draws each as. :point is the one that has it: it draws :size as a radius and :alpha as an opacity. The plan reads this to decide whether a column mapped to an aesthetic is drawn at all:
(:varies (layer-type/lookup :point)){:size :radius, :alpha :opacity}Every other mark draws one size and one opacity for the whole layer, so a column mapped to those aesthetics changes nothing, and Plotje warns. See Extensibility for declaring :varies on a layer type of your own.
:text and :label share a mark, a stat, and a position; the “Presets” column shows that a label starts with its box switched on:
(mapv #(select-keys (layer-type/lookup %) [:mark :stat :defaults])
[:text :label])[{:mark :text, :stat :identity}
{:mark :text, :stat :identity, :defaults {:box true}}]The “Position” column shows each layer-type’s registered default. A few marks (:bar, :lollipop, :boxplot, :violin) carry no registered default and the table therefore lists :identity for them, but they apply :dodge when the plot is planned, if a categorical color or group splits the data into multiple sub-bars per category. So a colored (pj/lay-bar data :cohort {:color :site}) produces dodged bars even though the table shows :identity for :bar. To force a different layout, write :position in the layer’s mapping.
Marks
A mark is the visual shape shown for each data point or group. Several layer types may share the same mark – for instance, tile and density-2d both produce tiles, and line and smooth both produce lines.
(kind/table
{:column-names ["Mark" "Shape" "Used by"]
:row-maps
(for [mk (distinct-in-order :mark)]
{"Mark" (kind/code (pr-str mk))
"Shape" (pj/mark-doc mk)
"Used by" (used-by :mark mk)})})| Mark | Shape | Used by |
|---|---|---|
|
Filled circle | point |
|
Connected path | line, smooth |
|
Horizontal-then-vertical path | step |
|
Filled region under a curve | area, density |
|
Vertical rectangles (binned) | histogram |
|
Positioned rectangles | bar |
|
Grid of colored cells | density-2d, tile |
|
Iso-value polylines | contour |
|
Box-and-whisker | boxplot |
|
Mirrored density shape | violin |
|
Stacked density curves | ridgeline |
|
Point with error bar | summary |
|
Vertical error bar | errorbar |
|
Stem with dot | lollipop |
|
Data-driven label, optionally on a background box | label, text |
|
Axis-margin tick marks | rug |
|
Horizontal bars from x to x-end at categorical y | interval-h |
|
Straight lines from (x, y) to (x-end, y-end) | segment |
|
Horizontal reference line at a written y | rule-h |
|
Vertical reference line at a written x | rule-v |
|
Horizontal shaded band between two written y values | band-h |
|
Vertical shaded band between two written x values | band-v |
Stats
A stat (statistical transform) processes raw data before rendering. Each stat takes data-space inputs and produces the geometry that its mark will show.
(kind/table
{:column-names ["Stat" "What it computes" "Used by"]
:row-maps
(for [st (distinct-in-order :stat)]
{"Stat" (kind/code (pr-str st))
"What it computes" (pj/stat-doc st)
"Used by" (used-by :stat st)})})| Stat | What it computes | Used by |
|---|---|---|
|
Pass-through -- no transform | area, band-h, band-v, bar, errorbar, interval-h, label, line, lollipop, point, rug, rule-h, rule-v, segment, step, text |
|
Bin numerical values into ranges | histogram |
|
(no description) | |
|
LOESS (local regression) smoothing | smooth |
|
Density -- 1D kernel density estimation (KDE) | density |
|
2D grid binning (heatmap counts) | tile |
|
Density 2D -- 2D Gaussian kernel density estimation (KDE) | contour, density-2d |
|
Five-number summary + outliers | boxplot |
|
KDE per category (density profile) | ridgeline, violin |
|
Mean +/- standard error per category | summary |
Positions
A position adjustment determines how groups share a categorical axis slot. Position runs between stat computation and rendering.
(kind/table
{:column-names ["Position" "What it does" "Used by"]
:row-maps
(for [pos [:identity :dodge :stack :fill]]
{"Position" (kind/code (pr-str pos))
"What it does" (pj/position-doc pos)
"Used by" (used-by :position pos)})})| Position | What it does | Used by |
|---|---|---|
|
Plot at exact data coordinates (groups overlap) | area, band-h, band-v, bar, boxplot, contour, density, density-2d, errorbar, histogram, interval-h, label, line, lollipop, point, ridgeline, rug, rule-h, rule-v, segment, smooth, step, summary, text, tile, violin |
|
Shift groups side-by-side within a band | |
|
Pile groups cumulatively, the first group on top | |
|
Stack normalized to [0, 1] (proportions) |
You can override the default position by writing :position in the layer’s mapping. When multiple layers share :position :dodge, they are coordinated together – error bars automatically align with bars.
A Layer’s Mapping
The mapping passed to a pj/lay-* function takes that layer’s aesthetics and its layer settings: statistical parameters, the position adjustment, the layer’s own data.
Keys every layer type accepts
(kind/table
{:column-names ["Key" "Description"]
:row-maps
(for [k layer-type/universal-mapping-keys]
{"Key" (kind/code (pr-str k))
"Description" (get layer-type/layer-mapping-docs k)})})| Key | Description |
|---|---|
|
Column keyword or string naming the column drawn along the x axis, or a value to draw at that x. A value beside a column :y broadcasts over the layer's data; values for both :x and :y draw one mark |
|
Column keyword or string naming the column drawn along the y axis, or a value to draw at that y. The same two shapes as :x |
|
A column of the layer's data, or a color -- a hex string with its #, a CSS name, or a keyword naming one. The data decides: a column called blue wins over the color of that name, and {:value "blue"} or {:column "blue"} insists. A column always passes through the color scale; {:color {:column :hex :scale false}} draws the colors it holds |
|
Read the color column as a type other than its own. :categorical gives a numeric column one color per distinct value instead of a gradient. Same rule as :x-type: only :categorical can be asked of a column holding something else |
|
A column of the layer's data (per-row opacity), or a number within 0 and 1 for the whole layer. A column is scaled and a written number is drawn; {:alpha {:column :r :scale false}} reads the column as opacities, {:alpha {:value 0.3 :scale true}} sends the number through the scale |
|
A column of the layer's data, or a vector of them, grouping without color |
|
Position adjustment keyword -- how overlapping groups are arranged (see pj/position-doc) |
|
Dataset or plain data for this layer alone, overriding the pose's |
|
Read the x column as a type other than its own -- :categorical, :numerical or :temporal. Only :categorical can be asked of a column holding something else, because every value can name a group: it puts numbers (hours, years, identifiers) or dates on a categorical axis, which a bar or a boxplot needs. The other two are accepted where they name the column's own type and refused where they do not |
|
Mirror of :x-type, on the y column. Used for horizontal layouts |
|
Override the mark the layer type draws with -- the shape on the panel |
|
Override the statistic the layer type computes -- e.g. {:stat :count} on a text layer labels counted bars |
|
Shift the whole layer right by this many drawing units, after the scales. Unlike :dx the amount is a distance on the page rather than in the axis's units, so it means the same on every axis and does not move the axis domain -- use it to clear a label of the mark it labels |
|
Shift the whole layer down by this many drawing units, after the scales. See :offset-x |
|
The space this layer's :x and :y are in -- :data (default, values mapped through the scales) or :drawing-area (drawing units from the top left of the panel background). It does not widen to the other aesthetics; to take one axis off its scale on its own, write {:y {:column :b :scale false}}. An unscaled layer is placed on the panel rather than in the data, so it does not move the axis domains |
|
What a mark says on hover: a column of the layer's data, one value per row, or one value every mark of the layer shows. A string is shown as it stands, so format it in the data language before plotting -- a currency sign, a thousands separator, a value from a column the layer does not draw -- and a newline in it breaks the line. A hiccup vector is drawn as markup, for a label carrying a heading or an emphasis; a string that spells out a tag is shown as that text. Writing it turns tooltips on, so `{:tooltip true}` in pj/options is not also needed. Read by the point and interval-h marks; a tooltip written on any other layer type is reported and draws none |
Layer-type-specific keys
Some layer types accept additional keys beyond the keys every layer type accepts. Layer types not listed here accept only the keys in the table above.
(kind/table
{:column-names ["Layer type" "Additional keys"]
:row-maps
(for [k layer-type/layer-type-order
:let [m (layer-type/lookup k)
accepts (:accepts m)]
:when (seq accepts)]
{"Layer type" (kind/code (pr-str k))
"Additional keys" accepts})})| Layer type | Additional keys |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
All keys of a layer’s mapping
(kind/table
{:column-names ["Key" "Description"]
:row-maps
(for [[k desc] (sort-by key layer-type/layer-mapping-docs)]
{"Key" (kind/code (pr-str k))
"Description" desc})})| Key | Description |
|---|---|
|
Horizontal text anchor -- :left, :center, or :right (default :left); which part of the label sits at its x |
|
Vertical text anchor -- :top, :center, or :bottom (default :center); which part of the label sits at its y. Data-oriented: :top puts the label's top edge at the point |
|
A column of the layer's data (per-row opacity), or a number within 0 and 1 for the whole layer. A column is scaled and a written number is drawn; {:alpha {:column :r :scale false}} reads the column as opacities, {:alpha {:value 0.3 :scale true}} sends the number through the scale |
|
Which ends of a segment carry an arrow head: :end, :start or :both. true means :end |
|
Smoothing bandwidth for density and LOESS methods |
|
How wide a bar is drawn, in the unit its axis offers. On a categorical axis, the fraction (0.0-1.0) of the category band the bar fills, as :box-width is for a box; defaults to 0.8. On a numeric or temporal axis, where there is no band, a width in data units; defaults to 0.9 of the smallest gap between adjacent x values. |
|
Number of histogram bins, overriding the :bin-method estimate |
|
Width of one histogram bin in data units, an alternative to :bins |
|
Number of bootstrap resamples for a LOESS confidence ribbon (default 200) |
|
Background box behind text -- true for the default box, false or absent for none, or a map of box properties: {:corner-radius n} in drawing units (default 3, 0 for square corners). pj/lay-label is pj/lay-text with the box on |
|
Fraction (0.0-1.0) of the categorical band that a box fills (default 0.6) |
|
Width of an errorbar's end caps in drawing units |
|
A column of the layer's data, or a color -- a hex string with its #, a CSS name, or a keyword naming one. The data decides: a column called blue wins over the color of that name, and {:value "blue"} or {:column "blue"} insists. A column always passes through the color scale; {:color {:column :hex :scale false}} draws the colors it holds |
|
Read the color column as a type other than its own. :categorical gives a numeric column one color per distinct value instead of a gradient. Same rule as :x-type: only :categorical can be asked of a column holding something else |
|
true to show a standard-error confidence ribbon around the fitted line |
|
Dataset or plain data for this layer alone, overriding the pose's |
|
2D density grid resolution -- number of bins per axis (default 25) |
|
Shift all x-coordinates by this amount in the axis's own units -- a data value on a numerical or temporal axis, one band on a categorical one, where 0.5 is half a band along. The unit is whatever :x is measured in, which is why the name says a change in x without naming a unit; for a shift measured on the page, see :offset-x |
|
Shift all y-coordinates by this amount in the axis's own units. See :dx |
|
A column of the layer's data holding tile fill values (pre-computed heatmap) |
|
Text height in drawing units for a text or label mark (default 10) |
|
Draws the text italic -- :normal (default) or :italic |
|
Draws the text bold -- :normal (default) or :bold |
|
A column of the layer's data, or a vector of them, grouping without color |
|
The space this layer's :x and :y are in -- :data (default, values mapped through the scales) or :drawing-area (drawing units from the top left of the panel background). It does not widen to the other aesthetics; to take one axis off its scale on its own, write {:y {:column :b :scale false}}. An unscaled layer is placed on the panel rather than in the data, so it does not move the axis domains |
|
Fraction (0.0-1.0) of the categorical band that an interval bar fills (default 0.7) |
|
true or an amount in drawing units -- random offset to reduce overplotting |
|
Length of a rug tick in drawing units |
|
Confidence level of a smooth's ribbon (default 0.95) |
|
Number of contour iso-levels (default 5) |
|
Override the mark the layer type draws with -- the shape on the panel |
|
Histogram normalization -- :density (area integrates to 1) or nil |
|
Shift the whole layer right by this many drawing units, after the scales. Unlike :dx the amount is a distance on the page rather than in the axis's units, so it means the same on every axis and does not move the axis domain -- use it to clear a label of the mark it labels |
|
Shift the whole layer down by this many drawing units, after the scales. See :offset-x |
|
Position adjustment keyword -- how overlapping groups are arranged (see pj/position-doc) |
|
A column of the layer's data, one symbol per category; or one symbol for the whole layer, from the list pj/shape-symbols gives |
|
Which axis margin a rug's ticks are drawn in -- :x (default), :y, or :both |
|
A column of the layer's data, or a positive number -- point radius or stroke width. A column is scaled and a written number is drawn; {:size {:column :r :scale false}} reads the column as radii, {:size {:value 7 :scale true}} sends the number through the scale |
|
Override the statistic the layer type computes -- e.g. {:stat :count} on a text layer labels counted bars |
|
Outline color for an area or density curve -- the fill still comes from :color |
|
Dash pattern for a line, step, smooth, reference line, or area outline -- :dashed, :dotted, :solid, or a raw [dash gap ...] pattern in drawing units |
|
Width of that outline in drawing units |
|
A column of the layer's data, or a string, which labels every row with itself |
|
What a mark says on hover: a column of the layer's data, one value per row, or one value every mark of the layer shows. A string is shown as it stands, so format it in the data language before plotting -- a currency sign, a thousands separator, a value from a column the layer does not draw -- and a newline in it breaks the line. A hiccup vector is drawn as markup, for a label carrying a heading or an emphasis; a string that spells out a tag is shown as that text. Writing it turns tooltips on, so `{:tooltip true}` in pj/options is not also needed. Read by the point and interval-h marks; a tooltip written on any other layer type is reported and draws none |
|
Whether a density curve is estimated only over its own group's values. Density defaults to false (every group spans the whole layer's range); violin and ridgeline default to true (each body ends at its category's values) |
|
Column keyword or string naming the column drawn along the x axis, or a value to draw at that x. A value beside a column :y broadcasts over the layer's data; values for both :x and :y draw one mark |
|
A column of the layer's data, or a written value, for where a mark ends on x: the right edge of a horizontal interval bar, or the x a segment is drawn to. A written value ends every mark alike; a bare name is read as a column, so a category is written {:x-end {:value "Q4"}}. On a segment, leaving it out ends each segment at its own x |
|
Numeric or temporal x value a vertical reference line is drawn at. The same two shapes as :y-intercept |
|
Upper x bound of a vertical shaded band. The same two shapes as :x-min |
|
Lower x bound of a vertical shaded band, as a number or a date. Only lay-band-v reads it, and it reads the value straight from the mapping, so this names no column; {:value 1.5} says the same thing at more length |
|
Read the x column as a type other than its own -- :categorical, :numerical or :temporal. Only :categorical can be asked of a column holding something else, because every value can name a group: it puts numbers (hours, years, identifiers) or dates on a categorical axis, which a bar or a boxplot needs. The other two are accepted where they name the column's own type and refused where they do not |
|
Column keyword or string naming the column drawn along the y axis, or a value to draw at that y. The same two shapes as :x |
|
A column of the layer's data, or a written value, for the y a segment is drawn to. A written value ends every segment alike, so {:y-end 0} draws stems from the zero line; a bare name is read as a column, so a category is written {:y-end {:value "high"}}. Leaving it out ends each segment at its own y |
|
Numeric or temporal y value a horizontal reference line is drawn at. Read straight from the mapping, so it names no column; {:value 2.0} says the same thing at more length |
|
A column of the layer's data, for an errorbar's upper bound; or a number, for a horizontal band's upper edge. The same two shapes as :y-min |
|
A column of the layer's data, for an errorbar's lower bound; or a number, for a horizontal band's lower edge. Which one the layer type decides, and {:column :lo} or {:value 12} says the same thing at more length |
|
Mirror of :x-type, on the y column. Used for horizontal layouts |
What’s Next
Glossary – the last chapter of Foundations, a reference of terms to look up when you meet them
Relationships – see point, line, and regression layer types in action
Distributions – histograms, density, boxplots, violins
Customization – colors, palettes, themes, and per-layer styling