diff --git a/Changes b/Changes index 87b3c38..6d275a4 100644 --- a/Changes +++ b/Changes @@ -1,3 +1,9 @@ +feedgnuplot (1.52) + + * Added --squarexy and --square-xy as synonyms to --square_xy + + -- Dima Kogan Sun, 25 Aug 2019 15:32:37 -0700 + feedgnuplot (1.51) * Added .gp "terminal" to create self-plotting gnuplot files diff --git a/INSTALL b/INSTALL index 3d6c8df..895e724 100644 --- a/INSTALL +++ b/INSTALL @@ -10,4 +10,11 @@ Without a package, an installation can be done with make make install -This installs feedgnuplot to /usr/local. Adjust the paths as required +This installs feedgnuplot to /usr/local. Adjust the paths as required. + +Also, note that this is a self-contained utility. Usually running from the tree +works just fine: + + git clone https://github.com/dkogan/feedgnuplot.git + cd feedgnuplot/bin + ./feedgnuplot ... diff --git a/README.pod b/README.pod deleted file mode 120000 index abe0c14..0000000 --- a/README.pod +++ /dev/null @@ -1 +0,0 @@ -bin/feedgnuplot \ No newline at end of file diff --git a/README.pod b/README.pod new file mode 100644 index 0000000..9af43ab --- /dev/null +++ b/README.pod @@ -0,0 +1,987 @@ +=head1 TALK + +I just gave a talk about this at L. Presentation lives +L. + +=head1 NAME + +feedgnuplot - General purpose pipe-oriented plotting tool + +=head1 SYNOPSIS + +Simple plotting of piped 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 + --unset grid --terminal 'dumb 80,40' --exit + + Test plot + + 10 +-----------------------------------------------------------------+ 25 + | + + + + + + + *##| + | data 0 ***A*#* | + | ** # | + 9 |-+ ** ## | + | ** # | + | ** # | + | ** ## +-| 20 + 8 |-+ A # | + | ** # | + | ** ## | + | ** # | + | ** B | + 7 |-+ ** ## | + | ** ## +-| 15 + | ** # | + | ** ## | + 6 |-+ *A ## | + | ** ## | + | ** # | + | ** ## +-| 10 + 5 |-+ ** ## | + | ** #B | + | ** ## | + | ** ## | + 4 |-+ A ### | + | ** ## | + | ** ## +-| 5 + | ** ## | + | ** ##B# | + 3 |-+ ** #### | + | **#### | + | #### | + |## + + + + + + + | + 2 +-----------------------------------------------------------------+ 0 + 1 1.5 2 2.5 3 3.5 4 4.5 5 + + +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 command generates some data to +plot and the C reads it in from STDIN and generates the plot. The +C 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 options such as +C<--set>, C<--extracmds> C<--style>, etc. Arbitrary gnuplot commands can be +passed in with C<--extracmds>. For example, to turn off the grid, you can pass +in C<--extracmds 'unset grid'>. Commands C<--set> and C<--unset> exists to +provide nicer syntax, so this is equivalent to passing C<--unset grid>. As many +of these options as needed can be passed in. To add arbitrary curve styles, use +C<--style curveID extrastyle>. Pass these more than once to affect more than one +curve. + +To apply an extra style to I the curves that lack an explicit C<--style>, +pass in C<--styleall extrastyle>. In the most common case, the extra style is +C. To support this more simply, you can pass in C<--with +something> instead of C<--styleall 'with something'>. C<--styleall> and +C<--with> are mutually exclusive. Furthermore any curve-specific C<--style> +overrides the global C<--styleall> or C<--with> setting. + +=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-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 original +example above produces 2 curves, with B<1,2,3,4,5> as the I-values. If we run +the same command with C<--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 + +We index the curves in one of 3 ways: sequentially, explicitly with a +C<--dataid> or by C<--vnlog> headers. + +By default, each column represents a separate curve. The first column (after any +domain) is curve C<0>. The next one is curve C<1> and so on. 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. + +If we're plotting C data (L) then we +can get the curve IDs from the vnlog header. Vnlog is a trivial data format +where lines starting with C<#> are comments and the first comment contains +column labels. If we have such data, C can interpret these +column labels if the C perl modules are available. + +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> or C<--vnlog>. + +=head3 Multi-value style support + +Depending on how gnuplot is plotting the data, more than one value may be needed +to represent the range of a single point. Basic 2D plots have 2 numbers +representing each point: 1 domain and 1 range. But if plotting with +C<--circles>, for instance, then there's an extra range value: the radius. Many +other gnuplot styles require more data: errorbars, variable colors (C), variable sizes (C), labels and so on. +The feedgnuplot tool itself does not know about all these intricacies, but they +can still be used, by specifying the specific style with C<--style>, and +specifying how many values are needed for each point with any of +C<--rangesizeall>, C<--tuplesizeall>, C<--rangesize>, C<--tuplesize>. These +options are required I for styles not explicitly supported by feedgnuplot; +supported styles do the right thing automatically. + +Specific example: if making a 2d plot of y error bars, the exact format can be +queried by running C and invoking C. This tells us +that there's a 3-column form: C and a 4-column form: C. With 2d plots feedgnuplot will always output the 1-value domain C, so +the rangesize is 2 and 3 respectively. Thus the following are equivalent: + + $ echo '1 2 0.3 + 2 3 0.4 + 3 4 0.5' | feedgnuplot --domain --rangesizeall 2 --with 'yerrorbars' + + $ echo '1 2 0.3 + 2 3 0.4 + 3 4 0.5' | feedgnuplot --domain --tuplesizeall 3 --with 'yerrorbars' + + $ echo '1 2 1.7 2.3 + 2 3 2.6 3.4 + 3 4 3.5 4.5' | feedgnuplot --domain --rangesizeall 3 --with 'yerrorbars' + +=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. + +=head3 Time/date data + +If the input data domain is a time/date, this can be interpreted with +C<--timefmt>. This option takes a single argument: the format to use to parse +the data. The format is documented in 'set timefmt' in gnuplot, although the +common flags that C understands are generally supported. The backslash +sequences in the format are I supported, so if you want a tab, put in a tab +instead of \t. Whitespace in the format I supported. When this flag is +given, some other options act a little bit differently: + +=over + +=item + +C<--xlen> is an I in seconds + +=item + +C<--xmin> and C<--xmax> I use the format passed in to C<--timefmt> + +=back + +Using this option changes both the way the input is parsed I the way the +x-axis tics are labelled. Gnuplot tries to be intelligent in this labelling, but +it doesn't always do what the user wants. The labelling can be controlled with +the gnuplot C command, which takes the same type of format string as +C<--timefmt>. Example: + + $ sar 1 -1 | + awk '$1 ~ /..:..:../ && $8 ~/^[0-9\.]*$/ {print $1,$8; fflush()}' | + feedgnuplot --stream --domain + --lines --timefmt '%H:%M:%S' + --set 'format x "%H:%M:%S"' + +This plots the 'idle' CPU consumption against time. + +Note that while gnuplot supports the time/date on any axis, I +currently supports it I as the x-axis domain. This may change in the +future. + +=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 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 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. Look in +L for more information. + +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). If the domain is a time/date via C<--timefmt>, then +C is and I in seconds. If we're plotting a histogram, then +C<--xlen> causes a histogram over a moving window to be computed. The subtlely +here is that with a histogram you don't actually I the domain since only +the range is analyzed. But the domain is still there, and can be utilized with +C<--xlen>. With C<--xlen> we can plot I histograms or I +I-histograms. + +=head3 Special data commands + +If we are reading streaming data, the input stream can contain special commands +in addition to the raw data. Feedgnuplot looks for these at the start of every +input line. If a command is detected, the rest of the line is discarded. These +commands are + +=over + +=item C + +This command refreshes the plot right now, instead of waiting for the next +refresh time indicated by the timer. This command works in addition to the timed +refresh, as indicated by C<--stream [refreshperiod]>. + +=item C + +This command clears out the current data in the plot. The plotting process +continues, however, to any data following the C. + +=item C + +This command causes feedgnuplot to exit. + +=back + +=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>, B<.png> or B<.gp> is requested. If any other file type is requested, +C<--terminal> I be passed in to tell gnuplot how to make the plot. If +C<--terminal> is passed in, then the C<--hardcopy> argument only provides the +output filename. + +The B<.gp> output is special. Instead of asking gnuplot to plot to a particular +terminal, writing to a B<.gp> simply dumps a self-executable gnuplot script into +the given file. This is similar to what C<--dump> does, but writes to a file, +and makes sure that the file can be self-executing. + +=head2 Self-plotting data files + +This script can be used to enable self-plotting data files. There are several +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 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 +characters 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 gnuplot + +Running C will create a self-executable +gnuplot script in C + +=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( ) + { + 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 + +=over + +=item + +--C<[no]domain> + +If enabled, the first element of each line is the domain variable. If not, the +point index is used + +=item + +--C<[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" then + +=over + +=item + +C<--nodomain --nodataid> would parse the 4 numbers as points in 4 different +curves at x=3 + +=item + +C<--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 + +=item + +C<--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 + +=item + +C<--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 + +=back + +=item + +C<--vnlog> + +Vnlog is a trivial data format where lines starting with C<#> are comments and +the first comment contains column labels. Some tools for working with such data +are available from the C project: L. +With the C perl modules installed, we can read the vnlog column headers +with C. This replaces C<--dataid>, and we can do all the +normal things with these headers. For instance C will generate plot legends for each column in the vnlog, using the +vnlog column label in the legend. + +=item + +C<--[no]3d> + +Do [not] plot in 3D. This only makes sense with C<--domain>. Each domain here is +an (x,y) tuple + +=item + +--C + +Interpret the X data as a time/date, parsed with the given format + +=item + +C<--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 sets the +C<--rangesize>/C<--tuplesize>. + +=item + +C<--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 I when the incoming data dictates this. See the +L section of the man page. + +=item + +C<--[no]lines> + +Do [not] draw lines to connect consecutive points + +=item + +C<--[no]points> + +Do [not] draw points + +=item + +C<--circles> + +Plot with circles. This requires a radius be specified for each point. +Automatically sets the C<--rangesize>/C<--tuplesize>. C supported for 3d +plots. + +=item + +C<--title xxx> + +Set the title of the plot + +=item + +C<--legend curveID legend> + +Set the label for a curve plot. Use this option multiple times for multiple +curves. With C<--dataid>, curveID is the ID. Otherwise, it's the index of the +curve, starting at 0 + +=item + +C<--autolegend> + +Use the curve IDs for the legend. Titles given with C<--legend> override these + +=item + +C<--xlen xxx> + +When using C<--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 +C<--monotonic>. If we're plotting a histogram, then C<--xlen> causes a histogram +over a moving window to be computed. The subtlely here is that with a histogram +you don't actually I the domain since only the range is analyzed. But the +domain is still there, and can be utilized with C<--xlen>. With C<--xlen> we can +plot I histograms or I I-histograms. + + +=item + +C<--xmin/xmax/ymin/ymax/y2min/y2max/zmin/zmax xxx> + +Set the range for the given axis. These x-axis bounds are ignored in a streaming +plot. The y2-axis bound do not apply in 3d plots. The z-axis bounds apply +I to 3d plots or colormaps. Note that there is no C<--xrange> to set both +sides at once or C<--xinv> to flip the axis around: anything more than the +basics supported in this option is clearly obtainable by talking to gnuplot, for +instance C<--set 'xrange [20:10]'> to set the given inverted bounds. + +=item + +C<--xlabel/ylabel/y2label/zlabel xxx> + +Label the given axis. The y2-axis label does not apply to 3d plots while the +z-axis label applies I to 3d plots. + +=item + +C<--y2 xxx> + +Plot the data specified by this curve ID on the y2 axis. Without C<--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. By default the y2-axis +curves look the same as the y-axis ones. I.e. the viewer of the resulting plot +has to be told which is which via an axes label, legend, etc. Prior to version +1.25 of feedgnuplot the curves plotted on the y2 axis were drawn with a thicker +line. This is no longer the case, but that behavior can be brought back by +passing something like + + --y2 curveid --style curveid 'linewidth 3' + +=item + +C<--histogram curveID> + +Set up a this specific curve to plot a histogram. The bin width is given with +the C<--binwidth> option (assumed 1.0 if omitted). If a drawing style is not +specified for this curve (C<--curvestyle>) or all curves (C<--with>, +C<--curvestyleall>) then the default histogram style is set: filled boxes with +borders. This is what the user generally wants. This works with C<--domain> +and/or C<--stream>, but in those cases the x-value is used I to cull old +data because of C<--xlen> or C<--monotonic>. I.e. the domain values are I +drawn in any way. Can be passed multiple times, or passed a comma- separated +list + +=item + +C<--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. + +=item + +C<--histstyle style> + +Normally, histograms are generated with the 'smooth frequency' gnuplot style. +C<--histstyle> can be used to select different C settings (see the +gnuplot C page for more info). Allowed values are 'frequency' (the +default), 'fnormal' (available in very recent gnuplots), 'unique', 'cumulative' +and 'cnormal'. 'fnormal' is a normalized histogram. '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 'frequency' histogram. +'cnormal' is like 'cumulative', but rescaled to end up at 1.0. + +=item + +C<--style curveID style> + +Additional styles per curve. With C<--dataid>, curveID is the ID. Otherwise, +it's the index of the curve, starting at 0. curveID can be a comma-separated +list of IDs to which the given style should apply. Use this option multiple +times for multiple curves. C<--styleall> does I apply to curves that have a +C<--style>. + +=item + +C<--curvestyle curveID> + +Synonym for C<--style> + +=item + +C<--styleall xxx> + +Additional styles for all curves that have no C<--style>. This is overridden by +any applicable C<--style>. Exclusive with C<--with>. + +=item + +C<--curvestyleall xxx> + +Synonym for C<--styleall> + +=item + +C<--with xxx> + +Same as C<--styleall>, but prefixed with "with". Thus + + --with boxes + +is equivalent to + + --styleall 'with boxes' + +Exclusive with C<--styleall>. + +=item + +C<--extracmds xxx> + +Additional commands to pass on to gnuplot verbatim. These could contain extra +global styles for instance. Can be passed multiple times. + +=item + +C<--set xxx> + +Additional 'set' commands to pass on to gnuplot verbatim. C<--set 'a b c'> will +result in gnuplot seeing a C command. Can be passed multiple times. + +=item + +C<--unset xxx> + +Additional 'unset' commands to pass on to gnuplot verbatim. C<--unset 'a b c'> +will result in gnuplot seeing a C command. Can be passed multiple +times. + +=item + +C<--image filename> + +Overlays the data on top of a raster image given in C. This is passed +through to gnuplot via C<--equation>, and is not interpreted by C +other than checking for existence. Usually images have their origin at the +top-left corner, while plots have it in the bottom-left corner instead. Thus if +the y-axis extents are not specified (C<--ymin>, C<--ymax>, C<--set 'yrange +...'>) this option will also flip around the y axis to make the image appear +properly. Since this option is just a passthrough to gnuplot, finer control can +be achieved by passing in C<--equation> and C<--set yrange ...> directly. + +C<--equation xxx> + +Gnuplot can plot both data and symbolic equations. C generally +plots data, but with this option can plot symbolic equations I. This is +generally intended to augment data plots, since for equation-only plots you +don't need C. C<--equation> can be passed multiple times for +multiple equations. The given strings are passed to gnuplot directly without +anything added or removed, so styling and such should be applied in the string. +A basic example: + + seq 100 | awk '{print $1/10, $1/100}' | + feedgnuplot --with 'lines lw 3' --domain --ymax 1 + --equation 'sin(x)/x' --equation 'cos(x)/x with lines lw 4' + +Here I plot the incoming data (points along a line) with the given style (a line +with thickness 3), I I plot two damped sinusoids on the same plot. The +sinusoids are not affected by C styling, so their styles are set +separately, as in this example. More complicated example: + + seq 360 | perl -nE '$th=$_/360 * 3.14*2; $c=cos($th); $s=sin($th); say "$c $s"' | + feedgnuplot --domain --square + --set parametric --set "trange [0:2*3.14]" --equation "sin(t),cos(t)" + +Here the data I generate is points along the unit circle. I plot these as +points, and I I plot a true circle as a parametric equation. + +=item + +C<--square> + +Plot data with aspect ratio 1. For 3D plots, this controls the aspect ratio for +all 3 axes + +=item + +C<--square-xy> + +For 3D plots, set square aspect ratio for ONLY the x,y axes + +=item + +C<--hardcopy xxx> + +If not streaming, output to a file specified here. Format inferred from +filename, unless specified by C<--terminal>. If C<--terminal> is given, +C<--hardcopy> sets I the output filename. + +=item + +C<--terminal xxx> + +String passed to 'set terminal'. No attempts are made to validate this. +C<--hardcopy> sets this to some sensible defaults if C<--hardcopy> is set to a +filename ending in C<.png>, C<.pdf>, C<.ps>, C<.eps> or C<.svg>. If any other +file type is desired, use both C<--hardcopy> and C<--terminal> + +=item + +C<--maxcurves N> + +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 + +=item + +C<--monotonic> + +If C<--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 C<--monotonic>, all data is +kept. Does not make sense with 3d plots. No C<--monotonic> by default. The data +is replotted before being purged. This is useful in streaming plots where the +incoming data represents multiple iterations of the same process (repeated +simulations of the same period in time, for instance). + +=item + +C<--rangesize curveID N> + +The options C<--rangesizeall> and C<--rangesize> set the number of values are +needed to represent each point being plotted (see L above). These options are I needed if unknown styles are used, +with C<--styleall> or C<--with> for instance. + +C<--rangesize> is used to set how many values are needed to represent the range +of a point for a particular curve. This overrides any defaults that may exist +for this curve only. + +With C<--dataid>, curveID is the ID. Otherwise, it's the index of the curve, +starting at 0. curveID can be a comma-separated list of IDs to which the given +rangesize should apply. + +=item + +C<--tuplesize curveID N> + +Very similar to C<--rangesize>, but instead of specifying the I only, +this specifies the whole tuple. For instance if we're plotting circles, the +tuplesize is 3: C. In a 2D plot there's a 1-dimensional domain: +C, so the rangesize is 2: C. This dimensionality can be given +either way. + +=item + +C<--rangesizeall N> + +Like C<--rangesize>, but applies to I the curves. + +=item + +C<--tuplesizeall N> + +Like C<--tuplesize>, but applies to I the curves. + +=item + +C<--dump> + +Instead of printing to gnuplot, print to STDOUT. Very useful for debugging. It +is possible to send the output produced this way to gnuplot directly. + +=item + +C<--exit> + +This controls what happens when the input data is exhausted, or when some part +of the C pipeline is killed. This option does different things +depending on whether C<--stream> is active, so read this closely. + +With interactive gnuplot terminals (qt, x11, wxt), the plot windows live in a +separate process from the main C process. It is thus possible for the +main C process to exit, while leaving the plot windows up (a caveat is +that such decapitated windows aren't interactive). There are 3 possible states +of the polotting pipeline: + +=over + +=item Alive: C, C alive, plot window process alive, no +shell prompt (shell busy with C) + +=item Half-alive: C, C dead, plot window process alive +(but non-interactive), shell prompt available + +=item Dead: C, C dead, plot window process dead, shell +prompt available + +=back + +The possibilities are: + +=over + +=item No C<--stream>, all data read in + +=over + +=item no C<--exit> (default) + +Alive. Need to Ctrl-C to get back into the shell + +=item C<--exit> + +Half-alive. Non-interactive prompt up, and the shell accepts new commands. +Without C<--stream> the goal is to show a plot, so a Dead state would not be +useful. + +=back + +=item C<--stream>, all data read in or the C process terminated + +=over + +=item no C<--exit> (default) + +Alive. Need to Ctrl-C to get back into the shell. This means that when making +live plots, the first Ctrl-C kills the data feeding process, but leaves the +final plot up for inspection. A second Ctrl-C kills feedgnuplot as well. + +=item C<--exit> + +Dead. No plot is shown, and the shell accepts new commands. With C<--stream> the +goal is to show a plot as the data comes in, which we have been doing. Now that +we're done, we can clean up everything. + +=back + +=back + +Note that one usually invokes C as a part of a shell pipeline: + + $ write_data | feedgnuplot + +If the user terminates this pipeline with ^C, then I the processes in the +pipeline receive SIGINT. This normally kills C and all its +C children, and we let this happen unless C<--stream> and no C<--exit>. +If C<--stream> and no C<--exit>, then we ignore the first ^C. The data feeder +dies, and we behave as if the input data was exhausted. A second ^C kills us +also. + +=item + +C<--geometry> + +If using X11, specifies the size, position of the plot window + +=item + +C<--version> + +Print the version and exit + +=back + +=head1 RECIPES + +=head2 Basic plotting of piped 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 + +=head2 Realtime plot of network throughput + +Looks at wlan0 on 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 + +=head2 Realtime plot of battery charge in respect to time + +Uses the result of the C command. + + $ while true; do acpi; sleep 15; done | + perl -nE 'BEGIN{ $| = 1; } /([0-9]*)%/; say join(" ", time(), $1);' | + feedgnuplot --stream --ymin 0 --ymax 100 --lines --domain --xlabel 'Time' --timefmt '%s' --ylabel "Battery charge (%)" + +=head2 Realtime plot of temperatures in an IBM Thinkpad + +Uses C, which reports temperatures at various locations +in a Thinkpad. + + $ while true; do cat /proc/acpi/ibm/thermal | awk '{$1=""; print}' ; sleep 1; done | + feedgnuplot --stream --xlen 100 --lines --autolegend --ymax 100 --ymin 20 --ylabel 'Temperature (deg C)' + +=head2 Plotting a histogram of file sizes in a directory, granular to 10MB + + $ ls -l | awk '{print $5/1e6}' | + feedgnuplot --histogram 0 + --binwidth 10 + --ymin 0 --xlabel 'File size (MB)' --ylabel Frequency + +=head2 Plotting a live histogram of the ping round-trip times for the past 20 seconds + + $ ping -A -D 8.8.8.8 | + perl -anE 'BEGIN { $| = 1; } + $F[0] =~ s/[\[\]]//g or next; + $F[7] =~ s/.*=//g or next; + say "$F[0] $F[7]"' | + feedgnuplot --stream --domain --histogram 0 --binwidth 10 \ + --xlabel 'Ping round-trip time (s)' \ + --ylabel Frequency --xlen 20 + +=head2 Plotting points on top of an existing image + +This can be done with C<--image>: + + $ < features_xy.data + feedgnuplot --points --domain --image "image.png" + +or with C<--equation>: + + $ < features_xy.data + feedgnuplot --points --domain + --equation '"image.png" binary filetype=auto flipy with rgbimage' + --set 'yrange [:] reverse' + +The C<--image> invocation is a convenience wrapper for the C<--equation> +version. Finer control is available with C<--equation>. + + +Here an existing image is given to gnuplot verbatim, and data to plot on top of +it is interpreted by feedgnuplot as usual. C is useful here because +usually the y axis points up, but when looking at images, this is usually +reversed: the origin is the top-left pixel. + +=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-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 b/bin/feedgnuplot index 0864fda..c3c6a37 100755 --- a/bin/feedgnuplot +++ b/bin/feedgnuplot @@ -16,7 +16,7 @@ use Pod::Usage; use Time::Piece; # Makefile.PL assumes this is in '' -my $VERSION = '1.51'; +my $VERSION = '1.52'; my %options; interpretCommandline(); @@ -109,7 +109,7 @@ sub interpretCommandline 'title=s', 'xlen=f', 'ymin=f', 'ymax=f', 'xmin=s', 'xmax=s', 'y2min=f', 'y2max=f', 'zmin=f', 'zmax=f', 'y2=s@', 'style=s{2}', 'curvestyle=s{2}', 'curvestyleall=s', 'styleall=s', 'with=s', 'extracmds=s@', 'set=s@', 'unset=s@', - 'square!', 'square_xy!', 'hardcopy=s', 'maxcurves=i', 'monotonic!', 'timefmt=s', + 'square!', 'square_xy!', 'square-xy!', 'squarexy!', 'hardcopy=s', 'maxcurves=i', 'monotonic!', 'timefmt=s', 'equation=s@', 'image=s', 'histogram=s@', 'binwidth=f', 'histstyle=s', @@ -143,6 +143,10 @@ sub interpretCommandline delete $options{styleall}; } + # various square-xy synonyms + $options{'square_xy'} = 1 if $options{'square-xy'} || $options{'squarexy'}; + + push @{$options{curvestyle}}, @{$options{style}}; delete $options{style}; @@ -2005,7 +2009,7 @@ all 3 axes =item -C<--square_xy> +C<--square-xy> For 3D plots, set square aspect ratio for ONLY the x,y axes diff --git a/completions/bash/feedgnuplot b/completions/bash/feedgnuplot index 1cb7e3b..0509c6e 100644 --- a/completions/bash/feedgnuplot +++ b/completions/bash/feedgnuplot @@ -33,7 +33,7 @@ complete -W \ --monotonic \ --points \ --square \ - --square_xy \ + --square-xy \ --stream \ --terminal \ --timefmt \ diff --git a/completions/zsh/_feedgnuplot b/completions/zsh/_feedgnuplot index 3f57213..465a0f1 100644 --- a/completions/zsh/_feedgnuplot +++ b/completions/zsh/_feedgnuplot @@ -35,7 +35,7 @@ _arguments -S '*--equation[Raw symbolic equation]:equation' \ '--image[Image file to render beneath the data]:image:_files -g "(#i)*.(jpg|jpeg|png|gif)"' \ '--square[Plot data with square aspect ratio]' \ - '--square_xy[For 3D plots, set square aspect ratio for ONLY the x,y axes]' \ + '--square-xy[For 3D plots, set square aspect ratio for ONLY the x,y axes]' \ '--hardcopy[Plot to a file]:new image filename:_files -g "(#i)*.(jpg|jpeg|png|gif)"' \ '--maxcurves[The maximum allowed number of curves]:number of curves' \ '(--3d)--monotonic[Resets plot if an X in the past is seen]' \