
\section{Polar Axes}
\label{sec:polar}

{
\def\pgfplotsmanualcurlibrary{polar}
\tikzset{external/figure name/.add={}{polar_}}

\begin{pgfplotslibrary}{polar}
    A library to draw polar axes and plot types relying on polar coordinates,
    represented by angle (in degrees or, optionally, in radians) and radius.
\end{pgfplotslibrary}


\subsection{Polar Axes}

\begin{environment}{{polaraxis}}
    The |polar| library provides the |polaraxis| environment.
    Inside of such an environment, all coordinates are expected to be given in
    polar representation of the form $(\meta{angle},\meta{radius})$, i.e.\@ the
    $x$ coordinate is always the angle and the $y$ coordinate the radius:
\end{environment}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}
    \addplot coordinates {
        (0,1)
        (90,1)
        (180,1)
        (270,1)
    };
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}
    \addplot+ [domain=0:3] (360*x,x); % (angle,radius)
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}
    \addplot+ [
        mark=none,
        domain=0:720,
        samples=600,
    ]
        {sin(2*x)*cos(2*x)};
    % equivalent to (x,{sin(..)cos(..)}), i.e.
    % the expression is the RADIUS
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

Polar axes support most of the \PGFPlots{} user interface, i.e.\@
|legend entries|, any axis descriptions, |xtick|/|ytick| and so on:
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}[
    xtick={0,90,180,270},
    title=A polar axis,
]
    \addplot coordinates {(0,1) (45,1)};
        \addlegendentry{First}

    \addplot coordinates {(180,0.5) (0,0)};
        \addlegendentry{Second}
    \end{polaraxis}
\end{tikzpicture}
\end{codeexample}
%
\noindent Furthermore, you can use all of the supported input coordinate
methods (like \verbpdfref{\addplot coordinates}, \verbpdfref{\addplot table},
\verbpdfref{\addplot expression}). The only difference is that polar axes
interpret the (first two) input coordinates as polar coordinates of the form
$(\meta{angle in degrees},\meta{radius})$.

It is also possible to provide \verbpdfref{\addplot3}; in this case, the third
coordinate will be ignored (although it can be used as color data using
|point meta=z|). An example can be found below in Section~\ref{sec:polar:cart}.


\subsection{Using Radians instead of Degrees}

The initial configuration uses degrees for the angle ($x$ component of every
input coordinate). \PGFPlots{} also supports to provide the angle in radians
using the |data cs=polarrad| switch:
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}[title={Degrees and/or Radians}]
    \addplot coordinates {
        (0,1) (90,1) (180,1) (270,1)
    };
        \addlegendentry{Deg}

    \addplot+ [
        data cs=polarrad,
    ] coordinates {
        (0,1.5) (pi/2,1.5)
        (pi,1.5) (pi*3/2,1.5)
    };
        \addlegendentry{Rad}
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

The |data cs| key is described in all detail on page~\pageref{key:data:cs}; it
tells \PGFPlots{} the coordinate system of input data. \PGFPlots{} will then
take steps to automatically transform each coordinate into the required
coordinate system (in our case, this is |data cs=polar|).


\subsection{Mixing With Cartesian Coordinates}
\label{sec:polar:cart}

Similarly to the procedure described above, you can also provide Cartesian
coordinates inside of a polar axis: simply tell \PGFPlots{} that it should
automatically transform them to polar representation by means of
|data cs=cart|:
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}[title=Cartesian Input]
    \addplot+ [
        data cs=cart,
    ] coordinates {
        (1,0) (0,1) (-1,0) (0,-1)
    };
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
%
\noindent More details about the |data cs| key can be found on
page~\pageref{key:data:cs}.

This does also allow more involved visualization techniques which may operate
on Cartesian coordinates. The following example uses \verbpdfref{\addplot3} to
sample a function $f\colon \R^2 \to \R$, computes |contour| lines (with the
help of |gnuplot|) and displays the result in a |polaraxis|:
%
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}
    \addplot3 [
        contour gnuplot,
        domain=-3:3,
        data cs=cart,
    ]
        {exp(-x^2-y^2)};
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
%
\noindent What happens is that $z=\exp(-x^2-y^2)$ is sampled for $x,y \in
[-3,3]$, then contour lines are computed on $(x,y,z)$, then the resulting
triples $(x,y,z)$ are transformed to polar coordinates $(\alpha,r,z)$ (leaving
$z$ intact). Finally, the $z$ coordinate is used as |point meta| to determine
the color.

Note that \verbpdfref{\addplot3} allows to process three-dimensional input
types, but the result will always be two-dimensional (the $z$ coordinate is
ignored for point placement in |polaraxis|). However, the $z$ coordinate can be
used to determine point colors (using |point meta=z|).


\subsection{Polar Descriptions}

Polar axes support axis labels just as other plot types.\footnote{Attention:
support for polar axis labels is broken in versions before 1.13. Please upgrade
to \PGFPlots{} 1.13 and use \texttt{compat=1.13} or higher in order to use
polar axis descriptions.} In this case, |xticklabel cs| refers to a label
position for the angles ($x$-axis) and |yticklabel cs| refers to a label
position for the radius ($y$-axis).

The default axis label for the angles is placed at $45$ degrees,
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}[
    xlabel=x axis,
    ylabel=y axis,
]
    \addplot coordinates {
        (0,1) (90,1) (180,1) (270,1)
    };
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
%
and is configured as a |sloped|\index{sloped Polar labels} label using the
default configuration
%
\begin{codeexample}[code only]
    every axis x label/.style={
        at={(xticklabel cs:0.125)},
        sloped={at position=45},
        anchor=near ticklabel,
        near ticklabel at=45,
    },
    every axis y label/.style={
        at={(yticklabel cs:0.5)},
        anchor=near ticklabel,
    },
\end{codeexample}

This also allows sloped $x$ labels as in the following example.\footnote{Note
that sloped polar labels also requires \PGFPlots{} 1.13 and
\texttt{compat=1.13} or newer.}
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}[
    xlabel=x axis,
    ylabel=y axis,
    xticklabel style={sloped like x axis},
]
    \addplot coordinates {
        (0,1) (90,1) (180,1) (270,1)
    };
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}


\subsection{Special Polar Plot Types}

\begin{plottype}{polar comb}
    The |polar comb| plot handler is provided by \Tikz{}; it draws paths from
    the origin to the designated position and places |mark|s at the positions
    (similar to the |comb| plot handler). Since the paths always start at the
    origin, it is particularly suited for |polaraxis|:
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}
    \addplot+ [
        polar comb,
    ] coordinates {
        (300,1)
        (20,0.3)
        (40,0.5)
        (120,1)
        (200,0.4)
    };
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
\end{plottype}


\subsection{Partial Polar Axes}

The |polar| library also supports partial axes. If you provide |xmin|/|xmax|,
you can restrict the angles used for the axis:
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}[
    xmin=45,
    xmax=360,
]
    \addplot coordinates {
        (0,1) (90,1) (180,1) (270,1)
    };
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

Currently, the first angle must be lower than the second one. But you can
employ the periodicity to get pies as follows:
%
\message{Overfull hbox is OK}%
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{polaraxis}[xmin=90,xmax=270]
        \addplot coordinates { (0,1) (90,1) (180,1) (270,1) };
    \end{polaraxis}
\end{tikzpicture}~%
\begin{tikzpicture}
    \begin{polaraxis}[xmin=270,xmax=420]
        \addplot coordinates { (0,1) (90,1) (180,1) (270,1) };
    \end{polaraxis}
\end{tikzpicture}
\end{codeexample}
%
\noindent Similarly, an explicitly provided value for |ymin| allows to reduce
the displayed range away from $0$:
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}[
    ymin=0.3,
]
    \addplot coordinates {
        (0,1) (90,1) (180,1) (270,1)
    };
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

\noindent Modifying |xmin| and |xmax| manually can also be used to move the $y$
axis line (the line with |ytick| and |yticklabels|):
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{polaraxis}[
    xmin=45,
    xmax=405,
]
    \addplot coordinates {
        (0,1) (90,1) (180,1) (270,1)
    };
\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
}
