% Copyright 2010 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.




\section{Polar Axes}

\label{section-dv-polar}


\subsection{Overview}

\begin{tikzlibrary}{datavisualization.polar}
  This library contains keys that allow you to create plots in a polar
  axis system is used. 
\end{tikzlibrary}

In a \emph{polar axis system} two attributes are visualized by
displacing a data point as follows: One attribute is used to compute a
an angle (a direction) while a second attribute is used as a radius (a
distance). The angle can be measured in degrees, radians, or can be
scaled arbitrarily.


\begin{codeexample}[width=8.5cm]
\tikz \datavisualization [
  scientific polar axes={0 to pi, clean},
  all axes=grid,
  style sheet=vary hue,
  legend=below
  ]
  [visualize as smooth line=sin,
   sin={label in legend={text=$1+\sin \alpha$}}]
  data [format=function] {
    var  angle : interval [0:pi];
    func radius = sin(\value{angle}r) + 1;
  }
  [visualize as smooth line=cos,
   cos={label in legend={text=$1+\cos\alpha$}}]
  data [format=function] {
    var  angle : interval [0:pi];
    func radius = cos(\value{angle}r) + 1;
  };
\end{codeexample}

Most of the time, in order to create a polar axis system, you will
just use the |scientific polar axes| key, which takes a number of
options that allow you to configure the axis system in greater
detail. This key is documented in
Section~\ref{section-dv-sci-polar-axes}. Internally, this key uses
more low level keys which are documented in the en suite sections.

It is worthwhile to note that the axes of a polar axis system are,
still, normal axes of the data visualization system. In particular,
all the configurations possible for, say, Cartesian axes also apply to
the ``angle axis'' and the ``radius axis'' of a polar axis system. For
instance, you can could make both axes logarithmic or style their
ticks:

\begin{codeexample}[]
\tikz[baseline] \datavisualization [
  scientific axes={clean},
  x axis={attribute=angle, ticks={minor steps between steps=4}},
  y axis={attribute=radius, ticks={some, style=red!80!black}},
  all axes=grid,
  visualize as smooth line=sin]
  data [format=function] {
    var t : interval [-3:3];
    func angle = exp(\value t);
    func radius = \value{t}*\value{t};
  };
\qquad
\tikz[baseline] \datavisualization [
  scientific polar axes={right half clockwise, clean},
  angle axis={logarithmic,
    ticks={
      minor steps between steps=8,
      major also at/.list={2,3,4,5,15,20}}},
  radius axis={ticks={some, style=red!80!black}},
  all axes=grid,
  visualize as smooth line=sin]
  data [format=function] {
    var t : interval [-3:3];
    func angle = exp(\value t);
    func radius = \value{t}*\value{t};
  }; 
\end{codeexample}


\subsection{Scientific Polar Axis System}
\label{section-dv-sci-polar-axes}

\begin{key}{/tikz/data visualization/scientific polar axes=\meta{options}}
  This key installs a polar axis system that can be used in a
  ``scientific'' publication. Two axes are created called the
  |angle axis| and the |radius axis|. Unlike ``normal'' Cartesian
  axes, these axes do not point in a specific direction. Rather, the
  |radius axis| is used to map the values of one attribute to a
  distance from the origin while the |angle axis| is used to map the
  values of another attribute to a rotation angle.
  
  The \meta{options} will be executed with the path prefix
\begin{codeexample}[code only]
/tikz/data visualization/scientific polar axes    
\end{codeexample}
  The permissible keys are documented in the later subsections of this
  section. 

  Let us start with the configuration of the radius axis since it is
  easier. Firstly, you should specify which attribute is linked to the
  radius. The default is |radius|, but you will typically wish to
  change this. As with any other axis, the |attribute| key is used to
  configure the axis, see Section~\ref{section-dv-axis-attribute} for
  details. You can also apply all other configurations to the radius
  axis like, say, |unit length| or |length| or |style|. Note, however,
  that the |logarithmic| key will not work with the radius axis for a
  |scientific polar axes| system since the attribute value zero is
  always placed at the center -- and for a logarithmic plot the value
  |0| cannot be mapped.
\begin{codeexample}[width=8.8cm]
\tikz \datavisualization [
  scientific polar axes,
  radius axis={
    attribute=distance,
    ticks={step=5000},
    padding=1.5em,
    length=3cm,
    grid
  },
  visualize as smooth line]
data [format=function] {
  var  angle : interval [0:100];
  func distance = \value{angle}*\value{angle};
};
\end{codeexample}

  For the |angle axis|, you can also specify an attribute using the
  |attribute| key. However, for this axis the mapping of a value to an
  actual angle is a complicated process involving many considerations
  of how the polar axis system should be visualized. For this reason,
  there are a large number of predefined such mappings documented in
  Section~\ref{section-dv-angle-ranges}.

  Finally, as for a |scientific plot|, you can configure where the
  ticks should be shown using the keys |inner ticks|, |outer ticks|,
  and |clean|, documented below.
\end{key}


\subsubsection{Tick Placements}

\begin{key}{/tikz/data visualization/scientific polar axes/outer ticks}
  This key, which is the default, causes ticks to be drawn
  ``outside'' the outer ``ring'' of the polar axes:
\begin{codeexample}[width=8.8cm]
\tikz \datavisualization [
  scientific polar axes={outer ticks, 0 to 180},
  visualize as smooth line]
data [format=function] {
  var  angle : interval [0:100];
  func radius = \value{angle};
};
\end{codeexample}
\end{key}

\begin{key}{/tikz/data visualization/scientific polar axes/inner ticks}
  This key causes the ticks to be ``turned to the inside.'' I do not
  recommend using this key.
\begin{codeexample}[width=8.8cm]
\tikz \datavisualization [
  scientific polar axes={inner ticks, 0 to 180},
  visualize as smooth line]
data [format=function] {
  var  angle : interval [0:100];
  func radius = \value{angle};
};
\end{codeexample}
\end{key}

\begin{key}{/tikz/data visualization/scientific polar axes/clean}
  This key separates the area where the data is shown from the area
  where the ticks are shown. Usually, this is the best choice for the
  tick placement since it avoids a collision of data and
  explanations. 
\begin{codeexample}[width=8.8cm]
\tikz \datavisualization [
  scientific polar axes={clean, 0 to 180},
  visualize as smooth line]
data [format=function] {
  var  angle : interval [0:100];
  func radius = \value{angle};
};
\end{codeexample}  
\end{key}


\subsubsection{Angle Ranges}
\label{section-dv-angle-ranges}

Suppose you create a polar plot in which the radius values vary
between, say, $567$ and $1234$. Then the normal axis scaling mechanisms 
can be used to compute a good scaling for the ``radius axis'': Place
the value $1234$ at a distance of , say, $5\,\mathrm{cm}$ from the
origin and place the value $0$ at the origin. Now, by comparison,
suppose that the values of the angle axis's attribute ranged between,
say, $10$ and $75.7$. In this case, we may wish the angles to be
scaled so that the minimum value is horizontal and the maximum value is
vertical. But we may also wish the a value of $0$ is horizontal and a
value of $90$ is vertical. 

Since it is unclear which interpretation is the right one, you have to
use an option to select which should happen. The applicable options
fall into three categories:

\begin{itemize}
\item Options that request the scaling to be done in such a way that
  the attribute is interpreted as a value in degrees and such that the
  minimum and maximum of the depicted range is a multiple of
  $90^\circ$. For instance, the option |0 to 180| causes the angle
  axis to range from $0^\circ$ to $180^\circ$, independently of the
  actual range of the values.
\item Options that work as above, but use radians rather than
  degrees. An example is the option |0 to pi|.
\item Options that map the minimum value in the data to a horizontal
  or vertical line and the maximum value to another such line. This is
  useful when the values neither directly correspond to degrees or
  radians. In this case, the angle axis may also be a logarithmic
  axis. 
\end{itemize}

In addition to the above categories, all of the option documented in
the following implicitly also select quadrants that are used to depict
the data. For instance, the |0 to 90| key and also the |0 to pi half|
key setup the polar axis system in such a way that only first (upper
right) quadrant is used. No check is done whether the data fill
actually lie in this quadrant -- if it does not, the data will ``bleed
outside'' the range. Naturally, with a key like |0 to 360| or
|0 to 2pi| this cannot happen.

In order to save some space in this manual, in the following the
different possible keys are only given in a table together with a
small example for each key. The examples were created using the
following code:

\begin{codeexample}[]
\tikz \datavisualization [
  scientific polar axes={
    clean,
    0 to 90  % the option 
  },
  angle axis={ticks={step=30}},
  radius axis={length=1cm, ticks={step=1}},
  visualize as scatter]
data point [angle=20, radius=0.5]
data point [angle=30, radius=1]
data point [angle=40, radius=1.5];
\end{codeexample}

For the options on radians, the angle values have been replaced by
|0.2|, |0.3|, and |0.4| and the stepping has been changed by setting
|step=(pi/6)|. For the quadrant options, no stepping is set at all (it
is computed automatically).

\def\polarexample#1#2#3#4#5{%
  \texttt{#1}% 
  \indexkey{/tikz/data visualization/scientific polar axes/#1}&
  \tikz [baseline]{\path(-2.25cm,0)(2.25cm,0); \datavisualization [
    scientific polar axes={clean, #1},
    angle axis={ticks={#2}},
    radius axis={length=1cm, ticks={step=1}},
    visualize as scatter
    ]
    data point [angle=#3, radius=0.5]
    data point [angle=#4, radius=1]
    data point [angle=#5, radius=1.5];
    \path ([yshift=-1em]current bounding box.south);
  }&
  \tikz [baseline]{\path(-2.25cm,0)(2.25cm,0); \datavisualization [
    scientific polar axes={outer ticks, #1},
    angle axis={ticks={#2}},
    radius axis={length=1cm, ticks={step=1}},
    visualize as scatter
    ]
    data point [angle=#3, radius=0.5]
    data point [angle=#4, radius=1]
    data point [angle=#5, radius=1.5];
    \path ([yshift=-1em]current bounding box.south);
  }
  \\
}

\begin{tabular}{lcc}
  \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
  \polarexample{0 to 90}{step=30}{20}{30}{40}
  \polarexample{-90 to 0}{step=30}{20}{30}{40}
  \polarexample{0 to 180}{step=30}{20}{30}{40}
  \polarexample{-90 to 90}{step=30}{20}{30}{40}
  \polarexample{0 to 360}{step=30}{20}{30}{40}
  \polarexample{-180 to 180}{step=30}{20}{30}{40}
\end{tabular}

\begin{tabular}{lcc}
  \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
  \polarexample{0 to pi half}{step=(pi/6)}{0.2}{0.3}{0.4}
  \polarexample{-pi half to 0}{step=(pi/6)}{0.2}{0.3}{0.4}
  \polarexample{0 to pi}{step=(pi/6)}{0.2}{0.3}{0.4}
  \polarexample{-pi half to pi half}{step=(pi/6)}{0.2}{0.3}{0.4}
  \polarexample{0 to 2pi}{step=(pi/6)}{0.2}{0.3}{0.4}
  \polarexample{-pi to pi}{step=(pi/6)}{0.2}{0.3}{0.4}
\end{tabular}

\begin{tabular}{lcc}
  \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
  \polarexample{quadrant}{}{20}{30}{40}
  \polarexample{quadrant clockwise}{}{20}{30}{40}
  \polarexample{fourth quadrant}{}{20}{30}{40}
  \polarexample{fourth quadrant clockwise}{}{20}{30}{40}
  \polarexample{upper half}{}{20}{30}{40}
  \polarexample{upper half clockwise}{}{20}{30}{40}
  \polarexample{lower half}{}{20}{30}{40}
  \polarexample{lower half clockwise}{}{20}{30}{40}
\end{tabular}

\begin{tabular}{lcc}
  \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
  \polarexample{left half}{}{20}{30}{40}
  \polarexample{left half clockwise}{}{20}{30}{40}
  \polarexample{right half}{}{20}{30}{40}
  \polarexample{right half clockwise}{}{20}{30}{40}
\end{tabular}



\subsection{Advanced: Creating a New Polar Axis System}

\begin{key}{/tikz/data visualization/new polar axes=|\char`\{|\meta{angle axis
      name}|\char`\}||\char`\{|\meta{radius axis name}|\char`\}|}
  This key actually creates two axes, whose names are give as
  parameters: An \emph{angle axis} and a \emph{radius axis}. These two
  axes work in concert in the following way: Suppose a data point has two
  attributes called |angle| and |radius| (these attribute names can be
  changed by changing the |attribute| of the \meta{angle axis name} or
  the \meta{radius axis name}, respectively). These two attributes are
  then scaled as usual, resulting in two ``reasonable'' values $a$
  (for the angle) and $r$ (for the radius). Then, the data point gets
  visualized (in principle, details will follow) at a position on the
  page that is at a distance of $r$ from the origin and at an angle
  of~$a$.  
\begin{codeexample}[]
\tikz \datavisualization
    [new polar axes={angle axis}{radius axis},
     radius axis={length=2cm},
     visualize as scatter]
  data [format=named] {
    angle={0,20,...,160}, radius={0,...,5}
  };
\end{codeexample}
  In detail, the \meta{angle axis} keeps track of two vectors $v_0$
  and $v_{90}$, each of which will usually have unit length (length
  |1pt|) and which point in two different directions. Given a radius
  $r$ (measured in \TeX\ |pt|s, so if the 
  radius attribute |10pt|, then $r$ would be $10$) and an angle $a$,
  let $s$ be the sine of $a$ and let $c$ be the cosine
  of $a$, where $a$ is a number is degrees (so $s$
  would be $1$ for $a = 90$). Then, the current page position is
  shifted by $c \cdot r$ times $v_0$ and, additionally, by $s \cdot r$
  times $v_{90}$. This means that in the
  ``polar coordinate system'' $v_0$ is the unit vector along the
  ``$0^\circ$-axis'' and $v_{90}$ is the unit vector along
  ``$90^\circ$-axis''. The values of $v_0$ and $v_{90}$ can be changed
  using the following key on the \meta{angle axis}:
  \begin{key}{/tikz/data visualization/axis options/unit
      vectors=|\char`\{|\meta{unit vector 0
        degrees}|\char`\}\char`\{|\meta{unit vector 90
        degrees}|\char`\}| (initially {\char`\{(1pt,0pt)\char`\}\char`\{(0pt,1pt)\char`\}})}
    Both the \meta{unit vector 0 degrees} and the \meta{unit vector 90
      degrees} are \tikzname\ coordinates:
\begin{codeexample}[]
\tikz \datavisualization
    [new polar axes={angle axis}{radius axis},
     radius axis={unit length=1cm},
     angle axis={unit vectors={(10:1pt)}{(60:1pt)}},
     visualize as scatter]
  data [format=named] {
    angle={0,90}, radius={0.25,0.5,...,2}
  };
\end{codeexample}    
  \end{key}
\end{key}

Once created, the |angle axis| can be scaled conveniently using the
following keys:

\begin{key}{/tikz/data visualization/axis options/degrees}
  When this key is passed to the angle axis of a polar axis system, it
  sets up the scaling so that a value of |360| on this axis
  corresponds to a complete circle.
\begin{codeexample}[]
\tikz \datavisualization
    [new polar axes={angle axis}{radius axis},
     radius axis={unit length=1cm},
     angle axis={degrees},
     visualize as scatter]
  data [format=named] {
    angle={10,90}, radius={0.25,0.5,...,2}
  };
\end{codeexample}    
\end{key}

\begin{key}{/tikz/data visualization/axis options/radians}
  In contrast to |degrees|, this option sets up things so that a value
  of |2*pi| on this axis corresponds to a complete circle.
\begin{codeexample}[]
\tikz \datavisualization
    [new polar axes={angle axis}{radius axis},
     radius axis={unit length=1cm},
     angle axis={radians},
     visualize as scatter]
  data [format=named] {
    angle={0,1.5}, radius={0.25,0.5,...,2}
  };
\end{codeexample}
\end{key}



