diff --git a/README b/README deleted file mode 100644 index 0b90534..0000000 --- a/README +++ /dev/null @@ -1,115 +0,0 @@ -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 diff --git a/README.pod b/README.pod new file mode 100644 index 0000000..c9ca34b --- /dev/null +++ b/README.pod @@ -0,0 +1,193 @@ +=head1 NAME + +feedGnuplot - A pipe-oriented frontend to Gnuplot + +=head1 SYNOPSIS + +Simple plotting of stored data: + + $ seq 5 | awk '{print 2*$1, $1*$1}' + 2 1 + 4 4 + 6 9 + 8 16 + 10 25 + + $ seq 5 | awk '{print 2*$1, $1*$1}' | + feedGnuplot --lines --points --legend "data 0" --title "Test plot" --y2 1 + +Simple real-time plotting example: plot how much data is received on the wlan0 +network interface in bytes/second (uses bash, awk and Linux): + + $ while true; do sleep 1; cat /proc/net/dev; done | + awk '/wlan0/ {if(b) {print $2-b; fflush()} b=$2}' | + feedGnuplot --lines --stream --xlen 10 --ylabel 'Bytes/sec' --xlabel seconds + +=head1 DESCRIPTION + +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 + +You should see a plot with two curves. The C command generates some data to +plot and the C reads it in from STDIN and generates the plot. The + invocation is just an example; more interesting things would be plotted in +normal usage. 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. + +The most commonly used functionality of gnuplot is supported directly by the +script. Anything not directly supported can still be done with the +C<--extracmds> and C<--curvestyle> options. Arbitrary gnuplot commands can be +passed in with C<--extracmds>. For example, to turn off the grid, pass in +C<--extracmds 'unset grid'>. As many of these options as needed can be pased +in. To add arbitrary curve styles, use C<--curvestyle extrastyle>. Pass these +more than once to affect more than one curve. To apply an extra style to I +the curves, pass in C<--curvestyleall extrastyle>. + +=head2 Data formats + +By default, each value present in the incoming data represents a distinct data +point, as demonstrated in the above example (we had 10 numbers in the input and +10 points in the plot). If requested, the script supports more sophisticated +interpretation of input data + +=head3 Domain selection + +If C<--domain> is passed in, the first value on each line of input is +interpreted as the I-value for the rest of the data on that line. Without +C<--domain> the I-value is the line number, and the first value on a line is +a plain data point like the others. Default is C<--nodomain>. Thus the example +above produces 2 curves, with B<1,2,3,4,5> as the I-values. If we run the +same command with --domain: + + $ seq 5 | awk '{print 2*$1, $1*$1}' | feedGnuplot --domain + +we get only 1 curve, with B<2,4,6,8,10> as the I-values. As many points as +desired can appear on a single line, but all points on a line are associated +with the I-value at the start of that line. + +=head3 Curve indexing + +By default, each column represents a separate curve. This is fine unless sparse +data is to be plotted. With the C<--dataid> option, each point is represented by +2 values: a string identifying the curve, and the value itself. If we add +C<--dataid> to the original example: + + $ seq 5 | awk '{print 2*$1, $1*$1}' | feedGnuplot --dataid --autolegend + +we get 5 different curves with one point in each. The first column, as produced +by C, is B<2,4,6,8,10>. These are interpreted as the IDs of the curves to +be plotted. The C<--autolegend> option adds a legend using the given IDs to +label the curves. The IDs need not be numbers; generic strings are accepted. As +many points as desired can appear on a single line. C<--domain> can be used in +conjunction with C<--dataid>. + +=head3 Multi-value style support + +Depending on how gnuplot is plotting the data, more than one value may be needed +to represent a single point. For example, the script has support to plot all the +data with C<--circles>. This requires a radius to be specified for each point in +addition to the position of the point. Thus, when plotting with C<--circles>, 2 +numbers are read for each data point instead of 1. A similar situation exists +with C<--colormap> where each point contains the position I the +color. There are other gnuplot styles that require more data (such as error +bars), but none of these are directly supported by the script. They can still be +used, though, by specifying the specific style with C<--curvestyle>, and +specifying how many extra values are needed for each point with +C<--extraValuesPerPoint extra>. C<--extraValuesPerPoint> is ONLY needed for the +styles not explicitly supported; supported styles set that variable +automatically. + +=head3 3D data + +To plot 3D data, pass in C<--3d>. C<--domain> MUST be given when plotting 3D +data to avoid domain ambiguity. If 3D data is being plotted, there are by +definition 2 domain values instead of one (I as a function of I and I +instead of I as a function of I). Thus the first 2 values on each line are +interpreted as the domain instead of just 1. The rest of the processing happens +the same way as before. + +=head2 Real-time streaming data + +To plot real-time data, pass in the C<--stream> option. Data will then be +plotted as it is received, with the refresh rate limited to 1Hz (currently +hard-coded). To plot only the most recent data (instead of I the data), +C<--xlen windowsize> can be given. This will create an constantly-updating, +scrolling view of the recent past. C should be replaced by the +desired length of the domain window to plot, in domain units (passed-in values +if C<--domain> or line numbers otherwise). + +=head2 Hardcopy output + +The script is able to produce hardcopy output with C<--hardcopy outputfile>. The +output type is inferred from the filename with B<.ps>, B<.eps>, B<.pdf> and +B<.png> currently supported. + +=head2 Self-plotting data files + +This script can be used to create self-plotting data files. A self-plotting, +executable data file C is formatted as + + $ cat data + #!/usr/bin/feedGnuplot --lines --points + 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 is the shebang (#!) line followed by the data, formatted as before. The +data file can be plotted simply with + + $ ./data + +The caveats here are that on Linux the whole #! line is limited to 127 charaters +and that the full path to feedGnuplot must be given. The 127 character limit is +a serious limitation, but this can likely be resolved with a kernel patch. I +have only tried on Linux 2.6. + +=head2 Further help + +All the options are described with + + $ feedGnuplot --help + +=head1 ACKNOWLEDGEMENT + +This program is originally based on the driveGnuPlots.pl script from +Thanassis Tsiodras. It is available from his site at +L + +=head1 REPOSITORY + +L + +=head1 AUTHOR + +Dima Kogan, C<< >> + +=head1 LICENSE AND COPYRIGHT + +Copyright 2011 Dima Kogan. + +This program is free software; you can redistribute it and/or modify it +under the terms of either: the GNU General Public License as published +by the Free Software Foundation; or the Artistic License. + +See http://dev.perl.org/licenses/ for more information. + +=cut diff --git a/bin/feedGnuplot b/bin/feedGnuplot index 2520587..519ab14 100755 --- a/bin/feedGnuplot +++ b/bin/feedGnuplot @@ -677,7 +677,6 @@ sub pushPoint push @$curve, $xy; } - __END__ =head1 NAME