% Copyright 2019 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,
    preamble={\usetikzlibrary{
    datavisualization.formats.functions,
    datavisualization.polar,
}},
]
\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}[preamble={\usetikzlibrary{
    datavisualization.formats.functions,
    datavisualization.polar,
}}]
\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,
    preamble={\usetikzlibrary{
    datavisualization.formats.functions,
    datavisualization.polar,
}},
]
\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,
    preamble={\usetikzlibrary{
    datavisualization.formats.functions,
    datavisualization.polar,
}},
]
\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,
    preamble={\usetikzlibrary{
    datavisualization.formats.functions,
    datavisualization.polar,
}},
]
\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,
    preamble={\usetikzlibrary{
    datavisualization.formats.functions,
    datavisualization.polar,
}},
]
\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}[preamble={\usetikzlibrary{datavisualization.polar}}]
\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}[preamble={\usetikzlibrary{datavisualization.polar}}]
\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}[preamble={\usetikzlibrary{datavisualization.polar}}]
\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}[preamble={\usetikzlibrary{datavisualization.polar}}]
\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}[preamble={\usetikzlibrary{datavisualization.polar}}]
\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}