mirror of
https://github.com/dkogan/feedgnuplot.git
synced 2025-05-05 22:11:12 +08:00
removed old README file
This commit is contained in:
Dima Kogan
parent
d9593759ca
commit
2912b90f40
115
README
115
README
@ -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
|
||||
193
README.pod
Normal file
193
README.pod
Normal file
@ -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<awk> command generates some data to
|
||||
plot and the C<feedGnuplot> reads it in from STDIN and generates the plot. The
|
||||
<awk> 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<all>
|
||||
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<X>-value for the rest of the data on that line. Without
|
||||
C<--domain> the I<X>-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<X>-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<X>-values. As many points as
|
||||
desired can appear on a single line, but all points on a line are associated
|
||||
with the I<X>-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<awk>, 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<and> 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<Z> as a function of I<X> and I<Y>
|
||||
instead of I<Y> as a function of I<X>). 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<all> the data),
|
||||
C<--xlen windowsize> can be given. This will create an constantly-updating,
|
||||
scrolling view of the recent past. C<windowsize> 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<data> 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<http://users.softlab.ece.ntua.gr/~ttsiod/gnuplotStreaming.html>
|
||||
|
||||
=head1 REPOSITORY
|
||||
|
||||
L<https://github.com/dkogan/feedgnuplot>
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Dima Kogan, C<< <dkogan at cds.caltech.edu> >>
|
||||
|
||||
=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
|
||||
@ -677,7 +677,6 @@ sub pushPoint
|
||||
push @$curve, $xy;
|
||||
}
|
||||
|
||||
|
||||
__END__
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Loading…
Reference in New Issue
Block a user