feedgnuplot/guide/guide.org

• Tutorial
• Recipes
  • Line, point sizes, thicknesses, styles
  • Error bars
  • Polar coordinates
  • Labels
  • 3D plots
  • Histograms

This is an overview of the capabilities of feedgnuplot and a set of example recipes. The documentation provides a complete reference. The capabilities of gnuplot itself are demonstrated at its demo page.

Tutorial

First, a trivial plot: let's plot a sinusoid

seq 100 | \
perl -nE 'say sin($_/5.)' | \
feedgnuplot

This was a trivial plot, and was trivially-easy to make: we gave the tool one column of data with no specific instructions, and we got a plot.

The interpretation of the input data is controlled by two arguments: =--domain and --dataid. Here we passed neither, so each line of input is interpreted as y0 y1 y2... with sequential integers (0, 1, 2, …) used for the x coordinate. Let's pass in more than one y per line to plot a sine and a cosine together:

seq 100 | \
perl -nE '$th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          say "$c $s"' | \
feedgnuplot --lines --points

Here I also passed --lines --points to make more legible plots.

Note that, the lines may have different numbers of points. To plot the cosine from every line, but the sine from every 5th line:

seq 100 | \
perl -nE '$th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          if($.%5) { say "$c";    }
          else     { say "$c $s"; }' | \
feedgnuplot --lines --points

Each y is referred to as a "dataset" or "curve" in the code and documentation.

With --domain, the x values are read from the data instead of simply encoding line numbers: each line of input is interpreted as x y0 y1 y2.... Let's plot sin(theta) vs. cos(theta), i.e. a circle:

seq 100 | \
perl -nE '$th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          say "$c $s"' | \
feedgnuplot --lines --points --domain

Hmmm. We asked for a circle, but this looks more like an ellipse. Why? Because gnuplot is autoscaling the x and y axes independently to fill the plot window. We can scale the axes together by passing --square, and we get a circle:

seq 100 | \
perl -nE '$th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          say "$c $s"' | \
feedgnuplot --lines --points --domain --square

Again, we can have multiple y in each line, and each line may have a different number of y. Let's plot a circle and an ellipse, sampled more coarsely:

seq 100 | \
perl -nE '$th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          if($.%5) { say "$c $s"; }
          else     { $s2 = $s/2;
                     say "$c $s $s2"; }' | \
feedgnuplot --lines --points --domain --square

We just plotted something where each point is represented by 2 values: x and y. When making 2D plots, this is the most common case, but others are possible. What if we want to color-code our points using another column of data? We feed in the new column, and we tell feedgnuplot that we now have 3 values per point (the tuple size), and we tell gnuplot how we want this plot to be made. Color-coding by the angle, in degrees:

seq 100 | \
perl -nE '$thdeg = $_/100.*360.;
          $th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          say "$c $s $thdeg";' | \
feedgnuplot --domain --square \
            --tuplesizeall 3  \
            --styleall 'with linespoints palette'

Here we said that all the datasets have 3 values per point. And that all the datasets should be plotted with that particular style. The styles are strings that are passed on to gnuplot verbatim. So the full power of gnuplot is available, and there's nothing feedgnuplot-specific to learn. gnuplot has plenty of documentation about styling details.

The above --styleall argument may be identically replaced with a shorthand:

--with 'points palette'

Note that the --lines --points specify the default style only, so these options do nothing here, and if we want lines and points, we ask for those in the style:

--with 'linespoints palette'

The styles and tuple sizes can be different for each dataset. For instance, to apply the colors only to the circle (dataset 0), leaving the ellipse (dataset 1) with the default tuple size and style:

seq 100 | \
perl -nE '$thdeg = $_/100.*360.;
          $th = $_/100.*2.*3.14159;
          $s=sin($th); $c=cos($th);
          if($.%5) { say "$c $s $thdeg" }
          else     { $s2 = $s/2;
                     say "$c $s $thdeg $s2"; }' | \
feedgnuplot --lines --points --domain --square \
            --tuplesize 0 3   \
            --style     0 'with points palette' \
            --legend    0 'circle' \
            --legend    1 'ellipse'

Here we also asked for dataset labels to make it clear to the viewer what's what.

The other significant option involved in the interpretation of data is --dataid. This labels each dataset in the data, so instead of referring to dataset 0, you could refer to dataset circle. With --domain --dataid, each line of input is interpreted as x id0 y0 id1 y1..., with the number of y in each dataset reflecting the tuple size. Naturally, --dataid without --domain is identical, except without the leading x. The previous plot can be reproduced with --dataid:

seq 100 | \
perl -nE '$thdeg = $_/100.*360.;
          $th = $_/100.*2.*3.14159;
          $s=sin($th); $c=cos($th);
          if($.%5) { say "$c circle $s $thdeg" }
          else     { $s2 = $s/2;
                     say "$c circle $s $thdeg ellipse $s2"; }' | \
feedgnuplot --lines --points --domain --dataid --square \
            --tuplesize circle 3   \
            --style     circle 'with points palette' \
            --autolegend

Note that instead of labelling the datasets explicitly, we passed --autolegend to use the ID as the label for each dataset. This works without --dataid also, but the IDs are then the unhelpful sequential integers.

Recipes

This is a good overview of the syntax and of the data interpretation. Let's demo some fancy plots to serve as a cookbook.

Since the actual plotting is handled by gnuplot, its documentation and demos are the primary reference on how to do stuff.

Line, point sizes, thicknesses, styles

Most often, we're plotting lines or points. The most common styling keywords are:

• pt (or equivalently pointtype)
• ps (or equivalently pointsize)
• lt (or equivalently linetype)
• lw (or equivalently linewidth)
• lc (or equivalently linecolor)
• dt (or equivalently dashtype)

For details about these and all other styles, see the gnuplot documentation. For instance, the first little bit of the docs about the different line widths:

gnuplot -e 'help linewidth' | head -n 20

 Each terminal has a default set of line and point types, which can be seen
 by using the command `test`.  `set style line` defines a set of line types
 and widths and point types and sizes so that you can refer to them later by
 an index instead of repeating all the information at each invocation.

 Syntax:
       set style line <index> default
       set style line <index> {{linetype  | lt} <line_type> | <colorspec>}
                              {{linecolor | lc} <colorspec>}
                              {{linewidth | lw} <line_width>}
                              {{pointtype | pt} <point_type>}
                              {{pointsize | ps} <point_size>}
                              {{pointinterval | pi} <interval>}
                              {{pointnumber | pn} <max_symbols>}
                              {{dashtype | dt} <dashtype>}
                              {palette}
       unset style line
       show style line

 `default` sets all line style parameters to those of the linetype with

gnuplot has a test command, which produces a demo of the various available styles. This documentation uses the svg terminal (what gnuplot calls a backend). So for the svg terminal, the various styles look like this:

test

So for instance if you plot --with 'linespoints pt 4 dt 2 lc 7' you'll get a red dashed line with square points. By default you'd be using one of the interactive graphical terminals (x11 or qt), which would have largely similar styling.

Let's make a plot with some variable colors and point sizes:

seq -10 10 | \
perl -nE '$, = " ";
          say "parabola", $_*$_, abs($_)/2, $_*50;
          say "line",     $_*3. + 30.;' | \
feedgnuplot --dataid \
            --tuplesize parabola 4   \
            --style     parabola 'with points pointtype 7 pointsize variable palette' \
            --style     line     'with lines lw 3 lc "red" dashtype 2' \
            --set 'cbrange [-600:600]'

Here we used --set to set the range of the colorbar. --set (and --unset) map to the gnuplot set (and --unset) command.

Error bars

As before, the gnuplot documentation has the styling details:

gnuplot -e 'help xerrorbars'
gnuplot -e 'help yerrorbars'
gnuplot -e 'help xyerrorbars'

For brevity, I'm not including the contents of those help pages here. These tell us how to specify errorbars: how many columns to pass in, what they mean, etc. Example:

seq -10 10 | \
perl -nE '$, = " ";
          chomp;
          $x = $_;
          $y = $x*$x * 10 + 20;
          say $x+1, "parabola", $y;
          say $x+1, "parabola_symmetric_xyerrorbars", $y, $x*$x/80, $x*$x/4;
          say $x, "parabola_unsymmetric_xyerrorbars", $y, $x-$x*$x/80, $x+$x*$x/40, $y-$x*$x/4, $y+$x*$x/8;
          say $x, "line_unsymmetric_yerrorbars", $x*20+500, 40;' | \
feedgnuplot --domain --dataid \
            --tuplesize parabola 2   \
            --style     parabola "with lines" \
            --tuplesize parabola_symmetric_xyerrorbars 4   \
            --style     parabola_symmetric_xyerrorbars "with xyerrorbars" \
            --legend    parabola_symmetric_xyerrorbars "using the 'x y xdelta ydelta' style" \
            --tuplesize parabola_unsymmetric_xyerrorbars 6   \
            --style     parabola_unsymmetric_xyerrorbars "with xyerrorbars" \
            --legend    parabola_unsymmetric_xyerrorbars "using the 'x y xlow xhigh ylow yhigh' style" \
            --tuplesize line_unsymmetric_yerrorbars 3   \
            --style     line_unsymmetric_yerrorbars "with yerrorbars" \
            --legend    line_unsymmetric_yerrorbars "using the 'x y ydelta' style" \
            --xmin -10 --xmax 10 \
            --set 'key box opaque'

Polar coordinates

See

gnuplot -e 'help polar'

Let's plot a simple rho = theta spiral:

seq 100 | \
perl -nE '$x = $_/10; \
          say "$x $x"' | \
feedgnuplot --domain       \
            --with 'lines' \
            --set 'polar'  \
            --square

Labels

Docs:

gnuplot -e 'help labels'
gnuplot -e 'help set label'

Basic example:

echo \
    "1 1 aaa
     2 3 bbb
     4 5 ccc" | \
feedgnuplot --domain          \
            --with 'labels'   \
            --tuplesizeall 3  \
            --xmin 0 --xmax 5 \
            --ymin 0 --ymax 6 \
            --unset grid

More complex example (varied orientations and colors):

echo \
    "1 1 aaa 0  10
     2 3 bbb 30 18
     4 5 ccc 90 20" | \
feedgnuplot --domain          \
            --with 'labels rotate variable textcolor palette' \
            --tuplesizeall 5  \
            --xmin 0 --xmax 5 \
            --ymin 0 --ymax 6 \
            --unset grid

3D plots

We can plot in 3D by passing --3d. When plotting interactively, you can use the mouse to rotate the plot, and look at it from different directions. Otherwise, the viewing angle can be set with --set 'view ...'. See

gnuplot -e 'help set view'

Unlike 2D plots, 3D plots have a 2-dimensional domain, and --domain is required. So each line is interpreted x y z0 z1 z2....

A double-helix with variable color and variable pointsize

seq 200 | \
perl -nE '$, = " ";
          $th = $_/10;
          $z  = $_/40;
          $c  = cos($th);
          $s  = sin($th);
          $size = 0.5 + abs($c);
          $color = $z;
          say  $c,  $s, 0, $z, $size, $color;
          say -$c, -$s, 1, $z, $size, $color;' | \
feedgnuplot --domain --dataid --3d \
            --with 'points pointsize variable pointtype 7 palette' \
            --tuplesizeall 5 \
            --title "Double helix" \
            --squarexy

Histograms

gnuplot (and feedgnuplot) has support for histograms. So we can give it data, and have it bin it for us. Pre-sorting the data is unnecessary. Let's look at the central limit theorem: we look at the distribution of sums of 10 uniform samples in [-1,1]: it should be normal-ish. And let's draw the expected perfect PDF on top (as an equation, evaluated by gnuplot).

N=1000;
Nsum=200;
var=$((Nsum/3));
binwidth=2;
seq $N | \
perl -nE '$Nsum = '$Nsum';
          $s = 0; for $i (1..$Nsum) { $s += rand()*2-1; }
          say $s;' | \
feedgnuplot --histo 0 --binwidth $binwidth \
            --equation-above "($N * sqrt(2.*pi*$var) * erf($binwidth/(2.*sqrt(2.*$var)))) * \
                              exp(-(x*x)/(2.*$var)) / \
                              sqrt(2.*pi*$var) title \"Limit gaussian\" with lines lw 2"