chickadee » gnuplot-pipe

gnuplot-pipe

The gnuplot-pipe egg provides bindings to Gnuplot.

Project / Source Code Repository
https://gitlab.com/montanari/gnuplot-pipe
Issue Tracker
https://gitlab.com/montanari/gnuplot-pipe/issues
Maintainer
Francesco Montanari
License
GPL-3

Table of Contents

Requirements

The gnuplot-pipe egg requires Gnuplot (tested with version 5.2).

Usage and Examples

It is recommended to import the gnuplot-pipe egg using a prefix, for example gp:.

(use (prefix gnuplot-pipe gp:))

All gnuplot-pipe procedures calls must be wrapped by

(gp:call/gnuplot
 ...)

The default Gnuplot executable name is gnuplot. A different executable name (signaled by a warning) may cause the interpreter to crash.

Generic pipe to Gnuplot

The procedure gp:send is a simple pipe to gnuplot. Pass arbitrary command as string.

(gp:call/gnuplot
 (gp:send "set xlabel 'x'")
 (gp:send "plot sin(x)"))

Plot 2D data and save to file

Plot list of numbers as x and y coordinates with gp:plot. A new Gnuplot window will open at each plot. Save the last plot with gp:save.

(gp:call/gnuplot
 ;;; Plot x and y axes data as lines.
 (gp:plot "title 'x^2'" '(1 2 3 4) '(1 4 9 16))

 ;;; Plot multiple curves.
 (gp:plot '(("title 'x^2'" (1 2 3 4) (1 4 9 16))
            ("title 'x^3'" (1 2 3 4) (1 8 27 64))))

 ;;; Save last plot.
 (gp:save "plot.png"))

To avoid a persistent Gnuplot window after each plot (especially when running compiled code to save plots on file), set an interactive terminal (qt, wxt, x11, ...) as non-persistent. For example:

(gp:call/gnuplot
 (gp:send "set terminal x11 nopersist")
 ...)

Plot 3D data

Plot 3D data with gp:plot3d.

(gp:call/gnuplot
 (gp:send "unset key")
 (gp:send "set style data points")
 (gp:send "set title 'The valley of the Gnu'")
 (gp:plot3d ""
            '(0 0 0 1 1 1 2 2 2 3 3 3)
            '(0 1 2 0 1 2 0 1 2 0 1 2)
            '(10 10 10 10 5 10 10 1 10 10 0 10)))

Draw multiple data similarly as for 2D plots.

Understanding the plot procedures

Think to each list of numbers passed to gp:plot and gp:plot3d as a column passed as inline data in a Gnuplot script. The string passed to a plot element corresponds to properties optionally passed to the plot commands. For instance, the following Gnuplot script draws a pie chart with inline data.

set xrange [-15:15]
set style fill transparent solid 0.9 noborder
plot '-' using 1:2:3:4:5:6 with circles lc var
0    0    5    0    30    1
0    0    5   30    70    2
0    0    5   70   120    3
0    0    5  120   230    4
0    0    5  230   360    5
e

It is easily translated as follows.

(gp:call/gnuplot
 (gp:send "set xrange [-15:15]")
 (gp:send "set style fill transparent solid 0.9 noborder")
 (gp:plot "using 1:2:3:4:5:6 with circles lc var"
          '(0 0 0 0 0) '(0 0 0 0 0) '(5 5 5 5 5)
          '(0 30 70 120 230) '(30 70 120 230 360) '(1 2 3 4 5)))

For more involved plots additional specifications may be required. Consider the following Gnuplot script with inline data where we need to specify the data end e twice:

plot ’-’ matrix with image
5 4 3 1 0
2 2 0 0 1
0 0 0 1 0
0 1 2 4 3
e
e

When drawing the same image with gp:plot we need to declare the second data end signal manually:

(gp:call/gnuplot
 (gp:plot "matrix with image"
          '(5 2 0 0) '(4 2 0 1) '(3 0 0 2) '(1 0 1 4) '(0 1 0 3))
 (gp:end-data)) ; Send end signal a second time manually.

Current port

call/gnuplot changes (current-output-port). To display on stdout from within (call/gnuplot ...), the port must be passed as argument, otherwise calls to display, print, ... will direct output towards the Gnuplot pipe.

(gp:call/gnuplot
 (display "foo"))
; gnuplot> foo
;          ^
;          line 0: invalid command

(define stdout (current-output-port))
(gp:call/gnuplot
 (display "foo" stdout))
; foo

Version History

0.3
Improve gp:call/gnuplot.
0.2
Fix multiple plots. Remove unnecessary dependence.
0.1
Initial release.

API

gp:call/gnuplot

(call/gnuplot expr1 expr2 ...)syntax

Evaluate expressions redirecting output towards Gnuplot pipe. All procedures defined in this API must be used as gp:call/gnuplot expressions.

gp:send

send cmdlineprocedure

Send arbitrary command to Gnuplot as string.

gp:plot

plot #!rest elementprocedure

Draw 2D data. This is a wrapper for the Gnuplot plot command offering many different graphical representations for data. A plot element can be given in the form:

(plot str list1 list2 ...)

where str is a (possibly empty) string with optional properties corresponding to Gnuplot axes <axes>, <title-spec> and with <style> specifications (see the Gnuplot manual or launch gnuplot -e "help plot" for more information). List of numbers list1, list2, ... are passed to Gnuplot as inline data columns.

To draw multiple sets of data, a plot element can be also given in the form:

(plot '((str-1 list1-1 list2-1 ...)
        (str-2 list1-2 list2-2 ...)
        ...))

gp:plot3d

plot3d #!rest elementprocedure

Draw 2D projections of 3D data. This is a wrapper for the Gnuplot splot command. Plot elements must be in the same format as in the gp:plot procedure.

gp:save

save fnameprocedure

Save last plot to file. Permitted file name fname extensions are: png, pdf, svg, txt.

gp:end-data

end-dataprocedure

Send end data signal e to Gnuplot pipe and flush output.

Contents »