more guide plots

guide/guide.org

@@ -4,6 +4,7 @@ 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
@@ -18,11 +19,12 @@ seq 100 | \
 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:
+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 | \
@@ -33,21 +35,22 @@ seq 100 | \
 #+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:
+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"; }' | \
+              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
+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:
 
@@ -61,7 +64,7 @@ seq 100 | \
 [[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.
+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
@@ -78,9 +81,64 @@ 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"; }' | \
+              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]]