feedgnuplot/guide/guide.org

• Tutorial
• Recipes
  • Line, point sizes, thicknesses, styles

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 --lines --points --domain --square \
            --tuplesizeall 3  \
            --styleall 'with points 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