The eazy-gnuplot Reference Manual

Table of Contents

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 2.3 "Robert April" on Tue Jan 09 14:31:12 2018 GMT+0.


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

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* 
+ Supports a single datafile with multiple =:using= options. Plotting made more efficient. [Oct 2015]
+ 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)` ...
+ PLOT function accepts strings (treated as functions) and pathnames (treated as datafile). func-plot and datafile-plot are deprecated (but still available).

** 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 (*standard-output* :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 t "~%unset key")
   
   ;; We are extending its expressivity. For example, as of 39d60d, there is gp-unset and gp-set.
   ;; An equivalent of above is (gp-unset :keys) .
   ;; The list is growing!

   ;; Functions can be protted with func-plot
   (plot "sin(x)" :title "super sin curve!")
   ;; Plot a lisp data directly
   (plot (lambda ()
           (format t "~&0 0")
           (format t "~&1 1"))
         :using '(1 2)
         :title "1"
         :with '(:linespoint))
   (plot (lambda ()
           (format t "~&0 1")
           (format t "~&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





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

2 Systems

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


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

2.1 eazy-gnuplot

Author

Masataro Asai

Contact

guicho2.71828@gmail.com

License

LLGPL

Description

An intuitive CL interface to gnuplot.

Version

0.2.0

Dependencies
Source

eazy-gnuplot.asd (file)

Component

src (module)


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

3 Modules

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


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

3.1 eazy-gnuplot/src

Parent

eazy-gnuplot (system)

Location

src/

Component

package.lisp (file)


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

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 files   [Contents][Index]

4.1.1 eazy-gnuplot.asd

Location

eazy-gnuplot.asd

Systems

eazy-gnuplot (system)

Packages

eazy-gnuplot-asd


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

4.1.2 eazy-gnuplot/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

eazy-gnuplot

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 eazy-gnuplot-asd

Source

eazy-gnuplot.asd

Use List

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

5.2 eazy-gnuplot

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: *gnuplot-home*

gnuplot command available in the system.

Package

eazy-gnuplot

Source

package.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Macros

Macro: with-plots (STREAM &key DEBUG EXTERNAL-FORMAT) &body BODY
Package

eazy-gnuplot

Source

package.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Functions

Function: datafile-plot PATHSPEC &rest ARGS &key USING &allow-other-keys
Package

eazy-gnuplot

Source

package.lisp (file)

Function: datafile-splot PATHSPEC &rest ARGS &key USING &allow-other-keys
Package

eazy-gnuplot

Source

package.lisp (file)

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 (file)

Function: func-plot EXPRESSION &rest ARGS &key USING &allow-other-keys
Package

eazy-gnuplot

Source

package.lisp (file)

Function: func-splot EXPRESSION &rest ARGS &key USING &allow-other-keys
Package

eazy-gnuplot

Source

package.lisp (file)

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 (file)

Function: gp-quote VALUE

Map a value to the corresponding gnuplot string

Package

eazy-gnuplot

Source

package.lisp (file)

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 (file)

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 (file)

Function: row &rest ARGS

Write a row

Package

eazy-gnuplot

Source

package.lisp (file)

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 (file)


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

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [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 (file)

Special Variable: *keyword-separator-alist*

an alist from a keyword to the corresponding separator string.

Package

eazy-gnuplot

Source

package.lisp (file)

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 (file)

Special Variable: *plot-type*
Package

eazy-gnuplot

Source

package.lisp (file)

Special Variable: *plot-type-multiplot*
Package

eazy-gnuplot

Source

package.lisp (file)

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 (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Functions

Function: %gp ARGS
Package

eazy-gnuplot

Source

package.lisp (file)

Function: %plot DATA &rest ARGS &key TYPE &allow-other-keys &aux FILENAME
Package

eazy-gnuplot

Source

package.lisp (file)

Function: call-with-plots EXTERNAL-FORMAT DEBUG BODY
Package

eazy-gnuplot

Source

package.lisp (file)

Function: data-filename DATA
Package

eazy-gnuplot

Source

package.lisp (file)

Function: gp-quote-for KEYWORD VALUE
Package

eazy-gnuplot

Source

package.lisp (file)

Function: map-plist ARGS FN
Package

eazy-gnuplot

Source

package.lisp (file)

Function: wrap-range-result KEYWORD RESULT
Package

eazy-gnuplot

Source

package.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Conditions

Condition: new-plot ()
Package

eazy-gnuplot

Source

package.lisp (file)

Direct superclasses

condition (condition)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   E   F   L   M  
Index Entry  Section

E
eazy-gnuplot.asd: The eazy-gnuplot<dot>asd file
eazy-gnuplot/src: The eazy-gnuplot/src module
eazy-gnuplot/src/package.lisp: The eazy-gnuplot/src/package<dot>lisp file

F
File, Lisp, eazy-gnuplot.asd: The eazy-gnuplot<dot>asd file
File, Lisp, eazy-gnuplot/src/package.lisp: The eazy-gnuplot/src/package<dot>lisp file

L
Lisp File, eazy-gnuplot.asd: The eazy-gnuplot<dot>asd file
Lisp File, eazy-gnuplot/src/package.lisp: The eazy-gnuplot/src/package<dot>lisp file

M
Module, eazy-gnuplot/src: The eazy-gnuplot/src module

Jump to:   E   F   L   M  

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

A.2 Functions

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

%
%gp: Internal functions
%plot: Internal functions

C
call-with-plots: Internal functions

D
data-filename: Internal functions
datafile-plot: Exported functions
datafile-splot: Exported functions

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

G
gp: Exported functions
gp-quote: Exported functions
gp-quote-for: Internal functions
gp-setup: Exported functions

M
Macro, with-plots: Exported macros
map-plist: Internal functions

P
plot: Exported functions

R
row: Exported functions

S
splot: Exported functions

W
with-plots: Exported macros
wrap-range-result: Internal functions

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

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*data-stream*: Internal special variables
*gnuplot-home*: Exported special variables
*keyword-separator-alist*: Internal special variables
*plot-command-stream*: Internal special variables
*plot-type*: Internal special variables
*plot-type-multiplot*: Internal special variables
*user-stream*: Internal special variables

S
Special Variable, *data-stream*: Internal special variables
Special Variable, *gnuplot-home*: Exported special variables
Special Variable, *keyword-separator-alist*: Internal special variables
Special Variable, *plot-command-stream*: Internal special variables
Special Variable, *plot-type*: Internal special variables
Special Variable, *plot-type-multiplot*: Internal special variables
Special Variable, *user-stream*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   C   E   N   P   S  
Index Entry  Section

C
Condition, new-plot: Internal conditions

E
eazy-gnuplot: The eazy-gnuplot system
eazy-gnuplot: The eazy-gnuplot package
eazy-gnuplot-asd: The eazy-gnuplot-asd package

N
new-plot: Internal conditions

P
Package, eazy-gnuplot: The eazy-gnuplot package
Package, eazy-gnuplot-asd: The eazy-gnuplot-asd package

S
System, eazy-gnuplot: The eazy-gnuplot system

Jump to:   C   E   N   P   S