[SCM] Feedgnuplot. Pipe-oriented frontend to Gnuplot. branch, debian, updated. debian/1.23-2-15-g184102a
Dima Kogan
dima at secretsauce.net
Fri Feb 8 10:32:57 UTC 2013
The following commit has been merged in the debian branch:
commit e8e92082a1e6bebb9362bd44fa2f6e5249b41338
Author: Dima Kogan <dima at secretsauce.net>
Date: Fri Feb 8 01:11:14 2013 -0800
moved POD back into the main source file
Separating it made pod2usage not work
diff --git a/MANIFEST b/MANIFEST
index 8ed0a3e..7a47fbf 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1,7 +1,6 @@
Makefile.PL
MANIFEST
bin/feedgnuplot
-bin/feedgnuplot.pod
t/00-load.t
t/manifest.t
Changes
diff --git a/Makefile.PL b/Makefile.PL
index 04ffa4b..b14e8c8 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -42,13 +42,11 @@ WriteMakefile
NAME => 'feedgnuplot',
AUTHOR => q{Dima Kogan <dima at secretsauce.net>},
VERSION => parseversion(),
- ABSTRACT_FROM => 'bin/feedgnuplot.pod',
($ExtUtils::MakeMaker::VERSION >= 6.3002
? ('LICENSE' => 'perl')
: ()),
PL_FILES => {},
EXE_FILES => [ 'bin/feedgnuplot' ],
- MAN1PODS => { 'bin/feedgnuplot.pod' => 'blib/man1/feedgnuplot.1' },
PREREQ_PM => { 'Test::Script::Run' => 0},
dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
clean => { FILES => 'feedgnuplot-*' },
diff --git a/README.pod b/README.pod
deleted file mode 120000
index cc120d0..0000000
--- a/README.pod
+++ /dev/null
@@ -1 +0,0 @@
-bin/feedgnuplot.pod
\ No newline at end of file
diff --git a/bin/feedgnuplot b/bin/feedgnuplot
index a50fcce..f0da7f4 100755
--- a/bin/feedgnuplot
+++ b/bin/feedgnuplot
@@ -696,3 +696,401 @@ sub pushPoint
my ($curve, $xy) = @_;
push @$curve, $xy;
}
+
+
+=head1 NAME
+
+feedgnuplot - 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 0 "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 |
+ gawk '/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
+C<awk> invocation is just an example; more interesting things would be plotted
+in normal usage. No 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 passed
+in. To add arbitrary curve styles, use C<--curvestyle curveID extrastyle>. Pass
+these more than once to affect more than one curve. To apply an extra style to
+I<all> the curves that lack an explicit C<--curvestyle>, 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 original example above (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 original
+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.
+
+=head3 Special data commands
+
+Other than the raw data, 2 special commands are interpreted if they appear in
+the input. These are C<replot> and C<clear>. If a line of data begins with
+C<replot> and we're plotting in realtime with C<--stream>, the plot will be
+refreshed immediately. If a line of data begins with C<clear>, the plot is
+cleared, to be re-filled with any data following the C<clear>.
+
+=head2 Real-time streaming data
+
+To plot real-time data, pass in the C<--stream [refreshperiod]> option. Data
+will then be plotted as it is received. The plot will be updated every
+C<refreshperiod> seconds. If the period isn't specified, a 1Hz refresh rate is
+used. To refresh at specific intervals indicated by the data, set the
+refreshperiod to 0 or to 'trigger'. The plot will then I<only> be refreshed when
+a data line 'replot' is received. This 'replot' command works in both triggered
+and timed modes, but in triggered mode, it's the only way to replot.
+
+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 can be inferred from the filename, if B<.ps>, B<.eps>, B<.pdf>,
+B<.svg> or B<.png> is requested. If any other file type is requested,
+C<--terminal> I<must> be passed in to tell gnuplot how to make the plot.
+
+=head2 Self-plotting data files
+
+This script can be used to enable self-plotting data files. There are 2 ways of
+doing this: with a shebang (#!) or with inline perl data.
+
+=head3 Self-plotting data with a #!
+
+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.
+
+=head3 Self-plotting data with perl inline data
+
+Perl supports storing data and code in the same file. This can also be used to
+create self-plotting files:
+
+ $ cat plotdata.pl
+ #!/usr/bin/perl
+ use strict;
+ use warnings;
+
+ open PLOT, "| feedgnuplot --lines --points" or die "Couldn't open plotting pipe";
+ while( <DATA> )
+ {
+ my @xy = split;
+ print PLOT "@xy\n";
+ }
+ __DATA__
+ 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 especially useful if the logged data is not in a format directly
+supported by feedgnuplot. Raw data can be stored after the __DATA__ directive,
+with a small perl script to manipulate the data into a useable format and send
+it to the plotter.
+
+=head1 ARGUMENTS
+
+ --[no]domain If enabled, the first element of each line is the
+ domain variable. If not, the point index is used
+
+ --[no]dataid If enabled, each data point is preceded by the ID
+ of the data set that point corresponds to. This ID is
+ interpreted as a string, NOT as just a number. If not
+ enabled, the order of the point is used.
+
+As an example, if line 3 of the input is "0 9 1 20"
+ '--nodomain --nodataid' would parse the 4 numbers as points in 4
+ different curves at x=3
+
+ '--domain --nodataid' would parse the 4 numbers as points in 3 different
+ curves at x=0. Here, 0 is the x-variable and 9,1,20 are the data values
+
+ '--nodomain --dataid' would parse the 4 numbers as points in 2 different
+ curves at x=3. Here 0 and 1 are the data IDs and 9 and 20 are the
+ data values
+
+ '--domain --dataid' would parse the 4 numbers as a single point at
+ x=0. Here 9 is the data ID and 1 is the data value. 20 is an extra
+ value, so it is ignored. If another value followed 20, we'd get another
+ point in curve ID 20
+
+ --[no]3d Do [not] plot in 3D. This only makes sense with --domain.
+ Each domain here is an (x,y) tuple
+
+ --colormap Show a colormapped xy plot. Requires extra data for the color.
+ zmin/zmax can be used to set the extents of the colors.
+ Automatically increments extraValuesPerPoint
+
+ --stream [period] Plot the data as it comes in, in realtime. If period is given,
+ replot every period seconds. If no period is given, replot at
+ 1Hz. If the period is given as 0 or 'trigger', replot ONLY when
+ the incoming data dictates this . See the "Real-time streaming
+ data" section of the man page.
+
+ --[no]lines Do [not] draw lines to connect consecutive points
+ --[no]points Do [not] draw points
+ --circles Plot with circles. This requires a radius be specified for
+ each point. Automatically increments extraValuesPerPoint
+
+ --xlabel xxx Set x-axis label
+ --ylabel xxx Set y-axis label
+ --y2label xxx Set y2-axis label. Does not apply to 3d plots
+ --zlabel xxx Set y-axis label. Only applies to 3d plots
+
+ --title xxx Set the title of the plot
+
+ --legend curveID legend
+ Set the label for a curve plot. Use this option multiple times
+ for multiple curves. With --dataid, curveID is the ID. Otherwise,
+ it's the index of the curve, starting at 0
+
+ --autolegend Use the curve IDs for the legend. Titles given with --legend
+ override these
+
+ --xlen xxx When using --stream, sets the size of the x-window to plot.
+ Omit this or set it to 0 to plot ALL the data. Does not
+ make sense with 3d plots. Implies --monotonic
+
+ --xmin xxx Set the range for the x axis. These are ignored in a
+ streaming plot
+ --xmax xxx Set the range for the x axis. These are ignored in a
+ streaming plot
+ --ymin xxx Set the range for the y axis.
+ --ymax xxx Set the range for the y axis.
+ --y2min xxx Set the range for the y2 axis. Does not apply to 3d plots.
+ --y2max xxx Set the range for the y2 axis. Does not apply to 3d plots.
+ --zmin xxx Set the range for the z axis. Only applies to 3d plots or colormaps.
+ --zmax xxx Set the range for the z axis. Only applies to 3d plots or colormaps.
+
+ --y2 xxx Plot the data specified by this curve ID on the y2 axis.
+ Without --dataid, the ID is just an ordered 0-based index.
+ Does not apply to 3d plots. Can be passed multiple times, or passed a
+ comma-separated list
+
+ --histogram curveID
+ Set up a this specific curve to plot a histogram. The bin
+ width is given with the --binwidth option (assumed 1.0 if
+ omitted). --histogram does NOT touch the drawing style.
+ It is often desired to plot these with boxes, and this
+ MUST be explicitly requested with --curvestyleall 'with
+ boxes'. This works with --domain and/or --stream, but in
+ those cases the x-value is used ONLY to cull old data
+ because of --xlen or --monotonic. I.e. the x-values are
+ NOT drawn in any way. Can be passed multiple times, or passed a comma-
+ separated list
+ --binwidth width The width of bins when making histograms. This setting applies to ALL
+ histograms in the plot. Defaults to 1.0 if not given.
+ --histstyle style Normally, histograms are generated with the 'smooth freq'
+ gnuplot style. --histstyle can be used to select
+ different 'smooth' settings. Allowed are 'unique',
+ 'cumulative' and 'cnormal'. 'unique' indicates whether a
+ bin has at least one item in it: instead of counting the
+ items, it'll always report 0 or 1. 'cumulative' is the
+ integral of the "normal" histogram. 'cnormal' is like
+ 'cumulative', but rescaled to end up at 1.0.
+
+ --curvestyle curveID style
+ Additional styles per curve. With --dataid, curveID is
+ the ID. Otherwise, it's the index of the curve, starting
+ at 0. Use this option multiple times for multiple curves.
+ --curvestylall does NOT apply to curves that have a
+ --curvestyle
+
+ --curvestyleall xxx Additional styles for all curves that have no --curvestyle
+
+ --extracmds xxx Additional commands. These could contain extra global styles
+ for instance. Can be passed multiple times.
+
+ --square Plot data with aspect ratio 1. For 3D plots, this controls the
+ aspect ratio for all 3 axes
+
+ --square_xy For 3D plots, set square aspect ratio for ONLY the x,y axes
+
+ --hardcopy xxx If not streaming, output to a file specified here. Format
+ inferred from filename, unless specified by --terminal
+ --terminal xxx String passed to 'set terminal'. No attempts are made to
+ validate this. --hardcopy sets this to some sensible
+ defaults if --hardcopy is given .png, .pdf, .ps, .eps or
+ .svg. If any other file type is desired, use both
+ --hardcopy and --terminal
+
+ --maxcurves xxx The maximum allowed number of curves. This is 100 by default,
+ but can be reset with this option. This exists purely to
+ prevent perl from allocating all of the system's memory when
+ reading bogus data
+
+ --monotonic If --domain is given, checks to make sure that the x-
+ coordinate in the input data is monotonically increasing.
+ If a given x-variable is in the past, all data currently
+ cached for this curve is purged. Without --monotonic, all
+ data is kept. Does not make sense with 3d plots.
+ No --monotonic by default.
+
+ --extraValuesPerPoint xxx
+ How many extra values are given for each data point. Normally this
+ is 0, and does not need to be specified, but sometimes we want
+ extra data, like for colors or point sizes or error bars, etc.
+ feedgnuplot options that require this (colormap, circles)
+ automatically set it. This option is ONLY needed if unknown styles are
+ used, with --curvestyleall for instance
+
+ --dump Instead of printing to gnuplot, print to STDOUT. For
+ debugging.
+
+ --geometry If using X11, specifies the size, position of the plot window
+
+=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<< <dima at secretsauce.net> >>
+
+=head1 LICENSE AND COPYRIGHT
+
+Copyright 2011-2012 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.pod b/bin/feedgnuplot.pod
deleted file mode 100644
index 1db9962..0000000
--- a/bin/feedgnuplot.pod
+++ /dev/null
@@ -1,396 +0,0 @@
-=head1 NAME
-
-feedgnuplot - 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 0 "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 |
- gawk '/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
-C<awk> invocation is just an example; more interesting things would be plotted
-in normal usage. No 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 passed
-in. To add arbitrary curve styles, use C<--curvestyle curveID extrastyle>. Pass
-these more than once to affect more than one curve. To apply an extra style to
-I<all> the curves that lack an explicit C<--curvestyle>, 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 original example above (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 original
-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.
-
-=head3 Special data commands
-
-Other than the raw data, 2 special commands are interpreted if they appear in
-the input. These are C<replot> and C<clear>. If a line of data begins with
-C<replot> and we're plotting in realtime with C<--stream>, the plot will be
-refreshed immediately. If a line of data begins with C<clear>, the plot is
-cleared, to be re-filled with any data following the C<clear>.
-
-=head2 Real-time streaming data
-
-To plot real-time data, pass in the C<--stream [refreshperiod]> option. Data
-will then be plotted as it is received. The plot will be updated every
-C<refreshperiod> seconds. If the period isn't specified, a 1Hz refresh rate is
-used. To refresh at specific intervals indicated by the data, set the
-refreshperiod to 0 or to 'trigger'. The plot will then I<only> be refreshed when
-a data line 'replot' is received. This 'replot' command works in both triggered
-and timed modes, but in triggered mode, it's the only way to replot.
-
-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 can be inferred from the filename, if B<.ps>, B<.eps>, B<.pdf>,
-B<.svg> or B<.png> is requested. If any other file type is requested,
-C<--terminal> I<must> be passed in to tell gnuplot how to make the plot.
-
-=head2 Self-plotting data files
-
-This script can be used to enable self-plotting data files. There are 2 ways of
-doing this: with a shebang (#!) or with inline perl data.
-
-=head3 Self-plotting data with a #!
-
-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.
-
-=head3 Self-plotting data with perl inline data
-
-Perl supports storing data and code in the same file. This can also be used to
-create self-plotting files:
-
- $ cat plotdata.pl
- #!/usr/bin/perl
- use strict;
- use warnings;
-
- open PLOT, "| feedgnuplot --lines --points" or die "Couldn't open plotting pipe";
- while( <DATA> )
- {
- my @xy = split;
- print PLOT "@xy\n";
- }
- __DATA__
- 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 especially useful if the logged data is not in a format directly
-supported by feedgnuplot. Raw data can be stored after the __DATA__ directive,
-with a small perl script to manipulate the data into a useable format and send
-it to the plotter.
-
-=head1 ARGUMENTS
-
- --[no]domain If enabled, the first element of each line is the
- domain variable. If not, the point index is used
-
- --[no]dataid If enabled, each data point is preceded by the ID
- of the data set that point corresponds to. This ID is
- interpreted as a string, NOT as just a number. If not
- enabled, the order of the point is used.
-
-As an example, if line 3 of the input is "0 9 1 20"
- '--nodomain --nodataid' would parse the 4 numbers as points in 4
- different curves at x=3
-
- '--domain --nodataid' would parse the 4 numbers as points in 3 different
- curves at x=0. Here, 0 is the x-variable and 9,1,20 are the data values
-
- '--nodomain --dataid' would parse the 4 numbers as points in 2 different
- curves at x=3. Here 0 and 1 are the data IDs and 9 and 20 are the
- data values
-
- '--domain --dataid' would parse the 4 numbers as a single point at
- x=0. Here 9 is the data ID and 1 is the data value. 20 is an extra
- value, so it is ignored. If another value followed 20, we'd get another
- point in curve ID 20
-
- --[no]3d Do [not] plot in 3D. This only makes sense with --domain.
- Each domain here is an (x,y) tuple
-
- --colormap Show a colormapped xy plot. Requires extra data for the color.
- zmin/zmax can be used to set the extents of the colors.
- Automatically increments extraValuesPerPoint
-
- --stream [period] Plot the data as it comes in, in realtime. If period is given,
- replot every period seconds. If no period is given, replot at
- 1Hz. If the period is given as 0 or 'trigger', replot ONLY when
- the incoming data dictates this . See the "Real-time streaming
- data" section of the man page.
-
- --[no]lines Do [not] draw lines to connect consecutive points
- --[no]points Do [not] draw points
- --circles Plot with circles. This requires a radius be specified for
- each point. Automatically increments extraValuesPerPoint
-
- --xlabel xxx Set x-axis label
- --ylabel xxx Set y-axis label
- --y2label xxx Set y2-axis label. Does not apply to 3d plots
- --zlabel xxx Set y-axis label. Only applies to 3d plots
-
- --title xxx Set the title of the plot
-
- --legend curveID legend
- Set the label for a curve plot. Use this option multiple times
- for multiple curves. With --dataid, curveID is the ID. Otherwise,
- it's the index of the curve, starting at 0
-
- --autolegend Use the curve IDs for the legend. Titles given with --legend
- override these
-
- --xlen xxx When using --stream, sets the size of the x-window to plot.
- Omit this or set it to 0 to plot ALL the data. Does not
- make sense with 3d plots. Implies --monotonic
-
- --xmin xxx Set the range for the x axis. These are ignored in a
- streaming plot
- --xmax xxx Set the range for the x axis. These are ignored in a
- streaming plot
- --ymin xxx Set the range for the y axis.
- --ymax xxx Set the range for the y axis.
- --y2min xxx Set the range for the y2 axis. Does not apply to 3d plots.
- --y2max xxx Set the range for the y2 axis. Does not apply to 3d plots.
- --zmin xxx Set the range for the z axis. Only applies to 3d plots or colormaps.
- --zmax xxx Set the range for the z axis. Only applies to 3d plots or colormaps.
-
- --y2 xxx Plot the data specified by this curve ID on the y2 axis.
- Without --dataid, the ID is just an ordered 0-based index.
- Does not apply to 3d plots. Can be passed multiple times, or passed a
- comma-separated list
-
- --histogram curveID
- Set up a this specific curve to plot a histogram. The bin
- width is given with the --binwidth option (assumed 1.0 if
- omitted). --histogram does NOT touch the drawing style.
- It is often desired to plot these with boxes, and this
- MUST be explicitly requested with --curvestyleall 'with
- boxes'. This works with --domain and/or --stream, but in
- those cases the x-value is used ONLY to cull old data
- because of --xlen or --monotonic. I.e. the x-values are
- NOT drawn in any way. Can be passed multiple times, or passed a comma-
- separated list
- --binwidth width The width of bins when making histograms. This setting applies to ALL
- histograms in the plot. Defaults to 1.0 if not given.
- --histstyle style Normally, histograms are generated with the 'smooth freq'
- gnuplot style. --histstyle can be used to select
- different 'smooth' settings. Allowed are 'unique',
- 'cumulative' and 'cnormal'. 'unique' indicates whether a
- bin has at least one item in it: instead of counting the
- items, it'll always report 0 or 1. 'cumulative' is the
- integral of the "normal" histogram. 'cnormal' is like
- 'cumulative', but rescaled to end up at 1.0.
-
- --curvestyle curveID style
- Additional styles per curve. With --dataid, curveID is
- the ID. Otherwise, it's the index of the curve, starting
- at 0. Use this option multiple times for multiple curves.
- --curvestylall does NOT apply to curves that have a
- --curvestyle
-
- --curvestyleall xxx Additional styles for all curves that have no --curvestyle
-
- --extracmds xxx Additional commands. These could contain extra global styles
- for instance. Can be passed multiple times.
-
- --square Plot data with aspect ratio 1. For 3D plots, this controls the
- aspect ratio for all 3 axes
-
- --square_xy For 3D plots, set square aspect ratio for ONLY the x,y axes
-
- --hardcopy xxx If not streaming, output to a file specified here. Format
- inferred from filename, unless specified by --terminal
- --terminal xxx String passed to 'set terminal'. No attempts are made to
- validate this. --hardcopy sets this to some sensible
- defaults if --hardcopy is given .png, .pdf, .ps, .eps or
- .svg. If any other file type is desired, use both
- --hardcopy and --terminal
-
- --maxcurves xxx The maximum allowed number of curves. This is 100 by default,
- but can be reset with this option. This exists purely to
- prevent perl from allocating all of the system's memory when
- reading bogus data
-
- --monotonic If --domain is given, checks to make sure that the x-
- coordinate in the input data is monotonically increasing.
- If a given x-variable is in the past, all data currently
- cached for this curve is purged. Without --monotonic, all
- data is kept. Does not make sense with 3d plots.
- No --monotonic by default.
-
- --extraValuesPerPoint xxx
- How many extra values are given for each data point. Normally this
- is 0, and does not need to be specified, but sometimes we want
- extra data, like for colors or point sizes or error bars, etc.
- feedgnuplot options that require this (colormap, circles)
- automatically set it. This option is ONLY needed if unknown styles are
- used, with --curvestyleall for instance
-
- --dump Instead of printing to gnuplot, print to STDOUT. For
- debugging.
-
- --geometry If using X11, specifies the size, position of the plot window
-
-=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<< <dima at secretsauce.net> >>
-
-=head1 LICENSE AND COPYRIGHT
-
-Copyright 2011-2012 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
--
Feedgnuplot. Pipe-oriented frontend to Gnuplot.
More information about the debian-science-commits
mailing list