NAME

gplot.pl - A smart frontend for gnuplot 4.0 and above

SYNOPSIS

    gplot.pl my.data
    gplot.pl -color blue my.data
    gplot.pl -title "My results"  my.data
    gplot.pl -type jpg -title "My results"  my.data
    gplot.pl -title "Our results"  \
        -color red my.data   -color blue your.data

DESCRIPTION

This program provides a convenient front-end for gnuplot 4.0. Previous versions of gnuplot have a different syntax and you should be using gplot.pl version 1.1 for these. It accepts a large set of options to generate a single plot of one or more sets of data (overlaid as necessary). The X and Y axis will be scaled automatically.

The options are provide in two categories. Most options apply to the entire plot (e.g. title) whereas a smaller set can be entered multiple times so that certain values can be set for each plot (e.g. color for each plot). This may require careful reading of the options listed below.

This adds no new functionality to gnuplot, but makes it easier to generate GNUPLOT input. Gnuplot input can be very confusing when trying to assign useful colors (linetypes) or linepoints since it uses numeric values that vary based on the output device. gplot.pl allows you to set various attributes with English words like 'red' and 'triangle', thereby simplifying the interaction with gnuplot. This program only supports Postscript, PBM, PNG, JPG and 'X`` output.

Additional information on using gnuplot is available at

    http://www.gnuplot.info/
    http://www.ucc.ie/gnuplot/gnuplot.html
    http://www.duke.edu/~hpgavin/gnuplot.html

GLOBAL OPTIONS

These options apply to all data that is plotted. You may not usefully specify these more than once.

-font string
Specifies the font used for -xlabel and -ylabel. This uses the default for your gplot and terminal. This setting may not be applied for all -type settings, but *is* applied for Postscript.

-fontsize N
Specifies the fontsize used for -xlabel and -ylabel. This uses the default for your gplot and terminal. If you specify -font, this defaults to 12. This setting may not be applied for all -type settings, but *is* applied for Postscript.

-help
Shows help for this command.

-onecolumn
If specified, this indicates all of the datafiles to be plotted have only one column of Y data. We will copy the data creating two columns of data. The x axis begins with 0 and increments by 1. Temporary input files are deleted when the plot is finished.

-outfile file
Specifies the name of the output file to be created. The default is '/tmp/gplot.' followed by the -type of plot (e.g. '-type ps' creates '/tmp/gplot.ps').

-plotcmds file
Specifies that the input commands should be taken from 'file'. If not provided a default set are used. Read ``PSEUDO COMMANDS IN YOUR OWN GNUPLOT FILE'' for more details on this option.

-showgnuplot
If set, this will cause the GNUPLOT commands to be written to STDOUT. This is useful if you want to capture the output from gplot.pl and then tailor this to add your own gnuplot commands. See also the -plotcmds option.

-tfont string
Specifies the font used for -title. This uses the default for your gplot and terminal. This setting may not be applied for all -type settings, but *is* applied for Postscript.

-tfontsize N
Specifies the fontsize used for -title. This uses the default for your gplot and terminal. If you specify -font, this defaults to 14. This setting may not be applied for all -type settings, but *is* applied for Postscript.

-title string
Specifies the title shown at the top of the page. If 'string' is a null string, no title is displayed.

-type xwin|jpg|jpeg|png|pbm|ps|eps
Specifies the types of output plots are to be created. Values may be 'xwin' (generate a plot and show it on the screen), 'png', 'pbm', 'jpg' or 'jpeg' (create a graphic), 'eps' (create encapsulated postscript), or 'ps' (create a postscript file). The default is 'xwin'.

If you create a Postscript file, you can usefully print it with a command like:

    lpr my.ps

You may convert a Postscript file to a PDF with:

    ps2pdf14 my.ps my.pdf

You may create a JPEG file by first creating a PBM file and then:

    cjpeg  my.pbm > my.jpg

-xlabel string
Specifies the X label of the plot. Just how this is displayed will vary based on -type. If 'string' is a null string, no label is displayed.

-ylabel string
Specifies the Y label of the plot. Just how this is displayed will vary based on -type. Postscript output will have the label written vertically. If 'string' is a null string, no label is displayed.

OPTIONS FOR EACH FILE TO PLOT

These options may be specified more than once so that you may control the appearance of each data that is plotted. For example if you have three files of data to plot and want them plotted with different colors, you might do:

  gplot.pl -color red 1.data -color blue 2.data -color green 3.data
-dateformat format
Specifies the X coordinate data are dates in the format 'format'. 'Format' should consist of a series of %-keys describing the format of the data. For instance '%y%m%d' says the data conists of a TWO digit year followed by a two digit month and a two digit day. ``%m/%d/%y'' is month, day and year separated by a slash. If you want a barchart, include the option '-style impulses'.

-color string
Specifies the color the data will be plotted in. When generating a Postscript file, the lines will not only be in the color you specify, but the lines themselves are each different so you can print the Postscript file to a non-color printer and still distinguish the lines. Specify 'gplot.pl' to see a list of colors supported.

-name string
Specifies the label for this plot. This shows in the legend showing the line color and point.

-point string
Specifies the shape of the datapoint used for this plot. For no reason that is obvious, gnuplot has DIFFERENT SETS OF POINTS based on value of the -type option. Postscript has a large set of supported shapes (circles, boxes, fillcircles, filldowntriangles to name a few). The other types of output have only six supported shapes. Specify 'gplot.pl' (with no parameters) to see a list of points supported.

-pointsize F
Specifies the size of the datapoint used for this plot. See the -point option. This is a floating point number. Useful numbers seem to be about one-half. Larger values will create large and probably uninteresting datapoints on the plot.

-style name
Specifies the 'style' to be used for this plot. This value depends on your version of gnuplot, but includes at least the following: boxes, dots, impulses (for simple barcharts), lines, linespoints (the default), points, steps and vector.

-using X:Y
Specifies the input columns for the X and Y columns to be printed. Note that a colon separates the two values. A value like '-using 4:2' means that the input data has at least four columns and the fourth column is the X value and the second is the Y value. The default is '-using 1:2'.

-thickness N
Specifies the thickness of the line used for this plot. The default is 1. Values over two seem uninteresting unless you specify '-style impulses' to produce simple barcharts.

PARAMETERS

infile1 ... infileN
Specifies the name of the files to be plotted. If more than one is provided, the plots are overlaid and a new -color and -point will be chosen. You may (and should) specify your own -color and -point options for each plot.

PSEUDO COMMANDS IN YOUR OWN GNUPLOT FILE

It is possible for you to provide your own file of gnuplot commands and still take advantage of gplot.pl. The -showgnuplot command will print to STDOUT the input file provided to gnuplot. This is a good place to start. For example the command 'gplot.pl 1a.data' creates this file:

    #   GPLOT.PL pseudo commands for GNUPLOT
    set xlabel "X" font "Helvetica,12"
    set ylabel "Y" font "Helvetica,12"
    set multiplot
    set autoscale
    set data style lines
    set border 3
    set xtics border nomirror
    set ytics border nomirror
    set origin 0.0,0.0
    set title "No title provided" font "Helvetica,14"
    set style line 10 lt 1 lw 1 pt 10 ps 2.0
    plot '1a.data' using 1:2 title '1a.data' with linespoints linestyle 10

Most of this looks pretty straightforward - except for the 'style line' (especially) and plot lines. gplot.pl uses meaningful words as values for -color and -point and converts these to the numbers you see above.

You can provide your own gnuplot input and have gplot.pl make the substitution that it normally does. Specify the file of gnuplot commands with the -plotcmds option. If you put keywords in this file, gplot.pl will replace the keywords with the correct values for -color etc. The only thing to know are the details of the keywords. The default 'file' of gnuplot commands in gplot.pl looks like:

    #   GPLOT.PL pseudo commands for GNUPLOT
    IF TYPE eq ps   set terminal postscript landscape color
    IF TYPE eq eps  set terminal postscript eps color
    IF TYPE eq jpg  set terminal jpeg
    IF TYPE eq png  set terminal png
    IF TYPE eq pbm  set terminal pbm
    IF TYPE ne xwin set output "%OUTFILE%"
    set xlabel "%XLABEL%" font "%FONT%,%FONTSIZE%"
    set ylabel "%YLABEL%" font "%FONT%,%FONTSIZE%"
    set multiplot
    set autoscale
    set data style lines
    set border 3
    set xtics border nomirror
    set ytics border nomirror
    set origin 0.0,0.0
    set title "%TITLE%" font "%TFONT%,%TFONTSIZE%"

Comparing this file with the final input to gnuplot, you will immediately notice the 'IF TYPE' and '%key%' strings. The 'IF TYPE' strings provide a very simple logic capability so we can generate the proper 'set terminal' commands based on the -type option.

Strings of the form '%key%' are keywords substituted directly from the various options to gplot.pl (%XLABEL% is replaced by the value for -xlabel etc.).

For each input file, gplot.pl adds a 'style line' command like this:

    set style line %s lt &COLOR& lw %THICKNESS% pt &POINT& ps %POINTSIZE%

This has the same '%key%' strings which are changed as described above. You'll also notice '&key&' strings which go through a similar substitution, only twice. For instance '&COLOR&' is replaced by the value for -color which might be 'red' (actually it becomes '%red%'). This value is then replaced as above, converting '%red%' into '1'. Note that '%s' is replaced with a number that gets incremented for each input file.

A second string is built for each input file and looks like this:

    '%INFILE%' using %USING% title '%NAME%' with linespoints linestyle %s

This string follows the same substitution conventions shown above.

-PLOTCMDS EXAMPLE

A good start is the internal form used by gplot.pl itself (you may, of course, do anything that gnuplot will be happy with) and then add your own special commands. You may want to check out the URLs mentioned at the top of this help file. In this example, we start with the gplot.pl default file and add a few lines as noted in the comments:

    #   GPLOT.PL pseudo commands for GNUPLOT
    IF TYPE eq ps   set terminal postscript landscape color
    IF TYPE eq eps  set terminal postscript eps color
    IF TYPE eq jpg  set terminal jpeg
    IF TYPE eq png  set terminal png
    IF TYPE eq pbm  set terminal pbm
    IF TYPE ne xwin set output "%OUTFILE%"
    set xlabel "%XLABEL%" font "%FONT%,%FONTSIZE%"
    set ylabel "%YLABEL%" font "%FONT%,%FONTSIZE%"
    set multiplot
    set autoscale
    set data style lines
    set border 3
    set xtics border nomirror
    set ytics border nomirror
    set origin 0.0,0.0
    set title "%TITLE%" font "%TFONT%,%TFONTSIZE%"
    #   Get rid of the legend
    set nokey
    #   Add a couple of comments to the plot
    set label "Peak" at 145,1.95
    set label "RH Point" at 170,0.95
    #   Put in tags vertically at 1.8, downwards
    set label "June 1990"  at 60,1.8 right rotate font "Helvetica,8"
    set label "May 1990"   at 50,1.8 right rotate font "Helvetica,8"
    set label "April 1990" at 40,1.8 right rotate font "Helvetica,8"

Generate plots with

    gplot.pl -type ps -plotcmds test.gnuplot -xlabel Contributions \
        -ylabel "Rate (cm/day)" -title "Annotated Example" 1a.data

If you use -type xwin (the default), the labels will be horizontal and not vertical. Using another -type value will generate something more meaningful.

Notice that the test.gnuplot file contained no linetype or plot commands - gplot.pl generated them for you.

EXIT

If no fatal errors are detected, the program exits with a return code of 0. Any error will set a non-zero return code.

AUTHOR

Written by Terry Gliedt <tpg@umich.edu> in 2003 and is made available under terms of the GNU General Public License.