summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-polar.tex
blob: bbba69dee468f53449c470e28223626970240540 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
% 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}