:: Hani Jamjoom (هاني جمجوم) :: Tools

gnuplotme02

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...

SYNOPSIS

gnuplotme --help
--outfile <file_name>
--file <file_name> <plot_label> <column>
--xlabel <x_axes_label>
--ylabel <y_axes_label> [<axis>]
--xrange <low:hi>
--yrange <low:hi> [<axis>]
--title <title>
--key <x,y>
--percent [left,right,both]
--log_scale <x or y or xy>
--subsample <period>

advanced options:

--set <variable_name> { {file <filename> <column>} |
{range low high step} |
{list y1 y2 y3 ... } |
{avg <column> <outliers> <conf> file1 file2 ... }}
--plot <function> <plot_label> [<axis>]
--ytics <low,step,hi> [<axis>]

DESCRIPTION

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 are self-explanatory:

--outfils specifies the name of the output file. See OUTPUT section below
--files specifies the column in the file <file_name> to be plotted. It also specifies the identifier to be used in the legend key. 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.

How to specify the X-axis values?

Skipping ahead a bit, in --file or --plot, if <plot_label> is as "xaxis", the corresponding values are used as values for the x-axis.

--xlabel
--ylabel specifies the labels for the x and y axes, respectively the [<axis>] is an optional parameter that is either "left" or "right" (default is left)
--xrange
--yrange 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).
--title specifies the title of the graph. It is drawn above the graph
--key specifies the location of the legend key in the graph.
--percent a simple way to make either the left or right y axes draws with scale 0 to 100, with 4 ticks every 25 points
--logscale you can have the x, y, or both axes drawn in log scale.
--subsample if a file (or variable defined below) has too many sample points, you can increase the period by as much as you like with this option. For example, --subsample 5 will use every 5th sample point in the plot.
--ytics is used to change the ticks on either the left or right axes.

SUPPORTED FUNCTIONS

Any mathematical function that is supported in Perl is also supported in gnuplotme. The --set option defines a variable and the values that it could take. These values can be from a file, a range, or a list. For example,

--set x file foo 2

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

--set y range 5 30 5

--set y list 5 10 15 20 25 30

defines y as a variable with the values [5,10,15,20,25,30]. The --plot can then be used to plot any function of the defined variables. For example:

--plot y RTT left

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

--plot x**2 - y**2 Diff

would plot the difference between corresponding square values of x and y. Notice that the functions does not allow manipulating more than one point at a time from all variables. That is, if x=[6,12,18,24,30 ,36] and y=[5,10,15,20,25,30], then the result will be [11,44,99,176,275,396]. To manipulate all the values of a single variable, gnuplotme provides four functions with each variable:

total_varname: sum of all values of the variable varname.
count_varname: how many points the variable has.
mean_varname: mean value of all values of the variable varname
variance_varname: the corresponding variance of all values.

For example,

--plot "x-mean_x" error right

will plot the difference between each value of x and the mean of all values on the right axis.

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. Here is an example,

--set z avg 3 1 95 foo.1 foo.2 foo.3 foo.4

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,

--plot z somename

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

--plot z**2 somename

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.

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.