☰
tikz.dev / PGFplots Manual

Manual for Package pgfplots
2D/3D Plots in LA, Version 1.18.1
http://sourceforge.net/projects/pgfplots

Related Libraries

\(\newcommand{\footnotename}{footnote}\) \(\def \LWRfootnote {1}\) \(\newcommand {\footnote }[2][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\newcommand {\footnotemark }[1][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\let \LWRorighspace \hspace \) \(\renewcommand {\hspace }{\ifstar \LWRorighspace \LWRorighspace }\) \(\newcommand {\mathnormal }[1]{{#1}}\) \(\newcommand \ensuremath [1]{#1}\) \(\newcommand {\LWRframebox }[2][]{\fbox {#2}} \newcommand {\framebox }[1][]{\LWRframebox } \) \(\newcommand {\setlength }[2]{}\) \(\newcommand {\addtolength }[2]{}\) \(\newcommand {\setcounter }[2]{}\) \(\newcommand {\addtocounter }[2]{}\) \(\newcommand {\arabic }[1]{}\) \(\newcommand {\number }[1]{}\) \(\newcommand {\noalign }[1]{\text {#1}\notag \\}\) \(\newcommand {\cline }[1]{}\) \(\newcommand {\directlua }[1]{\text {(directlua)}}\) \(\newcommand {\luatexdirectlua }[1]{\text {(directlua)}}\) \(\newcommand {\protect }{}\) \(\def \LWRabsorbnumber #1 {}\) \(\def \LWRabsorbquotenumber "#1 {}\) \(\newcommand {\LWRabsorboption }[1][]{}\) \(\newcommand {\LWRabsorbtwooptions }[1][]{\LWRabsorboption }\) \(\def \mathchar {\ifnextchar "\LWRabsorbquotenumber \LWRabsorbnumber }\) \(\def \mathcode #1={\mathchar }\) \(\let \delcode \mathcode \) \(\let \delimiter \mathchar \) \(\def \oe {\unicode {x0153}}\) \(\def \OE {\unicode {x0152}}\) \(\def \ae {\unicode {x00E6}}\) \(\def \AE {\unicode {x00C6}}\) \(\def \aa {\unicode {x00E5}}\) \(\def \AA {\unicode {x00C5}}\) \(\def \o {\unicode {x00F8}}\) \(\def \O {\unicode {x00D8}}\) \(\def \l {\unicode {x0142}}\) \(\def \L {\unicode {x0141}}\) \(\def \ss {\unicode {x00DF}}\) \(\def \SS {\unicode {x1E9E}}\) \(\def \dag {\unicode {x2020}}\) \(\def \ddag {\unicode {x2021}}\) \(\def \P {\unicode {x00B6}}\) \(\def \copyright {\unicode {x00A9}}\) \(\def \pounds {\unicode {x00A3}}\) \(\let \LWRref \ref \) \(\renewcommand {\ref }{\ifstar \LWRref \LWRref }\) \( \newcommand {\multicolumn }[3]{#3}\) \(\require {textcomp}\) \( \newcommand {\meta }[1]{\langle \textit {#1}\rangle } \) \(\newcommand {\toprule }[1][]{\hline }\) \(\let \midrule \toprule \) \(\let \bottomrule \toprule \) \(\def \LWRbooktabscmidruleparen (#1)#2{}\) \(\newcommand {\LWRbooktabscmidrulenoparen }[1]{}\) \(\newcommand {\cmidrule }[1][]{\ifnextchar (\LWRbooktabscmidruleparen \LWRbooktabscmidrulenoparen }\) \(\newcommand {\morecmidrules }{}\) \(\newcommand {\specialrule }[3]{\hline }\) \(\newcommand {\addlinespace }[1][]{}\) \(\require {colortbl}\) \(\let \LWRorigcolumncolor \columncolor \) \(\renewcommand {\columncolor }[2][named]{\LWRorigcolumncolor [#1]{#2}\LWRabsorbtwooptions }\) \(\let \LWRorigrowcolor \rowcolor \) \(\renewcommand {\rowcolor }[2][named]{\LWRorigrowcolor [#1]{#2}\LWRabsorbtwooptions }\) \(\let \LWRorigcellcolor \cellcolor \) \(\renewcommand {\cellcolor }[2][named]{\LWRorigcellcolor [#1]{#2}\LWRabsorbtwooptions }\) \(\newcommand {\intertext }[1]{\text {#1}\notag \\}\) \(\let \Hat \hat \) \(\let \Check \check \) \(\let \Tilde \tilde \) \(\let \Acute \acute \) \(\let \Grave \grave \) \(\let \Dot \dot \) \(\let \Ddot \ddot \) \(\let \Breve \breve \) \(\let \Bar \bar \) \(\let \Vec \vec \) \(\newcommand {\nicefrac }[3][]{\mathinner {{}^{#2}\!/\!_{#3}}}\)

5.10Polar Axes

  • \usepgfplotslibrary{polar} % and plain

  • \usepgfplotslibrary[polar] % Cont

  • \usetikzlibrary{pgfplots.polar} % and plain

  • \usetikzlibrary[pgfplots.polar] % Cont

    • A library to draw polar axes and plot types relying on polar coordinates, represented by angle (in degrees or, optionally, in radians) and radius.

5.10.1Polar Axes

  • \begin{polaraxis}

  • (math image)environment contents(math image)

  • \end{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:

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \begin{tikzpicture} \begin{polaraxis} \addplot coordinates { (0,1) (90,1) (180,1) (270,1) }; \end{polaraxis} \end{tikzpicture}

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \begin{tikzpicture} \begin{polaraxis} \addplot+ [domain=0:3] (360*x,x); % (angle,radius) \end{polaraxis} \end{tikzpicture}

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \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}

Polar axes support most of the pgfplots user interface, i.e. legend entries, any axis descriptions, xtick/ytick and so on:

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \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}

Furthermore, you can use all of the supported input coordinate methods (like \addplot coordinates, \addplot table, \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 \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 5.10.3.

5.10.2Using 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:

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \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}

The data cs key is described in all detail on page (page for section 4.23); 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).

5.10.3Mixing With Cartesian Coordinates

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:

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \begin{tikzpicture} \begin{polaraxis}[title=Cartesian Input] \addplot+ [ data cs=cart, ] coordinates { (1,0) (0,1) (-1,0) (0,-1) }; \end{polaraxis} \end{tikzpicture}

More details about the data cs key can be found on page (page for section 4.23).

This does also allow more involved visualization techniques which may operate on Cartesian coordinates. The following example uses \addplot3 to sample a function \(f\colon \mathbb {R}^2 \to \mathbb {R}\), computes contour lines and displays the result in a polaraxis:

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \begin{tikzpicture} \begin{polaraxis} \addplot3 [ contour lua, domain=-3:3, data cs=cart, ] {exp(-x^2-y^2)}; \end{polaraxis} \end{tikzpicture}

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 \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).

5.10.4Polar Descriptions

Polar axes support axis labels just as other plot types.96 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,

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \begin{tikzpicture} \begin{polaraxis}[ xlabel=x axis, ylabel=y axis, ] \addplot coordinates { (0,1) (90,1) (180,1) (270,1) }; \end{polaraxis} \end{tikzpicture}

and is configured as a sloped label using the default configuration

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, },

This also allows sloped \(x\) labels as in the following example.97

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \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}

96 Attention: support for polar axis labels is broken in versions before 1.13. Please upgrade to pgfplots 1.13 and use compat=1.13 or higher in order to use polar axis descriptions.

97 Note that sloped polar labels also requires pgfplots 1.13 and compat=1.13 or newer.

5.10.5Special Polar Plot Types

  • /tikz/polar comb(no value)

5.10.6Partial Polar Axes

The polar library also supports partial axes. If you provide xmin/xmax, you can restrict the angles used for the axis:

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \begin{tikzpicture} \begin{polaraxis}[ xmin=45, xmax=360, ] \addplot coordinates { (0,1) (90,1) (180,1) (270,1) }; \end{polaraxis} \end{tikzpicture}

Currently, the first angle must be lower than the second one. But you can employ the periodicity to get pies as follows:

(-tikz- diagram) (-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \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}

Similarly, an explicitly provided value for ymin allows to reduce the displayed range away from \(0\):

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \begin{tikzpicture} \begin{polaraxis}[ ymin=0.3, ] \addplot coordinates { (0,1) (90,1) (180,1) (270,1) }; \end{polaraxis} \end{tikzpicture}

Modifying xmin and xmax manually can also be used to move the \(y\) axis line (the line with ytick and yticklabels):

(-tikz- diagram)

% Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{polar} \begin{tikzpicture} \begin{polaraxis}[ xmin=45, xmax=405, ] \addplot coordinates { (0,1) (90,1) (180,1) (270,1) }; \end{polaraxis} \end{tikzpicture}