This is the vgplot Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jun 15 07:54:21 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
vgplotInterface to gnuplot
Volker Sarodnick
GPL
ltk (system).
cl-fad (system).
cl-ppcre (system).
package.lisp (file).
vgplot.lisp (file).
demo.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
vgplot/vgplot.lisppackage.lisp (file).
vgplot (system).
*debug* (special variable).
*gnuplot-binary* (special variable).
3d-plot (function).
axis (function).
bar (function).
close-all-plots (function).
close-plot (function).
format-plot (function).
grid (function).
legend (function).
load-data-file (function).
loglog (function).
meshgrid-map (function).
meshgrid-x (function).
meshgrid-y (function).
new-plot (function).
plot (function).
plot-file (function).
print-plot (function).
range (function).
replot (function).
semilogx (function).
semilogy (function).
stairs (function).
stairs-no-plot (function).
subplot (function).
surf (function).
text (function).
text-delete (function).
text-show-label (function).
title (function).
xlabel (function).
ylabel (function).
zlabel (function).
add-del-tmp-files-to-exit-hook (function).
count-data-columns (function).
del-tmp-files (function).
do-plot (function).
extract-min-x-diff (function).
get-color-cmd (function).
get-separator (function).
get-tc-rgb-cmd (function).
listelize-list (function).
make-del-tmp-file-function (function).
make-doc (function).
make-plot (function).
min-x-diff (function).
multiplot-p (reader method).
(setf multiplot-p) (writer method).
open-plot (function).
parse-axis (function).
parse-bar-vals (function).
parse-floats (function).
parse-label (function).
parse-vals (function).
parse-vals-3d (function).
plot-stream (reader method).
(setf plot-stream) (writer method).
plots (class).
read-n-print-no-hang (function).
read-no-hang (function).
set-label (function).
tmp-file-list (reader method).
(setf tmp-file-list) (writer method).
v-format (function).
vectorize (function).
vectorize-lists (function).
vectorize-val-list (function).
vgplot/demo.lispvgplot.lisp (file).
vgplot (system).
demo (function).
drop-substring (function).
print-n-run-list (function).
Packages are listed by definition order.
vgplot# vgplot
This common lisp library is an interface to the gnuplot plotting
utility.
The intention of the API is to resemble to some of the plot commands
of octave or matlab.
## Usage
(asdf:load-system :vgplot) or (ql:quickload :vgplot)
(vgplot:plot ’(1 2 3) ’(0 -2 17))
For examples run the demo function:
(vgplot:demo)
and see API documentation in docs/vgplot.html or on http://volkers.github.io/vgplot/vgplot.html
## License
Copyright (C) 2013 - 2022 Volker Sarodnick
mail: (remove #\y (subseq "avoidspamyvolykerysyar@gymyx.net" 9))
GNU General Public License
common-lisp.
*debug* (special variable).
*gnuplot-binary* (special variable).
3d-plot (function).
axis (function).
bar (function).
close-all-plots (function).
close-plot (function).
demo (function).
figure (function).
format-plot (function).
grid (function).
legend (function).
load-data-file (function).
loglog (function).
meshgrid-map (function).
meshgrid-x (function).
meshgrid-y (function).
new-plot (function).
plot (function).
plot-file (function).
print-plot (function).
range (function).
replot (function).
semilogx (function).
semilogy (function).
stairs (function).
stairs-no-plot (function).
subplot (function).
surf (function).
text (function).
text-delete (function).
text-show-label (function).
title (function).
xlabel (function).
ylabel (function).
zlabel (function).
add-del-tmp-files-to-exit-hook (function).
count-data-columns (function).
del-tmp-files (function).
do-plot (function).
drop-substring (function).
extract-min-x-diff (function).
get-color-cmd (function).
get-separator (function).
get-tc-rgb-cmd (function).
listelize-list (function).
make-del-tmp-file-function (function).
make-doc (function).
make-plot (function).
min-x-diff (function).
multiplot-p (generic reader).
(setf multiplot-p) (generic writer).
open-plot (function).
parse-axis (function).
parse-bar-vals (function).
parse-floats (function).
parse-label (function).
parse-vals (function).
parse-vals-3d (function).
plot-stream (generic reader).
(setf plot-stream) (generic writer).
plots (class).
print-n-run-list (function).
read-n-print-no-hang (function).
read-no-hang (function).
set-label (function).
tmp-file-list (generic reader).
(setf tmp-file-list) (generic writer).
v-format (function).
vectorize (function).
vectorize-lists (function).
vectorize-val-list (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Actvate debugging when true.
Gnuplot binary. Change when gnuplot not in path.
Do a 3d plot. Uses gnuplot’s ’splot’.
The inputs are similar to ’plot’, but with some key differences:
vals could be: x y z
x y z label-string
style commands in the label-string work the same as in ’plot’.
Set axis to limit-list and return actual limit-list, limit-list could be:
’(xmin xmax) or ’(xmin xmax ymin ymax),
values can be:
a number: use it as the corresponding limit
nil: do not change this limit
t: autoscale this limit
without limit-list do return current axis.
Create a bar plot y = f(x) on active plot, create plot if needed.
:x (optional) vector or list of x strings or numbers
plot to index if not provided
:y list of y ’((y &key :label :color) (y &key :label :color) ...)
y vector or list of y values
:label string for legend label (optional)
:color string defining the color (optional);
must be known by gnuplot, e.g. blue, green, red or cyan
:style (optional) "grouped" (default) or "stacked"
:width (optional) width of the bars where 1.0 means to fill the space completely
(for the gap in style "grouped" see parameter gap)
:gap (optional, only used in style "grouped") the gap between the groups
in units of width of one boxwidth
e.g.:
(bar :x #("Item 1" "Item 2" "Item 3")
:y ’((#(0.3 0.2 0.1) :label "Values" :color "blue")
(#(0.1 0.2 0.3) :label "Values" :color "red"))
:style "stacked"
:width 0.6)
Close all connected gnuplots
Close connected gnuplot
Send a command directly to active gnuplot process, return gnuplots response print also response to stdout if print? is true
Add grid to plot if style t, otherwise remove grid.
If key parameter replot is true (default) run an additional replot thereafter.
Provide options to the legend aka keys.
:show Show legend (default)
:hide Hide legend
:boxon Use box around the legend
:boxoff Don’t use a box (default)
:left Title left of sample line (default)
:right Title right of sample line
:north Place legend center top
:south Center bottom
:east Right center
:west Left center
:northeast Right top (default)
:northwest Left top
:southeast Right bottom
:southwest Left bottom
:at x y Place legend at position x,y
:inside Place legend inside the plot (default)
:outside Place legend outside the plot
Return a list of found vectors (one vector for one column) in data file fname
(e.g. a csv-file).
Datafile fname must hold columns separated by spaces, tabs or commas (other separators may work),
content after # till end of line is assumed to be a comment and ignored.
Produce a two-dimensional plot using logarithmic scales scale for both axis. See the documentation of the plot command for a description of the arguments.
Helper function for a surface plot (surf).
Map fun to every pair of elements of the arrays xx and yy and return the corresponding array zz.
See surf for an example.
Helper function for a surface plot (surf).
Given vectors of X and Y coordinates, return array XX for a 2-D grid.
The columns of XX are copies of X.
Usually used in combination with meshgrid-y.
See surf for examples.
Helper function for a surface plot (surf).
Given vectors of X and Y coordinates, return array YY for a 2-D grid.
The rows of YY are copies of Y.
Usually used in combination with meshgrid-x.
See surf for examples.
Add a new plot window to a current one.
Plot y = f(x) on active plot, create plot if needed.
vals could be: y plot y over its index
y label-string plot y over its index using label-string as label
x y plot y = f(x)
x y label-string plot y = f(x) using label-string as label
following parameters add curves to same plot e.g.:
x y label x1 y1 label1 ...
label:
A simple label in form of "text" is printed directly.
A label with style commands: label in form "styles;text;add-styles":
In the ordinary case add-styles will be empty.
styles can be (combinations possible):
"-" lines
":" dotted lines
"." dots
"+" points
"o" circles
"r" red
"g" green
"b" blue
"c" cyan
"k" black
"y" yellow
"m" magenta
"w" white
"#RRGGBB" sets an arbitrary 24-bit RGB color (have to be exactly 6 digits)
e.g.:
(plot x y "r+;red values;") plots y = f(x) as red points with the
label "red values"
If add-styles is not empty, the string in add-styles is send unmodyfied to gnuplot, other styles and colors are skipped.
This is useful to set more complicated styles, e.g.:
(plot x y ";use of additional styles;with linespoints pt 7 ps 2 lc ’red’")
plots y = f(x) as lines with red points, pointsize 2 with the
label "use of additional styles"
To use a backslash in add-styles you have to quote it, e.g.:
(plot x y ";;with points pt ’\U+2299’")
Plot data-file directly, datafile must hold columns separated by spaces, tabs or commas
(other separators may work), use with-lines style.
:x-col (optional) column to use as x values.
plot to index if not provided
Print the actual plot into filename (a pathname).
Use the (optional) terminal or if not provided,
use the extension of filename to guess the terminal type.
Guessing of terminals works currently for: gif, pdf, png
Examples: (vgplot:print-plot #p"plot.pdf")
(vgplot:print-plot #p"plot.eps" :terminal "epscairo")
It is possible to give additional parameters inside the terminal parameter, e.g.: (vgplot:print-plot #p"plot.pdf" :terminal "pdfcairo size \"5cm\",\"5cm\"")
Return vector of values in a certain range:
(range limit) return natural numbers below limit
(range start limit) return ordinary numbers starting with start below limit
(range start limit step) return numbers starting with start, successively adding step untill reaching limit (excluding)
Send the replot command to gnuplot, i.e. apply all recent changes in the plot.
Produce a two-dimensional plot using a logarithmic scale for the X axis. See the documentation of the plot command for a description of the arguments.
Produce a two-dimensional plot using a logarithmic scale for the Y axis. See the documentation of the plot command for a description of the arguments.
Produce a stairstep plot.
vals could be: y plot y over its index
x y plot y = f(x)
x y label-string plot y = f(x) using label-string as label
following parameters add curves to same plot e.g.:
x y label x1 y1 label1 ...
For the syntax of label-string see documentation of plot command.
If you only want to prepare the sequences for later plot, see
function stairs-no-plot.
Prepare a stairstep plot, but don’t actually plot it.
Return a list of 2 sequences, x and y, usable for the later plot.
If one argument is given use it as y sequence, there x are the indices.
If both arguments are given use yx as x and y is y.
If you want to plot the stairplot directly, see function stairs.
Set up a plot grid with rows by cols subwindows and use location index for next plot command.
The plot index runs row-wise. First all the columns in a row are
filled and then the next row is filled.
For example, a plot with 2 rows by 3 cols will have following plot indices:
+—–+—–+—–+
| 0 | 1 | 2 |
+—–+—–+—–+
| 3 | 4 | 5 |
+—–+—–+—–+
Observe, gnuplot doesn’t allow interactive mouse commands in multiplot mode.
Plot a 3-D surface mesh.
Vals could be: zz [label-string]
xx yy zz [label-string]
For label-string see documentation of plot.
xx, yy and zz are 2 dimensional arrays usually produced by meshgrid-x, meshgrid-y and meshgrid-map.
All 3 arrays have to have the same form where the rows follow the x direction and the columns the y.
xx: #2A((x0 x0 x0 ... x0)
(x1 x1 x1 ... x1)
...
(xn xn xn ... xn))
yy: #2A((y0 y1 y2 ... ym)
(y0 y1 y2 ... ym)
...
(y0 y1 y2 ... ym))
zz: #2A((z00 z01 z02 ... z0m)
(z10 z11 z12 ... z1m)
...
(zn0 zn1 zn2 ... znm))
Example 1: Plot some measurement data without providing xx and yy:
(let ((zz (make-array (list 3 4) :initial-contents ’((0.8 1.5 1.7 2.8) (1.8 1.2 1.2 2.1) (1.7 1.0 1.0 1.9)))))
(vgplot:surf zz "r;array plotted without providing xx or yy;"))
Example 2: Plot some measurement data:
(let* ((x #(1.0 2.0 3.0))
(y #(0.0 2.0 4.0 6.0))
(zz (make-array (list (length x) (length y)) :initial-contents ’((0.8 1.5 1.7 2.8) (1.8 1.2 1.2 2.1) (1.7 1.0 1.0 1.9))))
(xx (vgplot:meshgrid-x x y))
(yy (vgplot:meshgrid-y x y)))
(vgplot:surf xx yy zz))
Example 3: Plot a function z = f(x,y), e.g. the sombrero function:
(let* ((eps double-float-epsilon)
(fun #’(lambda (x y) (/ (sin (sqrt (+ (* x x) (* y y) eps))) (sqrt (+ (* x x) (* y y) eps)))))
(x (vgplot:range -8 8 0.2))
(y (vgplot:range -8 8 0.2))
(xx (vgplot:meshgrid-x x y))
(yy (vgplot:meshgrid-y x y))
(zz (vgplot:meshgrid-map fun xx yy)))
(vgplot:surf xx yy zz)
(vgplot:format-plot nil "set hidden3d")
(vgplot:format-plot nil "set pm3d")
(vgplot:replot))
Add text label text-string at position x,y
optional:
:tag nr label number specifying which text label to modify
(integer you get when running (text-show-label))
:horizontalalignment "left"(default), "center" or "right"
:rotation degree rotate text by this angle in degrees (default 0) [if the terminal can do so]
:font "<name>" use this font, e.g. :font "Times" [terminal depending, gnuplot help
recommends: http://fontconfig.org/fontconfig-user.html for more information]
:fontsize nr
:color "color" one of red, green, blue, cyan, black, yellow or white
an unrecogniced color is send unchanged to gnuplot, this can be used to get other colors or effects, e.g:
"tc rgb ’#112233’" gives color with the RGB code 0x112233 (0xRRGGBB)
"tc lt 1" gives the same color as line 1
Observe, it could alter the font of the labels (aka legend or key in
gnuplot terms) if you change font or fontsize of a text field. To
explicitly chose fontsize (or font) for the label you could use:
(format-plot t "set key font \",10\"")
(replot)
Delete text labels specified by tags.
A tag is the number of the text label you get when running (text-show-label).
Show text labels. This is useful to get the tag number for (text-delete)
Add title str to plot. If key parameter replot is true (default) run an additional replot thereafter.
Add x axis label. If key parameter replot is true (default) run an additional replot thereafter.
Add y axis label. If key parameter replot is true (default) run an additional replot thereafter.
Add z axis label. If key parameter replot is true (default) run an additional replot thereafter.
If possible, add delete of tmp files to exit hooks. (implemented on sbcl and clisp)
Count data columns in strings like "1 2 3 # comment", separators could be a variable number of spaces, tabs or the optional separator
Delete files in tmp-file-list and return nil
Do the actual plot. For documentation see doc string of the macro plot
l is a list in the form
((:x x :y y :label lbl :color clr) (:x x :y y :label lbl :color clr) ...).
Return minimal difference of two consecutive x values
Return color command string or empty string
Return the used separator in data string
t for whitespace (standard separator in gnuplot)
c separator character
nil comment line (or empty line)
Return textcolor rgb command string for color name or unchanged color-string when not found
Coerce sequences in l except strings to lists:
(listelize-list ’(#(1 2 3) #(a b c)))
-> ((1 2 3) (A B C))
Return a function that removes the files in tmp-file-list.
Update README and html documentation. Load cl-api before use.
Return minimal difference between 2 consecutive elements in x.
Throw an error if x is not increasing, i.e. difference not bigger than 0
Start gnuplot process and return stream to gnuplot
Parse gnuplot string e.g.
" set xrange [ * : 4.00000 ] noreverse nowriteback # (currently [1.00000:] )"
and return range as a list of floats, e.g. ’(1.0 3.0)
Parse input values to plot and return grouped list: ((x y lbl-string) (x1 y1 lbl-string)...) Create x if not existing.
Parse string line and return the found numbers separated by separator or whitespace when separator is just t
Parse label string e.g. "-k;label;add-styles" and return style command, e.g.: "with points linecolor rgb ’red’ title ’label’". If add-styles isn’t empty it will replace all styles and color strings.
Parse input values to plot and return grouped list: ((x y lbl-string) (x1 y1 lbl-string)...) For efficiency reasons return ((y nil lbl-string)(...)) if only y given
Analogous to parse-vals, but for 3d plots.
Parse input values to 3d-plot and return grouped list: ((x y z lbl-string) (x1 y1 z1 lbl-string) ...)
Print commands in lst and run them after a (read-char), ENTER continue, all other characters break and quit demo
Read from stream and print directly (non blocking). Return read string
Read from stream and return string (non blocking)
Set label label to string, replot if replot is true.
Convert members of sequence v to strings using format-string and concatenates the result.
Coerce all sequences except strings to simple-vectors
Coerce lists in vals to simple-vectors
Coerce :x and :y lists in vals to vectors
vals has the form
((:x x :y y :label lbl :color clr) (:x x :y y :label lbl :color clr) ...)
| Jump to: | (
3
A B C D E F G L M N O P R S T V X Y Z |
|---|
| Jump to: | (
3
A B C D E F G L M N O P R S T V X Y Z |
|---|
| Jump to: | *
M P S T |
|---|
| Jump to: | *
M P S T |
|---|
| Jump to: | C D F P S V |
|---|
| Jump to: | C D F P S V |
|---|