2  Quickstart

A minimal introduction to Plotje

Setup

Add Plotje to your deps.edn:

{:deps {org.scicloj/plotje {:mvn/version "0.1.0-SNAPSHOT"}}}

Then require the API:

(ns plotje-book.quickstart
  (:require
   ;; Rdatasets -- standard datasets
   [scicloj.metamorph.ml.rdatasets :as rdatasets]
   ;; Kindly -- notebook rendering protocol
   [scicloj.kindly.v4.kind :as kind]
   ;; Plotje -- composable plotting
   [scicloj.plotje.api :as pj]))

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

Your First Plot

Load the classic iris dataset and scatter two columns:

(-> (rdatasets/datasets-iris)
    (pj/lay-point :sepal-length :sepal-width))

• rdatasets/datasets-iris loads the classic iris dataset from R datasets as a Tablecloth dataset with keyword column names.

• pj/lay-point shows each row as a dot (scatter plot).

Plain Data

You do not need to load a CSV – Plotje 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]}
    (pj/lay-point :x :y))

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

(-> {:x [1 2 3 4 5] :y [2 4 3 5 4]}
    pj/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]}
    (pj/lay-point "x" "y"))

Color

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

(-> (rdatasets/datasets-iris)
    (pj/lay-point :sepal-length :sepal-width {:color :species}))

More Chart Types

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

Histogram – pass a single column for automatic binning:

(-> (rdatasets/datasets-iris)
    (pj/lay-histogram :sepal-length))

Bar chart – count occurrences of a categorical column:

(-> (rdatasets/datasets-iris)
    (pj/lay-bar :species))

Horizontal bars – flip with pj/coord:

(-> (rdatasets/datasets-iris)
    (pj/lay-bar :species)
    (pj/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]}
    (pj/lay-line :x :y))

Boxplot – compare distributions across categories:

(-> (rdatasets/datasets-iris)
    (pj/lay-boxplot :species :sepal-width))

See the Layer Types chapter for the full list of chart types.

Inference

pj/pose declares which columns to plot without committing to a chart type. When a pipeline ends at pj/pose (no pj/lay-*), Plotje picks the chart type from the column types. Two numerical columns produce a scatter plot:

(-> (rdatasets/datasets-iris)
    (pj/pose :sepal-length :sepal-width))

A single categorical column produces a bar chart:

(-> (rdatasets/datasets-iris)
    (pj/pose :species))

A single numerical column produces a histogram:

(-> (rdatasets/datasets-iris)
    (pj/pose :sepal-length))

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

Multiple Layers

Use pj/pose to set column mappings for a pose, then add layers with pj/lay-*. All layers on this pose inherit the pose’s mappings. Here (pj/lay-smooth {:stat :linear-model}) adds a linear model (regression line) per group:

(-> (rdatasets/datasets-iris)
    (pj/pose :sepal-length :sepal-width {:color :species})
    pj/lay-point
    (pj/lay-smooth {:stat :linear-model}))

Titles and Labels

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

(-> (rdatasets/datasets-iris)
    (pj/lay-point :petal-length :petal-width {:color :species})
    (pj/options {:width 500 :height 350
                 :title "Iris Petals"
                 :x-label "Petal Length (cm)"
                 :y-label "Petal Width (cm)"}))

Dashboards

Combine multiple plots with pj/arrange:

(pj/arrange [(pj/lay-point (rdatasets/datasets-iris) :sepal-length :sepal-width {:color :species})
             (pj/lay-histogram (rdatasets/datasets-iris) :sepal-length {:color :species})]
            {:cols 2})

Export

Save a plot to SVG with pj/save. It writes the file and returns the path:

(-> (rdatasets/datasets-iris)
    (pj/lay-point :sepal-length :sepal-width)
    (pj/save "/tmp/iris-scatter.svg"))

"/tmp/iris-scatter.svg"

For PNG output, pj/save-png goes through a raster backend; see the Cookbook for other export paths.

What’s Next

• Datasets – what kinds of data Plotje accepts (tablecloth datasets, maps of vectors, sequences of row maps)
• Pose Model – the mental model behind composable plotting
• 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
• Configuration – themes, backgrounds, palettes, and other plot-level defaults
• Gallery – many more chart variations with side-by-side code

source: notebooks/plotje_book/quickstart.clj