== gnuplot-pipe
The gnuplot-pipe egg provides bindings to
[[http://gnuplot.info/|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'''
[[toc:]]
== Requirements
The gnuplot-pipe egg requires [[http://gnuplot.info/|Gnuplot]] (tested
with version 5.2).
== Usage and Examples
It is recommended to import the gnuplot-pipe egg using a prefix, for
example {{gp:}}.
(import (prefix gnuplot-pipe gp:))
All gnuplot-pipe procedures calls must be wrapped by
(gp:call/gnuplot
...)
The default [[http://gnuplot.info/|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)))
(gp:call/gnuplot
;;; 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.4 : Port to CHICKEN Scheme 5. Add tests.
; 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 ...)
Evaluate expressions redirecting output towards Gnuplot pipe. All
procedures defined in this API must be used as {{gp:call/gnuplot}}
expressions.
=== gp:send
(send cmdline)
Send arbitrary command to Gnuplot as string.
=== gp:plot
(plot . element)
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 }}, {{}} and {{with