• TALK I just gave a talk about this at [[https://www.socallinuxexpo.org/scale/18x][SCaLE 18x]]. Here are the [[https://www.youtube.com/watch?v=YOOapXNtUWw][video of the talk]] and the [[https://github.com/dkogan/talk-numpysane-gnuplotlib/raw/master/numpysane-gnuplotlib.pdf]["slides"]].

• NAME gnuplotlib: a gnuplot-based plotting backend for numpy

• SYNOPSIS

#+BEGIN_SRC python import numpy as np import gnuplotlib as gp

x = np.arange(101) - 50 gp.plot(x**2) #+END_SRC [[file:basic-parabola-plot-pops-up.svg]] #+BEGIN_SRC python

g1 = gp.gnuplotlib(title = 'Parabola with error bars', _with = 'xyerrorbars') g1.plot( x**2 * 10, np.abs(x)/10, np.abs(x)*25, legend = 'Parabola', tuplesize = 4 ) #+END_SRC [[file:parabola-with-x-y-errobars-pops-up-in-a-new-window.svg]] #+BEGIN_SRC python

x,y = np.ogrid[-10:11,-10:11] gp.plot( x2 + y2, title = 'Heat map', unset = 'grid', cmds = 'set view map', square = True, _with = 'image', tuplesize = 3) #+END_SRC [[file:Heat-map-pops-up-where-first-parabola-used-to-be.svg]] #+BEGIN_SRC python

theta = np.linspace(0, 6*np.pi, 200) z = np.linspace(0, 5, 200) g2 = gp.gnuplotlib(_3d = True) g2.plot( np.cos(theta), np.vstack((np.sin(theta), -np.sin(theta))), z ) #+END_SRC [[file:Two-3D-spirals-together-in-a-new-window.svg]] #+BEGIN_SRC python

x = np.arange(1000) gp.plot( (xx, dict(histogram= True, binwidth = 20000, legend = 'Frequency')), (xx, dict(histogram='cumulative', legend = 'Cumulative', y2 = True )), ylabel = 'Histogram frequency', y2label = 'Cumulative sum') #+END_SRC [[file:A-density-and-cumulative-histogram-of-x-2-are-plotted-on-the-same-plot.svg]] #+BEGIN_SRC python

gp.plot( (xx, dict(histogram=True, binwidth =20000, legend = 'Frequency')), (xx, dict(histogram='cumulative', legend = 'Cumulative')), _xmin=0, _xmax=1e6, multiplot='title "multiplot histograms" layout 2,1', _set='lmargin at screen 0.05') #+END_SRC [[file:Same-histograms-but-plotted-on-two-separate-plots.svg]] #+BEGIN_SRC python #+END_SRC

• DESCRIPTION For an introductory tutorial and some demos, please see the guide:

https://github.com/dkogan/gnuplotlib/blob/master/guide/guide.org

This module allows numpy data to be plotted using Gnuplot as a backend. As much as was possible, this module acts as a passive pass-through to Gnuplot, thus making available the full power and flexibility of the Gnuplot backend. Gnuplot is described in great detail at its upstream website: http://www.gnuplot.info

gnuplotlib has an object-oriented interface (via class gnuplotlib) and a few global class-less functions (plot(), plot3d(), plotimage()). Each instance of class gnuplotlib has a separate gnuplot process and a plot window. If multiple simultaneous plot windows are desired, create a separate class gnuplotlib object for each.

The global functions reuse a single global gnuplotlib instance, so each such invocation rewrites over the previous gnuplot window.

The object-oriented interface is used like this:

#+BEGIN_SRC python import gnuplotlib as gp g = gp.gnuplotlib(options) g.plot( curve, curve, .... ) #+END_SRC

The global functions consolidate this into a single call:

#+BEGIN_SRC python import gnuplotlib as gp gp.plot( curve, curve, ...., options ) #+END_SRC

** Option arguments

Each gnuplotlib object controls ONE gnuplot process. And each gnuplot process produces ONE plot window (or hardcopy) at a time. Each process usually produces ONE subplot at a time (unless we asked for a multiplot). And each subplot contains multiple datasets (referred to as "curves").

These 3 objects (process, subplot, curve) are controlled by their own set of options, specified as a python dict. A FULL (much more verbose than you would ever be) non-multiplot plot command looks like

#+BEGIN_SRC python import gnuplotlib as gp g = gp.gnuplotlib( subplot_options, process_options )

curve_options0 = dict(...) curve_options1 = dict(...)

curve0 = (x0, y0, curve_options0) curve1 = (x1, y1, curve_options1)

g.plot( curve0, curve1 ) #+END_SRC

and a FULL multiplot command wraps this once more:

#+BEGIN_SRC python import gnuplotlib as gp g = gp.gnuplotlib( process_options, multiplot=... )

curve_options0 = dict(...) curve_options1 = dict(...) curve0 = (x0, y0, curve_options0) curve1 = (x1, y1, curve_options1) subplot_options0 = dict(...) subplot0 = (curve0, curve1, subplot_options0)

curve_options2 = dict(...) curve_options3 = dict(...) curve2 = (x2, y2, curve_options2) curve3 = (x3, y3, curve_options3) subplot_options1 = dict(...) subplot1 = (curve2, curve3, subplot_options1)

g.plot( subplot0, subplot1 ) #+END_SRC

This is verbose, and rarely will you actually specify everything in this much detail:

• Anywhere that expects process options, you can pass the DEFAULT subplot options and the DEFAULT curve options for all the children. These defaults may be overridden in the appropriate place

• Anywhere that expects plot options you can pass DEFAULT curve options for all the child curves. And these can be overridden also

• Broadcasting (see below) reduces the number of curves you have to explicitly specify

• Implicit domains (see below) reduce the number of numpy arrays you need to pass when specifying each curve

• If only a single curve tuple is to be plotted, it can be inlined

The following are all equivalent ways of making the same plot:

#+BEGIN_SRC python import gnuplotlib as gp import numpy as np x = np.arange(10) y = x*x

Global function. Non-inlined curves. Separate curve and subplot options

gp.plot( (x,y, dict(_with = 'lines')), title = 'parabola')

Global function. Inlined curves (possible because we have only one curve).

The curve, subplot options given together

gp.plot( x,y, _with = 'lines', title = 'parabola' )

Object-oriented function. Non-inlined curves.

p1 = gp.gnuplotlib(title = 'parabola') p1.plot((x,y, dict(_with = 'lines')),)

Object-oriented function. Inlined curves.

p2 = gp.gnuplotlib(title = 'parabola') p2.plot(x,y, _with = 'lines') #+END_SRC

If multiple curves are to be drawn on the same plot, then each 'curve' must live in a separate tuple, or we can use broadcasting to stack the extra data in new numpy array dimensions. Identical ways to make the same plot:

#+BEGIN_SRC python import gnuplotlib as gp import numpy as np import numpysane as nps

x = np.arange(10) y = xx z = xx*x

Object-oriented function. Separate curve and subplot options

p = gp.gnuplotlib(title = 'parabola and cubic') p.plot((x,y, dict(_with = 'lines', legend = 'parabola')), (x,z, dict(_with = 'lines', legend = 'cubic')))

Global function. Separate curve and subplot options

gp.plot( (x,y, dict(_with = 'lines', legend = 'parabola')), (x,z, dict(_with = 'lines', legend = 'cubic')), title = 'parabola and cubic')

Global function. Using the default _with

gp.plot( (x,y, dict(legend = 'parabola')), (x,z, dict(legend = 'cubic')), _with = 'lines', title = 'parabola and cubic')

Global function. Using the default _with, inlining the curve options, omitting

the 'x' array, and using the implicit domain instead

gp.plot( (y, dict(legend = 'parabola')), (z, dict(legend = 'cubic')), _with = 'lines', title = 'parabola and cubic')

Global function. Using the default _with, inlining the curve options, omitting

the 'x' array, and using the implicit domain instead. Using broadcasting for

the data and for the legend, inlining the one curve

gp.plot( nps.cat(y,z), legend = np.array(('parabola','cubic')), _with = 'lines', title = 'parabola and cubic') #+END_SRC

When making a multiplot (see below) we have multiple subplots in a plot. For instance I can plot a sin() and a cos() on top of each other:

#+BEGIN_SRC python import gnuplotlib as gp import numpy as np th = np.linspace(0, np.pi*2, 30)

gp.plot( (th, np.cos(th), dict(title="cos")), (th, np.sin(th), dict(title="sin")), _xrange = [0,2.*np.pi], _yrange = [-1,1], multiplot='title "multiplot sin,cos" layout 2,1') #+END_SRC

Process options are parameters that affect the whole plot window, like the output filename, whether to test each gnuplot command, etc. We have ONE set of process options for ALL the subplots. These are passed into the gnuplotlib constructor or appear as keyword arguments in a global plot() call. All of these are described below in "Process options".

Subplot options are parameters that affect a subplot. Unless we're multiplotting, there's only one subplot, so we have a single set of process options and a single set of subplot options. Together these are sometimes referred to as "plot options". Examples are the title of the plot, the axis labels, the extents, 2D/3D selection, etc. If we aren't multiplotting, these are passed into the gnuplotlib constructor or appear as keyword arguments in a global plot() call. In a multiplot, these are passed as a python dict in the last element of each subplot tuple. Or the default values can be given where process options usually live. All of these are described below in "Subplot options".

Curve options: parameters that affect only a single curve. These are given as a python dict in the last element of each curve tuple. Or the defaults can appear where process or subplot options are expected. Each is described below in "Curve options".

A few helper global functions are available:

#+BEGIN_SRC python plot3d(...) #+END_SRC

is equivalent to

#+BEGIN_SRC python plot(..., _3d=True) #+END_SRC

And

#+BEGIN_SRC python plotimage(...) #+END_SRC

is e