The vgplot Reference Manual

Table of Contents

The vgplot Reference Manual

This is the vgplot Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 12:35:10 2020 GMT+0.

1 Introduction

# 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: http://quickdocs.org/vgplot/api

## License

Copyright (C) 2013 - 2020 Volker Sarodnick

mail: (remove #\y (subseq "avoidspamyvolykerysyar@gymyx.net" 9))

GNU General Public License

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 vgplot

Author

Volker Sarodnick

License

GPL

Description

Interface to gnuplot

Dependencies

• ltk
• cl-fad
• cl-ppcre

Source

vgplot.asd (file)

Components

• package.lisp (file)
• vgplot.lisp (file)
• demo.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 vgplot.asd

Location

vgplot.asd

Systems

vgplot (system)

3.1.2 vgplot/package.lisp

Parent

vgplot (system)

Location

package.lisp

Packages

vgplot

3.1.3 vgplot/vgplot.lisp

Dependency

package.lisp (file)

Parent

vgplot (system)

Location

vgplot.lisp

Exported Definitions

• *debug* (special variable)
• *gnuplot-binary* (special variable)
• 3d-plot (function)
• axis (function)
• bar (function)
• close-all-plots (function)
• close-plot (function)
• figure (function)
• format-plot (function)
• grid (function)
• legend (function)
• load-data-file (function)
• loglog (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)
• text (function)
• text-delete (function)
• text-show-label (function)
• title (function)
• xlabel (function)
• ylabel (function)

Internal Definitions

• 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)
• listelize-list (function)
• make-del-tmp-file-function (function)
• make-doc (function)
• make-plot (function)
• min-x-diff (function)
• multiplot-p (method)
• (setf multiplot-p) (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 (method)
• (setf plot-stream) (method)
• plots (class)
• read-n-print-no-hang (function)
• read-no-hang (function)
• tmp-file-list (method)
• (setf tmp-file-list) (method)
• v-format (function)
• vectorize (function)
• vectorize-lists (function)
• vectorize-val-list (function)

3.1.4 vgplot/demo.lisp

Dependency

vgplot.lisp (file)

Parent

vgplot (system)

Location

demo.lisp

Exported Definitions

demo (function)

Internal Definitions

• drop-substring (function)
• print-n-run-list (function)

4 Packages

Packages are listed by definition order.

4.1 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: http://quickdocs.org/vgplot/api

## License

Copyright (C) 2013 - 2020 Volker Sarodnick

mail: (remove #\y (subseq "avoidspamyvolykerysyar@gymyx.net" 9))

GNU General Public License

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *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)
• 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)
• text (function)
• text-delete (function)
• text-show-label (function)
• title (function)
• xlabel (function)
• ylabel (function)

Internal Definitions

• 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)
• listelize-list (function)
• make-del-tmp-file-function (function)
• make-doc (function)
• make-plot (function)
• min-x-diff (function)
• multiplot-p (generic function)
• multiplot-p (method)
• (setf multiplot-p) (method)
• (setf multiplot-p) (generic function)
• 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 function)
• plot-stream (method)
• (setf plot-stream) (method)
• (setf plot-stream) (generic function)
• plots (class)
• print-n-run-list (function)
• read-n-print-no-hang (function)
• read-no-hang (function)
• tmp-file-list (generic function)
• tmp-file-list (method)
• (setf tmp-file-list) (method)
• (setf tmp-file-list) (generic function)
• v-format (function)
• vectorize (function)
• vectorize-lists (function)
• vectorize-val-list (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *debug*

Actvate debugging when true.

Package

vgplot

Source

vgplot.lisp (file)

Special Variable: *gnuplot-binary*

Gnuplot binary. Change when gnuplot not in path.

Package

vgplot

Source

vgplot.lisp (file)

5.1.2 Functions

Function: 3d-plot &rest VALS

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’.

Package

vgplot

Source

vgplot.lisp (file)

Function: axis &optional LIMIT-LIST

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.

Package

vgplot

Source

vgplot.lisp (file)

Function: bar &key X Y STYLE WIDTH GAP

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)

Package

vgplot

Source

vgplot.lisp (file)

Function: close-all-plots ()

Close all connected gnuplots

Package

vgplot

Source

vgplot.lisp (file)

Function: close-plot ()

Close connected gnuplot

Package

vgplot

Source

vgplot.lisp (file)

Function: demo ()

Show usecases of vgplot.

Package

vgplot

Source

demo.lisp (file)

Function: figure ()

Add a new plot window to a current one.

Package

vgplot

Source

vgplot.lisp (file)

Function: format-plot PRINT? TEXT &rest ARGS

Send a command directly to active gnuplot process, return gnuplots response print also response to stdout if print? is true

Package

vgplot

Source

vgplot.lisp (file)

Function: grid STYLE &key REPLOT

Add grid to plot if style t, otherwise remove grid.
If key parameter replot is true (default) run an additional replot thereafter.

Package

vgplot

Source

vgplot.lisp (file)

Function: legend &rest OPTIONS

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

Package

vgplot

Source

vgplot.lisp (file)

Function: load-data-file FNAME

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.

Package

vgplot

Source

vgplot.lisp (file)

Function: loglog &rest VALS

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.

Package

vgplot

Source

vgplot.lisp (file)

Function: new-plot ()

Add a new plot window to a current one.

Package

vgplot

Source

vgplot.lisp (file)

Function: plot &rest VALS

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 added style commands: label in form "styles;text;":
styles can be (combinations possible):
"-" lines
":" dotted lines
"." dots
"+" points
"o" circles
"r" red
"g" green
"b" blue
"c" cyan
"k" black

e.g.:
(plot x y "r+;red values;") plots y = f(x) as red points with the
label "red values"

Package

vgplot

Source

vgplot.lisp (file)

Function: plot-file DATA-FILE &key X-COL

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

Package

vgplot

Source

vgplot.lisp (file)

Function: print-plot FILENAME &key TERMINAL

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\"")

Package

vgplot

Source

vgplot.lisp (file)

Function: range A &optional B STEP

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)

Package

vgplot

Source

vgplot.lisp (file)

Function: replot ()

Send the replot command to gnuplot, i.e. apply all recent changes in the plot.

Package

vgplot

Source

vgplot.lisp (file)

Function: semilogx &rest VALS

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.

Package

vgplot

Source

vgplot.lisp (file)

Function: semilogy &rest VALS

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.

Package

vgplot

Source

vgplot.lisp (file)

Function: stairs &rest VALS

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.

Package

vgplot

Source

vgplot.lisp (file)

Function: stairs-no-plot YX &optional Y

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.

Package

vgplot

Source

vgplot.lisp (file)

Function: subplot ROWS COLS INDEX

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.

Package

vgplot

Source

vgplot.lisp (file)

Function: text X Y TEXT-STRING &key TAG HORIZONTALALIGNMENT ROTATION FONT FONTSIZE

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

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)

Package

vgplot

Source

vgplot.lisp (file)

Function: text-delete &rest TAGS

Delete text labels specified by tags.
A tag is the number of the text label you get when running (text-show-label).

Package

vgplot

Source

vgplot.lisp (file)

Function: text-show-label ()

Show text labels. This is useful to get the tag number for (text-delete)

Package

vgplot

Source

vgplot.lisp (file)

Function: title STR &key REPLOT

Add title str to plot. If key parameter replot is true (default) run an additional replot thereafter.

Package

vgplot

Source

vgplot.lisp (file)

Function: xlabel STR &key REPLOT

Add x axis label. If key parameter replot is true (default) run an additional replot thereafter.

Package

vgplot

Source

vgplot.lisp (file)

Function: ylabel STR &key REPLOT

Add y axis label. If key parameter replot is true (default) run an additional replot thereafter.

Package

vgplot

Source

vgplot.lisp (file)

5.2 Internal definitions

5.2.1 Functions

Function: add-del-tmp-files-to-exit-hook TMP-FILE-LIST

If possible, add delete of tmp files to exit hooks. (implemented on sbcl and clisp)

Package

vgplot

Source

vgplot.lisp (file)

Function: count-data-columns S &optional SEPARATOR

Count data columns in strings like "1 2 3 # comment", seperators could be a variable number of spaces, tabs or the optional separator

Package

vgplot

Source

vgplot.lisp (file)

Function: del-tmp-files TMP-FILE-LIST

Delete files in tmp-file-list and return nil

Package

vgplot

Source

vgplot.lisp (file)

Function: do-plot &rest VALS

Do the actual plot. For documentation see doc string of the macro plot

Package

vgplot

Source

vgplot.lisp (file)

Function: drop-substring SUBSTRING INSTRING

Package

vgplot

Source

demo.lisp (file)

Function: extract-min-x-diff L

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

Package

vgplot

Source

vgplot.lisp (file)

Function: get-color-cmd COLOR

Return color command string or empty string

Package

vgplot

Source

vgplot.lisp (file)

Function: get-separator S

Return the used separator in data string
t for whitespace (standard separator in gnuplot) c separator character
nil comment line (or empty line)

Package

vgplot

Source

vgplot.lisp (file)

Function: listelize-list L

Coerce sequences in l except strings to lists: (listelize-list ’(#(1 2 3) #(a b c)))
-> ((1 2 3) (A B C))

Package

vgplot

Source

vgplot.lisp (file)

Function: make-del-tmp-file-function TMP-FILE-LIST

Return a function that removes the files in tmp-file-list.

Package

vgplot

Source

vgplot.lisp (file)

Function: make-doc ()

Update README.
(Generating of html docs is removed because: - cl-api no longer in quicklisp
- there is quickdocs)

Package

vgplot

Source

vgplot.lisp (file)

Function: make-plot ()

Package

vgplot

Source

vgplot.lisp (file)

Function: min-x-diff X-L

Return minimal difference between 2 consecutive elements in x.
Throw an error if x is not increasing, i.e. difference not bigger than 0

Package

vgplot

Source

vgplot.lisp (file)

Function: open-plot ()

Start gnuplot process and return stream to gnuplot

Package

vgplot

Source

vgplot.lisp (file)

Function: parse-axis AXIS-S

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)

Package

vgplot

Source

vgplot.lisp (file)

Function: parse-bar-vals VALS

Parse input values to plot and return grouped list: ((x y lbl-string) (x1 y1 lbl-string)...) Create x if not existing.

Package

vgplot

Source

vgplot.lisp (file)

Function: parse-floats S SEP

Parse string s and return the found numbers separated by separator

Package

vgplot

Source

vgplot.lisp (file)

Function: parse-label LBL

Parse label string e.g. "-k;label;" and return key list (list :style style :color color :title title).

Package

vgplot

Source

vgplot.lisp (file)

Function: parse-vals VALS

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

Package

vgplot

Source

vgplot.lisp (file)

Function: parse-vals-3d VALS

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) ...)

Package

vgplot

Source

vgplot.lisp (file)

Function: print-n-run-list LST

Print commands in lst and run them after a (read-char), ENTER continue, all other characters break and quit demo

Package

vgplot

Source

demo.lisp (file)

Function: read-n-print-no-hang S

Read from stream and print directly (non blocking). Return read string

Package

vgplot

Source

vgplot.lisp (file)

Function: read-no-hang S

Read from stream and return string (non blocking)

Package

vgplot

Source

vgplot.lisp (file)

Function: v-format FORMAT-STRING V

Convert members of sequence v to strings using format-string and concatenates the result.

Package

vgplot

Source

vgplot.lisp (file)

Function: vectorize VALS

Coerce all sequences except strings to simple-vectors

Package

vgplot

Source

vgplot.lisp (file)

Function: vectorize-lists VALS

Coerce lists in vals to simple-vectors

Package

vgplot

Source

vgplot.lisp (file)

Function: vectorize-val-list VALS

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) ...)

Package

vgplot

Source

vgplot.lisp (file)

5.2.2 Generic functions

Generic Function: multiplot-p OBJECT

Generic Function: (setf multiplot-p) NEW-VALUE OBJECT

Package

vgplot

Methods

Method: multiplot-p (PLOTS plots)

automatically generated reader method

Source

vgplot.lisp (file)

Method: (setf multiplot-p) NEW-VALUE (PLOTS plots)

automatically generated writer method

Source

vgplot.lisp (file)

Generic Function: plot-stream OBJECT

Generic Function: (setf plot-stream) NEW-VALUE OBJECT

Package

vgplot

Methods

Method: plot-stream (PLOTS plots)

automatically generated reader method

Source

vgplot.lisp (file)

Method: (setf plot-stream) NEW-VALUE (PLOTS plots)

automatically generated writer method

Source

vgplot.lisp (file)

Generic Function: tmp-file-list OBJECT

Generic Function: (setf tmp-file-list) NEW-VALUE OBJECT

Package

vgplot

Methods

Method: tmp-file-list (PLOTS plots)

automatically generated reader method

Source

vgplot.lisp (file)

Method: (setf tmp-file-list) NEW-VALUE (PLOTS plots)

automatically generated writer method

Source

vgplot.lisp (file)

5.2.3 Classes

Class: plots ()

Holding properties of the plot

Package

vgplot

Source

vgplot.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• tmp-file-list (method)
• tmp-file-list (method)
• multiplot-p (method)
• multiplot-p (method)
• plot-stream (method)
• plot-stream (method)

Direct slots

Slot: plot-stream

Initform

(vgplot::open-plot)

Readers

plot-stream (generic function)

Writers

(setf plot-stream) (generic function)

Slot: multiplot-p

Readers

multiplot-p (generic function)

Writers

(setf multiplot-p) (generic function)

Slot: tmp-file-list

Readers

tmp-file-list (generic function)

Writers

(setf tmp-file-list) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types