* Guide

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.

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:

#+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
#+END_SRC

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

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

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

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:

#+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 --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 --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 --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 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:

#+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 --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_SRC sh :results none :exports none
--with points palette'
#+END_SRC

The styles and tuple sizes can be different for each dataset. For instance, to
apply the colors only to the circle, leaving the ellipse 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 --domain --square \
                --tuplesize 0 3  \
                --style 0 'with points palette'
#+END_SRC

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