feedgnuplot/guide/guide.org

• Guide
• Tutorial

Guide

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.

Here each point we plotted was 2-dimensional (has an x value an a y value), but we passed in only one number for each point. This is what is expected without --domain, so feedgnuplot filled in sequential integers (0, 1, 2, …) for the x coordinate. Without --domain and without --dataid, each line of input is interpreted as y0 y1 y2.... So we can plot a sin and a cos together:

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

Note that, the lines may have different numbers of points. To plot the cosine from every line, but a 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

If we pass in two columns and --domain, feedgnuplot will use one for the x, and the other for the y. With --domain and without --dataid, 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 --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 --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 --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 situation, 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 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'

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 --domain --square \
            --tuplesize 0 3  \
            --style 0 'with points palette'