feedgnuplot/guide/guide.org

This is an overview of the capabilities of =feedgnuplot= and a set of example
recipes. The [[https://github.com/dkogan/feedgnuplot/][documentation]] provides a complete reference. The capabilities of
gnuplot itself are demonstrated at [[http://www.gnuplot.info/demo/][its demo page]].

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

#+BEGIN_SRC sh :results file link :exports both
seq 100 | \
perl -nE 'say sin($_/5.)' | \
feedgnuplot
#+END_SRC

#+RESULTS:
[[file:guide-1.svg]]

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:

#+BEGIN_SRC sh :results file link :exports both
seq 100 | \
perl -nE '$th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          say "$c $s"' | \
feedgnuplot --lines --points
#+END_SRC

#+RESULTS:
[[file:guide-2.svg]]

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:

#+BEGIN_SRC sh :results file link :exports both
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
#+END_SRC

#+RESULTS:
[[file:guide-3.svg]]

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:

#+BEGIN_SRC sh :results file link :exports both
seq 100 | \
perl -nE '$th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          say "$c $s"' | \
feedgnuplot --lines --points --domain
#+END_SRC

#+RESULTS:
[[file:guide-4.svg]]

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:

#+BEGIN_SRC sh :results file link :exports both
seq 100 | \
perl -nE '$th = $_/100.*2.*3.14159;
          $s  = sin($th);
          $c  = cos($th);
          say "$c $s"' | \
feedgnuplot --lines --points --domain --square
#+END_SRC

#+RESULTS:
[[file:guide-5.svg]]

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:
#+BEGIN_SRC sh :results file link :exports both
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
#+END_SRC

#+RESULTS:
[[file:guide-6.svg]]

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:

#+BEGIN_SRC sh :results file link :exports both
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'
#+END_SRC

#+RESULTS:
[[file:guide-7.svg]]

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:

#+BEGIN_EXAMPLE
--with 'points palette'
#+END_EXAMPLE

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:

#+BEGIN_EXAMPLE
--with 'linespoints palette'
#+END_EXAMPLE

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:

#+BEGIN_SRC sh :results file link :exports both
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'
#+END_SRC

#+RESULTS:
[[file:guide-8.svg]]

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=:

#+BEGIN_SRC sh :results file link :exports both
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
#+END_SRC

#+RESULTS:
[[file:guide-9.svg]]

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 [[http://www.gnuplot.info/demo/][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:

#+BEGIN_SRC sh :results output verbatim :exports both
gnuplot -e 'help linewidth' | head -n 20
#+END_SRC

#+RESULTS:
#+begin_example
 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
#+end_example