Fplot: A Declarative Plotting Library for Fennel and Lua

Fplot is a simple, declarative wrapper around the powerful Gnuplot charting system. It provides a clean, table-based API that lets you create beautiful 2D and 3D plots directly from your Fennel or Lua code.

The goal of fplot is to remove the need to manually construct Gnuplot command strings, allowing you to focus on your data, and the plot's appearance. By consoquence, fplot gives you the ability to integrate Gnuplot into your fennel (or lua) project.

(Example 3d-interactive plot generated by fplot)

---

Features

Declarative API: Define your entire plot, including labels, ranges, styles, and datasets, with a single configuration table.

Simple & Clean: No complex object models. Just data and tables.

Supports plot and splot: Create both 2D and 3D surface plots with the same easy-to-use API.

Extensive Customization: Customize everything, from titles, labels, colors, to styles, and ranges.

Multiplot Support: Combine multiple plots into a single image.

Output Options: Output plots to various formats supported by Gnuplot.

PNG, SVG, PDF, and even the interactive GUI via qt, gtk, etc.

Cross-Platform: Works on any system (Linux, macOS, Windows) where Gnuplot is installed.

Fennel First: Written in Fennel, for Fennel, but with first-class support for Lua users.

No Dependencies (Almost): Besides Gnuplot, fplot is self-contained. It relies on the single fplot.fnl script, and the single-file fennel.lua compiler, which can be bundled with your project.

Prerequisites

You must have Gnuplot installed on your system and available in your system's PATH. Fplot calls the Gnuplot command via shell (as a sub-process) to generate plots.

You can check if it's installed by running this in your shell:

gnuplot --version

Installation & Setup (Using Fennel)

To install fplot using LuaRocks, simply run:

luarocks install fplot

This command will download and install the fplot library and make it available for use in your fennel/lua projects. Make sure you have Gnuplot installed and accessible in your system's PATH, as fplot relies on it to generate plots.

Git Clone

Another way to use fplot is to drop fplot.fnl and the fennel.lua compiler directly into your project directory.

1. Download fplot.fnl and fennel.lua into your project.

2. Write your plot script in a Fennel file (e.g., make-plot.fnl).

Quick Start (Fennel)

Here's how you could create a simple sine wave plot, and save it as a PNG.

make-plot.fnl:

(local fplot (require :fplot))

;; 1. Generate some data
(local sin-data [])
(for [i 0 100]
  (let [x (* i 0.1)]
    (table.insert sin-data [x (math.sin x)])))

;; 2. Define and generate the plot
(fplot.plot
  {:options {:title "Sine Wave"
             :x-label "x"
             :y-label "sin(x)"
             :output-file "sine.png"
             :output-type "pngcairo"}
   :datasets [{:title "y = sin(x)"
               :style "lines"
               :data sin-data}]})

(print "Plot generated at sine.png!")

Run the script from your terminal:

fennel make-plot.fnl

Installation & Setup (Using Lua)

You can use fplot from any standard Lua project. The recommended approach is to bundle the fennel.lua compiler with your application.

NOTE: Fennel is simply just Lua with a lisp, so it compiles directly to lua.

This allows Lua to require .fnl files directly.

1. Make sure fplot.fnl and fennel.lua are in your project.

2. In your Lua script, load and install the Fennel compiler before requiring fplot.

make-plot.lua:

-- 1. Load and install the Fennel compiler
require("fennel").install()

-- 2. Now you can require .fnl files like any .lua file
local fplot = require("fplot")

-- 3. Generate some data
local sin_data = {}
for i = 0, 100 do
  local x = i * 0.1
  table.insert(sin_data, {x, math.sin(x)})
end

-- 4. Define and generate the plot
fplot.plot({
  options = {
    title = "Sine Wave from Lua",
    -- IMPORTANT: Fennel's kebab-case keys (:x-label) become
    -- strings in Lua. You must use this ["key-name"] syntax.
    ["x-label"] = "x",
    ["y-label"] = "sin(x)",
    ["output-file"] = "sine_from_lua.png",
    ["output-type"] = "pngcairo"
  },
  datasets = {
    {
      title = "y = sin(x)",
      style = "lines",
      data = sin_data
    }
  }
})

print("Plot generated at sine_from_lua.png!")

Run it with Lua:

lua make-plot.lua

Alternative Setup: Pre-compiling fplot to Lua

If you prefer not to bundle fennel.lua as a dependency, you can pre-compile fplot.fnl into a standard Lua file.

1. Install the Fennel compiler using Luarocks:

   luarocks install fennel

2. Compile fplot.fnl to fplot.lua:

   fennel --compile fplot.fnl > fplot.lua

Now you can require("fplot") from your Lua code like any other Lua module, without needing fennel.install(). However, you will still need to use the ["kebab-case"] syntax for options, as this is fundamental to the library's API.

Further Documentation

For more advanced examples, API details, and guides on creating reusable plot components, please see the fplot Wiki.

License

Fplot is released under the LGPL-3.0 License. See the LICENSE file for details.