* 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]].

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 cos from
every line, but a sin 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]]