2  Quickstart

A minimal introduction to Napkinsketch

Setup

Add Napkinsketch to your deps.edn:

{:deps {org.scicloj/napkinsketch {:mvn/version "..."}}}

Then require the API:

(ns napkinsketch-book.quickstart
  (:require
   ;; Tablecloth — dataset manipulation
   [tablecloth.api :as tc]
   ;; Kindly — notebook rendering protocol
   [scicloj.kindly.v4.kind :as kind]
   ;; Napkinsketch — composable plotting
   [scicloj.napkinsketch.api :as sk]))

Use Clay or other Kindly-compatible tools to visualize the examples below.

Your First Plot

Load the classic iris dataset and scatter two columns. That is all it takes — one def and one pipeline:

(def iris (tc/dataset "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv"
                      {:key-fn keyword}))

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

• tc/dataset loads a CSV into a tech.ml.dataset dataset (which we typically use through Tablecloth).

• The :key-fn keyword option converts the CSV header strings to Clojure keywords, which is conventional.

• sk/lay-point adds a scatter layer — each row becomes a dot.

Plain Data

You do not need to load a CSV — Napkinsketch accepts plain Clojure data and coerces it into a dataset internally. A map of columns works directly:

(-> {:x [1 2 3 4 5] :y [2 4 3 5 4]}
    (sk/lay-point :x :y))

When the dataset has few columns, you can skip the column names — napkinsketch infers them from the dataset shape:

(-> {:x [1 2 3 4 5] :y [2 4 3 5 4]}
    sk/lay-point)

See Core Concepts for more input formats.

String column names also work — keywords are conventional but not required:

(-> {"x" [1 2 3 4 5] "y" [2 4 3 5 4]}
    (sk/lay-point "x" "y"))

Color

Bind :color to a column to color points by group.

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

More Chart Types

Each sk/lay-* function adds a different chart type.

Histogram — pass a single column for automatic binning:

(-> iris
    (sk/lay-histogram :sepal_length))

Bar chart — count occurrences of a categorical column:

(-> iris
    (sk/lay-bar :species))

Horizontal bars — flip with sk/coord:

(-> iris
    (sk/lay-bar :species)
    (sk/coord :flip))

Line chart — connect points in order:

(-> {:x [1 2 3 4 5 6 7 8]
     :y [3 5 4 7 6 8 7 9]}
    (sk/lay-line :x :y))

Boxplot — compare distributions across categories:

(-> iris
    (sk/lay-boxplot :species :sepal_width))

See the Methods chapter for the full list of 25 chart types.

Inference

sk/view can pick the chart type for you based on column types. Two numerical columns produce a scatter plot:

(-> iris
    (sk/view :sepal_length :sepal_width))

A single categorical column produces a bar chart:

(-> iris
    (sk/view :species))

A single numerical column produces a histogram:

(-> iris
    (sk/view :sepal_length))

See the Inference Rules chapter for the full set of rules.

Multiple Layers

Use sk/view to set shared column mappings, then add layers with sk/lay-*. All layers inherit the view’s mappings. Here sk/lay-lm adds a linear model (regression line) per group:

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

Titles and Labels

Use sk/options for width, height, title, and axis labels:

(-> iris
    (sk/lay-point :petal_length :petal_width {:color :species})
    (sk/options {:width 500 :height 350
                 :title "Iris Petals"
                 :x-label "Petal Length (cm)"
                 :y-label "Petal Width (cm)"}))

Dashboards

Combine multiple plots with sk/arrange:

(sk/arrange [(sk/lay-point iris :sepal_length :sepal_width {:color :species})
             (sk/lay-histogram iris :sepal_length {:color :species})]
            {:cols 2})

Export

Save a plot to SVG with sk/save:

(-> iris
    (sk/lay-point :sepal_length :sepal_width)
    (sk/save "my-plot.svg"))

What’s Next

• Composable Plotting — how sketches, views, and layers compose
• Core Concepts — data formats, marks, stats, color, grouping, coordinates
• Scatter Plots — the most common starting point for chart types
• Cookbook — recipes for common multi-layer plots

source: notebooks/napkinsketch_book/quickstart.clj