Gnuplot and gpwrapper

Introduction

Excel does not produce acceptable plots for publication. Therefore, we use gnuplot to produce clean professional plots especially for publications and thesis documentation.

Gnuplot

Gnuplot is available for all operating systems. Here is the primary link for gnuplot. Gnuplot has a bit of a learning curve and requires setting a lot of options to produce consistent plots.

gpwrapper

While expert users can easily write gnuplot scripts to generate plots, beginners find it really hard to use. Furthermore, in order to maintain a consistent look across all the work done as a part of ResiliNets group, users need to maintain consistent linestyles. Therefore, I have written a front end script in perl that makes life a bit easier. (Note: I said a bit....not magic) The purpose of gpwrapper is to

1. Provide a easy to use front end to generate reasonable plots
2. Define sensible defaults for line styles, line colors, and font sizes (so that they are still visible when the figures are scaled down to IEEE two column format)
3. Generate three versions of each plot:
   1. colored plot for light background
   2. colored plot for dark background
   3. black and white plot
4. Convert eps plots generated by the postscript terminal of the gnuplot to pdf and transparent pngs
5. Minor adjustments to axes labels, margins, legend, etc to account for larger font sizes

NOTE: gpwrapper can run only on linux. Sorry Windows and OS X.

Installation

In order to use gpwrapper on a personal machine, you will need gnuplot 4.3 or higher (note that 4.3 is beta), ImageMagick, epstopdf. Also you need to either change or remove the font path specified to postscript terminal. Unless you are an expert (at least advanced) user in Linux, you are highly encouraged to use gpwrapper on ITTC machines. You do not need to install anything when using gpwrapper on any ittc machine. The inbuilt paths will work fine.

To use gpwrapper in ITTC download the latest_version of the gpwrapper (currently version 5) from the ResiliNets SVN repository.

DO NOT COPY the script from email/trac/browser. This script produces a gnuplot script that is fed to gnuplot. So, yes, its fragile. An additional space or line feed will result in incomprehensible errors.

Plotting Terminology

This info is only for beginners. Skip this if you already know it.

1. Plot : Generated figure
2. Curve: One set of data [(x,y) points] constitutes a curve. In other words, every line (or points) that you see on the plot is a curve
3. Axes: There are 4 axes: x1,x2,y1,y2. x1 is the bottom x-axis, x2 is the top x-axis, y1 is the left y-axis, y2 is the right y-axis
4. Legend: The information regarding the curves that is displayed on the plot (usually on the top right hand corner of the plot)
5. Title of the curve: The text that goes in the legend for each plot is the title of the curve

Usage

The basic way to use gpwrapper to plot one curve is to give gpwrapper a file with x,y values. gpwrapper can be used in three modes: files, columns, multiaxis

• Files mode: Use this mode if you want to plot only one curve on the plot or the data for multiple curves is in separate files

syntax: 
gpwrapper files  <num_of_curves[n]>  <scenario_name[foobar]>  <file1> <title1> <file2> <title2>...
example:
./gpwrapper files 2 testscenario data1file.txt 'p=0.1' data2file 'p=0.2'

• Columns mode: Use this mode if you want to plot multiple curves and the data for these curves in in one file as columns

syntax:
gpwrapper columns  <num_of_curves[n]>  <scenario_name[foobar]>  <input_data_file[foobar]> <cols1[1:2]> <title1> <cols2[1:3]> <title2>...
example:
./gpwrapper columns 2 testscenario datafile.txt 1:2 'p=0.1' 1:3 'p=0.2'

• Multi-axis columns mode: Use this mode if you want to use multiple axis. For multiple curves this mode only supports multiple columns.

syntax:
gpwrapper multiaxis-col  <num_of_curves[n]>  <scenario_name[foobar]>  <input_data_file[foobar]> <cols1[1:2]> <title1> <axes[x1y1]> <cols2[1:3]> <title2>...
example:
./gpwrapper multiaxis-cols 2 testscenario datafile.txt 1:2 'p=0.1' x1y1 1:3 'p=0.2' x1y2

User Options

Remember that I said earlier that gpwrapper makes it only easier to generate plots and can't do magic? I was serious!

The user needs to set a number of options that are plot specific. At the bare minimum, the user must specify

• axes labels
• location of the legend

To further tune the plot, the user can specify a lot more options.

All options can be set inside the grpwrapper script at the very top under the section "User Defined Variables". All variables are commented and self explanatory.

Testing Flag

Since gpwrapper produces 9 version of a single plot [ 3types (light color, dark color, black and white) and 3 formats (eps, pdf, png)], the user can set a testing flag in the user defined properties to produce only 3 versions of a plot (light color - eps,pdf,png). This options avoids too many files when user is simply trying out the program or data.

Error Bars

gpwrapper supports both symmetric or asymmetric error bars. In order to use error bars, the input data must contain either a ydelta (error of a value) or the min and max (ymin, ymax) values.

In order to use display error bars in the plot, use the following steps

1. set the curve_type to "yerrorlines" or "yerrorbars" in the gpwrapper (line 72). Note that yerrorlines will produce error bars on top of a line graph where as yerrorbars puts the error bars on top of a point graph.
2. Invoke gpwrapper in columns mode.
3. Pass the errovalue (or min, max) columns along with the data columns.
4. For example, if the x is first column, y is second column and ydelta (error) is third column, use as follows

./gpwrapper columns 2 testscenario datafile.txt 1:2:3 'p=0.1'

1. Multiple curves can be plotted as usual. Example:

./gpwrapper columns 2 testscenario datafile.txt 1:2:3 'p=0.1' 1:4:5 'p=0.2'

NOTES:

1. Error bars are also supported when using gpwrapper in "files" mode. In this case, set the proper columns data_cols filed (line 71)
2. Error bars on x-values are also supported. For this purpose, simply use "xerrorlines" or "xerrorbars" as the curvetype

Questions/Help

See Figure 1. If you still have questions, email me at jabbar@ittc.ku.edu

Miscellaneous Stuff

Wikipedia link for postscript terminal line and point types: link