feedgnuplot/README

feedGnuplot README
==================

This is a flexible, command-line-oriented frontend to Gnuplot. It creates
plots from data coming in on STDIN or given in a filename passed on the
commandline. Various data representations are supported, as is hardcopy
output and streaming display of live data. A simple example:


seq 5 | awk '{print 2*$1, $1*$1}' |
feedGnuplot.pl --lines --points --legend "data 0" --title "Test plot" --y2 1


You should see a plot with two curves (one on the y1 axis and the other on
the y2 axis), a legend and a title. The first line of the example generates
some data to plot and the second reads it in from STDIN and generates the
plot. None of the commandline-options are required for the most basic
plotting. Input parsing is flexible; every line need not have the same
number of points. New curves will be created as needed.

By default, the line number of the incoming data is used for the x-axis. To
plot an x-y dataset, feed in the x values as the first element in every line
and pass in --domain. With the previous example:


seq 5 | awk '{print 2*$1, $1*$1}' |
feedGnuplot.pl --domain --lines --points --legend "data 0" --title "Test plot" --y2 1


we get only one curve, with different x values. As many points as desired
can appear on a single line, but all points on a line are associated with
the X value that starts that line.

By default, each column represents a separate curve. If sparse data is to be
plotted, this is undesireable. With the --dataid option, each point in the
input is preceded by string identifying the curve the point belongs
to. With the previous example:


seq 5 | awk '{print 2*$1, $1*$1}' |
feedGnuplot.pl --dataid --lines --points --legend "data 0" --title "Test plot" --y2 1


we get 5 different curves with one point in each. The first column, as
produced by awk, is '2,4,6,8,10'. These are interpreted as the indices of
the curves to be plotted. The feedGnuplot.pl script created 11 different
curves (0-10 inclusive), but only 5 of them were given any data. Note that
with this invocation of the example no legend was created. This is because
the legend commandline parameters are applied in order to curves
0,1,2,... Above, "data 0" applied to curve 0, which had no data. If we
passed in --legend "data 0" --legend "data 1" --legend "data 2", a legend
would be created with "data 2" labeled, but no labels for the other
curves. As many points as desired can appear on a single line, and --domain
can be used together with --dataid.

Note that the IDs used with --dataid are general strings, NOT just
numbers. These IDs can be used to generate the plot legend with --autolegend.

The script is able to produce hardcopy output with "--hardcopy
outputfile". The output type is inferred from the filename with .ps, .pdf
and .png currently supported.

If live data is received in realtime, feedGnuplot.pl can be used to produce a
realtime display by passing in the --stream option. The "--xlen windowsize"
option can be passed in also to plot a scrolling window, containing the last
windowsize-worth of data (windowsize has the units of the x axis, whether it
is a point index or the passed-in domain). If --xlen is omitted or set to 0,
all of the available data is plotted, with no moving window. The realtime data
is updated at 1 Hz, so the script can handle rapidly-incoming data without
spending all of its time replotting. Example:


seq 500 | awk '{print 2*$1, $1*$1; system("sleep 2"); fflush()}' |
feedGnuplot.pl --stream --lines --points --legend "data 0" --title "Test plot" --y2 1


This script can be used to generate self-plotting data files. If a file
called 'data' is created with:


#!/usr/local/bin/feedGnuplot.pl --lines --points --legend "data 0" --title "Test plot" --y2 1
2 1
4 4
6 9
8 16
10 25
12 36
14 49
16 64
18 81
20 100
22 121
24 144
26 169
28 196
30 225


This file can be plotted with


bash$ ./tst


The caveats here are that on Linux the whole #! line is limited to 127
charaters and that the full path to feedGnuplot.pl must be given.

For more information, invoke with --help, or read the source. Any bugs or
suggestions should be addressed to dkogan@cds.caltech.edu. The latest
version of the script is available at http://github.com/dkogan/feedgnuplot


This program is originally based on the driveGnuPlots.pl script from
Thanassis Tsiodras. It is available from his site at
http://users.softlab.ece.ntua.gr/~ttsiod/gnuplotStreaming.html