From 008576fd9deb8e953288a0535c37fef3345c3df2 Mon Sep 17 00:00:00 2001 From: Dima Kogan Date: Sun, 21 Feb 2021 00:59:25 -0800 Subject: [PATCH] README.pod is a symlink again. Did github fix their bug? --- README.pod | 1033 +--------------------------------------------------- 1 file changed, 1 insertion(+), 1032 deletions(-) mode change 100644 => 120000 README.pod diff --git a/README.pod b/README.pod deleted file mode 100644 index 453bddc..0000000 --- a/README.pod +++ /dev/null @@ -1,1032 +0,0 @@ -=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 - -Here we asked for ASCII plotting, which is useful for documentation. - -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. For a tutorial and a gallery please see the guide at -L - -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/x2min/x2max/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 x2/y2-axis bounds 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/x2label/ylabel/y2label/zlabel xxx> - -Label the given axis. The x2/y2-axis labels do not apply to 3d plots while the -z-axis label applies I to 3d plots. - -=item - -C<--x2/--y2/--x1y2/--x2y1/--x2y2 xxx> - -By default data is plotted against the x1 and y1 axes (the left and bottom one -respectively). If we want a particular curve plotted against a different axis, -we can specify that with these options. You pass C<--AXIS ID> where C -defines the axis (C or C or C or C or C) and the C -is the curve ID. C<--x2> is a synonym for C<--x2y1> and C<--y2> is a synonym for -C<--x1y2>. The curve ID is an ordered 0-based index or a specific ID if -C<--dataid> or C<--vnlog>. None of these apply to 3d plots. Can be passed -multiple times for different curve IDs, multiple IDs can be passed in as a -comma-separated list. By default the curves plotted against the various axes -aren not drawn in any differentiated way: the viewer of the resulting plot has -to be told which is which via an axes label, legend, colors, etc. Prior to -version 1.25 of C 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<--every curveID factor> - -Decimates the input. Instead of plotting every point in the given curve, plot -one point per factor. This is useful to quickly process huge datasets. For -instance, to plot 1% of the data, pass a factor of 100. - -=item - -C<--everyall factor> - -Decimates the input. This works exactly like C<--every>, except it applies to -I the curves. - -=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. - -=item - -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<--equation-below xxx> - -Synonym for C<--equation>. These are rendered I all the other data. - -=item - -C<--equation-above xxx> - -Like C<--equation>, but is rendered I of all the other data. - -=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> - -Specifies the size, position of the plot window. This applies I to the -C gnuplot terminal, and has no effect otherwise. To control the window size -for any other terminal, ask for the terminal explicitly, with the options -specifying the size. For instance C<--terminal 'qt size 1024,768'> - -=item - -C<--version> - -Print the version and exit - -=back - -=head1 RECIPES - -For a tutorial and a gallery please see the guide at -L - -=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 -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-2021 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/README.pod b/README.pod new file mode 120000 index 0000000..abe0c14 --- /dev/null +++ b/README.pod @@ -0,0 +1 @@ +bin/feedgnuplot \ No newline at end of file