Quick Plot

Overview

The geom and gg packages provide a set of composable helper functions for building Vega-Lite plot specifications. Inspired by R’s ggplot2, specifications are constructed by combining independent layers — geometry, labels, scales, coordinates and themes — rather than writing monolithic JSON-like plists by hand.

Each helper returns a plist. The function merge-plists recursively merges them into a single Vega-Lite spec, which vega:defplot compiles and plot:plot renders.

;; Import marks
(import '(geom:point geom:bar geom:box-plot geom:histogram geom:line geom:loess geom:func))

;; Import modifiers
(import '(gg:label gg:axes gg:coord gg:theme gg:tooltip gg:layer))

;; Import quick plotting
(import '(qplot:qplot))

Design philosophy

In ggplot2, a plot is built from independent concerns:

Each function knows about one concern and nothing else. A mark function never sets axis titles; label never touches mark types; theme never alters encodings. This separation means any helper can be used with any plot type.

The merge pattern

Every helper returns a plist fragment. merge-plists performs a recursive deep merge: when two plists both supply a nested plist for the same key (e.g. :encoding), the inner plists are merged rather than one replacing the other. This is what allows label to add :axis entries to the :encoding that point already created.

Note that merge-plists is a utility function, not a layer helper — it is the mechanism that makes composition work, not a layer you pass to qplot yourself. See the API reference for full details.

Two ways to plot

Lisp-Stat provides two entry points for creating plots. Choose the one that fits your workflow.

defplot + plot:plot — the explicit pattern

The traditional approach separates definition from rendering. Use this when you want full control, or when writing scripts and notebooks. Replace :x-field, :y-field, and my-data with your actual field names and data source:

(plot:plot
 (vega:defplot my-plot
   (merge-plists
    `(:title "My Plot"
      :data (:values ,my-data))
     (point :x-field :y-field)
     (label :x "X Label" :y "Y Label")
     (theme :width 600))))

defplot is a macro that:

1. Calls %defplot to create a vega-plot object
2. Binds it to a global variable (my-plot)
3. Registers it in *all-plots* so show-plots can list it

plot:plot then renders the object to the browser.

qplot — quick plot for the REPL

For interactive exploration, the three-line scaffold of plot:plot / vega:defplot / merge-plists is repetitive. qplot collapses it into a single function call:

(qplot 'my-plot my-data
  `(:title "My Plot")
   (point :x-field :y-field)
   (label :x "X Label" :y "Y Label")
   (theme :width 600))

qplot takes a name (a symbol), a data object (a data frame, plist data, or URI), and any number of layer plists. It:

1. Prepends (:data (:values ,data)) and merges all layers
2. Creates the plot object via %defplot
3. Binds it to the named global variable
4. Registers it in *all-plots*
5. Renders immediately via plot:plot
6. Returns the plot object

Because qplot binds a named variable, the standard REPL workflow is to re-evaluate the same form as you iterate on a plot. Each call overwrites the previous definition — there is no accumulation in *all-plots* or in the global namespace:

;; First attempt — rough sketch
(qplot 'cars vgcars
  (point :horsepower :miles-per-gallon))

;; Second attempt — add color and a title
(qplot 'cars vgcars
  `(:title "HP vs MPG")
   (point :horsepower :miles-per-gallon :color :origin :filled t))

;; Third attempt — polish for presentation
(qplot 'cars vgcars
  `(:title "HP vs MPG")
   (point :horsepower :miles-per-gallon :color :origin :filled t)
   (label :x "Horsepower" :y "Fuel Efficiency")
   (theme :width 600 :height 400))

;; Later — the variable is still bound
cars                ; => #<VEGA-PLOT ...>
(plot:plot cars)    ; re-render
(describe cars)     ; inspect the spec
(show-plots)        ; lists one 'cars' entry

Helpers reference

The layering helpers work with all mark types.

label — Set axis titles.

(label :x "Horsepower" :y "Miles per Gallon")

axes — Set axis types, domains, ranges, and color schemes.

(axes :x-type :log :color-scheme :dark2)
(axes :x-domain #(0 300) :y-domain #(0 50))

tooltip — Add hover tooltips. Each argument is a field spec.

(tooltip '(:field :name :type :nominal)
         '(:field :horsepower :type :quantitative))

coord — Restrict the visible viewport and clip marks, like coord_cartesian() in ggplot2. Only data within the domain is visible; points outside are clipped rather than dropped.

(coord :x-domain #(50 150) :y-domain #(20 40))

theme — Set dimensions, font, background, or named presets.

(theme :width 600 :height 400 :font "Georgia")

;; Correct — produces [50, 150]
(coord :x-domain #(50 150))

;; Wrong — produces {"50": 150}
(coord :x-domain '(50 150))

;; Correct — keywords for fields, strings for labels
(point :horsepower :miles-per-gallon :color :origin)
(label :x "Engine Horsepower" :y "Fuel Efficiency")

;; Wrong — strings for field names
(point :horsepower :miles-per-gallon :color "origin")

;; Keyword — map the :origin field to color (encoding)
(point :horsepower :miles-per-gallon :color :origin)

;; String — paint every point teal (mark property)
(point :horsepower :miles-per-gallon :color "teal")

;; Same convention applies to all mark types
(histogram :miles-per-gallon :color :origin)        ; stacked by origin
(histogram :miles-per-gallon :color "darkslategray") ; uniform bar color
(bar :origin :miles-per-gallon :color "teal")        ; uniform bar color

Loading example data

The examples below use datasets from the Vega datasets collection. Load them into your session before running the examples:

(vega:load-vega-examples)

This makes the following variables available in your environment:

• vgcars — Automobile specifications (horsepower, MPG, origin, etc.) for 406 cars.
• stocks — Daily closing prices for several major tech stocks over multiple years.

For datasets loaded using vega:read-vega, field names are automatically converted to Lisp-style keywords (e.g. Miles_per_Gallon becomes :miles-per-gallon). Note that the :year field in vgcars is stored as a date string (e.g. "1970-01-01") rather than an integer, which is why the line chart examples pass :x-type :temporal for that field.

Scatter plot

A scatter plot maps two quantitative variables to x and y positions. Use point for exploring relationships, correlations and clusters in data. The name follows the ggplot2 convention where geom_point() produces a scatter plot.

Basic scatter plot

The simplest scatter plot needs just a name, a data frame, and two field names:

(qplot 'cars-basic vgcars
  `(:title "Horsepower vs. MPG")
   (point :horsepower :miles-per-gallon))

Color by category

Pass a keyword to :color to map a nominal variable to hue. Use :filled t to fill the point marks:

(qplot 'cars-colored vgcars
  `(:title "Cars by Origin")
   (point :horsepower :miles-per-gallon
          :color :origin :filled t))

Bubble plot

When :size is a keyword, it encodes a third quantitative field as point area — a bubble plot:

(qplot 'cars-bubble vgcars
  `(:title "Bubble: Size = Acceleration")
   (point :horsepower :miles-per-gallon
          :color :origin :size :acceleration
          :filled t)
   (label :x "Horsepower" :y "Miles per Gallon"))

Adding axis labels

Use label to give axes meaningful titles:

(qplot 'cars-with-labels vgcars
  `(:title "Vega Cars")
   (point :horsepower :miles-per-gallon :filled t)
   (label :x "Engine Horsepower" :y "Fuel Efficiency (MPG)"))

Log scale with custom color scheme

Use axes to transform an axis and change the color palette:

(qplot 'cars-log-scale vgcars
  `(:title "Horsepower (log) vs. MPG")
   (point :horsepower :miles-per-gallon
          :color :origin :filled t)
   (axes :x-type :log :color-scheme :dark2)
   (label :x "Horsepower (log scale)" :y "Miles per Gallon"))

Tooltips on hover

Add tooltip to show details when the user hovers over a point:

(qplot 'cars-tooltip vgcars
  `(:title "Car Details on Hover")
   (point :horsepower :miles-per-gallon
          :color :origin :filled t)
   (tooltip '(:field :name :type :nominal)
            '(:field :horsepower :type :quantitative)
            '(:field :miles-per-gallon :type :quantitative)
            '(:field :origin :type :nominal)))

Zoom into a region

Use coord to restrict the visible area. Unlike axes, this clips marks that fall outside the domain — only points within the viewport are drawn:

(qplot 'cars-zoomed vgcars
  `(:title "Cars: 50-150 HP, 20-40 MPG")
   (point :horsepower :miles-per-gallon
          :color :origin :filled t)
   (coord :x-domain #(50 150) :y-domain #(20 40))
   (label :x "Horsepower" :y "Miles per Gallon"))

Custom theme

Use theme to set plot dimensions, font, and visual style:

(qplot 'cars-themed vgcars
  `(:title "Themed Scatter Plot")
   (point :horsepower :miles-per-gallon
          :color :origin :filled t)
   (label :x "Horsepower" :y "MPG")
   (theme :width 600 :height 400 :font "Georgia"))

Full example — all layers

Combine every layer for a production-quality plot:

(qplot 'cars-full vgcars
  `(:title "Complete Example: All Layers"
    :description "Demonstrating label, axes, tooltip, coord, and theme")
   (point :horsepower :miles-per-gallon
          :color :origin
          :size :acceleration
          :filled t)
   (label :x "Engine Horsepower" :y "Fuel Efficiency (MPG)")
   (axes :color-scheme :category10)
   (tooltip '(:field :name :type :nominal)
            '(:field :horsepower :type :quantitative)
            '(:field :miles-per-gallon :type :quantitative)
            '(:field :origin :type :nominal))
   (coord :x-domain #(40 240) :y-domain #(5 50))
   (theme :width 700 :height 450))

LOESS smoother

A LOESS (locally estimated scatterplot smoothing) curve fits a non-parametric smooth line through data, revealing trends without assuming a fixed functional form. Use loess to overlay a trend line on a scatter plot or to compare smoothed trajectories across groups.

Scatter plot with LOESS smoother

Use gg:layer to compose the scatter points and the smoother into a single layered view:

(qplot 'cars-loess vgcars
  `(:title "HP vs. MPG with LOESS Smoother")
  (gg:layer
    (point :horsepower :miles-per-gallon
           :color :origin :filled t :opacity 0.5)
    (loess :horsepower :miles-per-gallon
           :group :origin
           :stroke-width 2)))

The :group :origin argument fits a separate curve for each origin and encodes it with the matching hue automatically. Increase :bandwidth toward 1.0 for a flatter, more global fit; decrease it toward 0.05 for a curve that tracks local variation closely.

Histogram

A histogram bins a quantitative variable and counts observations per bin. Use histogram to visualize the distribution of a single variable.

Basic histogram

Pass a single field name. The default uses Vega-Lite’s automatic binning and counts occurrences:

(qplot 'mpg-hist vgcars
  `(:title "Distribution of Miles per Gallon")
   (histogram :miles-per-gallon)
   (label :x "Miles per Gallon" :y "Count"))

Custom bin count

Control granularity with the :bin keyword. Pass a plist with :maxbins to limit the number of bins:

(qplot 'mpg-hist-bins vgcars
  `(:title "MPG Distribution (10 bins)")
   (histogram :miles-per-gallon :bin '(:maxbins 10))
   (label :x "Miles per Gallon" :y "Count"))

Horizontal histogram

Set :orient :horizontal to place bins on the y-axis:

(qplot 'mpg-hist-horiz vgcars
  `(:title "MPG Distribution (Horizontal)")
   (histogram :miles-per-gallon :orient :horizontal)
   (label :x "Count" :y "Miles per Gallon"))

Stacked histogram by group

Pass :group to split bins by a nominal field. Vega-Lite automatically stacks the bars:

(qplot 'mpg-hist-stacked vgcars
  `(:title "MPG Distribution by Origin")
   (histogram :miles-per-gallon :group :origin)
   (label :x "Miles per Gallon" :y "Count"))

Layered histogram

Use :stack :null with :opacity to overlay distributions transparently instead of stacking them:

(qplot 'mpg-hist-layered vgcars
  `(:title "MPG: Overlaid by Origin")
   (histogram :miles-per-gallon
              :group :origin
              :stack :null
              :opacity 0.5)
   (label :x "Miles per Gallon" :y "Count"))

Normalized (100%) stacked histogram

Use :stack :normalize to show proportions instead of counts:

(qplot 'mpg-hist-normalized vgcars
  `(:title "MPG: Proportion by Origin")
   (histogram :miles-per-gallon
              :group :origin
              :stack :normalize)
   (label :x "Miles per Gallon" :y "Proportion"))

Styled histogram

Use :color, :corner-radius-end, and :bin-spacing for visual polish. Combine with theme for custom dimensions:

(qplot 'mpg-hist-styled vgcars
  `(:title "Styled Histogram")
   (histogram :miles-per-gallon
              :color "darkslategray"
              :corner-radius-end 3
              :bin-spacing 0)
   (label :x "Miles per Gallon" :y "Count")
   (theme :width 500 :height 300))