Plotting with Gnuplot
Keywords: manual

Subsections

- Proper Gnuplot configuration
- The `IPython.GnuplotRuntime` module
- The `numeric` profile: a scientific computing environment

#
Plotting with `Gnuplot`

Through the magic extension system described in sec. 6.2, IPython incorporates a mechanism for conveniently interfacing with the Gnuplot system (`http://www.gnuplot.info`). Gnuplot is a very complete 2D and 3D plotting package available for many operating systems and commonly included in modern Linux distributions.

Besides having Gnuplot installed, this functionality requires the `Gnuplot.py` module for interfacing python with Gnuplot. It can be downloaded from: `http://gnuplot-py.sourceforge.net`.

## Proper Gnuplot configuration

As of version 4.0, Gnuplot has excellent mouse and interactive keyboard support. However, as of `Gnuplot.py` version 1.7, a new option was added to communicate between Python and Gnuplot via FIFOs (pipes). This mechanism, while fast, also breaks the mouse system. You must therefore set the variable `prefer_fifo_data` to `0` in file `gp_unix.py` if you wish to keep the interactive mouse and keyboard features working properly (`prefer_inline_data` also must be `0`, but this is the default so unless you've changed it manually you should be fine).

'Out of the box', Gnuplot is configured with a rather poor set of size, color and linewidth choices which make the graphs fairly hard to read on modern high-resolution displays (although they work fine on old 640x480 ones). Below is a section of my `.Xdefaults` file which I use for having a more convenient Gnuplot setup. Remember to load it by running ``xrdb .Xdefaults``:

`!******************************************************************`
`! gnuplot options`
`! modify this for a convenient window size`
`gnuplot*geometry: 780x580`

`! on-screen font (not for PostScript)`
`gnuplot*font: -misc-fixed-bold-r-normal-15-120-100-100-c-90-iso8859-1`

`! color options`
`gnuplot*background: black`
`gnuplot*textColor: white`
`gnuplot*borderColor: white`
`gnuplot*axisColor: white`
`gnuplot*line1Color: red`
`gnuplot*line2Color: green`
`gnuplot*line3Color: blue`
`gnuplot*line4Color: magenta`
`gnuplot*line5Color: cyan`
`gnuplot*line6Color: sienna`
`gnuplot*line7Color: orange`
`gnuplot*line8Color: coral`

`! multiplicative factor for point styles`
`gnuplot*pointsize: 2`

`! line width options (in pixels)`
`gnuplot*borderWidth: 2`
`gnuplot*axisWidth: 2`
`gnuplot*line1Width: 2`
`gnuplot*line2Width: 2`
`gnuplot*line3Width: 2`
`gnuplot*line4Width: 2`
`gnuplot*line5Width: 2`
`gnuplot*line6Width: 2`
`gnuplot*line7Width: 2`
`gnuplot*line8Width: 2`

## The `IPython.GnuplotRuntime` module

IPython includes a module called `Gnuplot2.py` which extends and improves the default `Gnuplot`.`py` (which it still relies upon). For example, the new `plot` function adds several improvements to the original making it more convenient for interactive use, and `hardcopy` fixes a bug in the original which under some circumstances blocks the creation of PostScript output.

For scripting use, `GnuplotRuntime.py` is provided, which wraps `Gnuplot2.py` and creates a series of global aliases. These make it easy to control Gnuplot plotting jobs through the Python language.

Below is some example code which illustrates how to configure Gnuplot inside your own programs but have it available for further interactive use through an embedded IPython instance. Simply run this file at a system prompt. This file is provided as `example-gnuplot.py` in the examples directory:

    #!/usr/bin/env python
    """
    Example code showing how to use Gnuplot and an embedded IPython shell.
    """

    from Numeric import *
    from IPython.numutils import *
    from IPython.Shell import IPShellEmbed

    # Arguments to start IPython shell with. Load numeric profile.
    ipargs = ['-profile','numeric']
    ipshell = IPShellEmbed(ipargs)

    # Compute sin(x) over the 0..2pi range at 200 points
    x = frange(0,2*pi,npts=200)
    y = sin(x)

    # In the 'numeric' profile, IPython has an internal gnuplot instance:
    g = ipshell.IP.gnuplot

    # Change some defaults
    g('set style data lines')

    # Or also call a multi-line set of gnuplot commands on it:
    g("""
    set xrange [0:pi]     # Set the visible range to half the data only
    set title 'Half sine' # Global gnuplot labels
    set xlabel 'theta'
    set ylabel 'sin(theta)'
    """)

    # Now start an embedded ipython.
    ipshell('Starting the embedded IPyhton.\n'
            'Try calling plot(x,y), or @gpc for direct access to Gnuplot"\n')

    #********************** End of file <example-gnuplot.py> *********************

## The `numeric` profile: a scientific computing environment

The `numeric` IPython profile, which you can activate with ``ipython -p numeric`' will automatically load the IPython Gnuplot extensions (plus Numeric and other useful things for numerical computing), contained in the `IPython.GnuplotInteractive` module. This will create the globals `Gnuplot` (an alias to the improved Gnuplot2 module), `gp` (a Gnuplot active instance), the new magic commands `%gpc` and `%gp_set_instance` and several other convenient globals. Type `gphelp()` for further details.

This should turn IPython into a convenient environment for numerical computing, with all the functions in the NumPy library and the Gnuplot facilities for plotting. Further improvements can be obtained by loading the SciPy libraries for scientific computing, available at `http://scipy.org`.

If you are in the middle of a working session with numerical objects and need to plot them but you didn't start the `numeric` profile, you can load these extensions at any time by typing
`from IPython.GnuplotInteractive import *`
at the IPython prompt. This will allow you to keep your objects intact and start using Gnuplot to view them.