From 7c9c9b82be882a3c48dc0b1bff93150268ae3dd0 Mon Sep 17 00:00:00 2001 From: Dima Kogan Date: Tue, 12 Jan 2010 21:39:02 -0800 Subject: [PATCH] initial commit of the README --- README | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..b7e5d8f --- /dev/null +++ b/README @@ -0,0 +1,62 @@ +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 --dataindex option, each point in +the input is preceded by an integer identifying the curve the point belongs +to. With the previous example: + +seq 5 | awk '{print 2*$1, $1*$1}' | +feedGnuplot.pl --dataindex --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 --dataindex. + +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 something is producing data in realtime, feedGnuplot.pl can be used to +produce a realtime display. The --stream option should be passed in along +with "--xlen windowsize". This will produce 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 data). The scrolling window is +updated at 1 Hz, so the script can handle rapidly-incoming data without +spending all of its time replotting. + +For more information, invoke with --help, or read the source.