8  Glossary

Key terms used throughout Napkinsketch, with brief definitions and code examples.

(ns napkinsketch-book.glossary
  (:require
   ;; Shared datasets for these docs
   [napkinsketch-book.datasets :as data]
   ;; Kindly β€” notebook rendering protocol
   [scicloj.kindly.v4.kind :as kind]
   ;; Napkinsketch β€” composable plotting
   [scicloj.napkinsketch.api :as sk]
   ;; Method constructors β€” for inspecting method maps
   [scicloj.napkinsketch.method :as method]))

View

A view is a map describing what to plot: data and column-to-channel mappings β€” which columns map to :x, :y, :color, :size, and other visual channels. sk/view sets the shared mappings; layer functions (sk/lay-point, sk/lay-lm, etc.) add methods on top.

(def views
  (-> data/iris
      (sk/lay-point :sepal_length :sepal_width {:color :species})))
(kind/pprint views)
{:views
 [{:data
   https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv [150 5]:

| :sepal_length | :sepal_width | :petal_length | :petal_width |  :species |
|--------------:|-------------:|--------------:|-------------:|-----------|
|           5.1 |          3.5 |           1.4 |          0.2 |    setosa |
|           4.9 |          3.0 |           1.4 |          0.2 |    setosa |
|           4.7 |          3.2 |           1.3 |          0.2 |    setosa |
|           4.6 |          3.1 |           1.5 |          0.2 |    setosa |
|           5.0 |          3.6 |           1.4 |          0.2 |    setosa |
|           5.4 |          3.9 |           1.7 |          0.4 |    setosa |
|           4.6 |          3.4 |           1.4 |          0.3 |    setosa |
|           5.0 |          3.4 |           1.5 |          0.2 |    setosa |
|           4.4 |          2.9 |           1.4 |          0.2 |    setosa |
|           4.9 |          3.1 |           1.5 |          0.1 |    setosa |
|           ... |          ... |           ... |          ... |       ... |
|           6.9 |          3.1 |           5.4 |          2.1 | virginica |
|           6.7 |          3.1 |           5.6 |          2.4 | virginica |
|           6.9 |          3.1 |           5.1 |          2.3 | virginica |
|           5.8 |          2.7 |           5.1 |          1.9 | virginica |
|           6.8 |          3.2 |           5.9 |          2.3 | virginica |
|           6.7 |          3.3 |           5.7 |          2.5 | virginica |
|           6.7 |          3.0 |           5.2 |          2.3 | virginica |
|           6.3 |          2.5 |           5.0 |          1.9 | virginica |
|           6.5 |          3.0 |           5.2 |          2.0 | virginica |
|           6.2 |          3.4 |           5.4 |          2.3 | virginica |
|           5.9 |          3.0 |           5.1 |          1.8 | virginica |
,
   :x :sepal_length,
   :y :sepal_width,
   :mark :point,
   :stat :identity,
   :accepts [:size :shape :jitter :text :nudge-x :nudge-y],
   :doc "Scatter β€” individual data points.",
   :color :species,
   :__base
   {:data
    https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv [150 5]:

| :sepal_length | :sepal_width | :petal_length | :petal_width |  :species |
|--------------:|-------------:|--------------:|-------------:|-----------|
|           5.1 |          3.5 |           1.4 |          0.2 |    setosa |
|           4.9 |          3.0 |           1.4 |          0.2 |    setosa |
|           4.7 |          3.2 |           1.3 |          0.2 |    setosa |
|           4.6 |          3.1 |           1.5 |          0.2 |    setosa |
|           5.0 |          3.6 |           1.4 |          0.2 |    setosa |
|           5.4 |          3.9 |           1.7 |          0.4 |    setosa |
|           4.6 |          3.4 |           1.4 |          0.3 |    setosa |
|           5.0 |          3.4 |           1.5 |          0.2 |    setosa |
|           4.4 |          2.9 |           1.4 |          0.2 |    setosa |
|           4.9 |          3.1 |           1.5 |          0.1 |    setosa |
|           ... |          ... |           ... |          ... |       ... |
|           6.9 |          3.1 |           5.4 |          2.1 | virginica |
|           6.7 |          3.1 |           5.6 |          2.4 | virginica |
|           6.9 |          3.1 |           5.1 |          2.3 | virginica |
|           5.8 |          2.7 |           5.1 |          1.9 | virginica |
|           6.8 |          3.2 |           5.9 |          2.3 | virginica |
|           6.7 |          3.3 |           5.7 |          2.5 | virginica |
|           6.7 |          3.0 |           5.2 |          2.3 | virginica |
|           6.3 |          2.5 |           5.0 |          1.9 | virginica |
|           6.5 |          3.0 |           5.2 |          2.0 | virginica |
|           6.2 |          3.4 |           5.4 |          2.3 | virginica |
|           5.9 |          3.0 |           5.1 |          1.8 | virginica |
,
    :x :sepal_length,
    :y :sepal_width}}],
 :opts {},
 :kindly/f #'scicloj.napkinsketch.api/render-sketch}

Sketch

A sketch is the value returned by layer functions (sk/lay-point, sk/lay-histogram, etc.) and by sk/options. It wraps one or more views together with plot options and auto-renders in Kindly-compatible tools like Clay.

You can inspect or decompose a sketch using sk/sketch? and sk/views-of:

(def my-sketch
  (-> data/iris
      (sk/lay-point :sepal_length :sepal_width {:color :species})
      (sk/options {:title "Iris"})))
(sk/sketch? my-sketch)
true
(count (sk/views-of my-sketch))
1

Method

A method is the bundle of mark + stat + position that determines how data becomes a visual element. See the Methods chapter for detailed tables of all built-in methods, marks, stats, and positions.

Mark

The mark is the visual shape drawn for each data point or group. Several methods may share the same mark β€” for instance, lm and loess both draw lines, and area, stacked-area, and density all draw filled regions. See the Methods chapter for a table of all built-in marks.

Stat

A stat (statistical transform) processes raw data before rendering. Each stat takes data-space inputs and produces the geometry that its mark will draw. See the Methods chapter for a table of all built-in stats.

Position

A position adjustment determines how groups share a categorical axis slot. Position runs between stat computation and rendering. You can override the default position by passing :position in the layer options. When multiple layers share :position :dodge, they are coordinated together β€” error bars automatically align with bars. See the Methods chapter for a table of all built-in positions.

(def tips {:day ["Mon" "Mon" "Tue" "Tue"]
           :count [30 20 45 15]
           :meal ["lunch" "dinner" "lunch" "dinner"]})
(-> tips
    (sk/lay-value-bar :day :count {:color :meal :position :stack})
    sk/plan
    (get-in [:panels 0 :layers 0 :groups 1 :y0s]))
[30.0 45.0]

Aesthetic

An aesthetic is a visual property of a mark that can be mapped to a data column. Napkinsketch supports these aesthetic mappings:

Key Controls Column type
:color Fill/stroke color Categorical or numerical
:size Point radius Numerical
:alpha Opacity Numerical
:shape Point shape Categorical
:text Label content Any
:fill Tile gradient color Numerical

When a keyword is passed, it maps to a dataset column. A literal value (e.g., "#E74C3C", "red", 0.5) sets a fixed aesthetic for all points.

(merge (method/lookup :point) {:color :species :size :petal_length :alpha 0.7})
{:mark :point,
 :stat :identity,
 :accepts [:size :shape :jitter :text :nudge-x :nudge-y],
 :doc "Scatter β€” individual data points.",
 :color :species,
 :size :petal_length,
 :alpha 0.7}

Group

A group is a subset of data that is processed and drawn together. Mapping :color to a categorical column automatically creates groups β€” one per unique value. You can also create groups without color using the :group key.

(-> data/iris
    (sk/lay-line :sepal_length :sepal_width {:group :species})
    sk/plan
    (get-in [:panels 0 :layers 0 :groups])
    count)
3

Nudge

A nudge shifts data coordinates by a constant offset. It is orthogonal to position β€” you can nudge within a dodge, or nudge at identity. Applied via :nudge-x and :nudge-y keys in the layer options.

(-> {:x [1 2 3] :y [4 5 6]}
    (sk/lay-point :x :y {:nudge-x 0.5})
    sk/plan
    (get-in [:panels 0 :layers 0 :groups 0 :xs]))
[1.5 2.5 3.5]

Jitter

Jitter adds random pixel-space offsets to reduce overplotting. Unlike position and nudge, jitter operates in pixel space (not data space) and is deterministic β€” seeded by group color for reproducibility.

On categorical x-axes, jitter is applied along the band axis only.

(merge (method/lookup :point) {:jitter true})
{:mark :point,
 :stat :identity,
 :accepts [:size :shape :jitter :text :nudge-x :nudge-y],
 :doc "Scatter β€” individual data points.",
 :jitter true}

Plan

A plan is the fully resolved intermediate representation β€” a plain Clojure map containing everything needed to render a plot: data-space geometry, domains, tick info, legend, layout dimensions. No membrane types, no datasets, no scale objects.

Created with sk/plan. Numeric arrays (:xs, :ys, etc.) are dtype-next buffers for efficiency.

(def my-plan (sk/plan views))
(sort (keys my-plan))
(:alpha-legend
 :caption
 :grid
 :height
 :layout
 :layout-type
 :legend
 :legend-position
 :margin
 :panel-height
 :panel-width
 :panels
 :size-legend
 :subtitle
 :title
 :total-height
 :total-width
 :width
 :x-label
 :y-label)

Panel

A panel is a single plotting area within a plan. It contains x/y domains, scale specs, tick info, coordinate type, and layers. A simple plot has one panel; sk/facet and sk/facet-grid produce multiple.

(sort (keys (first (:panels my-plan))))
(:col
 :coord
 :layers
 :row
 :x-domain
 :x-scale
 :x-ticks
 :y-domain
 :y-scale
 :y-ticks)

Layer

A layer is a plan-level descriptor: resolved mark type, style, and groups of data-space geometry. Layers live inside panels in the plan.

(-> views
    sk/plan
    (get-in [:panels 0 :layers 0]))
{:mark :point,
 :style {:opacity 0.75, :radius 3.0},
 :groups
 [{:color
   [0.8941176470588236 0.10196078431372549 0.10980392156862745 1.0],
   :xs #tech.v3.dataset.column<float64>[50]
:sepal_length
[5.100, 4.900, 4.700, 4.600, 5.000, 5.400, 4.600, 5.000, 4.400, 4.900, 5.400, 4.800, 4.800, 4.300, 5.800, 5.700, 5.400, 5.100, 5.700, 5.100...],
   :ys #tech.v3.dataset.column<float64>[50]
:sepal_width
[3.500, 3.000, 3.200, 3.100, 3.600, 3.900, 3.400, 3.400, 2.900, 3.100, 3.700, 3.400, 3.000, 3.000, 4.000, 4.400, 3.900, 3.500, 3.800, 3.800...],
   :label "setosa",
   :row-indices #tech.v3.dataset.column<int64>[50]
:__row-idx
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19...]}
  {:color
   [0.21568627450980393 0.49411764705882355 0.7215686274509804 1.0],
   :xs #tech.v3.dataset.column<float64>[50]
:sepal_length
[7.000, 6.400, 6.900, 5.500, 6.500, 5.700, 6.300, 4.900, 6.600, 5.200, 5.000, 5.900, 6.000, 6.100, 5.600, 6.700, 5.600, 5.800, 6.200, 5.600...],
   :ys #tech.v3.dataset.column<float64>[50]
:sepal_width
[3.200, 3.200, 3.100, 2.300, 2.800, 2.800, 3.300, 2.400, 2.900, 2.700, 2.000, 3.000, 2.200, 2.900, 2.900, 3.100, 3.000, 2.700, 2.200, 2.500...],
   :label "versicolor",
   :row-indices #tech.v3.dataset.column<int64>[50]
:__row-idx
[50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69...]}
  {:color
   [0.30196078431372547 0.6862745098039216 0.2901960784313726 1.0],
   :xs #tech.v3.dataset.column<float64>[50]
:sepal_length
[6.300, 5.800, 7.100, 6.300, 6.500, 7.600, 4.900, 7.300, 6.700, 7.200, 6.500, 6.400, 6.800, 5.700, 5.800, 6.400, 6.500, 7.700, 7.700, 6.000...],
   :ys #tech.v3.dataset.column<float64>[50]
:sepal_width
[3.300, 2.700, 3.000, 2.900, 3.000, 3.000, 2.500, 2.900, 2.500, 3.600, 3.200, 2.700, 3.000, 2.500, 2.800, 3.200, 3.000, 3.800, 2.600, 2.200...],
   :label "virginica",
   :row-indices #tech.v3.dataset.column<int64>[50]
:__row-idx
[100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119...]}],
 :y-domain [2.0 4.4],
 :x-domain [4.3 7.9]}

Facet

A facet splits data into multiple panels by a categorical column. Each panel shows a subset of the data, sharing the same scales for easy comparison.

  • sk/facet creates a row or column of panels
  • sk/facet-grid creates a row Γ— column grid from two columns

By default all panels share the same axis ranges. Use (sk/options {:scales ...}) to allow panels to have independent ranges: :shared (default), :free-x, :free-y, or :free.

(-> data/iris
    (sk/lay-point :sepal_length :sepal_width)
    (sk/facet :species)
    sk/plan :panels count)
3

Domain

A domain is the range of data values along an axis.

  • Numerical: [min max] with padding (e.g., [4.0 8.2])
  • Categorical: sequence of distinct values (e.g., ["setosa" "versicolor" "virginica"])
(let [p (first (:panels my-plan))]
  {:x-domain (:x-domain p)
   :y-domain (:y-domain p)})
{:x-domain [4.12 8.08], :y-domain [1.88 4.5200000000000005]}

Scale

A scale maps data values to pixel positions. Built from a domain and a pixel range using wadogo.

Type Use
:linear Numerical data (default)
:log Orders-of-magnitude data
:categorical Distinct categories (band scale)

Scales are created at render time, not stored in the plan. The plan stores scale specs (:type, :domain).

Temporal columns (LocalDate, LocalDateTime, Instant, java.util.Date) are automatically detected and treated as numerical. Tick labels are calendar-aware β€” snapped to year, month, day, or hour boundaries depending on the time span.

Coord

A coord (coordinate system) defines how data-space maps to pixel-space.

Type Behavior
:cartesian Standard x→right, y→up
:flip Swap x and y axes
:polar Radial: x→angle, y→radius

Annotation

An annotation is a non-data mark that adds visual reference to a plot. Annotations are not connected to data columns β€” they overlay fixed positions.

Constructor What
sk/rule-v Vertical line at x = value
sk/rule-h Horizontal line at y = value
sk/band-v Vertical shaded region from x₁ to xβ‚‚
sk/band-h Horizontal shaded region from y₁ to yβ‚‚ 
(:mark (sk/rule-h 5))
:rule-h

Legend

A legend is generated automatically when a color (or shape) aesthetic maps to a data column. It appears in the plan as a :legend key containing entries with labels and colors. Position is controlled via {:legend-position :bottom} in options.

(:legend my-plan)
{:title :species,
 :entries
 [{:label "setosa",
   :color
   [0.8941176470588236 0.10196078431372549 0.10980392156862745 1.0]}
  {:label "versicolor",
   :color
   [0.21568627450980393 0.49411764705882355 0.7215686274509804 1.0]}
  {:label "virginica",
   :color
   [0.30196078431372547 0.6862745098039216 0.2901960784313726 1.0]}]}

Theme

A theme controls the visual appearance of non-data elements: background color, grid lines, font sizes, margins. Passed as {:theme {...}} via sk/options or directly to sk/plan.

(-> data/iris
    (sk/lay-point :sepal_length :sepal_width {:color :species})
    (sk/options {:theme {:background "#2d2d2d" :grid "#444444"
                         :text "#cccccc" :tick "#999999"}})
    sk/svg-summary :panels)
1

Membrane

A membrane is a value of the Membrane library β€” a tree of layout and drawing primitives (Translate, WithColor, RoundedRectangle, Label, etc.) that represents a complete plot.

The membrane is an intermediate step in the SVG rendering path: plan β†’ membrane β†’ SVG hiccup. Direct renderers (e.g., Plotly) skip the membrane entirely.

(def my-membrane (sk/plan->membrane my-plan))
(vector? my-membrane)
true
(count my-membrane)
7

Figure

A figure is the final rendered output β€” the result of rendering a plan to a specific format. For SVG, the figure is hiccup markup wrapped in kind/hiccup.

Created by sk/plot or by auto-rendering a sketch.

(def my-figure (sk/plan->figure my-plan :svg {}))
(first my-figure)
:svg

Palette

A palette is an ordered set of colors used for categorical aesthetics. When :color maps to a categorical column, colors are assigned from the active palette in order.

Napkinsketch uses clojure2d for palettes β€” over 7,000 named palettes are available. Set via {:palette :set2} in options.

Gradient

A gradient (or color scale) maps a continuous numeric range to a smooth color ramp. Used when :color maps to a numerical column.

Common gradients: :viridis, :inferno, :plasma, :magma. Diverging gradients center on a midpoint value. Set via {:color-scale :inferno} in options.

Configuration

Configuration controls rendering behavior β€” dimensions, theme, palette, color scale, margins, and more. It is one of three option scopes β€” the others are plot options and layer options. Configuration follows a precedence chain:

plot options > sk/with-config > sk/set-config! > napkinsketch.edn > library defaults

napkinsketch.edn is an optional file in your project root that provides project-level defaults (e.g., a consistent palette or theme across all plots).

See the Configuration chapter for details.

Plot Options

Plot options are per-plot settings passed to sk/options, sk/plan, or sk/plot. They include text content (title, subtitle, caption, axis labels) and a nested :config override. Unlike configuration keys, plot options are inherently per-plot β€” a title does not make sense as a global default.

See sk/plot-option-docs for the full list, or the Configuration chapter for usage examples.

(count sk/plot-option-docs)
6

Layer Options

Layer options are per-layer settings passed in the options map of layer functions (sk/lay-point, sk/lay-histogram, etc.). They control aesthetics (:color, :size, :alpha, :shape), grouping (:group), position adjustment (:position), and method-specific parameters (:bandwidth, :se, :normalize, etc.).

Four keys are universal β€” accepted by every layer β€” and each method may accept additional keys. The Methods chapter lists which options each method accepts. See also sk/layer-option-docs for descriptions, or inspect a specific method with sk/method-lookup.

(count sk/layer-option-docs)
20

Tooltip and Brush

A tooltip shows data values on hover. A brush enables click-and-drag selection that highlights a rectangular region. Both are JavaScript-based interactions added to the SVG output.

Enabled via {:tooltip true} and {:brush true} in options.

Summary Table

Term What Lifetime
View Map: data + column-to-channel mappings + method User builds, consumed by plan
Sketch Auto-rendering wrapper (views + options) Returned by layer functions
Method Mark + stat + position bundle Looked up via method/lookup; added by sk/lay-point, sk/lay-histogram, etc.
Mark Visual type: point, line, bar, … Key in view map
Aesthetic Data-driven visual property: color, size, alpha, shape Key in view map
Group Subset of data drawn together (from :color or :group) Created during stat computation
Stat Data transform: identity, bin, count, lm (linear model), kde (kernel density), etc. Computed during plan resolution
Position How groups share space: dodge, stack, fill, identity Applied between stat and rendering
Nudge Constant data-space offset (:nudge-x, :nudge-y) Applied during layer extraction
Jitter Random pixel offset to reduce overplotting Applied at render time
Layer Resolved geometry + style for one mark Lives inside plan panels
Plan Complete resolved plot description Inspectable (dtype-next buffers for numerics)
Panel One plotting area (domain, ticks, layers) One or more per plan
Facet Split data into panels by a categorical column Configured on views, realized in plan
Domain Data range on an axis Part of panel
Scale Data β†’ pixel mapping Created at render time
Coord Coordinate system (cartesian, flip, polar) Applied at render time
Annotation Non-data reference marks (rules, bands) Overlay on panels
Legend Color/shape key generated from aesthetic mappings Part of plan
Theme Visual styling: background, grid, fonts, margins Passed in options, merged with defaults
Membrane Drawable tree (membrane library) Intermediate (SVG path only)
Figure Final output (SVG hiccup, Plotly spec, …) Returned to user
Palette Ordered color set for categorical aesthetics Resolved at render time
Gradient Continuous color ramp for numerical color mappings Resolved at render time
Configuration Rendering options: dimensions, theme, palette, etc. Layered precedence chain
Plot Options Title, subtitle, caption, labels β€” per-plot text content Passed to sk/options
Layer Options Per-layer aesthetics, grouping, position, and method parameters Passed to layer functions
Tooltip / Brush JavaScript hover and selection interactions Added to SVG output 
source: notebooks/napkinsketch_book/glossary.clj