Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FEEDGNUPLOT(1)	      User Contributed Perl Documentation	FEEDGNUPLOT(1)

NAME
       feedgnuplot - General purpose pipe-oriented plotting tool

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
		      --terminal 'dumb 80,40' --exit

					 Test plot

	 10 ++------+--------+-------+-------+-------+--------+-------+------*A	25
	    +	    +	     +	     +	     +	     +	      +	      +	   **#+
	    |	    :	     :	     :	     :	     :	      :	data 0+**A*** |
	    |	    :	     :	     :	     :	     :	      :	      :** #   |
	  9 ++.......................................................**.##....|
	    |	    :	     :	     :	     :	     :	      :	   ** :#      |
	    |	    :	     :	     :	     :	     :	      :	 **   #	      |
	    |	    :	     :	     :	     :	     :	      :**   ##:	     ++	20
	  8 ++................................................A....#..........|
	    |	    :	     :	     :	     :	     :	    **:	  #   :	      |
	    |	    :	     :	     :	     :	     :	  **  :	##    :	      |
	    |	    :	     :	     :	     :	     :	**    :#      :	      |
	    |	    :	     :	     :	     :	     :**      B	      :	      |
	  7 ++......................................**......##................|
	    |	    :	     :	     :	     :	  ** :	  ##  :	      :	     ++	15
	    |	    :	     :	     :	     :	**   :	 #    :	      :	      |
	    |	    :	     :	     :	     :**     : ##     :	      :	      |
	  6 ++..............................*A.......##.......................|
	    |	    :	     :	     :	  ** :	   ##:	      :	      :	      |
	    |	    :	     :	     :	**   :	  #  :	      :	      :	      |
	    |	    :	     :	     :**     :	##   :	      :	      :	     ++	10
	  5 ++......................**........##..............................|
	    |	    :	     :	  ** :	    #B	     :	      :	      :	      |
	    |	    :	     :	**   :	  ## :	     :	      :	      :	      |
	    |	    :	     :**     :	##   :	     :	      :	      :	      |
	  4 ++...............A.......###......................................|
	    |	    :	   **:	   ##:	     :	     :	      :	      :	      |
	    |	    :	 **  :	 ##  :	     :	     :	      :	      :	     ++	5
	    |	    :  **    : ##    :	     :	     :	      :	      :	      |
	    |	    :**	   ##B#	     :	     :	     :	      :	      :	      |
	  3 ++.....**..####...................................................|
	    |	 **####	     :	     :	     :	     :	      :	      :	      |
	    |  **## :	     :	     :	     :	     :	      :	      :	      |
	    B**	    +	     +	     +	     +	     +	      +	      +	      +
	  2 A+------+--------+-------+-------+-------+--------+-------+------++	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

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 "awk"	command	generates some
       data to plot and	the "feedgnuplot" reads	it in from STDIN and generates
       the plot. The "awk" invocation is just an example; more interesting
       things would be plotted in normal usage.	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 "--set",	"--extracmds" "--style", etc. Arbitrary
       gnuplot commands	can be passed in with "--extracmds". For example, to
       turn off	the grid, you can pass in "--extracmds 'unset grid'". Commands
       "--set" and "--unset" exists to provide nicer syntax, so	this is
       equivalent to passing "--unset grid". As	many of	these options as
       needed can be passed in.	To add arbitrary curve styles, use "--style
       curveID extrastyle". Pass these more than once to affect	more than one
       curve.

       To apply	an extra style to all the curves that lack an explicit
       "--style", pass in "--styleall extrastyle". In the most common case,
       the extra style is "with	something". To support this more simply, you
       can pass	in "--with something" instead of "--styleall 'with
       something'". "--styleall" and "--with" are mutually exclusive.
       Furthermore any curve-specific "--style"	overrides the global
       "--styleall" or "--with"	setting.

   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

       Domain selection

       If "--domain" is	passed in, the first value on each line	of input is
       interpreted as the X-value for the rest of the data on that line.
       Without "--domain" the X-value is the line number, and the first	value
       on a line is a plain data point like the	others.	Default	is
       "--nodomain". Thus the original example above produces 2	curves,	with
       1,2,3,4,5 as the	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 2,4,6,8,10 as the X-values. As	many points as
       desired can appear on a single line, but	all points on a	line are
       associated with the X-value at the start	of that	line.

       Curve indexing

       By default, each	column represents a separate curve. This is fine
       unless sparse data is to	be plotted. With the "--dataid"	option,	each
       point is	represented by 2 values: a string identifying the curve, and
       the value itself. If we add "--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 "awk", is 2,4,6,8,10. These are interpreted as the IDs of
       the curves to be	plotted. The "--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. "--domain"	can be used in conjunction with	"--dataid".

       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 "--circles", for instance,	then there's an	extra range
       value: the radius. A similar situation exists with "--colormap" where
       each point contains the position	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, however,
       by specifying the specific style	with "--style",	and specifying how
       many values are needed for each point with "--rangesizeall" or
       "--rangesize" or	"--extraValuesPerPoint". Those options that specify
       the range size are required only	for styles not explicitly supported by
       feedgnuplot; supported styles do	the right thing	automatically.

       More examples: if making	a 2d plot of y error bars where	gnuplot
       expects a (x,y,ydelta) tuple for	each point, you	want "--rangesizeall
       2" because you have one domain value (x)	and 2 range values (y,ydelta).
       Gnuplot can also	plot lopsided y	errorbars by giving a tuple
       (x,y,ylow,yhigh). This is similar as before, but	you want
       "--rangesizeall 3" instead.

       3D data

       To plot 3D data,	pass in	"--3d".	"--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	(Z as a	function of X
       and Y instead of	Y as a function	of 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.

       Time/date data

       If the input data domain	is a time/date,	this can be interpreted	with
       "--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 "strftime" understands are generally
       supported. The backslash	sequences in the format	are not	supported, so
       if you want a tab, put in a tab instead of \t. Whitespace in the	format
       is supported. When this flag is given, some other options act a little
       bit differently:

       o   "--xlen" is an integer in seconds

       o   "--xmin" and	"--xmax" must use the format passed in to "--timefmt"

       Using this option changes both the way the input	is parsed and 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 "set format" command,	which takes
       the same	type of	format string as "--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, feedgnuplot
       currently supports it only as the x-axis	domain.	This may change	in the
       future.

   Real-time streaming data
       To plot real-time data, pass in the "--stream [refreshperiod]" option.
       Data will then be plotted as it is received. The	plot will be updated
       every "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
       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. Look in "Special data commands" for	more
       information.

       To plot only the	most recent data (instead of all the data), "--xlen
       windowsize" can be given. This will create an constantly-updating,
       scrolling view of the recent past. "windowsize" should be replaced by
       the desired length of the domain	window to plot,	in domain units
       (passed-in values if "--domain" or line numbers otherwise). If the
       domain is a time/date via "--timefmt", then "windowsize"	is and integer
       in seconds. If we're plotting a histogram, then "--xlen"	causes a
       histogram over a	moving window to be computed. The subtlely here	is
       that with a histogram you don't actually	see the	domain since only the
       range is	analyzed. But the domain is still there, and can be utilized
       with "--xlen". With "--xlen" we can plot	only histograms	or only
       non-histograms.

       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

       "replot"
	   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 "--stream
	   [refreshperiod]".

       "clear"
	   This	command	clears out the current data in the plot. The plotting
	   process continues, however, to any data following the "clear".

       "exit"
	   This	command	causes feedgnuplot to exit.

   Hardcopy output
       The script is able to produce hardcopy output with "--hardcopy
       outputfile". The	output type can	be inferred from the filename, if .ps,
       .eps, .pdf, .svg	or .png	is requested. If any other file	type is
       requested, "--terminal" must be passed in to tell gnuplot how to	make
       the plot. If "--terminal" is passed in, then the	"--hardcopy" argument
       only provides the output	filename.

   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.

       Self-plotting data with a #!

       A self-plotting,	executable data	file "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
       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.

       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.

ARGUMENTS
       o   --"[no]domain"

	   If enabled, the first element of each line is the domain variable.
	   If not, the point index is used

       o   --"[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

	   o   "--nodomain --nodataid" would parse the 4 numbers as points in
	       4 different curves at x=3

	   o   "--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

	   o   "--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

	   o   "--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

       o   "--[no]3d"

	   Do [not] plot in 3D.	This only makes	sense with "--domain". Each
	   domain here is an (x,y) tuple

       o   --"timefmt [format]"

	   Interpret the X data	as a time/date,	parsed with the	given format

       o   "--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 "--rangesize".

       o   "--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.

       o   "--[no]lines"

	   Do [not] draw lines to connect consecutive points

       o   "--[no]points"

	   Do [not] draw points

       o   "--circles"

	   Plot	with circles. This requires a radius be	specified for each
	   point.  Automatically sets the "--rangesize". "Not" supported for
	   3d plots.

       o   "--title xxx"

	   Set the title of the	plot

       o   "--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

       o   "--autolegend"

	   Use the curve IDs for the legend. Titles given with "--legend"
	   override these

       o   "--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". If we're plotting a	histogram,
	   then	"--xlen" causes	a histogram over a moving window to be
	   computed. The subtlely here is that with a histogram	you don't
	   actually see	the domain since only the range	is analyzed. But the
	   domain is still there, and can be utilized with "--xlen". With
	   "--xlen" we can plot	only histograms	or only	non-histograms.

       o   "--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 only	to 3d plots or colormaps.

       o   "--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 only to 3d plots.

       o   "--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. 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'

       o   "--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).	If a
	   drawing style is not	specified for this curve ("--curvestyle") or
	   all curves ("--with", "--curvestyleall") then the default histogram
	   style is set: filled	boxes with borders. This is what the user
	   generally wants. 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 domain values are not drawn in
	   any way. Can	be passed multiple times, or passed a comma- separated
	   list

       o   "--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.

       o   "--histstyle	style"

	   Normally, histograms	are generated with the 'smooth frequency'
	   gnuplot style.  "--histstyle" can be	used to	select different
	   "smooth" settings (see the gnuplot "help smooth" 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.

       o   "--style curveID style"

	   Additional styles per curve.	With "--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.
	   "--styleall"	does not apply to curves that have a "--style".

       o   "--curvestyle curveID"

	   Synonym for "--style"

       o   "--styleall xxx"

	   Additional styles for all curves that have no "--style". This is
	   overridden by any applicable	"--style". Exclusive with "--with".

       o   "--curvestyleall xxx"

	   Synonym for "--styleall"

       o   "--with xxx"

	   Same	as "--styleall", but prefixed with "with". Thus

	    --with boxes

	   is equivalent to

	    --styleall 'with boxes'

	   Exclusive with "--styleall".

       o   "--extracmds	xxx"

	   Additional commands to pass on to gnuplot verbatim. These could
	   contain extra global	styles for instance. Can be passed multiple
	   times.

       o   "--set xxx"

	   Additional 'set' commands to	pass on	to gnuplot verbatim. "--set 'a
	   b c'" will result in	gnuplot	seeing a "set a	b c" command. Can be
	   passed multiple times.

       o   "--unset xxx"

	   Additional 'unset' commands to pass on to gnuplot verbatim.
	   "--unset 'a b c'" will result in gnuplot seeing a "unset a b	c"
	   command. Can	be passed multiple times.

       o   "--equation xxx"

	   Gnuplot can plot both data and symbolic equations. "feedgnuplot"
	   generally plots data, but with this option can plot symbolic
	   equations also. This	is generally intended to augment data plots,
	   since for equation-only plots you don't need	"feedgnuplot".
	   "--equation"	can be passed multiple times for multiple equations.
	   The given strings are passed	to gnuplot directly without any	thing
	   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), and	I plot two damped sinusoids on
	   the same plot. The sinusoids	are not	affected by "feedgnuplot"
	   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 also plot a true circle as a parametric
	   equation.

       o   "--square"

	   Plot	data with aspect ratio 1. For 3D plots,	this controls the
	   aspect ratio	for all	3 axes

       o   "--square_xy"

	   For 3D plots, set square aspect ratio for ONLY the x,y axes

       o   "--hardcopy xxx"

	   If not streaming, output to a file specified	here. Format inferred
	   from	filename, unless specified by "--terminal". If "--terminal" is
	   given, "--hardcopy" sets only the output filename.

       o   "--terminal xxx"

	   String passed to 'set terminal'. No attempts	are made to validate
	   this.  "--hardcopy" sets this to some sensible defaults if
	   "--hardcopy"	is set to a filename ending in ".png", ".pdf", ".ps",
	   ".eps" or ".svg". If	any other file type is desired,	use both
	   "--hardcopy"	and "--terminal"

       o   "--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

       o   "--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. The data is
	   replotted before being purged

       o   "--rangesize	curveID	xxx"

	   The options "--rangesizeall", "--rangesize" and
	   "--extraValuesPerPoint" set the number of values are	needed to
	   represent each point	being plotted (see "Multi-value	style support"
	   above). These options are only needed if unknown styles are used,
	   with	"--styleall" or	"--with" for instance.

	   "--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	"--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.

       o   "--rangesizeall xxx"

	   Like	"--rangesize", but applies to all the curves.

	   "--extraValuesPerPoint xxx"

	   Like	"--rangesizeall", but instead of overriding the	default, adds
	   to it. For example, if plotting non-lopsided	y errorbars gnuplot
	   wants (x,y,ydelta) tuples.  These can be specified both with
	   "--rangesizeall 2" (because there are 2 range values) or
	   "--extraValuesPerPoint 1" (because there's 1	more value than
	   usual).

	   This	option is only needed if unknown styles	are used, with
	   "--styleall"	or "--with" for	instance.

       o   "--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.

       o   "--exit"

	   This	controls what happens when the input data is exhausted,	or
	   when	some part of the "feedgnuplot" pipeline	is killed. This	option
	   does	different things depending on whether "--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 "gnuplot" process. It is
	   thus	possible for the main "gnuplot"	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:

	   Alive: "feedgnuplot", "gnuplot" alive, plot window process alive,
	   no shell prompt (shell busy with "feedgnuplot")
	   Half-alive: "feedgnuplot", "gnuplot"	dead, plot window process
	   alive (but non-interactive),	shell prompt available
	   Dead: "feedgnuplot",	"gnuplot" dead,	plot window process dead,
	   shell prompt	available

	   The possibilities are:

	   No "--stream", all data read	in
	       no "--exit" (default)
		   Alive. Need to Ctrl-C to get	back into the shell

	       "--exit"
		   Half-alive. Non-interactive prompt up, and the shell
		   accepts new commands.  Without "--stream" the goal is to
		   show	a plot,	so a Dead state	would not be useful.

	   "--stream", all data	read in	or the "feedgnuplot" process
	   terminated
	       no "--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.

	       "--exit"
		   Dead. No plot is shown, and the shell accepts new commands.
		   With	"--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.

	   Note	that one usually invokes "feedgnuplot" as a part of a shell
	   pipeline:

	    $ write_data | feedgnuplot

	   If the user terminates this pipeline	with ^C, then all the
	   processes in	the pipeline receive SIGINT. This normally kills
	   "feedgnuplot" and all its "gnuplot" children, and we	let this
	   happen unless "--stream" and	no "--exit".  If "--stream" and	no
	   "--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.

       o   "--geometry"

	   If using X11, specifies the size, position of the plot window

       o   "--version"

	   Print the version and exit

RECIPES
   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

   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

   Realtime plot of battery charge in respect to time
       Uses the	result of the "acpi" 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 (%)"

   Realtime plot of temperatures in an IBM Thinkpad
       Uses "/proc/acpi/ibm/thermal", 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)'

   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

   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

   Plotting points on top of an	existing image
       This can	be done	by using "--equation" to pass arbitrary	plot input to
       gnuplot:

	$ < features_xy.data
	  feedgnuplot --points --domain
	    --equation '"image.png" binary filetype=png	flipy with rgbimage'

       Here an existing	image is given to gnuplot verbatim, and	data to	plot
       on top of it is interpreted by feedgnuplot as usual. "flipy" 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.

ACKNOWLEDGEMENT
       This program is originally based	on the driveGnuPlots.pl	script from
       Thanassis Tsiodras. It is available from	his site at
       <http://users.softlab.ece.ntua.gr/~ttsiod/gnuplotStreaming.html>

REPOSITORY
       <https://github.com/dkogan/feedgnuplot>

AUTHOR
       Dima Kogan, "<dima@secretsauce.net>"

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.

perl v5.24.1			  2017-03-31			FEEDGNUPLOT(1)

NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | RECIPES | ACKNOWLEDGEMENT | REPOSITORY | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=feedgnuplot&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help