The eazy-gnuplot Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The eazy-gnuplot Reference Manual

This is the eazy-gnuplot Reference Manual, version 0.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 05:39:18 2022 GMT+0.

Table of Contents


1 Introduction


* Eazy-Gnuplot [[https://travis-ci.org/guicho271828/eazy-gnuplot.svg]]

Lispy Gnuplot library

- Structure-less -- no CFFI, no CLOS, no STRUCTURE 
- Just print the data to the =*standard-output*= inside =plot= function

*News* 
+ *[Oct 2015]* Supports a single datafile with multiple =:using= options. Plotting made more efficient.
+ Supports for Multiplot environment partially available.
+ When :terminal is missing, eazy-gnuplot tries to guess its terminal type from the given pathname.
+ Growing the list of interfaces available as functions. Still, "unsupported commands" can be directly printed to the stream.
+ Fitting function now available.
+ Most arguments supports list notation. e.g. not only `:using '(1 2)` but
  also `:errors`, `:via`, `:size`, `m?[xyzr]2?(range|tics)` ...
+ *[Feb 2016]* PLOT function accepts strings (treated as functions) and pathnames (treated as datafile). func-plot and datafile-plot are deprecated (but still available).
+ *[Mar 2022]* More arguments support list notation, e.g., `:first :second :graph :screen :character`


** Library Usage

Write 1 =with-plots= and (at least) 1 =gp-setup= per output file.
=gp-setup= accepts and sets any attributes -- mighty
=&allow-other-keys=. /no compatibility issue re: different gnuplot!/.

For more examples, see the [[http://guicho271828.github.io/eazy-gnuplot/][eazy-gnuplot cookbook]] !

#+BEGIN_SRC lisp
;;; when :debug is non-nil, gnuplot code is copied to *trace-output*
(with-plots (s :debug t)
  (gp-setup :xlabel "x-label"      ; strings : "\"x-label\""
            :ylabel "y-label"
            :output #p"sample.png" ; pathnames : "\"sample.png\""
            :terminal :png         ; keyword/symbols: "terminal png"
            
            ;; list contents are recursively quoted, then joined by a space
            :key '(:bottom :right :font "Times New Roman, 6")
            
            :pointsize "0.4px"
            
            :yrange :|[0:1]|
            ;; currently, specifying these kinds of options requires to abuse
            ;; keywords and symbols. Another example: comma separated list, e.g.,
            ;; :terminal '(:png :size |10cm,6cm|)
            ;;
            ;; 2/4/2016 Major options are now covered. 
            )

  ;; any unsupported commands are available by printing it to the stream
  (format s "~%unset key")
  ;; or through `gp` command 
  (gp :unset :key)
  ;; gp-set and gp-unset are equivalent
  (gp-unset :key)
  
  ;; to force something to be printed verbatim inside a command, use symbols whose names are escaped with ||
  (gp :set :xrange '|[0:1]|)

  ;; Functions
  (plot "sin(x)" :title "super sin curve!")

  ;; Plot data
  (plot #p"data.csv" :title "super sin curve!")

  ;; Plot a lisp data directly
  (plot (lambda ()
          (format s "~&0 0")
          (format s "~&1 1"))
        :using '(1 2)
        :title "1"
        :with '(:linespoint))

  (plot (lambda ()
          (format s "~&0 1")
          (format s "~&1 0"))
        :using '(1 2)
        :title "2"
        :with '(:lines)))
#+END_SRC

It results in the following png:

[[https://raw.githubusercontent.com/guicho271828/eazy-gnuplot/master/sample.png]]

** From the Command Line

Requirements: Install [[https://github.com/roswell/roswell/wiki/1.-Installation][roswell]].

: PATH+=~/.roswell/bin/
: ros install eazy-gnuplot
: plot-init myplot.ros
: 


** How it works

Above code This produces the following gnuplot code internally. It will
then be fed into gnuplot interpreter.

#+BEGIN_SRC gnuplot
set xlabel "x-label"
set ylabel "y-label"
set output "sample.png"
set terminal png
set key bottom right font "Times New Roman, 6"
set pointsize "0.4px"
plot sin(x) title "super sin curve!", '-' using 1:2 title "1" with linespoint, '-' using 1:2 title "2" with lines
0 0
1 1
end
0 1
1 0
end
#+END_SRC

When the script contains some error and gnuplot finishes with non-zero value,
it signals UIOP:SUBPROCESS-ERROR .

* Advanced Usage

** Use the GUI terminals e.g. WXT, QT

You can even try a wxt terminal or qt terminal and see the GUI interactively.

#+BEGIN_SRC lisp
(eazy-gnuplot:with-plots (*standard-output* :debug t)
  (eazy-gnuplot:gp-setup :terminal '(:qt))
  (eazy-gnuplot:plot (lambda ()
                       (format t "~&~A ~A" 1 2)
                       (format t "~&~A ~A" 2 5)
                       (format t "~&~A ~A" 3 4)))
  (format t "~&pause mouse button1;~%"))
#+END_SRC

However, these options may not be available on older versions of gnuplot.
QT terminal is supported from gnuplot-4.6.
WXT terminal has a known bug which leaves a zombie process until gnuplot-4.6.

** Dependencies

This library is at least tested on implementation listed below:

+ SBCL 1.2.1 on X86-64 Linux  3.13.0-39-generic (author's environment)

Also, it depends on the following libraries:

+ ITERATE by  ::
    Jonathan Amsterdam's iterator/gatherer/accumulator facility

+ OPTIMA by Tomohiro Matsuyama ::
    Optimized Pattern Matching Library

+ ALEXANDRIA by  ::
    Alexandria is a collection of portable public domain utilities.

** Author

+ Masataro Asai

* Copyright

LLGPL





2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 eazy-gnuplot

An intuitive CL interface to gnuplot.

Author

Masataro Asai

Contact

guicho2.71828@gmail.com

License

LLGPL

Version

0.2.0

Dependencies
  • iterate (system).
  • trivia (system).
  • alexandria (system).
  • uiop (system).
Source

eazy-gnuplot.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 eazy-gnuplot/src

Source

eazy-gnuplot.asd.

Parent Component

eazy-gnuplot (system).

Child Component

package.lisp (file).


4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

4.1.1 eazy-gnuplot/eazy-gnuplot.asd

Source

eazy-gnuplot.asd.

Parent Component

eazy-gnuplot (system).

ASDF Systems

eazy-gnuplot.

Packages

eazy-gnuplot-asd.


4.1.2 eazy-gnuplot/src/package.lisp

Source

eazy-gnuplot.asd.

Parent Component

src (module).

Packages

eazy-gnuplot.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 eazy-gnuplot

Source

package.lisp.

Use List
  • alexandria.
  • common-lisp.
  • iterate.
  • trivia.level2.
Public Interface
Internals

Previous: , Up: Packages   [Contents][Index]

5.2 eazy-gnuplot-asd

Source

eazy-gnuplot.asd.

Use List
  • asdf/interface.
  • common-lisp.

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Public Interface


Next: , Previous: , Up: Public Interface   [Contents][Index]

6.1.1 Special variables

Special Variable: *gnuplot-home*

gnuplot command available in the system.

Package

eazy-gnuplot.

Source

package.lisp.


6.1.2 Macros

Macro: with-plots ((stream &key debug external-format persist) &body body)

with-plots
stream - print commands to this stream.

Keywords
:debug boolean - prints debugging information.
:external-format encoding - the external format need for output, default is :default. :persist boolean - allows windows from GUI terminals to remain open; default is nil (not to persist).
Body
Place your plot code here.

Package

eazy-gnuplot.

Source

package.lisp.


Previous: , Up: Public Interface   [Contents][Index]

6.1.3 Ordinary functions

Function: datafile-plot (pathspec &rest args &key using &allow-other-keys)
Package

eazy-gnuplot.

Source

package.lisp.

Function: datafile-splot (pathspec &rest args &key using &allow-other-keys)
Package

eazy-gnuplot.

Source

package.lisp.

Function: fit (expression data &rest args &key using via unitweights yerror xyerror zerror errors &allow-other-keys)

EXPRESSION is a string representing gnuplot fitting target expressions e.g. f(x), ax**2+bx+c. DATA is either a function producing data, a string
representing a gnuplot expression, or a pathanme for input data.

Package

eazy-gnuplot.

Source

package.lisp.

Function: func-plot (expression &rest args &key using &allow-other-keys)
Package

eazy-gnuplot.

Source

package.lisp.

Function: func-splot (expression &rest args &key using &allow-other-keys)
Package

eazy-gnuplot.

Source

package.lisp.

Function: gp (&rest args)

Render single line gnuplot commands
For example:
Command:
(gp :set :param)
(gp :set :style :line 1 :lc :rgb ’("’#999999’") :lt 1 ’("#border")) Generates:
set param
set style line 1 lc rgb "’#999999’" lt 1 "#border"

- Return:
NIL

Package

eazy-gnuplot.

Source

package.lisp.

Function: gp-quote (value)

Map a value to the corresponding gnuplot string

Package

eazy-gnuplot.

Source

package.lisp.

Function: gp-setup (&rest args &key terminal output multiplot &allow-other-keys)

Special command for setting up gnuplot. This is almost the same as GP command, however it serves some special purposes such as terminal detection from the output, multiplot etc.

Package

eazy-gnuplot.

Source

package.lisp.

Function: plot (data &rest args &key using &allow-other-keys)

DATA is either a function producing data, a string representing gnuplot functions, or a pathanme for input data.

Package

eazy-gnuplot.

Source

package.lisp.

Function: row (&rest args)

Write a row

Package

eazy-gnuplot.

Source

package.lisp.

Function: splot (data &rest args &key using &allow-other-keys)

DATA is either a function producing data, a string representing gnuplot functions, or a pathanme for input data.

Package

eazy-gnuplot.

Source

package.lisp.


6.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

6.2.1 Special variables

Special Variable: *data-stream*

a stream dedicated for printing the inline data fed to the plot command. not meant to be exposed to the users.

Package

eazy-gnuplot.

Source

package.lisp.

Special Variable: *keyword-separator-alist*

an alist from a keyword to the corresponding separator string.

Package

eazy-gnuplot.

Source

package.lisp.

Special Variable: *plot-command-stream*

a stream dedicated for printing the plot command, and its non-data arguments, like plot style, linewidth, linetype. not meant to be exposed to the users.

Package

eazy-gnuplot.

Source

package.lisp.

Special Variable: *plot-type*
Package

eazy-gnuplot.

Source

package.lisp.

Special Variable: *plot-type-multiplot*
Package

eazy-gnuplot.

Source

package.lisp.

Special Variable: *user-stream*

a stream which is bounded by with-plots, and which the user can write some additional gnuplot commands into.

Package

eazy-gnuplot.

Source

package.lisp.


Next: , Previous: , Up: Internals   [Contents][Index]

6.2.2 Ordinary functions

Function: %gp (args)
Package

eazy-gnuplot.

Source

package.lisp.

Function: %plot (data &rest args &key type &allow-other-keys)
Package

eazy-gnuplot.

Source

package.lisp.

Function: call-with-plots (external-format persist debug body)
Package

eazy-gnuplot.

Source

package.lisp.

Function: data-filename (data)
Package

eazy-gnuplot.

Source

package.lisp.

Function: gp-quote-for (keyword value)
Package

eazy-gnuplot.

Source

package.lisp.

Function: map-plist (args fn)
Package

eazy-gnuplot.

Source

package.lisp.

Function: wrap-range-result (keyword result)
Package

eazy-gnuplot.

Source

package.lisp.


6.2.3 Conditions

Condition: new-plot
Package

eazy-gnuplot.

Source

package.lisp.

Direct superclasses

condition.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %  
C   D   F   G   M   P   R   S   W  
Index Entry  Section

%
%gp: Private ordinary functions
%plot: Private ordinary functions

C
call-with-plots: Private ordinary functions

D
data-filename: Private ordinary functions
datafile-plot: Public ordinary functions
datafile-splot: Public ordinary functions

F
fit: Public ordinary functions
func-plot: Public ordinary functions
func-splot: Public ordinary functions
Function, %gp: Private ordinary functions
Function, %plot: Private ordinary functions
Function, call-with-plots: Private ordinary functions
Function, data-filename: Private ordinary functions
Function, datafile-plot: Public ordinary functions
Function, datafile-splot: Public ordinary functions
Function, fit: Public ordinary functions
Function, func-plot: Public ordinary functions
Function, func-splot: Public ordinary functions
Function, gp: Public ordinary functions
Function, gp-quote: Public ordinary functions
Function, gp-quote-for: Private ordinary functions
Function, gp-setup: Public ordinary functions
Function, map-plist: Private ordinary functions
Function, plot: Public ordinary functions
Function, row: Public ordinary functions
Function, splot: Public ordinary functions
Function, wrap-range-result: Private ordinary functions

G
gp: Public ordinary functions
gp-quote: Public ordinary functions
gp-quote-for: Private ordinary functions
gp-setup: Public ordinary functions

M
Macro, with-plots: Public macros
map-plist: Private ordinary functions

P
plot: Public ordinary functions

R
row: Public ordinary functions

S
splot: Public ordinary functions

W
with-plots: Public macros
wrap-range-result: Private ordinary functions

Jump to:   %  
C   D   F   G   M   P   R   S   W