download v. 0.5

gnuplueme by Hani Jamjoom

Ever wanted to plot, manipulate, and compare data at the end of your experimentation. gnuplotme is a simple intuitive front-end script for gnuplot. It also provides powerful mathematical and statistical capabilities for manipulating input data. Just like gnuplot you can plot different columns from multiple files, however, you do not need to know or understand how gnuplot really works. Furthermore, similar to Excel, you can use arbitrary functions of your data and automatically take the average and plot the confidence interval of multiple files. Here is how it works...

KEY FEATURES

* Intuitive command line to common gnuplot features
* Subsample of input data (useful in very large input files)
* Averages data from multiple input files and removes outliers
* Creates confidence interval across averaged input
* Plots any mathematical function that can be written in perl (e.g., plot your data against a closed-form function)
* Allows data series from lists or interval ranges (useful to automatically create x-axis values)
* Creates both .eps and text file that contains all manipulated data (useful later use or import into excel)

QUICK LINKS

* Installation
* Synopsis
* The Basics
* Subsampling Your Data
* Plotting Mathematical Functions
* Averages, Confidence Intervals, and Removing Outliers
* Output

INSTALLATION

gnuplotme is a perl script on top of gnuplot. So, you need to have both (gnuplot and perl) installed on your system. I have successfully ran gnuplotme on Linux, Max OS X, and Cygwin on Windows XP. Here is a brief summary of steps:

* Check that perl is installed on your system (e.g., $> perl --version)
* Check that gnuplot is installed on your system (e.g., $> gnuplot --version)
* Download download v. 0.5 into your favorite directory (e.g., /home/hani/bin)
* Chmod gnuplotme to be executable (e.g., chmod +x /home/hani/bin/gnuplotme)
* Invoke gnuplotme with fully-qualified path (e.g., /home/hani/bin/gnuplotme) or make sure that the directory where gnuplotme is stored (e.g., /home/hani/bin) is in the bin search path.

SYNOPSIS

advanced options:

THE BASICS

gnuplotme is a front-end script for plotting using gnuplot. It also provides powerful mathematical functionality similar to Excel functions. The idea is to be able to manipulate output data very easily without the need to learn perl, gnuplot, or anything else (besides a couple of command options).

Most of the options (I hope) are self-explanatory:

specifies the name of the output file. Also, see OUTPUT section below.

To specify the y-axis values?

specifies the column in the file <file_name> to be plotted. It also specifies the label to be used in the legend key. Columns can be separated by spaces or tabs (not commas).

To specify the x-axis values?

In --file or --plot, if <plot_label> is as "xaxis", the corresponding values are used as values for the x-axis.

Simple Example:

Lets start with a simple example. This is a file (called mydata.txt) that contains the following:

Now, lets use the first column as the x-axis and second column for the data series:

Now, lets add a second data series (use the second column in mydata.txt):

To add labels:

specifies the labels for the x and y axes, respectively. The label should be in quotes. For -ylabel, the [<axis>] is an optional parameter that is either "left" or "right" (default is left)

specifies the title of the graph, it should be in quotes. It is drawn above the graph.

Back to our example, lets add x- and y-labels:

Additional Controls

specifies the range for the x and y axes, respectively the [<axis>] is an optional parameter that is either "left" or "right" (default is left).

specifies the location of the legend key in the graph.

a simple way to make either the left or right y axes draws with scale 0 to 100, with 4 ticks every 25 points

you can have the x, y, or both axes drawn in log scale.

is used to change the ticks on either the left or right axes.

Specifying data on right y-axis

All lines specified by the --file option are plotted on the left axis. If the right axis is desired, the --set and --plot options must be used.

SUBSAMPLING YOUR DATA

if a file (or variable defined below) has too many sample points, you can very easily subsample the data using the --subsample option.

Back to our example, lets subsample by 2 (i.e., will use every 2nd sample point in the plot):

PLOTTING MATHEMATICAL FUNCTIONS

Any mathematical function that is supported in Perl can be plotted in gnuplotme. Similar to matlab, you have to define the input variables to the function. Each variable holds a matrix of points (e.g., a column in a data file). There are three ways to define variables in gnuplotme:

* using a column in a file: --set <variable_name> file <filename> <column>
* using a range of values: --set <variable_name> range <low> <high> <step>
* using a list of values: --set <variable_name> list <y1> <y2> <y3> ...

For example,

defines x as a variable with values extracted from the second column of the file "foo", or

defines x as a variable with the values [2,4,6,8,10], or

defines x as a variable with the values [5,10,15,20,25,30].

Once a variable is defined, the --plot can then be used to plot any function of the defined variables. For example:

will plot the values of y with a legend name of RTT and on left axis. Recall, if the axis name is omitted, the left one is used by default. Another example is:

will plot the difference between corresponding square values of x and y on the right axis.

How functions are computed?

A function takes as input one value from each variable. Notice that the functions do not allow manipulating more than one point at a time from all variables. That is, if x=[6,12,18,24,30,36], y=[5,10,15,20,25,30], and f(x,y) = x**2 - y**2 then the result will be [11,44,99,176,275,396].

gnuplotme includes some macros that operate on all values of a variable. These macros can be used in "--plot" as part of the function:

1. total_<varname>: sum of all values of the variable varname.
2. count_<varname>: how many points the variable has.
3. mean_<varname>: mean value of all values of the variable varname
4. variance_<varname>: the corresponding variance of all values.

For example,

will plot the difference between each value of x and the mean of all values, with label "error".

AVERAGES, CONFIDENCE INTERVALS, AND REMOVING OUTLIERS

gnuplotme also provides simple method for averaging data from multiple files and plotting the confidence interval, if desired. This is done using the --set option with the avg sub-option (--set <variable_name> avg <column <outliers> <conf> <file1> <file2> ...)

Here is an example,

will average the third column of files foo.1, ..., foo.4. It also computes the 95% confidence interval. Other allowed confidence values are 20, 40, 60, 80, 90, 95, 98, and 99 intervals. The variable z will contain the average values of the four files, which can then be used just like any other value. The confidence interval is only plotted when the variable is specified by itself in the --plot command. For example,

will plot the average points of the variable z with the confidence bars. However,

will only plot the square of the average values of z.

The outlier field will remove the n highest and smallest values of each row in the specified files, where n is the specified value. This is used to remove the outliers from the collected data. In our example, we specified outlier=1 to remove the highest and lowest values.

will average the third column across the 12 files, but before computing the average, it will remove the top and bottom 2 values from each row.

OUTPUT

gnuplotme produces three files. There are the filename.data, filename.gnu, and filename.eps, where the filename is specified with the --outfile option. The .data file will contain the data points to be plotted. It can be imported into Excel for example for prettier plots. The .gnu file contains the script used by gnuplot to generate the plot, which is the .eps file.