Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-dv-polar.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Polar Axes}
12 \label{section-dv-polar}
13
14 \subsection{Overview}
15
16 \begin{tikzlibrary}{datavisualization.polar}
17 This library contains keys that allow you to create plots in a polar axis
18 system is used.
19 \end{tikzlibrary}
20
21 In a \emph{polar axis system} two attributes are visualized by displacing a
22 data point as follows: One attribute is used to compute a an angle (a
23 direction) while a second attribute is used as a radius (a distance). The angle
24 can be measured in degrees, radians, or can be scaled arbitrarily.
25 %
26 \begin{codeexample}[
27 width=8.5cm,
28 preamble={\usetikzlibrary{
29 datavisualization.formats.functions,
30 datavisualization.polar,
31 }},
32 ]
33 \tikz \datavisualization [
34 scientific polar axes={0 to pi, clean},
35 all axes=grid,
36 style sheet=vary hue,
37 legend=below
38 ]
39 [visualize as smooth line=sin,
40 sin={label in legend={text=$1+\sin \alpha$}}]
41 data [format=function] {
42 var angle : interval [0:pi];
43 func radius = sin(\value{angle}r) + 1;
44 }
45 [visualize as smooth line=cos,
46 cos={label in legend={text=$1+\cos\alpha$}}]
47 data [format=function] {
48 var angle : interval [0:pi];
49 func radius = cos(\value{angle}r) + 1;
50 };
51 \end{codeexample}
52
53 Most of the time, in order to create a polar axis system, you will just use the
54 |scientific polar axes| key, which takes a number of options that allow you to
55 configure the axis system in greater detail. This key is documented in
56 Section~\ref{section-dv-sci-polar-axes}. Internally, this key uses more low
57 level keys which are documented in the en suite sections.
58
59 It is worthwhile to note that the axes of a polar axis system are, still,
60 normal axes of the data visualization system. In particular, all the
61 configurations possible for, say, Cartesian axes also apply to the ``angle
62 axis'' and the ``radius axis'' of a polar axis system. For instance, you can
63 could make both axes logarithmic or style their ticks:
64 %
65 \begin{codeexample}[preamble={\usetikzlibrary{
66 datavisualization.formats.functions,
67 datavisualization.polar,
68 }}]
69 \tikz[baseline] \datavisualization [
70 scientific axes={clean},
71 x axis={attribute=angle, ticks={minor steps between steps=4}},
72 y axis={attribute=radius, ticks={some, style=red!80!black}},
73 all axes=grid,
74 visualize as smooth line=sin]
75 data [format=function] {
76 var t : interval [-3:3];
77 func angle = exp(\value t);
78 func radius = \value{t}*\value{t};
79 };
80 \qquad
81 \tikz[baseline] \datavisualization [
82 scientific polar axes={right half clockwise, clean},
83 angle axis={logarithmic,
84 ticks={
85 minor steps between steps=8,
86 major also at/.list={2,3,4,5,15,20}}},
87 radius axis={ticks={some, style=red!80!black}},
88 all axes=grid,
89 visualize as smooth line=sin]
90 data [format=function] {
91 var t : interval [-3:3];
92 func angle = exp(\value t);
93 func radius = \value{t}*\value{t};
94 };
95 \end{codeexample}
96
97
98 \subsection{Scientific Polar Axis System}
99 \label{section-dv-sci-polar-axes}
100
101 \begin{key}{/tikz/data visualization/scientific polar axes=\meta{options}}
102 This key installs a polar axis system that can be used in a ``scientific''
103 publication. Two axes are created called the |angle axis| and the
104 |radius axis|. Unlike ``normal'' Cartesian axes, these axes do not point in
105 a specific direction. Rather, the |radius axis| is used to map the values
106 of one attribute to a distance from the origin while the |angle axis| is
107 used to map the values of another attribute to a rotation angle.
108
109 The \meta{options} will be executed with the path prefix
110 %
111 \begin{codeexample}[code only]
112 /tikz/data visualization/scientific polar axes
113 \end{codeexample}
114 %
115 The permissible keys are documented in the later subsections of this
116 section.
117
118 Let us start with the configuration of the radius axis since it is easier.
119 Firstly, you should specify which attribute is linked to the radius. The
120 default is |radius|, but you will typically wish to change this. As with
121 any other axis, the |attribute| key is used to configure the axis, see
122 Section~\ref{section-dv-axis-attribute} for details. You can also apply all
123 other configurations to the radius axis like, say, |unit length| or
124 |length| or |style|. Note, however, that the |logarithmic| key will not
125 work with the radius axis for a |scientific polar axes| system since the
126 attribute value zero is always placed at the center -- and for a
127 logarithmic plot the value |0| cannot be mapped.
128 %
129 \begin{codeexample}[
130 width=8.8cm,
131 preamble={\usetikzlibrary{
132 datavisualization.formats.functions,
133 datavisualization.polar,
134 }},
135 ]
136 \tikz \datavisualization [
137 scientific polar axes,
138 radius axis={
139 attribute=distance,
140 ticks={step=5000},
141 padding=1.5em,
142 length=3cm,
143 grid
144 },
145 visualize as smooth line]
146 data [format=function] {
147 var angle : interval [0:100];
148 func distance = \value{angle}*\value{angle};
149 };
150 \end{codeexample}
151
152 For the |angle axis|, you can also specify an attribute using the
153 |attribute| key. However, for this axis the mapping of a value to an actual
154 angle is a complicated process involving many considerations of how the
155 polar axis system should be visualized. For this reason, there are a large
156 number of predefined such mappings documented in
157 Section~\ref{section-dv-angle-ranges}. Finally, as for a |scientific plot|,
158 you can configure where the ticks should be shown using the keys
159 |inner ticks|, |outer ticks|, and |clean|, documented below.
160 \end{key}
161
162
163 \subsubsection{Tick Placements}
164
165 \begin{key}{/tikz/data visualization/scientific polar axes/outer ticks}
166 This key, which is the default, causes ticks to be drawn ``outside'' the
167 outer ``ring'' of the polar axes:
168 %
169 \begin{codeexample}[
170 width=8.8cm,
171 preamble={\usetikzlibrary{
172 datavisualization.formats.functions,
173 datavisualization.polar,
174 }},
175 ]
176 \tikz \datavisualization [
177 scientific polar axes={outer ticks, 0 to 180},
178 visualize as smooth line]
179 data [format=function] {
180 var angle : interval [0:100];
181 func radius = \value{angle};
182 };
183 \end{codeexample}
184 %
185 \end{key}
186
187 \begin{key}{/tikz/data visualization/scientific polar axes/inner ticks}
188 This key causes the ticks to be ``turned to the inside''. I do not
189 recommend using this key.
190 %
191 \begin{codeexample}[
192 width=8.8cm,
193 preamble={\usetikzlibrary{
194 datavisualization.formats.functions,
195 datavisualization.polar,
196 }},
197 ]
198 \tikz \datavisualization [
199 scientific polar axes={inner ticks, 0 to 180},
200 visualize as smooth line]
201 data [format=function] {
202 var angle : interval [0:100];
203 func radius = \value{angle};
204 };
205 \end{codeexample}
206 %
207 \end{key}
208
209 \begin{key}{/tikz/data visualization/scientific polar axes/clean}
210 This key separates the area where the data is shown from the area where the
211 ticks are shown. Usually, this is the best choice for the tick placement
212 since it avoids a collision of data and explanations.
213 %
214 \begin{codeexample}[
215 width=8.8cm,
216 preamble={\usetikzlibrary{
217 datavisualization.formats.functions,
218 datavisualization.polar,
219 }},
220 ]
221 \tikz \datavisualization [
222 scientific polar axes={clean, 0 to 180},
223 visualize as smooth line]
224 data [format=function] {
225 var angle : interval [0:100];
226 func radius = \value{angle};
227 };
228 \end{codeexample}
229 %
230 \end{key}
231
232
233 \subsubsection{Angle Ranges}
234 \label{section-dv-angle-ranges}
235
236 Suppose you create a polar plot in which the radius values vary between, say,
237 $567$ and $1234$. Then the normal axis scaling mechanisms can be used to
238 compute a good scaling for the ``radius axis'': Place the value $1234$ at a
239 distance of , say, $5\,\mathrm{cm}$ from the origin and place the value $0$ at
240 the origin. Now, by comparison, suppose that the values of the angle axis's
241 attribute ranged between, say, $10$ and $75.7$. In this case, we may wish the
242 angles to be scaled so that the minimum value is horizontal and the maximum
243 value is vertical. But we may also wish the a value of $0$ is horizontal and a
244 value of $90$ is vertical.
245
246 Since it is unclear which interpretation is the right one, you have to use an
247 option to select which should happen. The applicable options fall into three
248 categories:
249 %
250 \begin{itemize}
251 \item Options that request the scaling to be done in such a way that the
252 attribute is interpreted as a value in degrees and such that the
253 minimum and maximum of the depicted range is a multiple of $90^\circ$.
254 For instance, the option |0 to 180| causes the angle axis to range from
255 $0^\circ$ to $180^\circ$, independently of the actual range of the
256 values.
257 \item Options that work as above, but use radians rather than degrees. An
258 example is the option |0 to pi|.
259 \item Options that map the minimum value in the data to a horizontal or
260 vertical line and the maximum value to another such line. This is
261 useful when the values neither directly correspond to degrees or
262 radians. In this case, the angle axis may also be a logarithmic axis.
263 \end{itemize}
264
265 In addition to the above categories, all of the option documented in the
266 following implicitly also select quadrants that are used to depict the data.
267 For instance, the |0 to 90| key and also the |0 to pi half| key setup the polar
268 axis system in such a way that only first (upper right) quadrant is used. No
269 check is done whether the data fill actually lie in this quadrant -- if it does
270 not, the data will ``bleed outside'' the range. Naturally, with a key like
271 |0 to 360| or |0 to 2pi| this cannot happen.
272
273 In order to save some space in this manual, in the following the different
274 possible keys are only given in a table together with a small example for each
275 key. The examples were created using the following code:
276 %
277 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
278 \tikz \datavisualization [
279 scientific polar axes={
280 clean,
281 0 to 90 % the option
282 },
283 angle axis={ticks={step=30}},
284 radius axis={length=1cm, ticks={step=1}},
285 visualize as scatter]
286 data point [angle=20, radius=0.5]
287 data point [angle=30, radius=1]
288 data point [angle=40, radius=1.5];
289 \end{codeexample}
290
291 For the options on radians, the angle values have been replaced by |0.2|,
292 |0.3|, and |0.4| and the stepping has been changed by setting |step=(pi/6)|.
293 For the quadrant options, no stepping is set at all (it is computed
294 automatically).
295
296 \def\polarexample#1#2#3#4#5{%
297 \texttt{#1}%
298 \indexkey{/tikz/data visualization/scientific polar axes/#1}&
299 \tikz [baseline]{\path(-2.25cm,0)(2.25cm,0); \datavisualization [
300 scientific polar axes={clean, #1},
301 angle axis={ticks={#2}},
302 radius axis={length=1cm, ticks={step=1}},
303 visualize as scatter
304 ]
305 data point [angle=#3, radius=0.5]
306 data point [angle=#4, radius=1]
307 data point [angle=#5, radius=1.5];
308 \path ([yshift=-1em]current bounding box.south);
309 }&
310 \tikz [baseline]{\path(-2.25cm,0)(2.25cm,0); \datavisualization [
311 scientific polar axes={outer ticks, #1},
312 angle axis={ticks={#2}},
313 radius axis={length=1cm, ticks={step=1}},
314 visualize as scatter
315 ]
316 data point [angle=#3, radius=0.5]
317 data point [angle=#4, radius=1]
318 data point [angle=#5, radius=1.5];
319 \path ([yshift=-1em]current bounding box.south);
320 }
321 \\
322 }
323
324 \begin{tabular}{lcc}
325 \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
326 \polarexample{0 to 90}{step=30}{20}{30}{40}
327 \polarexample{-90 to 0}{step=30}{20}{30}{40}
328 \polarexample{0 to 180}{step=30}{20}{30}{40}
329 \polarexample{-90 to 90}{step=30}{20}{30}{40}
330 \polarexample{0 to 360}{step=30}{20}{30}{40}
331 \polarexample{-180 to 180}{step=30}{20}{30}{40}
332 \end{tabular}
333
334 \begin{tabular}{lcc}
335 \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
336 \polarexample{0 to pi half}{step=(pi/6)}{0.2}{0.3}{0.4}
337 \polarexample{-pi half to 0}{step=(pi/6)}{0.2}{0.3}{0.4}
338 \polarexample{0 to pi}{step=(pi/6)}{0.2}{0.3}{0.4}
339 \polarexample{-pi half to pi half}{step=(pi/6)}{0.2}{0.3}{0.4}
340 \polarexample{0 to 2pi}{step=(pi/6)}{0.2}{0.3}{0.4}
341 \polarexample{-pi to pi}{step=(pi/6)}{0.2}{0.3}{0.4}
342 \end{tabular}
343
344 \begin{tabular}{lcc}
345 \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
346 \polarexample{quadrant}{}{20}{30}{40}
347 \polarexample{quadrant clockwise}{}{20}{30}{40}
348 \polarexample{fourth quadrant}{}{20}{30}{40}
349 \polarexample{fourth quadrant clockwise}{}{20}{30}{40}
350 \polarexample{upper half}{}{20}{30}{40}
351 \polarexample{upper half clockwise}{}{20}{30}{40}
352 \polarexample{lower half}{}{20}{30}{40}
353 \polarexample{lower half clockwise}{}{20}{30}{40}
354 \end{tabular}
355
356 \begin{tabular}{lcc}
357 \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
358 \polarexample{left half}{}{20}{30}{40}
359 \polarexample{left half clockwise}{}{20}{30}{40}
360 \polarexample{right half}{}{20}{30}{40}
361 \polarexample{right half clockwise}{}{20}{30}{40}
362 \end{tabular}
363
364
365 \subsection{Advanced: Creating a New Polar Axis System}
366
367 \begin{key}{/tikz/data visualization/new polar axes=|\char`\{|\meta{angle axis name}|\char`\}||\char`\{|\meta{radius axis name}|\char`\}|}
368 This key actually creates two axes, whose names are give as parameters: An
369 \emph{angle axis} and a \emph{radius axis}. These two axes work in concert
370 in the following way: Suppose a data point has two attributes called
371 |angle| and |radius| (these attribute names can be changed by changing the
372 |attribute| of the \meta{angle axis name} or the \meta{radius axis name},
373 respectively). These two attributes are then scaled as usual, resulting in
374 two ``reasonable'' values $a$ (for the angle) and $r$ (for the radius).
375 Then, the data point gets visualized (in principle, details will follow) at
376 a position on the page that is at a distance of $r$ from the origin and at
377 an angle of~$a$.
378 %
379 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
380 \tikz \datavisualization
381 [new polar axes={angle axis}{radius axis},
382 radius axis={length=2cm},
383 visualize as scatter]
384 data [format=named] {
385 angle={0,20,...,160}, radius={0,...,5}
386 };
387 \end{codeexample}
388 %
389 In detail, the \meta{angle axis} keeps track of two vectors $v_0$ and
390 $v_{90}$, each of which will usually have unit length (length |1pt|) and
391 which point in two different directions. Given a radius $r$ (measured in
392 \TeX\ |pt|s, so if the radius attribute |10pt|, then $r$ would be $10$) and
393 an angle $a$, let $s$ be the sine of $a$ and let $c$ be the cosine of $a$,
394 where $a$ is a number is degrees (so $s$ would be $1$ for $a = 90$). Then,
395 the current page position is shifted by $c \cdot r$ times $v_0$ and,
396 additionally, by $s \cdot r$ times $v_{90}$. This means that in the ``polar
397 coordinate system'' $v_0$ is the unit vector along the ``$0^\circ$-axis''
398 and $v_{90}$ is the unit vector along ``$90^\circ$-axis''. The values of
399 $v_0$ and $v_{90}$ can be changed using the following key on the
400 \meta{angle axis}:
401 %
402 \begin{key}{/tikz/data visualization/axis options/unit vectors=%
403 |\char`\{|\meta{unit vector 0 degrees}|\char`\}\char`\{|\meta{unit vector 90 degrees}|\char`\}|
404 (initially {\char`\{(1pt,0pt)\char`\}\char`\{(0pt,1pt)\char`\}})%
405 }
406 Both the \meta{unit vector 0 degrees} and the \meta{unit vector 90 degrees}
407 are \tikzname\ coordinates:
408 %
409 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
410 \tikz \datavisualization
411 [new polar axes={angle axis}{radius axis},
412 radius axis={unit length=1cm},
413 angle axis={unit vectors={(10:1pt)}{(60:1pt)}},
414 visualize as scatter]
415 data [format=named] {
416 angle={0,90}, radius={0.25,0.5,...,2}
417 };
418 \end{codeexample}
419 \end{key}
420 \end{key}
421
422 Once created, the |angle axis| can be scaled conveniently using the following
423 keys:
424
425 \begin{key}{/tikz/data visualization/axis options/degrees}
426 When this key is passed to the angle axis of a polar axis system, it sets
427 up the scaling so that a value of |360| on this axis corresponds to a
428 complete circle.
429 %
430 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
431 \tikz \datavisualization
432 [new polar axes={angle axis}{radius axis},
433 radius axis={unit length=1cm},
434 angle axis={degrees},
435 visualize as scatter]
436 data [format=named] {
437 angle={10,90}, radius={0.25,0.5,...,2}
438 };
439 \end{codeexample}
440 %
441 \end{key}
442
443 \begin{key}{/tikz/data visualization/axis options/radians}
444 In contrast to |degrees|, this option sets up things so that a value of
445 |2*pi| on this axis corresponds to a complete circle.
446 %
447 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
448 \tikz \datavisualization
449 [new polar axes={angle axis}{radius axis},
450 radius axis={unit length=1cm},
451 angle axis={radians},
452 visualize as scatter]
453 data [format=named] {
454 angle={0,1.5}, radius={0.25,0.5,...,2}
455 };
456 \end{codeexample}
457 %
458 \end{key}