README.md

April 12, 2026 · View on GitHub

Plot

A library for plotting with Common Lisp
Explore the tutorial »

Report Bug · Request Feature · Reference Manual

About the Project
- Built With
Getting Started
- Prerequisites
- Installation
Usage
Resources
Roadmap
Contributing
License
Contact

About the Project

The Plot system provides a way to visualize data in Common Lisp. It includes text-based plotting that works in the REPL and JavaScript visualizations rendered through Vega and Vega-Lite. For Vega work, make-plot is now the constructor center, while the public geom and gg packages provide the high-level plot-owned authoring fragments that are merged into a plot specification.

Plot integrates with data-frame, and can also be used independently.

Built With

Getting Started

To get a local copy up and running, follow these steps.

Prerequisites

An ANSI Common Lisp implementation. Developed and tested with SBCL and CCL.

Installation

To make the system accessible to ASDF, clone the repository in a directory ASDF already knows about. By default, ~/common-lisp/ is commonly used:

cd ~/common-lisp
git clone https://github.com/Lisp-Stat/plot

If needed, reset the ASDF source registry from the REPL:

(asdf:clear-source-registry)

Load the Vega backend with Quicklisp:

(ql:quickload :plot/vega)

After dependencies are available, loading through ASDF also works:

(asdf:load-system :plot/vega)

The examples below assume:

(use-package '#:vega)

Usage

High-Level Authoring

The recommended path is:

(make-plot data fragment &rest fragments)

geom and gg return plot-owned fragments. make-plot merges them into a Vega-Lite spec and returns a plot object. Construction does not display a plot implicitly.

A Small Point Plot

(defparameter *points*
  #((:x 1 :y 2 :group "A")
    (:x 2 :y 3 :group "B")
    (:x 3 :y 5 :group "A")))

(defparameter *point-plot*
  (make-plot *points*
             '(:title "Simple Point Plot")
             (geom:point :x :y :color :group :filled t)
             (gg:label :x "X" :y "Y")
             (gg:theme :width 360 :height 220)))

Display is explicit:

(plot:plot *point-plot*)

Layered Fragments

(defparameter *layered-plot*
  (make-plot *points*
             '(:title "Points and Trend")
             (gg:layer
              '(:mark (:type :point :filled t)
                :encoding (:x (:field :x :type :quantitative)
                           :y (:field :y :type :quantitative)))
              '(:mark :line
                :encoding (:x (:field :x :type :quantitative)
                           :y (:field :y :type :quantitative))))
             (gg:label :x "X" :y "Y")
             (gg:theme :width 360 :height 220)))

geom helpers also compose directly with gg fragments:

(defparameter *line-plot*
  (make-plot *points*
             '(:title "Geom + GG")
             (geom:line :x :y :color "steelblue" :point t)
             (gg:label :x "X" :y "Y")
             (gg:tooltip :x '(:y :quantitative))))

Advanced Explicit Construction

Use the explicit :base path when you already have an authored lower-level Vega-Lite plist and want make-plot to remain the constructor center.

(defparameter *base*
  '(:title "Base Plot"
    :mark :line
    :data (:values #((:x 1 :y 2)
                     (:x 2 :y 4)))
    :encoding (:x (:field :x :type :quantitative)
               :y (:field :y :type :quantitative))))

(defparameter *overlay*
  '((:title "Base Plot With Overlay")
    (:encoding (:tooltip (:field :y :type :quantitative)))))

Small explicit-construction forms:

(make-plot :base *base*)

(make-plot :base *base* :name "trend")

(make-plot :base *base* :overlay *overlay*)

(make-plot :base *base* :name "trend" :overlay *overlay*)

overlay is an explicit list of fragments that is merged on top of base.

Output Paths

make-plot constructs a plot object only. Common explicit next steps are:

(plot:plot plot) to render through the browser-oriented Vega path
(vega:write-html plot) to write an HTML wrapper
(vega:write-spec plot) to emit Vega-Lite JSON
notebook consumers via the optional plot/vega/jupyter adapter

Resources

This system is part of the Lisp-Stat project; that should be your first stop for information. Also see:

Tutorial: https://lisp-stat.dev/docs/tutorials/plotting/
Cookbook: https://lisp-stat.dev/docs/cookbooks/plotting/
Project page: https://lisp-stat.dev/docs/tasks/plotting/
Resources: https://lisp-stat.dev/resources
Community: https://lisp-stat.dev/community

Plot

Table of Contents