9  Scatter

Point mark variations — color, size, alpha, shape, jitter, and continuous color scale.

(ns napkinsketch-book.scatter
  (: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]))

Basic Scatter

Sepal dimensions, no color — the default mark.

(-> data/iris
    (sk/lay-point :sepal_length :sepal_width))

Colored by Species

Adding :color :species groups points by species with distinct colors.

(-> data/iris
    (sk/lay-point :sepal_length :sepal_width {:color :species}))

Petal Dimensions

Petal length vs width — a strongly correlated pair.

(-> data/iris
    (sk/lay-point :petal_length :petal_width {:color :species}))

Fixed Color

A fixed color string (not a column reference) applies to all points.

(-> data/iris
    (sk/lay-point :sepal_length :sepal_width {:color "#E74C3C"}))

Custom Dimensions

Wider plot with custom title and labels.

(-> data/tips
    (sk/lay-point :total_bill :tip {:color :day})
    (sk/options {:width 700 :height 300
                 :title "Tips by Day"
                 :x-label "Total Bill ($)"
                 :y-label "Tip ($)"}))

Bubble Plot

Map :size to a numeric column to create a bubble plot. Each point’s radius reflects the column value.

(-> data/tips
    (sk/lay-point :total_bill :tip {:color :day :size :size}))

Combine size with alpha for dense data.

(-> data/tips
    (sk/lay-point :total_bill :tip {:color :day :size :size :alpha 0.6}))

Jitter

When plotting a numeric column against a categorical column, points overlap. Use :jitter true to add random pixel offsets.

(-> data/iris
    (sk/lay-point :species :sepal_width {:jitter true}))

Control the jitter amount in pixels.

(-> data/iris
    (sk/lay-point :species :sepal_width {:jitter 10 :alpha 0.5}))

Continuous Color

When :color maps to a numeric column, Napkinsketch uses a continuous blue gradient instead of discrete palette colors.

(-> data/iris
    (sk/lay-point :sepal_length :sepal_width {:color :petal_length}))

Continuous color with size — a color-size bubble plot.

(-> data/iris
    (sk/lay-point :sepal_length :sepal_width {:color :petal_length :size :petal_width :alpha 0.7}))

Scatter Plot Matrix (SPLOM)

sk/cross generates all combinations of two lists. Passing column names produces a grid of scatter plots — one per pair of variables. The diagonal shows histograms (automatic inference for same-column pairs).

(def cols [:sepal_length :sepal_width :petal_length :petal_width])

(-> data/iris
    (sk/view (sk/cross cols cols) {:color :species})
    sk/lay-point)

See the Faceting chapter for more SPLOM variations, including brush selection.

What’s Next

• Distributions — histograms, density curves, boxplots, violins
• Relationships — heatmaps, contours, and 2D density
• Customization — colors, palettes, themes, and annotations

source: notebooks/napkinsketch_book/scatter.clj