py-gnuplot
**********

Gnuplot is a portable command-line driven graphing utility for many
platforms. To leverage the powful gnuplot and plot beautiful image in
python, we port gnuplot to python.

**py-python only support python3** since the function dictionary
paramaters in python2 is not in order.

This package has an object-oriented design as well as direct function
call to allows the user flexibility to set plot options and to run
multiple gnuplot sessions simultaneously.

At first let’s have an intuitive overview by showing an simple
example. Will introduce the detail in the below:

   [image]figure 1. pygnuplot demo 1: simple function

The python script to plot the image is as following, you can run
“python3 demo.py” to see the result.

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   gnuplot.plot('[-10:10] sin(x)', 'atan(x)', 'cos(atan(x))',
           terminal = 'pngcairo font "arial,10" fontscale 1.0 size 600, 400',
           output = '"simple.1.png"',
           key = 'fixed left top vertical Right noreverse enhanced autotitle box lt black linewidth 1.000 dashtype solid',
           style = 'increment default',
           samples = '50, 50',
           title = '"Simple Plots" font ",20" norotate')


1. Introduction and basic concept
=================================

As we know Gnuplot is a portable and powerful command-line driven
graphing utility for many platforms. To leverage the power of Gnuplot,
many wrapper are developed but it’s hard to use. We develop the py-
gnuplot in a easy and streightforward: If you are familar with
Gnuplot, it is seamless turn to py-python. If you are not very familar
with Gnuplot, it can also write the gnuplot script in pure python way.

Gnuplot use ‘plot/splot’ commands to plot data, use all kinds of
‘set/unset’ commands to change the plotting style or options for
subsequent plot/splot command. If we implement the plot()/splot()
functions with all those kinds of options, is it possible for us to
call Gnuplot in python script? The answer is yes. There are several
ways to plot the data in py-python:

We take the Gnuplot demo simple.dem (click to see the original Gnuplot
script) as a example and let’s see how use plot it in pyton way. We
have 3 ways to plot the simple function in pyton, it is:

   * line by line: simple1.py

   * Wrapper as object-oriented interface: simple2.py

   * global class-less function call: simple3.py

   * global class-less function call for python generated data:
     simple4.py

All the script including the original gnuplot script generate the same
output: figure1, Let’s have a deep check how they do it:


1.1 plot data line by line
--------------------------

We implemented the function cmd() and pass the command to call Gnuplot
to plot the data, Thus we could do everything with the only one simple
function. It’s the easiest way to call Gnuplot:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   # Illustration of object-oriented interface, you can see we only wrap the
   # gnuplot script by g.cmd('...') and it's simple and straitfoward if you
   # are familar with Gnuplot.
   g = gnuplot.Gnuplot()
   g.cmd('set terminal pngcairo font "arial,10" fontscale 1.0 size 600, 400')
   g.cmd('set output "simple.1.png"')
   g.cmd('set key fixed left top vertical Right noreverse enhanced autotitle box lt black linewidth 1.000 dashtype solid')
   g.cmd('set style increment default')
   g.cmd('set samples 50, 50')
   g.cmd('set title "Simple Plots" ')
   g.cmd('set title  font ",20" norotate')
   g.cmd('plot [-10:10] sin(x),atan(x),cos(atan(x))')

Or you can even pass the Gnuplot command as a string list or a text
paragraph:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   # Illustration of object-oriented interface, you can see we only wrap the
   # gnuplot script by g.cmd('...') and it's simple and straitfoward if you
   # are familar with Gnuplot.
   g = gnuplot.Gnuplot()

   # Take all the Gnuplot command as a list of command:
   g.cmd('set terminal pngcairo font "arial,10" fontscale 1.0 size 600, 400',
   'set output "simple.1.png"',
   'set key fixed left top vertical Right noreverse enhanced autotitle box lt black linewidth 1.000 dashtype solid',
   'set style increment default',
   'set samples 50, 50',
   'set title "Simple Plots" ',
   'set title  font ",20" norotate',
   'plot [-10:10] sin(x),atan(x),cos(atan(x))')

   # Take all the Gnuplot command as a script paragraph:
   plot_cmd = '''
   set terminal pngcairo font "arial,10" fontscale 1.0 size 600, 400
   set output "simple.1.png"
   set key fixed left top vertical Right noreverse enhanced autotitle box lt black linewidth 1.000 dashtype solid
   set style increment default
   set samples 50, 50
   set title "Simple Plots
   set title  font ",20" norotate
   plot [-10:10] sin(x),atan(x),cos(atan(x))'''
   g.cmd(plot_cmd)

By this way we can do everything that Gnuplot can do and cannot do
what Gnuplot itself can’t do. It’s the exact way that the Gnuplot do
it. and we don’t get any benifit besides we can call Gnuplot in
python.


1.2 Wrapper as object-oriented interface
----------------------------------------

As we know Gnuplot use ‘plot/splot’ commands to plot data, use all
kinds of ‘set/unset’ commands to change the plotting style or options
for subsequent plot/splot command. So we implement the
plot()/splot()/set() and so on functions to draw the data in python
way:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   g = gnuplot.Gnuplot()
   g.set(terminal = 'pngcairo font "arial,10" fontscale 1.0 size 600, 400',
           output = '"simple.1.png"',
           key = 'fixed left top vertical Right noreverse enhanced autotitle box lt black linewidth 1.000 dashtype solid',
           style = 'increment default',
           samples = '50, 50',
           title = '"Simple Plots" font ",20" norotate')
   g.plot('[-10:10] sin(x),atan(x),cos(atan(x))')

We set the options before plot and then call plot to render the image.
It’s equivalent to method 1 but seems muck like a python script.


1.3 global class-less function call
-----------------------------------

In above way we need to allocate a Gnuplot object and will use it
whenever we call Gnuplot function. It’s convenient but sometimes we
only need the plot command and don’t want to hande the Gnuplot
instance, this is a new way to draw the same image:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   gnuplot.plot('[-10:10] sin(x),atan(x),cos(atan(x))',
           terminal = 'pngcairo font "arial,10" fontscale 1.0 size 600, 400',
           output = '"simple.1.png"',
           key = 'fixed left top vertical Right noreverse enhanced autotitle box lt black linewidth 1.000 dashtype solid',
           style = 'increment default',
           samples = '50, 50',
           title = '"Simple Plots" font ",20" norotate')

This generates exact the same output but is more simple and seems muck
like a python script.


1.4 Plot python generated data
------------------------------

It’s powerful for the above plot function. But they only can plot the
functions and data in file. How about plotting the python generated
data? We’ve developed another submodule pyplot and you use this
summodule with the same function, you can plot the data in python.

   #!/usr/bin/env python3
   #coding=utf8
   import numpy as np
   import pandas as pd
   from pygnuplot import gnuplot, pyplot

   # Illusration of submodule: pyplot, Note that we use the pyplot.plot()
   # insteading of gnuplot.plot() in the following line and the parameters
   # are a little difference. See detail in the following section.
   df = pd.DataFrame(np.random.randn(8,3))
   pyplot.plot(df,
           'using 1:2',
           'using 1:3',
           'using 1:4',
           terminal = 'pngcairo font "arial,10" fontscale 1.0 size 600, 400',
           output = '"simple.1.png"',
           key = 'fixed left top vertical Right noreverse enhanced autotitle box lt black linewidth 1.000 dashtype solid',
           style = 'increment default',
           samples = '50, 50',
           title = '"Simple Plots" font ",20" norotate')


2 object-oriented interface and global class-less function call
===============================================================

As we see in section 1, we have several types of script to plot the
data, but they could be classified as two types:

   * object-oriented interface: It’s simple wrapper for gnuplot, every
     gnuplot instance is a Gnuplot object and every Gnuplot command is
     a line of python directive.

   * global class-less function call: It refer to the syntax of
     matplotlib and mplfinance, only a few single function could plot
     what you want.

The same functions could bey achieved by both kinds of call way,
object-oriented interface call is object-oriented and global class-
less function call is simple, it’s your up to decide which way to use.

Let’s see what’s the difference with more examples(Click the script
name to see the whole script) in Table1 and Table2:

As describe above, object-oriented interface is simple and easy to
understand as gnuplot’s logic. Easy way plot the data in python way.


3. Sub moduels: gnuplot and pyplot
==================================

We develop two submodule for different use cases:

   * gnuplot: To plot the functions and file data as in gnuplot.

   * pyplot: To plot the data generated in python itself, normally
     it’s in pandas dataframe format.

For each submodule, we both have an object-oriented interface (via
class Gnuplot) and a few global class-less functions (plot(),
splotlot3d(), multiplot()).

Let’s see what’s the difference with more examples(Click the script
name to see the whole script) in section3:


Table1 : A demostration of pygnuplot.gnuplot script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+-----------------+----------------------+----------------------+------------------------------------------------------------------------+
| gnuplot demo    | object-oriented      | direct function call | All the script produce the same image                                  |
| script          | interface script     | script               |                                                                        |
|=================|======================|======================|========================================================================|
| simple.dem      | simple2.py           | simple3.py           | [image: simple.1.png][image]                                           |
+-----------------+----------------------+----------------------+------------------------------------------------------------------------+
| surface2.dem    | surface2.py          | surface2.py          | [image: surface2.9.png][image]                                         |
+-----------------+----------------------+----------------------+------------------------------------------------------------------------+
| iterate.dem     | whale1.py            | whale2.py            | [image: whale.png][image]                                              |
+-----------------+----------------------+----------------------+------------------------------------------------------------------------+


Table 2: A demostration of pygnuplot.pyplot script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+-----------------+----------------------+----------------------+------------------------------------------------------------------------+
| gnuplot demo    | object-oriented      | direct function call | All the script produce the same image                                  |
| script          | interface script     | script               |                                                                        |
|=================|======================|======================|========================================================================|
| histo.1.gnu     | histo.1.py           | histo.2.py           | [image: histograms.1.png][image]                                       |
+-----------------+----------------------+----------------------+------------------------------------------------------------------------+
| finance.dem     | finance.py           | finance.py           | [image: finance.13.png][image]                                         |
+-----------------+----------------------+----------------------+------------------------------------------------------------------------+


4. Gnuplot command and py-gnuplot functions
===========================================

The principle is if you can write Gnuplot script, you can write py-
gnuplot. There is 1-1 mapping between almost all Gnuplot command and
python function;

Gnuplot commands are mapped to py-python function. Gnuplot has many
Commands but there is only a few ones which are related plot. We will
portting more and more commands and now the following commands are
available.


4.1 plot
--------

plot is the primary command for drawing plots with gnuplot:

   plot {<ranges>} <plot-element> {, <plot-element>, <plot-element>}

   # Examples:
   plot sin(x)
   plot sin(x), cos(x)
   plot "datafile.1" with lines, "datafile.2" with points

We port it as a function in py-python and the plot-element is passed
as variable parameters, please be noted that the plot-element should
be in the single quotation marks:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   # gnuplot.plot() is definied as:
   # def plot(*args, **kwargs)

   # usage examples, please note that we didn't give the
   # output so # could only see the image flash on the
   # screen. Will introduce how to output the image to
   # files.
   gnuplot.plot('sin(x)')
   gnuplot.plot('sin(x)', 'cos(x)')
   gnuplot.plot('"datafile.1" with lines',
               '"datafile.2" with points')

Important:

  Submodule gnuplot and submodule pyplot have difference in plot(),
  gnuplot.plot() support functions and file data while pyplot.plot()
  support pandas dataframe data type. Further more pyplot.plot() pass
  the df as the first parameter. This is the only difference between
  gnuplot submodule and pyplot module.

If we generate the data in the python insteading using the exist
funtions and datafile, we should use pyplot to plot the data, for
example:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   # pyplot.plot() is definied as:
   # def plot(df, *args, **kwargs)

   # usage examples, please note that we didn't give the output so could only
   # see the image flash on the screen. Will introduce how to output the
   # image to files.
   df = pd.DataFrame(data = {'col1': [1, 2],
                             'col2': [3, 4],
                             'col3': [5, 6]})
   gnuplot.plot(df, 'using 1:2 with lines', 'using 1:3 with points')


4.2 splot
---------

splot is the command for drawing 3D plots:

   splot {<ranges>}
   {<iteration>}
   <function> | {{<file name> | <datablock name>} {datafile-modifiers}}

   # Examples:
   splot sin(sqrt(x**2+y**2))/sqrt(x**2+y**2)
   splot ’<file_name>’

We port it as a function splot() in py-python and the plot-element is
passed as variable parameters, please be noted that the plot-element
should be in the single quotation marks:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   # gnuplot.splot() is definied as:
   # def splot(*args, **kwargs)

   # usage examples, please note that we didn't give the output so
   # could only see the image flash on the screen. Will introduce
   # how to output the image to files.
   gnuplot.splot('sin(sqrt(x**2+y**2))/sqrt(x**2+y**2)')
   gnuplot.splot('"<file_name>"')


4.3 set
-------

The set command can be used to set lots of options in gnuplot. for
example:

   set xtics offset 0,graph 0.05
   set label "y=x" at 1,2
   set label 2 "S" at graph 0.5,0.5 center font "Symbol,24"
   set label 3 "y=x^2" at 2,3,4 right

In py-gnuplot we use dictionary parameter to pass them to plot()
function, We use each option name as the key, the option value as the
dictionary value. If some option contain an iteration clause, we use
list as the dictionary value, then the above set command could be
writen as:

   xtics = 'offset 0,graph 0.05'
   labes = ['"y=x" at 1,2',
            '2 "S" at graph 0.5,0.5 center font "Symbol,24"',
            '3 "y=x^2" at 2,3,4 right']

For example the following Gnuplot script:

   set boxwidth 0.9 relative
   set style fill solid 1.0
   set label "y=x" at 1,2
   set label 2 "S" at graph 0.5,0.5 center font "Symbol,24"
   set label 3 "y=x^2" at 2,3,4 right
   plot ’file.dat’ with boxes

could be implemented as the following:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   # style is passed as function dictionary parameter
   gnuplot.plot('"file.dat’with boxes',
               boxwidth = '0.9 relative',
               style = 'fill solid 1.0',
               labes = ['"y=x" at 1,2',
               '2 "S" at graph 0.5,0.5 center font "Symbol,24"',
               '3 "y=x^2" at 2,3,4 right'])

By default, Gnuplot display the output to the standard output. The set
term and output command redirects the display to the specified file or
device:

   set terminal pngcairo font "arial,10" fontscale 1.0 size 600, 400
   set output "test.png"

Then if we want to redirect the image to a file, we could do that by
giving the term and output parameters:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   # style is passed as function dictionary parameter
   gnuplot.plot('"file.dat’with boxes',
               boxwidth = '0.9 relative',
               style = 'fill solid 1.0',
               labes = ['"y=x" at 1,2',
               '2 "S" at graph 0.5,0.5 center font "Symbol,24"',
               '3 "y=x^2" at 2,3,4 right'],
               output = '"finance.13.png"',
               term = 'pngcairo font "arial,10" fontscale 1.0 size 900, 600')


4.4 multiplot
-------------

In Gnuplot, multiplot is not a command but a option to enable
multiplot mode. But we use it as a seperate function multiplot() to
plot several data next to each other on the same page or screen
window:

   def multiplot(\*args, \*\*kwargs):
       @args: the subplot object list;
       @kwargs: the setting options that need to be set before call plot;

   def make_subplot(\*args, \*\*kwargs)
       The parameter definition is the same as plot()/splot, but it doesn't
       plot the df really, it only return the plot dictionary for later
       multiplot() use.

Before call multiplot() we must generate the subplot object by calling
make_subplot(), It is much like mplfinance.add_plot(), it only add the
subplot command for further call:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   sub1 = gnuplot.make_subplot('sin(x)', ylabel = 'ylabel')
   sub2 = gnuplot.make_subplot('cos(x)', xlabel = 'xlabel')
   sub3 = gnuplot.make_subplot('sin(2*x)', noxlabel = '', ylabel = '')
   sub4 = gnuplot.make_subplot('cos(2*x)', xlabel = 'xlabel')
   gnuplot.multiplot(sub1, sub2, sub3, sub4,
                     output = '"sample.multiplot.png"',
                     term = 'pngcairo size 900,600 font ",11"',
                     multiplot  = 'layout 2,2 columnsfirst margins 0.1,0.9,0.1,0.9 spacing 0.1')


5. Plot methods detail
======================


5.1 methods in gnuplot
----------------------


5.2 methods in pyplot
---------------------

pyplot is easy to use and it only has a few functions, all the
configuration are passed as function parameter.

pyplot take pandas dataframe as data.


plot(df, *args, **kwargs)
~~~~~~~~~~~~~~~~~~~~~~~~~

@ df: The data that need to plot. it should be pandas dataframe
format. In gnuplot we pass the data as a function or data file. But
normally in python script, we normally get the data in the memory, not
in the file. So we develop the submodule to plot the data in memory,
we should pass the df in pandas dataframe format, for example:

   df = pd.read_csv('immigration.dat', index_col = 0,
                   sep='\t', comment='#')
   pyplot.plot(df, ...)

@ args: The plot command we need to plot. Gnuplot plot data like that:

   plot 'finance.dat' using 0:2:3:4:5 notitle with financebars lt 8, \
        'finance.dat' using 0:9 notitle with lines lt 3, \
        'finance.dat' using 0:10 notitle with lines lt 1, \
        'finance.dat' using 0:11 notitle with lines lt 2

Now we omit the command “plot” and data “finance.dat” since we have
already pass them in the function name and the first parameter “df”,
we pass the command as a list of command as following:

   pyplot.plot(df,
               'using 0:2:3:4:5 notitle with financebars lt 8',
               'using 0:9 notitle with lines lt 3',
               'using 0:10 notitle with lines lt 1',
               'using 0:11 notitle with lines lt 2',
               ...)

@ kwargs: As we know The set command is used to set lots of options
before plot, splot, or replot command is given. We skip the ‘set’
keyword and use the options name as the key, the following part is
used the attribute value, for example we use the following line to set
the xtics in gnuplot:

   set xtics border in scale 1,0.5 nomirror rotate by -45 autojustify norangelimit

Then in the function, we will use:

   xtics = 'border in scale 1,0.5 nomirror rotate by -45 autojustify norangelimit'

as a parameters. Some options order sensitive, so we need the python
version > 3.7, which seems to pass the function parameter in order. Or
there will some issue and cause exception:

   pyplot.plot(df,
               'using 0:2:3:4:5 notitle with financebars lt 8',
               ...,
               xtics = 'border in scale 1,0.5 nomirror rotate by -45 autojustify norangelimit',
               ...)


splot(df, *args, **kwargs)
~~~~~~~~~~~~~~~~~~~~~~~~~~

The parameter are same as plot(), the only difference is it use
“splot” to plot insteading of “plot”.


make_subplot(df, *args, **kwargs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The parameter definition is the same as plot()/splot, but it doesn’t
plot the df really, it only return the plot dictionary for later
multiplot() use.

It is much like mplfinance.add_plot(), it only add the subplot command
for further call:

   sub1 = pyplot.make_subplot(df,
           'using 0:2:3:4:5 notitle with candlesticks lt 8',
           'using 0:9 notitle with lines lt 3',
           logscale = 'y',
           yrange = '[75:105]',
           ytics = '(105, 100, 95, 90, 85, 80)',
           xrange = '[50:253]',
           grid = 'xtics ytics',
           lmargin = '9',
           rmargin = '2',
           format = 'x ""',
           xtics = '(66, 87, 109, 130, 151, 174, 193, 215, 235)',
           title = '"Change to candlesticks"',
           size = ' 1, 0.7',
           origin = '0, 0.3',
           bmargin = '0',
           ylabel = '"price" offset 1',
           label = ['1 "Acme Widgets" at graph 0.5, graph 0.9 center front',
               '2 "Courtesy of Bollinger Capital" at graph 0.01, 0.07',
               '3 "  www.BollingerBands.com" at graph 0.01, 0.03']
           )


multiplot(*args, **kwargs)
~~~~~~~~~~~~~~~~~~~~~~~~~~

The multiplot set the setting in kwargs at first, and then call the
subplot in args to multiplot.

@args: It is the list of subplot generated by make_subplot(), it would
be called one by one.

@kwargs: The global setting for multiplot;

For example:

   pyplot.multiplot(sub1, sub2,
           output = '"history.%s.png"' %(code),
           term = 'pngcairo size 1920,1080 font ",11"')


multisplot(*args, **kwargs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~

To be implemented.


6. More examples
================


6.1 histogram
-------------

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot
   import pandas as pd

   df = pd.read_csv('immigration.dat', index_col = 0, sep='\t', comment='#')
   g = gnuplot.Gnuplot()
   g.set(terminal = 'pngcairo transparent enhanced font "arial,10" fontscale 1.0 size 600, 400 ',
           output = '"histograms.1.png"',
           key = 'fixed right top vertical Right noreverse noenhanced autotitle nobox',
           style = 'data linespoints',
           datafile = ' missing "-"',
           xtics = 'border in scale 1,0.5 nomirror rotate by -45 autojustify norangelimit',
           title = '"US immigration from Europe by decade"')
   pyplot.plot(df, 'using 2:xtic(1), for [i=3:22] "" using i ')

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot
   import pandas as pd

   df = pd.read_csv('immigration.dat', index_col = 0, sep='\t', comment='#')
   pyplot.plot(df,
           'using 2:xtic(1), for [i=3:22] "" using i ',
           terminal = 'pngcairo transparent enhanced font "arial,10" fontscale 1.0 size 600, 400 ',
           output = '"histograms.1.png"',
           key = 'fixed right top vertical Right noreverse noenhanced autotitle nobox',
           style = 'data linespoints',
           datafile = ' missing "-"',
           xtics = 'border in scale 1,0.5 nomirror rotate by -45 autojustify norangelimit',
           title = '"US immigration from Europe by decade"')

And the generated output is as following:

[image]


6.2 splot
---------

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   gnuplot.splot('cos(u)+.5*cos(u)*cos(v),sin(u)+.5*sin(u)*cos(v),.5*sin(v) with lines',
           '1+cos(u)+.5*cos(u)*cos(v),.5*sin(v),sin(u)+.5*sin(u)*cos(v) with lines',
           terminal = 'pngcairo enhanced font "arial,10" fontscale 1.0 size 600, 400 ',
           output = '"surface2.9.png"',
           dummy = 'u, v',
           key = 'bmargin center horizontal Right noreverse enhanced autotitle nobox',
           style = ['increment default','data lines'],
           parametric = '',
           view = '50, 30, 1, 1',
           isosamples = '50, 20',
           hidden3d = 'back offset 1 trianglepattern 3 undefined 1 altdiagonal bentover',
           xyplane = 'relative 0',
           title = '"Interlocking Tori" ',
           urange = '[ -3.14159 : 3.14159 ] noreverse nowriteback',
           vrange = '[ -3.14159 : 3.14159 ] noreverse nowriteback')

And the generated output is as following:

[image]


6.3 pm3d
--------

iterate.dem

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot

   g = gnuplot.Gnuplot()
   #g.set(terminal = 'pngcairo  transparent enhanced font "arial,10" fontscale 1.0 size 600, 400 ',
   #        output = '"iterate.2.png"',
   #        noborder = '',
   #        key = ['title "splot for [scan=1:*] \'whale.dat\' index scan" center',
   #              'bmargin center horizontal Right noreverse enhanced autotitle nobox',
   #              'noinvert samplen 0.6 spacing 1 width 0 height 0 ',
   #              'maxcolumns 0 maxrows 6'],
   #        style = 'increment default',
   #        view = '38, 341, 1, 1',
   #        noxtics = '',
   #        noytics = '',
   #        noztics = '',
   #        title = '"Iteration over all available data in a file" ',
   #        lmargin = 'at screen 0.09',
   #        rmargin = 'at screen 0.9')
   #g.splot('for [i=1:*] "whale.dat" index i title sprintf("scan %d",i) with lines')

    Black and white wahle
   g.set(style = 'line 100 lw 0.1 lc "black"',
           term = 'pngcairo size 480,480',
           out = '"whale.png"',
           pm3d = 'depth hidden3d ls 100',
           cbrange = '[-0.5:0.5]',
           palette = 'rgb -3,-3,-3',
           nocolorbox = '',
           noborder  = '',
           nokey = '',
           zrange = '[-2:2]',
           notics = '',
           view = '60,185,1.5')
   g.splot('"whale.dat" w pm3d')

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot
   import pandas as pd

   #gnuplot.splot('for [i=1:*] "whale.dat" index i title sprintf("scan %d",i) with lines',
   #        terminal = 'pngcairo  transparent enhanced font "arial,10" fontscale 1.0 size 600, 400 ',
   #        output = '"iterate.2.png"',
   #        noborder = '',
   #        key = ['title "splot for [scan=1:*] \'whale.dat\' index scan" center',
   #              'bmargin center horizontal Right noreverse enhanced autotitle nobox',
   #              'noinvert samplen 0.6 spacing 1 width 0 height 0 ',
   #              'maxcolumns 0 maxrows 6'],
   #        style = 'increment default',
   #        view = '38, 341, 1, 1',
   #        noxtics = '',
   #        noytics = '',
   #        noztics = '',
   #        title = '"Iteration over all available data in a file" ',
   #        lmargin = 'at screen 0.09',
   #        rmargin = 'at screen 0.9')

   # Black and white whale
   gnuplot.splot('"whale.dat" w pm3d',
           style = 'line 100 lw 0.1 lc "black"',
           term = 'pngcairo size 480,480',
           out = '"whale.png"',
           pm3d = 'depth hidden3d ls 100',
           cbrange = '[-0.5:0.5]',
           palette = 'rgb -3,-3,-3',
           nocolorbox = '',
           noborder  = '',
           nokey = '',
           zrange = '[-2:2]',
           notics = '',
           view = '60,185,1.5')

And the generated output is as following:

[image]


6.4 multiplot
-------------

we convert the gnuplot demo script: finance.dem to the final python
script:

   #!/usr/bin/env python3
   #coding=utf8
   from pygnuplot import gnuplot, pyplot
   import pandas as pd

   df = pd.read_csv('finance.dat', sep='\t', index_col = 0, parse_dates = True,
           names = ['date', 'open','high','low','close', 'volume','volume_m50',
               'intensity','close_ma20','upper','lower '])
   sub1 = pyplot.make_subplot(df,
           'using 0:2:3:4:5 notitle with candlesticks lt 8',
           'using 0:9 notitle with lines lt 3',
           'using 0:10 notitle with lines lt 1',
           'using 0:11 notitle with lines lt 2',
           'using 0:8 axes x1y2 notitle with lines lt 4',
           logscale = 'y',
           yrange = '[75:105]',
           ytics = '(105, 100, 95, 90, 85, 80)',
           xrange = '[50:253]',
           grid = 'xtics ytics',
           lmargin = '9',
           rmargin = '2',
           format = 'x ""',
           xtics = '(66, 87, 109, 130, 151, 174, 193, 215, 235)',
           title = '"Change to candlesticks"',
           size = ' 1, 0.7',
           origin = '0, 0.3',
           bmargin = '0',
           ylabel = '"price" offset 1',
           label = ['1 "Acme Widgets" at graph 0.5, graph 0.9 center front',
               '2 "Courtesy of Bollinger Capital" at graph 0.01, 0.07',
               '3 "  www.BollingerBands.com" at graph 0.01, 0.03']
           )

   sub2 = pyplot.make_subplot(df,
           'using 0:($6/10000) notitle with impulses lt 3',
           'using 0:($7/10000) notitle with lines lt 1',
           bmargin = '',
           size = '1.0, 0.3',
           origin = '0.0, 0.0',
           tmargin = '0',
           nologscale = 'y',
           autoscale = 'y',
           format = ['x', 'y "%1.0f"'],
           ytics = '500',
           xtics = '("6/03" 66, "7/03" 87, "8/03" 109, "9/03" 130, "10/03" 151, "11/03" 174, "12/03" 193, "1/04" 215, "2/04" 235)',
           ylabel = '"volume (0000)" offset 1')

   pyplot.multiplot(sub1, sub2,
           output = '"finance.13.png"',
           term = 'pngcairo font "arial,10" fontscale 1.0 size 900, 600')

And this the generated output:

[image]


7. Q/A
======


8. TODO
=======

The 0.1 release only support plot/multiplot, will support
splot/multisplot the next release
