vgplot

API Reference

vgplot

Interface to gnuplot

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 doc/vgplot.html or here: http://goto.glocalnet.net/volkers/vgplot/vgplot.html

## License

Copyright (C) 2013 - 2018 Volker Sarodnick

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

GNU General Public License
  • Variable *DEBUG*
    nil
    Actvate debugging when true.
  • Variable *GNUPLOT-BINARY*
    "gnuplot"
    Gnuplot binary. Change when gnuplot not in path.
  • 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.
  • 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.
  • 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
  • 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
  • Function CLOSE-PLOT
    Close connected gnuplot
  • Function CLOSE-ALL-PLOTS
    Close all connected gnuplots
  • Function NEW-PLOT
    Add a new plot window to a current one.
  • 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 "." 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"
  • 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\"")
  • 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.
  • 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.
  • 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.
  • Function BAR (&key x y (style "grouped") (width 0.8) (gap 2.0))
    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)
  • 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.
  • 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
  • Function REPLOT
    Send the replot command to gnuplot, i.e. apply all recent changes in the plot.
  • Function GRID (style &key (replot t))
    Add grid to plot if style t, otherwise remove grid. If key parameter replot is true (default) run an additional replot thereafter.
  • 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
  • Function TITLE (str &key (replot t))
    Add title str to plot. If key parameter replot is true (default) run an additional replot thereafter.
  • Function XLABEL (str &key (replot t))
    Add x axis label. If key parameter replot is true (default) run an additional replot thereafter.
  • Function YLABEL (str &key (replot t))
    Add y axis label. If key parameter replot is true (default) run an additional replot thereafter.
  • Function TEXT (x y text-string &key (tag) (horizontalalignment "left") (rotation 0) (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)
  • Function TEXT-SHOW-LABEL
    Show text labels. This is useful to get the tag number for (text-delete)
  • 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).
  • 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.
  • 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.
  • Function RANGE (a &optional b (step 1))
    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)
  • Function DEMO
    Show usecases of vgplot.