06_Advanced_Features

Advanced Features

This page covers some of the more advanced capabilities of fplot, such as creating composite plots, adding annotations, and using raw Gnuplot commands.

NOTE: Fennel Macros are not included in this wiki page, because they have their own dedicated section.

Multiplot

fplot makes it easy to combine several plots into a single image using Gnuplot’s multiplot feature. You enable this by passing multiple plot configuration tables to the fplot.plot function. The last table argument is special: it must contain the :multiplot configuration within its :options table.

The :multiplot table accepts the following keys:

:layout: A table [rows, cols] defining the grid for the subplots.

:title: An optional overall title for the entire multiplot figure.

Example: 2x1 Multiplot

This example creates two plots stacked vertically.

Fennel

(local fplot (require :fplot))
;; --- Data ---
(local sin-data [])
(local cos-data [])
(for [i 0 100]
(let [x (* i 0.1)]
(table.insert sin-data [x (math.sin x)])
(table.insert cos-data [x (math.cos x)])))
;; --- Plotting ---
(fplot.plot
;; Plot 1: Sine
{:options {:title "Sine"}
    :datasets [{:data sin-data}]}
;; Plot 2: Cosine
{:options {:title "Cosine"}
    :datasets [{:data cos-data}]}
;; Multiplot Configuration (in the last table)
{:options {:multiplot {:layout [2 1]
            :title "Trigonometric Functions"}}})

Lua

require("fennel").install()
local fplot = require("fplot")

-- --- Data ---
local sin_data = {}
local cos_data = {}
for i = 0, 100 do
local x = i * 0.1
table.insert(sin_data, {x, math.sin(x)})
table.insert(cos_data, {x, math.cos(x)})
end

-- --- Plotting ---
fplot.plot(
-- Plot 1: Sine
{
    options = { title = "Sine" },
    datasets = { { data = sin_data } }
},

-- Plot 2: Cosine
{
    options = { title = "Cosine" },
    datasets = { { data = cos_data } }
},

-- Multiplot Configuration (in the last table)
{
    options = {
        multiplot = {
            layout = {2, 1},
            title = "Trigonometric Functions"
        }
    }
}
)

(The resulting plot generated by fplot)

---

Labels, Arrows, and Objects

You can add arbitrary annotations to your plot using the :labels, :arrows, and :objects options.

• :labels: Add text to the plot. Each label is a table [text, x, y, options].

• :arrows: Draw arrows. Each arrow is a table [x1, y1, x2, y2, options].

• :objects: Draw shapes (rectangles, circles, etc.). Each object is a table [type, definition].

Example: Annotating a Peak

Fennel

(fplot.plot
{:options {:title "Annotated Plot"
        :x-range [0 10]
        :y-range [0 12]
        :labels [["Important Peak" 5 10.5 "center"]]
        :arrows [[7 8 5.2 9.8 "head filled"]]
        :objects [["rectangle" "from 4,0 to 6,10 fs transparent solid 0.1 noborder"]]}
    :datasets [{:data [[1 2] [3 7] [5 10] [7 6] [9 3]]
        :style "linespoints"}]})

Lua

fplot.plot({
    options = {
        title = "Annotated Plot",
        ["x-range"] = {0, 10},
        ["y-range"] = {0, 12},
        labels = {
            {"Important Peak", 5, 10.5, "center"}
        },
        arrows = {
            {7, 8, 5.2, 9.8, "head filled"}
        },
        objects = {
            {"rectangle", "from 4,0 to 6,10 fs transparent solid 0.1 noborder"}
        }
    },
    datasets = {
        {
            data = {{1, 2}, {3, 7}, {5, 10}, {7, 6}, {9, 3}},
            style = "linespoints"
        }
    }
})

(The resulting plot generated by fplot)

---

Custom Tics

You can take full control over the axis tic marks using the :xtics and :ytics options. This is useful for categorical data or for highlighting specific points. Provide a list of ["label", value] pairs.

Example: Labeled Tics

Fennel

(local fplot (require :fplot))

(fplot.plot
{:options {:title "Quarterly Sales"
        :xtics [["Q1" 1] ["Q2" 2] ["Q3" 3] ["Q4" 4]]
        :ytics [0 10000 20000 30000]
        :y-label "Revenue ($)"}
    :datasets [{:data [[1 15000] [2 22000] [3 18000] [4 25000]]
        :style "boxes"
        :title "Sales"}]})

Lua

require("fennel").install()
local fplot = require("fplot")

fplot.plot({
    options = {
        title = "Quarterly Sales",
        xtics = {{"Q1", 1}, {"Q2", 2}, {"Q3", 3}, {"Q4", 4}},
        ytics = {0, 10000, 20000, 30000},
        ["y-label"] = "Revenue ($)"
    },
    datasets = {
        {
            data = {{1, 15000}, {2, 22000}, {3, 18000}, {4, 25000}},
            style = "boxes",
            title = "Sales"
        }
    }
})

(The resulting plot generated by fplot)

---

Extra Options (:extra-opts)

For features that are not directly exposed by fplot, you can use the :extra-opts option to pass raw command strings directly to the Gnuplot script. This provides an escape hatch for accessing the full power of Gnuplot.

Example: Setting a Custom Fill Style

Fennel

(local fplot (require :fplot))

(fplot.plot
{:options {:title "Histogram"
        :extra-opts ["set style fill solid 0.6 border -1"
        "set style histogram clustered gap 2"
        "set style data histograms"]}
    :datasets [{:title "Group A" :data [10 15 12]}
    {:title "Group B" :data [12 11 14]}]})

Lua

require("fennel").install()
local fplot = require("fplot")

fplot.plot({
    options = {
        title = "Histogram",
        ["extra-opts"] = {
            "set style fill solid 0.6 border -1",
            "set style histogram clustered gap 2",
            "set style data histograms"
        }
    },
    datasets = {
        { title = "Group A", data = {10, 15, 12} },
        { title = "Group B", data = {12, 11, 14} }
    }
})

(The resulting plot generated by fplot)

---