Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-dv-axes.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{Axes}
12 \label{section-dv-axes}
13
14 \subsection{Overview}
15
16 When a data point is visualized, the most obvious way of creating a visual
17 representation of its many attributes is to vary \emph{where} the data point is
18 shown. The data visualization system uses \emph{axes} to turn data point
19 attributes into positions on a page. The simplest -- and most common -- use of
20 axes is to vary the horizontal position of data points according to one
21 attribute and to vary the vertical position according to another attribute. In
22 contrast, in a polar plot one attribute dictates the distance of the data point
23 from the origin and another attribute describes the angle. From the data
24 visualization engine's point of view, in both cases two \emph{axes} are
25 involved.
26
27 In addition to specifying how the value of a certain attribute is converted
28 into a displacement on the page, an axis is also typically (but not always)
29 visualized (``drawn'') somewhere on the page. In this case, it is also
30 customary to add a visual representation on this axis of which attribute values
31 correspond to which positions on the page -- something commonly known as
32 \emph{ticks}. Similar to ticks, \emph{grid lines} also indicate positions where
33 a certain attribute has a certain value, but instead of just indicating a
34 single position on an axis, a grid line goes through all points that share an
35 attribute value.
36
37 In the following, in Section~\ref{section-dv-axes-main} we first have a look at
38 how axes can be defined and configured. As you will see, a lot of powerful
39 configurations are available, but you will rarely define and configure an axis
40 from scratch. Rather, it is more common to use a preconfigured axis instead.
41 Section~\ref{section-dv-axis-systems} introduces \emph{axis systems}, which are
42 predefined bundles of axes. You can define your own axis systems, but, again,
43 in most cases it will suffice to just use one of the many preconfigured axis
44 systems and use a few options to configure it so that it fits your need.
45 Section~\ref{section-dv-ticks-and-grids} explains how ticks and grid lines can
46 be configured. Again, several layers of options allow you to configure the way
47 ticks look and where they are placed in great detail.
48
49 This section documents the standard axis systems that are always available. For
50 polar axis systems, a special library needs to be loaded, which is documented
51 in Section~\ref{section-dv-polar}.
52
53
54 \subsection{Basic Configuration of Axes}
55 \label{section-dv-axes-main}
56
57 Inside the data visualization system, an \emph{axis} is roughly a ``systematic,
58 named way of mapping an attribute to a position on a page''. For instance, the
59 classical ``$x$-axis'' is the ``systematic way of mapping the value of the |x|
60 attribute of data points to a horizontal position on the page''. An axis is
61 \emph{not} its visual representation (such as the horizontal line with the
62 ticks drawn to represent the $x$-axis), but a visual representation can be
63 created once an axis has been defined.
64
65 The transformation of an attribute value (such as the value |1000000000| for
66 the |x| attribute) to a specific displacement of the corresponding data point
67 on the page involves two steps:
68 %
69 \begin{enumerate}
70 \item First, the range of possible values such as $[-5.6\cdot
71 10^{12},7.8\cdot 10^{12}]$ must be mapped to a ``reasonable'' interval
72 such as $[0\mathrm{cm},5\mathrm{cm}]$ or $[0^\circ,180^\circ]$.
73 \tikzname's drawing routines will only be able to cope with values from
74 such a ``reasonable'' interval.
75 \item Second, the values from the reasonable interval must be mapped to a
76 transformation.
77 \end{enumerate}
78 %
79 The first step is always the same for all axes, while the second requires
80 different strategies. For this reason, the command |new axis base| is used to
81 create a ``basic'' axis that has a ``scaling mapper'', whose job it is to map
82 the range of values of a specific attribute to a reasonable interval, but such
83 a basic axis does not define an actual transformation object. For this second
84 step, additional objects such as a |linear transformer| need to be created
85 separately.
86
87
88 \subsubsection{Usage}
89
90 To create an axis, the key |new axis base| is used first. Since this key does
91 not create a transformation object, users typically do not use this key
92 directly. Rather, it is used internally by other keys that create ``real''
93 axes. These keys are listed in Section~\ref{section-dv-reference-axis-types}.
94
95 \begin{key}{/tikz/data visualization/new axis base=\meta{axis name}}
96 This key defines a new axis for the current data visualization called
97 \meta{name}. This has two effects:
98 %
99 \begin{enumerate}
100 \item A so called \emph{scaling mapper} is created that will monitor a
101 certain attribute, rescale it, and map it to another attribute.
102 (This will be explained in detail in a moment.)
103 \item The \meta{axis name} is made available as a key that can be used
104 to configure the axis:
105 %
106 \begin{key}{/tikz/data visualization/\meta{axis name}=\meta{options}}
107 This key becomes available once |new axis base=|meta{axis name}
108 has been called. It will execute the \meta{options} with the
109 path prefix |/tikz/data visualization/axis options|.
110 %
111 \begin{codeexample}[code only]
112 [new axis base=my axis,
113 my axis={attribute=some attribute}]
114 \end{codeexample}
115 \end{key}
116 \item The \meta{axis name} becomes part of the current set of axes.
117 This set can be accessed through the following key:
118 %
119 \begin{key}{/tikz/data visualization/all axes=\meta{options}}
120 This key passes the \meta{options} to all axes inside the
121 current scope, just as if you had written \meta{some axis
122 name}|=|\meta{options} for each \meta{some axis name} in the
123 current scope, including the just-created name \meta{axis
124 name}.
125 \end{key}
126 \end{enumerate}
127 %
128 There are many \meta{options} that can be passed to a newly created axis.
129 They are explained in the rest of this section.
130 \end{key}
131
132 Note the |new axis base| does \emph{not} cause attributes to be mapped to
133 positions on a page. Rather, special keys like |new Cartesian axis| first use
134 |new axis base| to create an axis and then create an internal object that
135 performs a linear mapping of the attribute to positions along a vectors.
136
137
138 \subsubsection{The Axis Attribute}
139 \label{section-dv-axis-attribute}
140
141 The first main job of an axis is to map the different values of some attribute
142 to a reasonable interval. To achieve this, the following options are important
143 (recall that these options are passed to the key whose name is the name of the
144 axis):
145
146 \begin{key}{/tikz/data visualization/axis options/attribute=\meta{attribute}}
147 Specifies that the axis is used to transform the data points according the
148 different values of the key |/data point/|\meta{attribute}. For instance,
149 when we create a classical two-dimensional Cartesian coordinate system,
150 then there are two axes called |x axis| and |y axis| that monitor the
151 values of the attributes |/data point/x| and |/data point/y|, respectively:
152 %
153 \begin{codeexample}[code only]
154 [new axis base=x axis,
155 new axis base=y axis,
156 x axis={attribute=x},
157 y axis={attribute=y}]
158 \end{codeexample}
159 %
160 In another example, we also create an |x axis| and a |y axis|. However,
161 this time, we want to plot the values of the |/data point/time| attribute
162 on the $x$-axis and, say, the value of the |height| attribute on the
163 $y$-axis:
164 %
165 \begin{codeexample}[code only]
166 [new axis base=x axis,
167 new axis base=y axis,
168 x axis={attribute=time},
169 y axis={attribute=height}]
170 \end{codeexample}
171 %
172 During the data visualization, the \meta{attribute} will be ``monitored''
173 during the survey phase. This means that for each data point, the current
174 value of |/data point/|\meta{attribute} is examined and the minimum value
175 of all of these values as well as the maximum value is recorded internally.
176 Note that this works even when very large numbers like |100000000000| are
177 involved.
178
179 Here is a real-life example. The |scientific axes| create two axes, called
180 |x axis| and |y axis|, respectively.
181 %
182 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
183 \tikz \datavisualization [scientific axes,
184 x axis={attribute=people, length=2.5cm, ticks=few},
185 y axis={attribute=year},
186 visualize as scatter]
187 data {
188 year, people
189 1900, 100
190 1910, 200
191 1950, 200
192 1960, 250
193 2000, 150
194 };
195 \end{codeexample}
196 %
197 \end{key}
198
199
200 \subsubsection{The Axis Attribute Range Interval}
201
202 Once an attribute has been specified for an axis, the data visualization engine
203 will start monitoring this value. This means that before anything actual
204 visualization is done, a ``survey phase'' is used to determine the range of
205 values encountered for the attribute for all data points. This range of values
206 results in what is called the \emph{attribute range interval}. Its minimum is
207 the smallest value encountered in the data and its maximum is the largest
208 value.
209
210 Even though the attribute range interval is computed automatically and even
211 though you typically do not need to worry about it, there are some situations
212 where you may wish to set or enlarge the attribute range interval:
213 %
214 \begin{itemize}
215 \item You may wish to start the interval with $0$, even though the range of
216 values contains only positive values.
217 \item You may wish to slightly enlarge the interval so that, say, the
218 maximum is some ``nice'' value like |100| or |60|.
219 \end{itemize}
220
221 The following keys can be used to influence the size of the attribute range
222 interval:
223 %
224 \begin{key}{/tikz/data visualization/axis options/include value=\meta{list of value}}
225 This key ``fakes'' data points for which the attribute's values are in the
226 comma-separated \meta{list of values}. For instance, when you write
227 |include value=0|, then the attribute range interval is guaranteed to
228 contain |0| -- even if the actual data points are all positive or all
229 negative.
230 %
231 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
232 \tikz \datavisualization [scientific axes, all axes={length=3cm},
233 visualize as line]
234 data [format=function] {
235 var x : interval [5:10];
236 func y = \value x * \value x;
237 };
238 \end{codeexample}
239 %
240 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
241 \tikz \datavisualization [scientific axes, all axes={length=3cm},
242 visualize as line,
243 x axis={include value=20},
244 y axis={include value=0}]
245 data [format=function] {
246 var x : interval [5:10];
247 func y = \value x * \value x;
248 };
249 \end{codeexample}
250 %
251 \end{key}
252
253 \begin{key}{/tikz/data visualization/axis options/min value=\meta{value}}
254 This key allows you to simply set the minimum value, regardless of which
255 values are present in the actual data. This key should be used with care:
256 If there are data points for which the attribute's value is less than
257 \meta{value}, they will still be depicted, but typically outside the normal
258 visualization area. Usually, saying |include value=|\meta{value} will
259 achieve the same as saying |min value=|\meta{value}, but with less danger
260 of creating ill-formed visualizations.
261 \end{key}
262
263 \begin{key}{/tikz/data visualization/axis options/max value=\meta{value}}
264 Works like |min value|.
265 \end{key}
266
267
268 \subsubsection{Scaling: The General Mechanism}
269
270 The above key allows us specify which attribute should be ``monitored''. The
271 next key is used to specify what should happen with the observed values.
272
273 \begin{key}{/tikz/data visualization/axis options/scaling=\meta{scaling spec}}
274 The \meta{scaling spec} must have the following form:
275 %
276 \begin{quote}
277 \meta{$s_1$}| at |\meta{$t_1$}| and |\meta{$s_2$}| at |\meta{$t_2$}
278 \end{quote}
279 %
280 This means that monitored values in the interval $[s_1,s_2]$ should be
281 mapped to values the ``reasonable'' interval $[t_1,t_2]$, instead. For
282 instance, we might write
283 %
284 \begin{codeexample}[code only]
285 [y axis = {scaling = 1900 at 0cm and 2000 at 5cm}]
286 \end{codeexample}
287 %
288 in order to map dates between 1900 and 2000 to the dimension interval
289 $[0\mathrm{cm},5\mathrm{cm}]$.
290 %
291 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
292 \tikz \datavisualization
293 [scientific axes,
294 x axis={attribute=people, length=2.5cm, ticks=few},
295 y axis={attribute=year, scaling=1900 at 0cm and 2000 at 5cm},
296 visualize as scatter]
297 data {
298 year, people
299 1900, 100
300 1910, 200
301 1950, 200
302 1960, 250
303 2000, 150
304 };
305 \end{codeexample}
306 %
307 So much for the basic idea. Let us now have a detailed look at what
308 happens.
309
310
311 \medskip
312 \textbf{Number format and the min and max keywords.}
313 The source values $s_1$ and $s_2$ are typically just numbers like |3.14| or
314 |10000000000|. However, as described in
315 Section~\ref{section-dv-expressions}, you can also specify expressions like
316 |(pi/2)|, provided that (currently) you put them in parentheses.
317
318 Instead of a number, you may alternatively also use the two key words |min|
319 and |max| for $s_1$ and/or $s_2$. In this case, |min| evaluates to the
320 smallest value observed for the attribute in the data, symmetrically |max|
321 evaluates to the largest values. For instance, in the above example with
322 the |year| attribute ranging from |1900| to |2000|, the keyword |min| would
323 stand for |1900| and |max| for |2000|. Similarly, for the |people|
324 attribute |min| stands for |100| and |max| for |250|. Note that |min| and
325 |max| can only be used for $s_1$ and $s_2$, not for $t_1$ and $t_2$.
326
327 A typical use of the |min| and |max| keywords is to say
328 %
329 \begin{codeexample}[code only]
330 scaling = min at 0cm and max at 5cm
331 \end{codeexample}
332 %
333 to map the complete range of values into an interval of length of 5cm.
334
335 The interval $[s_1,s_2]$ need not contain all values that the
336 \meta{attribute} may attain. It is permissible that values are less than
337 $s_1$ or more than $s_2$.
338
339
340 \medskip
341 \textbf{Linear transformation of the attribute.}
342 As indicated earlier, the main job of an axis is to map values from a
343 ``large'' interval $[s_1,s_2]$ to a more reasonable interval $[t_1,t_2]$.
344 Suppose that for the current data point the value of the key
345 |/data point/|\meta{attribute} is the number $v$. In the simplest case, the
346 following happens: A new value $v'$ is computed so that $v' = t_1$ when
347 $v=s_1$ and $v'=t_2$ when $v=s_2$ and $v'$ is some value in between $t_1$
348 and $t_2$ then $v$ is some value in between $s_1$ and $s_2$. (Formally, in
349 this basic case $v' = t_1 + (v-s_1)\frac{t_2-t_1}{s_2-s_1}$.)
350
351 Once $v'$ has been computed, it is stored in the key
352 |/data point/|\meta{attribute}|/scaled|. Thus, the ``reasonable'' value
353 $v'$ does not replace the value of the attribute, but it is placed in a
354 different key. This means that both the original value and the more
355 ``scaled'' values are available when the data point is visualized.
356
357 As an example, suppose you have written
358 %
359 \begin{codeexample}[code only]
360 [x axis = {attribute = x, scaling=1000 at 20 and 2000 at 30}]
361 \end{codeexample}
362 %
363 Now suppose that |/data point/x| equals |1200| for a data point. Then the
364 key |/data point/x/scaled| will be set to |22| when the data point is being
365 visualized.
366
367
368 \medskip
369 \textbf{Nonlinear transformations of the attribute.}
370 By default, the transformation of $[s_1,s_2]$ to $[t_1,t_2]$ is the linear
371 transformation described above. However, in some case you may be interested
372 in a different kind of transformation: For example, in a logarithmic plot,
373 values of an attribute may range between, say, |1| and |1000| and we want
374 an axis of length |3cm|. So, we would write
375 %
376 \begin{codeexample}[code only]
377 [x axis = {attribute = x, scaling=1 at 0cm and 1000 at 3cm}]
378 \end{codeexample}
379 %
380 Indeed, |1| will now be mapped to position |0cm| and |1000| will be mapped
381 to position |3cm|. Now, the value |10| will be mapped to approximately
382 |0.03cm| because it is (almost) at one percent between |1| and |1000|.
383 However, in a logarithmic plot we actually want |10| to be mapped to the
384 position |1cm| rather than |0.03cm| and we want |100| to be mapped to the
385 position |2cm|. Such a mapping a \emph{nonlinear} mapping between the
386 intervals.
387
388 In order to achieve such a nonlinear mapping, the |function| key can be
389 used, whose syntax is described in a moment. The effect of this key is to
390 specify a function $f \colon \mathbb{R} \to \mathbb{R}$ like, say, the
391 logarithm function. When such a function is specified, the mapping of $v$
392 to $v'$ is computed as follows:
393 %
394 \begin{align*}
395 v' = t_1 + (f(s_2) - f(v))\frac{t_2 - t_1}{f(s_2)-f(s_1)}.
396 \end{align*}
397
398 The syntax of the |function| key is described next, but you typically will
399 not call this key directly. Rather, you will use a key like |logarithmic|
400 that installs appropriate code for the |function| key for you.
401 %
402 \begin{key}{/tikz/data visualization/axis options/function=\meta{code}}
403 The \meta{code} should specify a function $f$ that is applied during
404 the transformation of the interval $[s_1,s_2]$ to the interval
405 $[t_1,t_2]$ in the following way: When the \meta{code} is called, the
406 macro |\pgfvalue| will have been set to an internal representation of
407 the to-be-transformed value~$v$. You can then call the commands of the
408 math-micro-kernel of the data visualization system, see
409 Section~\ref{section-dv-math-kernel}, to compute a new value. This new
410 value must once more be stored in |\pgfvalue|.
411
412 The most common use of this key is to say
413 %
414 \begin{codeexample}[code only]
415 some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}}
416 \end{codeexample}
417 %
418 This specifies that the function $f$ is the logarithm function.
419 %
420 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
421 \tikz \datavisualization
422 [scientific axes,
423 x axis={ticks={major={at={1,10,100,1000}}},
424 scaling=1 at 0cm and 1000 at 3cm,
425 function=\pgfdvmathln{\pgfvalue}{\pgfvalue}},
426 visualize as scatter]
427 data [format=named] {
428 x={1,100,...,1000}, y={1,2,3}
429 };
430 \end{codeexample}
431 %
432 Another possibility might be to use the square-root function, instead:
433 %
434 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
435 \tikz \datavisualization
436 [scientific axes,
437 x axis={ticks=few,
438 scaling=1 at 0cm and 1000 at 3cm,
439 function=\pgfdvmathunaryop{\pgfvalue}{sqrt}{\pgfvalue}},
440 visualize as scatter]
441 data [format=named] {
442 x={0,100,...,1000}, y={1,2,3}
443 };
444 \end{codeexample}
445 \end{key}
446
447
448 \medskip
449 \textbf{Default scaling.}
450 When no scaling is specified, it may seem natural to use $[0,1]$ both as
451 the source and the target interval. However, this would not work when the
452 logarithm function is used as transformations: In this case the logarithm
453 of zero would be computed, leading to an error. Indeed, for a logarithmic
454 axis it is far more natural to use $[1,10]$ as the source interval and
455 $[0,1]$ as the target interval.
456
457 For these reasons, the default value for the |scaling| that is used when no
458 value is specified explicitly can be set using a special key:
459 %
460 \begin{key}{/tikz/data visualization/axis options/scaling/default=\meta{text}}
461 The \meta{text} is used as |scaling| whenever no other scaling is
462 specified. This key is mainly used when a transformation function is
463 set using |function|; normally, you will not use this key directly.
464 \end{key}
465 \end{key}
466
467 Most of the time, you will not use neither the |scaling| nor the |function| key
468 directly, but rather you will use one of the following predefined styles
469 documented in the following.
470
471
472 \subsubsection{Scaling: Logarithmic Axes}
473
474 \begin{key}{/tikz/data visualization/axis options/logarithmic}
475 When this key is used with an axis, three things happen:
476 %
477 \begin{enumerate}
478 \item The transformation |function| of the axis is setup to the
479 logarithm.
480 \item The strategy for automatically generating ticks and grid lines is
481 set to the |exponential strategy|, see
482 Section~\ref{section-dv-exponential-strategy} for details.
483 \item The default scaling is setup sensibly.
484 \end{enumerate}
485 %
486 All told, to turn an axis into a logarithmic axis, you just need to add
487 this option to the axis.
488 %
489 \begin{codeexample}[
490 width=8cm,
491 preamble={\usetikzlibrary{datavisualization.formats.functions}},
492 ]
493 \tikz \datavisualization [scientific axes,
494 x axis={logarithmic},
495 y axis={logarithmic},
496 visualize as line]
497 data [format=function] {
498 var x : interval [0.01:100];
499 func y = \value x * \value x;
500 };
501 \end{codeexample}
502 %
503 Note that this will work with any axis, including, say, the degrees on a
504 polar axis:
505 %
506 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
507 \tikz \datavisualization
508 [new polar axes,
509 angle axis={logarithmic, scaling=1 at 0 and 90 at 90},
510 radius axis={scaling=0 at 0cm and 100 at 3cm},
511 visualize as scatter]
512 data [format=named] {
513 angle={1,10,...,90}, radius={1,10,...,100}
514 };
515 \end{codeexample}
516 %
517 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
518 \tikz \datavisualization
519 [new polar axes,
520 angle axis={degrees},
521 radius axis={logarithmic, scaling=1 at 0cm and 100 at 3cm},
522 visualize as scatter]
523 data [format=named] {
524 angle={1,10,...,90}, radius={1,10,...,100}
525 };
526 \end{codeexample}
527 %
528 \end{key}
529
530
531 \subsubsection{Scaling: Setting the Length or Unit Length}
532
533 \begin{key}{/tikz/data visualization/axis options/length=\meta{dimension}}
534 Sets |scaling| to |min at 0cm and max at |\meta{dimension}. The effect is
535 that the range of all values of the axis's attribute will be mapped to an
536 interval of exact length \meta{dimension}.
537 %
538 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
539 \tikz \datavisualization [scientific axes,
540 x axis={length=3cm},
541 y axis={length=2cm},
542 all axes={ticks=few},
543 visualize as line]
544 data {
545 x, y
546 10, 10
547 20, 20
548 15, 30
549 13, 20
550 };
551 \end{codeexample}
552 %
553 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
554 \tikz \datavisualization [scientific axes,
555 x axis={length=3cm},
556 y axis={length=4cm},
557 all axes={ticks=few},
558 visualize as line]
559 data {
560 x, y
561 10, 10
562 20, 20
563 15, 30
564 13, 20
565 };
566 \end{codeexample}
567 %
568 \end{key}
569
570 \begin{key}{/tikz/data visualization/axis options/unit length=\meta{dimension}\opt{| per |\meta{number}| units|}}
571 Sets |scaling| to |0 at 0cm and 1 at |\meta{dimension}. In other words,
572 this key allows you to specify how long a single unit should be. This key
573 is particularly useful when you wish to ensure that the same scaling is
574 used across multiple axes or pictures.
575 %
576 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
577 \tikz \datavisualization [scientific axes,
578 all axes={ticks=few, unit length=1mm},
579 visualize as line]
580 data {
581 x, y
582 10, 10
583 40, 20
584 15, 30
585 13, 20
586 };
587 \end{codeexample}
588 %
589 The optional |per |\meta{number}| units| allows you to apply more drastic
590 scaling. Suppose that you want to plot a graph where one billion
591 corresponds to one centimeter. Then the unit length would be need to be set
592 to a hundredth of a nanometer -- much too small for \TeX\ to handle as a
593 dimension. In this case, you can write
594 |unit length=1cm per 1000000000 units|:
595 %
596 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
597 \tikz \datavisualization
598 [scientific axes,
599 x axis={unit length=1mm per 1000000000 units, ticks=few},
600 visualize as line]
601 data {
602 x, y
603 10000000000, 10
604 40000000000, 20
605 15000000000, 30
606 13000000000, 20
607 };
608 \end{codeexample}
609 %
610 \end{key}
611 %
612 \begin{key}{/tikz/data visualization/axis options/power unit length=\meta{dimension}}
613 This key is used in conjunction with the |logarithmic| setting. It cases
614 the |scaling| to be set to |1 at 0cm and 10 at |\meta{dimension}. This
615 causes a ``power unit'', that is, one power of ten in a logarithmic plot,
616 to get a length of \meta{dimension}. Again, this key is useful for ensuring
617 that the same scaling is used across multiple axes or pictures.
618 %
619 \begin{codeexample}[width=8cm,preamble={\usetikzlibrary{datavisualization}}]
620 \tikz \datavisualization
621 [scientific axes,
622 y axis={logarithmic, power unit length=1mm, grid},
623 visualize as line]
624 data {
625 x, y
626 0, 0.0000000001
627 1, 1
628 2, 100000
629 3, 100000000000
630 4, 10000000000000000000000000000000
631 5, 500000000
632 6, 5000000000000000000
633 };
634 \end{codeexample}
635 %
636 \end{key}
637
638
639 \subsubsection{Axis Label}
640
641 An axis can have a \emph{label}, which is a textual representation of the
642 attribute according to which the axis varies the position of the page. You can
643 set the attribute using the following key:
644
645 \begin{key}{/tikz/data visualization/axis options/label=\opt{|\char`\{[|\meta{options}|]|}\meta{text}\opt{|\char`\}|}
646 (default \normalfont axis's label in math mode)%
647 }
648 This key sets the label of an axis to \meta{text}. This text will typically
649 be placed inside a |node| and the \meta{options} can be used to further
650 configure the way this node is rendered. The \meta{options} will be
651 executed with the path prefix |/tikz/data visualization/|, so you need to
652 say |node style| to configure the styling of a node, see
653 Section~\ref{section-dv-style}.
654 %
655 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
656 \tikz \datavisualization [
657 scientific axes,
658 x axis = {label, length=2.5cm},
659 y axis = {label={[node style={fill=blue!20}]{$x^2$}}},
660 visualize as smooth line]
661 data [format=function] {
662 var x : interval [-3:5];
663 func y = \value x * \value x;
664 };
665 \end{codeexample}
666 %
667 \end{key}
668
669 Note that using the |label| key does not actually cause a node to be created,
670 because it is somewhat unclear where the label should be placed. Instead, the
671 |visualize label| key is used (typically internally by an axis system) to show
672 the label at some sensible position. This key is documented in
673 Section~\ref{section-dv-visualize-label}.
674
675
676 \subsubsection{Reference: Axis Types}
677 \label{section-dv-reference-axis-types}
678
679 As explained earlier, when you use |new axis base| to create a new axis, a
680 powerful scaling and attribute mapping mechanism is installed, but no mapping
681 of values to positions on the page is performed. For this, a
682 \emph{transformation object} must be installed. The following keys take care of
683 this for you. Note, however, that even these keys do not cause a visual
684 representation of the axis to be added to the visualization -- this is the job
685 of an axis system, see Section~\ref{section-dv-axis-systems}.
686
687 \begin{key}{/tikz/data visualization/new Cartesian axis=\meta{name}}
688 This key creates a new ``Cartesian'' axis, named \meta{name}. For such an
689 axis, the (scaled) values of the axis's attribute are transformed into a
690 displacement on the page along a straight line. The following key is used
691 to configure in which ``direction'' the axis points:
692 %
693 \begin{key}{/tikz/data visualization/axis options/unit vector=\meta{coordinate} (initially {(1pt,0pt)})}
694 Recall that an axis takes the values of an attribute and rescales them
695 so that they fit into a ``reasonable'' interval $[t_1,t_2]$. Suppose
696 that $v'$ is the rescaled dimension in (\TeX) points. Then when the
697 data point is visualized, the coordinate system will be shifted by $v'$
698 times the \meta{coordinate}.
699
700 As an example, suppose that you have said
701 |scaling=0 and 10pt and 50 and 20pt|. Then when the underlying
702 attribute has the value |25|, it will be mapped to a $v'$ of $15$
703 (because |25| lies in the middle of |0| and |50| and |15pt| lies in the
704 middle of |10pt| and |20pt|). This, in turn, causes the data point to
705 be displaced by $15$ times the \meta{coordinate}.
706
707 The bottom line is that the \meta{coordinate} should usually denote a
708 point that is at distance |1pt| from the origin and that points into
709 the direction of the axis.
710 %
711 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
712 \begin{tikzpicture}
713 \draw [help lines] (0,0) grid (3,2);
714
715 \datavisualization
716 [new Cartesian axis=x axis, x axis={attribute=x},
717 new Cartesian axis=y axis, y axis={attribute=y},
718 x axis={unit vector=(0:1pt)},
719 y axis={unit vector=(60:1pt)},
720 visualize as scatter]
721 data {
722 x, y
723 0, 0
724 1, 0
725 2, 0
726 1, 1
727 2, 1
728 1, 1.5
729 2, 1.5
730 };
731 \end{tikzpicture}
732 \end{codeexample}
733 \end{key}
734 \end{key}
735
736
737 \subsection{Axis Systems}
738 \label{section-dv-axis-systems}
739
740 An \emph{axis system} is, as the name suggests, a whole family of axes that act
741 in concert. For example, in the ``standard'' axis system there is a horizontal
742 axis called the $x$-axis that monitors the |x| attribute (by default, you can
743 change this easily) and a vertical axis called the $y$-axis. Furthermore, a
744 certain number of ticks are added and labels are placed at sensible positions.
745
746
747 \subsubsection{Usage}
748
749 Using an axis system is usually pretty easy: You just specify a key like
750 |scientific axes| and the necessary axes get initialized with sensible default
751 values. You can then start to modify these default values, if necessary.
752
753 First, you can (and should) set the attributes to which the difference axes
754 refer. For instance, if the |time| attribute is plotted along the $x$-axis, you
755 would write
756 %
757 \begin{codeexample}[code only]
758 x axis = {attribute = time}
759 \end{codeexample}
760
761 Second, you may wish to modify the lengths of the axes. For this, you can use
762 keys like |length| or further keys as described in the references later on.
763
764 Third, you may often wish to modify how many ticks and grid lines are shown. By
765 default, no grid lines are shown, but you can say the following in order to
766 cause grid lines to be shown:
767 %
768 \begin{codeexample}[code only]
769 all axes={grid}
770 \end{codeexample}
771 %
772 Naturally, instead of |all axes| you can also specify a single axis, causing
773 only grid lines to be shown for this axis. In order to change the number of
774 ticks that are shown, you can say
775 %
776 \begin{codeexample}[code only]
777 all axes={ticks=few}
778 \end{codeexample}
779 %
780 or also |many| instead of |few| or even |none|. Far more fine-grained control
781 over the tick placement and rendering is possible, see
782 Section~\ref{section-dv-ticks-and-grids} for details.
783
784 Fourth, consider adding units (like ``cm'' for centimeters or
785 ``$\mathrm{m}/\mathrm{s}^2$'' for acceleration) to your ticks:
786 %
787 \begin{codeexample}[code only]
788 x axis={ticks={tick unit=cm}}, y axis={ticks={tick unit=m/s^2}}
789 \end{codeexample}
790
791 Finally, consider adding labels to your axes. For this, use the label option:
792 %
793 \begin{codeexample}[code only]
794 x axes={time $t$ (ms)}, y axis={distance $d$ (mm)}
795 \end{codeexample}
796
797 Here is an example that employs most of the above features:
798 %
799 \begin{codeexample}[width=8.5cm,preamble={\usetikzlibrary{datavisualization}}]
800 \tikz \datavisualization [
801 scientific axes=clean,
802 x axis={attribute=time, ticks={tick unit=ms},
803 label={elapsed time}},
804 y axis={attribute=v, ticks={tick unit=m/s},
805 label={speed of disc}},
806 all axes=grid,
807 visualize as line]
808 data {
809 time, v
810 0, 0
811 1, 0.001
812 2, 0.002
813 3, 0.004
814 4, 0.0035
815 5, 0.0085
816 6, 0.0135
817 };
818 \end{codeexample}
819
820
821 \subsubsection{Reference: Scientific Axis Systems}
822
823 \begin{key}{/tikz/data visualization/scientific axes=\opt{\meta{options}}}
824 This key installs a two-dimensional coordinate system based on the
825 attributes |/data point/x| and |/data point/y|.
826 %
827 \begin{codeexample}[
828 width=7cm,
829 preamble={\usetikzlibrary{datavisualization.formats.functions}},
830 ]
831 \begin{tikzpicture}
832 \datavisualization [scientific axes,
833 visualize as smooth line]
834 data [format=function] {
835 var x : interval [0:100];
836 func y = sqrt(\value x);
837 };
838 \end{tikzpicture}
839 \end{codeexample}
840
841 This axis system is usually a good choice to depict ``arbitrary two
842 dimensional data''. Because the axes are automatically scaled, you do not
843 need to worry about how large or small the values will be. The name
844 |scientific axes| is intended to indicate that this axis system is often
845 used in scientific publications.
846
847 You can use the \meta{options} to fine tune the axis system. The
848 \meta{options} will be executed with the following path prefix:
849 %
850 \begin{codeexample}[code only]
851 /tikz/data visualization/scientific axes
852 \end{codeexample}
853 %
854 All keys with this prefix can thus be passed as \meta{options}.
855
856 This axis system will always distort the relative magnitudes of the units
857 on the two axis. If you wish the units on both axes to be equal, consider
858 directly specifying the unit length ``by hand'':
859 %
860 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
861 \begin{tikzpicture}
862 \datavisualization [visualize as smooth line,
863 scientific axes,
864 all axes={unit length=1cm per 10 units, ticks={few}}]
865 data [format=function] {
866 var x : interval [0:100];
867 func y = sqrt(\value x);
868 };
869 \end{tikzpicture}
870 \end{codeexample}
871
872 The |scientific axes| have the following properties:
873 %
874 \begin{itemize}
875 \item The |x|-values are surveyed and the $x$-axis is then scaled and
876 shifted so that it has the length specified by the following key.
877 %
878 \begin{key}{/tikz/data visualization/scientific axes/width=\meta{dimension} (initially 5cm)}
879 \end{key}
880 %
881 The minimum value is at the left end of the axis and at the canvas
882 origin. The maximum value is at the right end of the axis. \item
883 The |y|-values are surveyed and the $y$-axis is then scaled so that
884 is has the length specified by the following key.
885 %
886 \begin{key}{/tikz/data visualization/scientific axes/height=\meta{dimension}}
887 By default, the |height| is the golden ratio times the |width|.
888 \end{key}
889 %
890 The minimum value is at the bottom of the axis and at the canvas
891 origin. The maximum value is at the top of the axis.
892 \item Lines (forming a frame) are depicted at the minimum and maximum
893 values of the axes in 50\% black.
894 \end{itemize}
895
896 The following keys are executed by default as options: |outer ticks| and
897 |standard labels|.
898
899 You can use the following style to overrule the defaults:
900
901 \begin{stylekey}{/tikz/data visualization/every scientific axes}
902 \end{stylekey}
903 \end{key}
904
905 The keys described in the following can be used to fine-tune the way the
906 scientific axis system is rendered.
907
908 \begin{key}{/tikz/data visualization/scientific axes/outer ticks}
909 This causes the ticks to be drawn `` on the outside'' of the frame so that
910 they interfere as little as possible with the data. It is the default.
911 %
912 \begin{codeexample}[
913 width=7cm,
914 preamble={\usetikzlibrary{datavisualization.formats.functions}},
915 ]
916 \begin{tikzpicture}
917 \datavisualization [scientific axes=outer ticks,
918 visualize as smooth line]
919 data [format=function] {
920 var x : interval [-12:12];
921 func y = \value x*\value x*\value x;
922 };
923 \end{tikzpicture}
924 \end{codeexample}
925 %
926 \end{key}
927
928 \begin{key}{/tikz/data visualization/scientific axes/inner ticks}
929 This axis system works like |scientific axes|, only the ticks are on the
930 ``inside'' of the frame.
931 %
932 \begin{codeexample}[
933 width=7cm,
934 preamble={\usetikzlibrary{datavisualization.formats.functions}},
935 ]
936 \begin{tikzpicture}
937 \datavisualization [scientific axes=inner ticks,
938 visualize as smooth line]
939 data [format=function] {
940 var x : interval [-12:12];
941 func y = \value x*\value x*\value x;
942 };
943 \end{tikzpicture}
944 \end{codeexample}
945
946 This axis system is also common in publications, but the ticks tend to
947 interfere with marks if they are near to the border as can be seen in the
948 following example:
949 %
950 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
951 \begin{tikzpicture}
952 \datavisualization [scientific axes={inner ticks, width=3.2cm},
953 style sheet=cross marks,
954 visualize as scatter/.list={a,b}]
955 data [set=a] {
956 x, y
957 0, 0
958 1, 1
959 0.5, 0.5
960 2, 1
961 }
962 data [set=b] {
963 x, y
964 0.05, 0
965 1.5, 1
966 0.5, 0.75
967 2, 0.5
968 };
969 \end{tikzpicture}
970 \end{codeexample}
971 %
972 \end{key}
973
974 \begin{key}{/tikz/data visualization/scientific axes/clean}
975 The axes and the ticks are completely removed from the actual data, making
976 this axis system especially useful for scatter plots, but also for most
977 other scientific plots.
978 %
979 \begin{codeexample}[
980 width=7.5cm,
981 preamble={\usetikzlibrary{datavisualization.formats.functions}},
982 ]
983 \tikz \datavisualization [
984 scientific axes=clean,
985 visualize as smooth line]
986 data [format=function] {
987 var x : interval [-12:12];
988 func y = \value x*\value x*\value x;
989 };
990 \end{codeexample}
991
992 The distance of the axes from the actual plot is given by the padding of
993 the axes.
994 \end{key}
995
996 For all scientific axis systems, different label placement strategies can be
997 specified. They are discussed in the following.
998
999 \begin{key}{/tikz/data visualization/scientific axes/standard labels}
1000 As the name suggests, this is the standard placement strategy. The label of
1001 the $x$-axis is placed below the center of the $x$-axis, the label of the
1002 $y$-axis is rotated by $90^\circ$ and placed left of the center of the
1003 $y$-axis.
1004 %
1005 \begin{codeexample}[
1006 width=8cm,
1007 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1008 ]
1009 \tikz \datavisualization
1010 [scientific axes={clean, standard labels},
1011 visualize as smooth line,
1012 x axis={label=degree $d$,
1013 ticks={tick unit={}^\circ}},
1014 y axis={label=$\sin d$}]
1015 data [format=function] {
1016 var x : interval [-10:10] samples 10;
1017 func y = sin(\value x);
1018 };
1019 \end{codeexample}
1020 %
1021 \end{key}
1022
1023 \begin{key}{/tikz/data visualization/scientific axes/upright labels}
1024 Works like |scientific axes standard labels|, only the label of the
1025 $y$-axis is not rotated.
1026 %
1027 \begin{codeexample}[
1028 width=8cm,
1029 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1030 ]
1031 \tikz \datavisualization [
1032 scientific axes={clean, upright labels},
1033 visualize as smooth line,
1034 x axis={label=degree $d$,
1035 ticks={tick unit={}^\circ}},
1036 y axis={label=$\cos d$, include value=1,
1037 ticks={style={
1038 /pgf/number format/precision=4,
1039 /pgf/number format/fixed zerofill}}}]
1040 data [format=function] {
1041 var x : interval [-10:10] samples 10;
1042 func y = cos(\value x);
1043 };
1044 \end{codeexample}
1045 %
1046 \end{key}
1047
1048 \begin{key}{/tikz/data visualization/scientific axes/end labels}
1049 Places the labels at the end of the $x$- and the $y$-axis, similar to the
1050 axis labels of a school book axis system.
1051 %
1052 \begin{codeexample}[
1053 width=8cm,
1054 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1055 ]
1056 \tikz \datavisualization [
1057 scientific axes={clean, end labels},
1058 visualize as smooth line,
1059 x axis={label=degree $d$,
1060 ticks={tick unit={}^\circ}},
1061 y axis={label=$\tan d$}]
1062 data [format=function] {
1063 var x : interval [-80:80];
1064 func y = tan(\value x);
1065 };
1066 \end{codeexample}
1067 %
1068 \end{key}
1069
1070
1071 \subsubsection{Reference: School Book Axis Systems}
1072
1073 \begin{key}{/tikz/data visualization/school book axes=\meta{options}}
1074 This axis system is intended to ``look like'' the coordinate systems often
1075 used in school books: The axes are drawn in such a way that they intersect
1076 to origin. Furthermore, no automatic scaling is done to ensure that the
1077 lengths of units are the same in all directions.
1078
1079 This axis system must be used with care -- it is nearly always necessary to
1080 specify the desired unit length by hand using the option |unit length|. If
1081 the magnitudes of the units on the two axes differ, different unit lengths
1082 typically need to be specified for the different axes.
1083
1084 Finally, if the data is ``far removed'' from the origin, this axis system
1085 will also ``look bad''.
1086 %
1087 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1088 \begin{tikzpicture}
1089 \datavisualization [school book axes, visualize as smooth line]
1090 data [format=function] {
1091 var x : interval [-1.3:1.3];
1092 func y = \value x*\value x*\value x;
1093 };
1094 \end{tikzpicture}
1095 \end{codeexample}
1096
1097 The stepping of the ticks is one unit by default. Using keys like
1098 |ticks=some| may help to give better steppings.
1099
1100 The \meta{options} are executed with the key itself as path prefix. Thus,
1101 the following subkeys are permissible options:
1102 %
1103 \begin{key}{/tikz/data visualization/school book axes/unit=\meta{value}}
1104 Sets the scaling so that 1\,cm corresponds to \meta{value} units. At
1105 the same time, the stepping of the ticks will also be set to
1106 \meta{value}.
1107 %
1108 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1109 \begin{tikzpicture}
1110 \datavisualization [school book axes={unit=10},
1111 visualize as smooth line,
1112 clean ticks,
1113 x axis={label=$x$},
1114 y axis={label=$f(x)$}]
1115 data [format=function] {
1116 var x : interval [-20:20];
1117 func y = \value x*\value x/10;
1118 };
1119 \end{tikzpicture}
1120 \end{codeexample}
1121 \end{key}
1122
1123 \begin{key}{/tikz/data visualization/school book axes/standard labels}
1124 This key makes the label of the $x$-axis appear at the right end of
1125 this axis and it makes the label of the $y$-axis appear at the top of
1126 the $y$-axis.
1127
1128 Currently, this is the only supported placement strategy for the school
1129 book axis system.
1130 %
1131 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1132 \begin{tikzpicture}
1133 \datavisualization [school book axes={standard labels},
1134 visualize as smooth line,
1135 clean ticks,
1136 x axis={label=$x$},
1137 y axis={label=$f(x)$}]
1138 data [format=function] {
1139 var x : interval [-1:1];
1140 func y = \value x*\value x + 1;
1141 };
1142 \end{tikzpicture}
1143 \end{codeexample}
1144 \end{key}
1145 \end{key}
1146
1147
1148 \subsubsection{Advanced Reference: Underlying Cartesian Axis Systems}
1149
1150 The axis systems described in the following are typically not used directly by
1151 the user. The systems setup \emph{directions} for several axes in some sensible
1152 way, but they do not actually draw anything on these axes. For instance, the
1153 |xy Cartesian| creates two axes called |x axis| and |y axis| and makes the
1154 $x$-axis point right and the $y$-axis point up. In contrast, an axis system
1155 like |scientific axes| uses the axis system |xy Cartesian| internally and then
1156 proceeds to setup a lot of keys so that the axis lines are drawn, ticks and
1157 grid lines are drawn, and labels are placed at the correct positions.
1158
1159 \begin{key}{/tikz/data visualization/xy Cartesian}
1160 This axis system creates two axes called |x axis| and |y axis| that point
1161 right and up, respectively. By default, one unit is mapped to one cm.
1162 %
1163 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1164 \begin{tikzpicture}
1165 \datavisualization [xy Cartesian, visualize as smooth line]
1166 data [format=function] {
1167 var x : interval [-1.25:1.25];
1168 func y = \value x*\value x*\value x;
1169 };
1170 \end{tikzpicture}
1171 \end{codeexample}
1172
1173 \begin{key}{/tikz/data visualization/xy axes=\meta{options}}
1174 This key applies the \meta{options} both to the |x axis| and the
1175 |y axis|.
1176 \end{key}
1177 \end{key}
1178
1179 \begin{key}{/tikz/data visualization/xyz Cartesian cabinet}
1180 This axis system works like |xy Cartesian|, only it \emph{additionally}
1181 creates an axis called |z axis| that points left and down. For this axis,
1182 one unit corresponds to $\frac{1}{2}\sin 45^\circ\mathrm{cm}$. This is also
1183 known as a cabinet projection.
1184
1185 \begin{key}{/tikz/data visualization/xyz axes=\meta{options}}
1186 This key applies the \meta{options} both to the |x axis| and the
1187 |y axis|.
1188 \end{key}
1189 \end{key}
1190
1191 \begin{key}{/tikz/data visualization/uv Cartesian}
1192 This axis system works like |xy Cartesian|, but it introduces two axes
1193 called |u axis| and |v axis| rather than the |x axis| and the |y axis|. The
1194 idea is that in addition to a ``major'' $xy$-coordinate system this is also
1195 a ``smaller'' or ``minor'' coordinate system in use for depicting, say,
1196 small vectors with respect to this second coordinate system.
1197
1198 \begin{key}{/tikz/data visualization/uv axes=\meta{options}}
1199 Applies the \meta{options} to both the |u axis| and the |y axis|.
1200 \end{key}
1201 \end{key}
1202
1203 \begin{key}{/tikz/data visualization/uvw Cartesian cabinet}
1204 Like |xyz Cartesian cabinet|, but for the $uvw$-system.
1205
1206 \begin{key}{/tikz/data visualization/uvw axes=\meta{options}}
1207 Like |xyz axes|.
1208 \end{key}
1209 \end{key}
1210
1211
1212 \subsection{Ticks and Grids}
1213 \label{section-dv-ticks-and-grids}
1214
1215 \subsubsection{Concepts}
1216
1217 A \emph{tick} is a small visual indication on an axis of the value of the
1218 axis's attribute at the position where the tick is shown. A tick may be
1219 accompanied additionally by a textual representation, but it need not. A
1220 \emph{grid line} is similar to a tick, but it is not an indication on the axis,
1221 but rather a whole line that indicates all positions where the attribute has a
1222 certain value. Unlike ticks, grid lines (currently) are not accompanied by a
1223 textual representation.
1224
1225 Just as for axes, the data visualization system decouples the specification of
1226 which ticks are present \emph{in principle} from where they are visualized. In
1227 the following, I describe how you specify which ticks and grid lines you would
1228 like to be drawn and how they should look like (their styling). The axis system
1229 of your choice will then visualize the ticks at a sensible position for the
1230 chosen system. For details on how to change where whole axis is shown along
1231 with its ticks, see Section~\ref{section-dv-visualize-ticks}.
1232
1233 Specifying which ticks you are interested in is done as follows: First, you use
1234 |ticks| key (or, for specifying which grid lines should be present, the |grid|
1235 key). This key takes several possible options, described in detail in the
1236 following, which have different effects:
1237 %
1238 \begin{enumerate}
1239 \item Keys like |step=10| or |minor steps between steps| cause a
1240 ``semi-automatic'' computation of possible steps. Here, you explicitly
1241 specify the stepping of steps, but the first stepping and their number
1242 are computed automatically according to the range of possible values
1243 for the attribute.
1244 \item Keys like |few|, |some|, or |many| can be passed to |ticks| in order
1245 to have \tikzname\ compute good tick positions automatically. This is
1246 usually what you want to happen, which is why most axis system will
1247 implicitly say |ticks={some}|.
1248 \item Keys like |at| or |also at| provide ``absolute control'' over which
1249 ticks or grid lines are shown. For these keys, you can not only specify
1250 at what value a tick should be shown, but also its styling and also
1251 whether it is a major, minor, or subminor tick or grid line.
1252 \end{enumerate}
1253
1254 In the following, the main keys |ticks| and |grids| are documented first. Then
1255 the different kinds of ways of specifying where ticks or grid lines should be
1256 shown are explained.
1257
1258
1259 \subsubsection{The Main Options: Tick and Grid}
1260
1261 \begin{key}{/tikz/data visualization/axis options/ticks=\meta{options} (default some)}
1262 This key can be passed to an axis in order to configure which ticks are
1263 present for the axis. The possible \meta{options} include, for instance,
1264 keys like |step|, which is used to specify a stepping for the ticks, but
1265 also keys like |major| or |minor| for specifying the positions of major and
1266 minor ticks in detail. The list of possible options is described in the
1267 rest of this section.
1268
1269 Note that the |ticks| option will only configure which ticks should be
1270 shown in principle. The actual rendering is done only when the
1271 |visualize ticks| key is used, documented in
1272 Section~\ref{section-dv-visualize-ticks}, which is typically done only
1273 internally by an axis system.
1274
1275 The \meta{options} will be executed with the path prefix
1276 |/tikz/data visualization/|. When the |ticks| key is used multiple times
1277 for an axis, the \meta{options} accumulate.
1278 %
1279 \begin{codeexample}[width=6cm,preamble={\usetikzlibrary{datavisualization}}]
1280 \tikz \datavisualization [
1281 scientific axes, visualize as line,
1282 x axis={ticks={step=24, minor steps between steps=3},
1283 label=hours}]
1284 data {
1285 x, y
1286 0, 0
1287 10, 0
1288 20, 0.5
1289 30, 0.75
1290 40, 0.7
1291 50, 0.6
1292 60, 0.5
1293 70, 0.45
1294 80, 0.47
1295 };
1296 \end{codeexample}
1297 %
1298 \end{key}
1299
1300 \begin{key}{/tikz/data visualization/axis options/grid=\meta{options} (default at default ticks)}
1301 This key is similar to |ticks|, only it is used to configure where grid
1302 lines should be shown rather than ticks. In particular, the options that
1303 can be passed to the |ticks| key can also be passed to the |grid| key. Just
1304 like |ticks|, the \meta{options} only specify which grid lines should be
1305 drawn in principle; it is the job of the |visualize grid| key to actually
1306 cause any grid lines to be shown.
1307
1308 If you do not specify any \meta{options}, the default text
1309 |at default ticks| is used. This option causes grid lines to be drawn at
1310 all positions where ticks are shown by default. Since this usually exactly
1311 what you would like to happen, most of the time you just need to
1312 |all axes=grid| to cause a grid to be shown.
1313 \end{key}
1314
1315 \begin{key}{/tikz/data visualization/axis options/ticks and grid=\meta{options}}
1316 This key passes the \meta{options} to both the |ticks| key and also to the
1317 |grid| key. This is useful when you want to specify some special points
1318 explicitly where you wish a tick to be shown and also a grid line.
1319 %
1320 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1321 \tikz \datavisualization
1322 [scientific axes,
1323 visualize as smooth line,
1324 all axes= {grid, unit length=1.25cm},
1325 y axis={ ticks=few },
1326 x axis={ ticks=many, ticks and grid={ major also at={(pi/2) as $\frac{\pi}{2}$}}}]
1327 data [format=function] {
1328 var x : interval [-pi/2:3*pi] samples 50;
1329 func y = sin(\value x r);
1330 };
1331 \end{codeexample}
1332 %
1333 \end{key}
1334
1335
1336 \subsubsection{Semi-Automatic Computation of Tick and Grid Line Positions}
1337 \label{section-dv-concept-tick-placement-strategies}
1338
1339 Consider the following problem: The data visualization engine determines that
1340 in a plot the $x$-values vary between $17.4$ and $34.5$. In this case, we
1341 certainly do not want, say, ten ticks at exactly ten evenly spaced positions
1342 starting with $17.4$ and ending with $34.5$, because this would yield ticks at
1343 positions like $32.6$. Ticks should be placed at ``nice'' positions like $20$,
1344 $25$, and $30$.
1345
1346 Determining which positions are ``nice'' is somewhat difficult. In the above
1347 example, the positions $20$, $25$, and $30$ are certainly nice, but only three
1348 ticks may be a bit few of them. Better might be the tick positions $17.5$,
1349 $20$, $22.5$, through to $32.5$. However, users might prefer even numbers over
1350 fractions like $2.5$ as the stepping.
1351
1352 A \emph{tick placement strategy} is a method of automatically deciding which
1353 positions are \emph{good} for placing ticks. The data visualization engine
1354 comes with a number of predefined strategies, but you can also define new ones
1355 yourself. When the data visualization is requested to automatically determine
1356 ``good'' positions for the placement of ticks on an axis, it uses one of
1357 several possible \emph{basic strategies}. These strategies differ dramatically
1358 in which tick positions they will choose: For a range of values between $5$ and
1359 $1000$, a |linear steps| strategy might place ticks at positions $100$, $200$,
1360 through to $1000$, while an |exponential steps| strategy would prefer the tick
1361 positions $10$, $100$ and $1000$. The exact number and values of the tick
1362 positions chosen by either strategy can be fine-tuned using additional options
1363 like |step| or |about|.
1364
1365 Here is an example of the different stepping chosen when one varies the tick
1366 placement strategy:
1367 %
1368 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1369 \begin{tikzpicture}
1370 \datavisualization [scientific axes, visualize as smooth line]
1371 data [format=function] {
1372 var x : interval [1:11];
1373 func y = \value x*\value x;
1374 };
1375 \end{tikzpicture}
1376 \qquad
1377 \begin{tikzpicture}
1378 \datavisualization [scientific axes, visualize as smooth line,
1379 y axis={exponential steps},
1380 x axis={ticks={quarter about strategy}},
1381 ]
1382 data [format=function] {
1383 var x : interval [1:11];
1384 func y = \value x*\value x;
1385 };
1386 \end{tikzpicture}
1387 \end{codeexample}
1388
1389 Two strategies are always available: |linear steps|, which yields
1390 (semi)automatic ticks are evenly spaced positions, and |exponential steps|,
1391 which yields (semi)automatic steps at positions at exponentially increasing
1392 positions -- which is exactly what is needed for logarithmic plots. These
1393 strategies are details in Section~\ref{section-dv-strategies}.
1394
1395 The following options are used to configure tick placement strategies like
1396 |linear steps|. Unlike the basic choice of a placement strategy, which is an
1397 axis option, the following should be passed to the option |ticks| or |grid|
1398 only. So, you would write things like |x axis={ticks={step=2}}|, but
1399 |x axis={linear steps}|.
1400
1401 \begin{key}{/tikz/data visualization/step=\meta{value} (initially 1)}
1402 The value of this key is used to determine the spacing of the major ticks.
1403 The key is used by the |linear steps| and |exponential steps| strategies,
1404 see the explanations in Section~\ref{section-dv-strategies} for details.
1405 Basically, all ticks are placed at all multiples of \meta{value} that lie
1406 in the attribute range interval.
1407 %
1408 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1409 \tikz \datavisualization [
1410 school book axes, visualize as smooth line,
1411 y axis={ticks={step=1.25}},
1412 ]
1413 data [format=function] {
1414 var x : interval [0:3];
1415 func y = \value x*\value x/2;
1416 };
1417 \end{codeexample}
1418 %
1419 \end{key}
1420
1421 \begin{key}{/tikz/data visualization/minor steps between steps=\meta{number} (default 9)}
1422 Specifies that between any two major steps (whose positions are specified
1423 by the |step| key), there should be \meta{number} many minor steps. Note
1424 that the default of |9| is exactly the right number so that each interval
1425 between two minor steps is exactly a tenth of the size of a major step. See
1426 also Section~\ref{section-dv-strategies} for further details.
1427 %
1428 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1429 \begin{tikzpicture}
1430 \datavisualization [school book axes, visualize as smooth line,
1431 x axis={ticks={minor steps between steps=3}},
1432 y axis={ticks={minor steps between steps}},
1433 ]
1434 data [format=function] {
1435 var x : interval [-1.5:1.5];
1436 func y = \value x*\value x;
1437 };
1438 \end{tikzpicture}
1439 \end{codeexample}
1440 %
1441 \end{key}
1442
1443 \begin{key}{/tikz/data visualization/phase=\meta{value} (initially 0)}
1444 See Section~\ref{section-dv-strategies} for details on how the phase of
1445 steps influences the tick placement.
1446 \end{key}
1447
1448
1449 \subsubsection{Automatic Computation of Tick and Grid Line Positions}
1450
1451 The |step| option gives you ``total control'' over the stepping of ticks on an
1452 axis, but you often do not know the correct stepping in advance. In this case,
1453 you may prefer to have a good value for |step| being computed for you
1454 automatically.
1455
1456 Like the |step| key, these options are passed to the |ticks| option. So, for
1457 instance, you would write |x axis={ticks={about=4}}| to request about four
1458 ticks to be placed on the $x$-axis.
1459
1460 \begin{key}{/tikz/data visualization/about=\meta{number}}
1461 This key asks the data visualization to place \emph{about} \meta{number}
1462 many ticks on an axis. It is not guaranteed that \emph{exactly}
1463 \meta{number} many ticks will be used, rather the actual number will be the
1464 closest number of ticks to \meta{number} so that their stepping is still
1465 ``good''. For instance, when you say |about=10|, it may happen that exactly
1466 |10|, but perhaps even |13| ticks are actually selected, provided that
1467 these numbers of ticks lead to good stepping values like |5| or |2.5|
1468 rather than numbers like |3.4| or |7|. The method that is used to determine
1469 which steppings a deemed to be ``good'' depends on the current tick
1470 placement strategy.
1471
1472
1473 \medskip
1474 \textbf{Linear steps.}
1475 Let us start with |linear steps|: First, the difference between the maximum
1476 value $v_{\max}$ and the minimum value $v_{\min}$ on the axis is computed;
1477 let us call it $r$ for ``range''. Then, $r$ is divided by \meta{number},
1478 yielding a target stepping~$s$. If $s$ is a number like $1$ or $5$ or $10$,
1479 then this number could be used directly as the new value of |step|.
1480 However, $s$ will typically something strange like $0.023\,45$ or
1481 $345\,223.76$, so $s$ must be replaced by a better value like $0.02$ in the
1482 first case and perhaps $250\,000$ in the second case.
1483
1484 In order to determine which number is to be used, $s$ is rewritten in the
1485 form $m \cdot 10^k$ with $1 \le m < 10$ and $k \in \mathbb Z$. For
1486 instance, $0.023\,45$ would be rewritten as $2.345 \cdot 10^{-2}$ and
1487 $345\,223.76$ as $3.452\,2376 \cdot 10^5$. The next step is to replace the
1488 still not-so-good number $m$ like $2.345$ or $3.452\,237$ by a ``good''
1489 value $m'$. For this, the current value of the |about strategy| is used:
1490 %
1491 \begin{key}{/tikz/data visualization/about strategy=\meta{list}}
1492 The \meta{list} is a comma-separated sequence of pairs
1493 \meta{threshold}/\meta{value} like for instance |1.5/1.0| or |2.3/2.0|.
1494 When a good value $m'$ is sought for a given $m$, we iterate over the
1495 list and find the first pair \meta{threshold}/\meta{value} where
1496 \meta{threshold} exceeds~$m$. Then $m'$ is set to \meta{value}. For
1497 instance, if \meta{list} is |1.5/1.0,2.3/2.0,4/2.5,7/5,11/10|, which is
1498 the default, then for $m=3.141$ we would get $m'=2.5$ since $4 >
1499 3.141$, but $2.3 \le 3.141$. For $m=6.3$ we would get $m'=5$.
1500 \end{key}
1501 %
1502 Once $m'$ has been determined, the stepping is set to $s' = m' \cdot 10^k$.
1503
1504 % Define an axis type
1505 \tikzdatavisualizationset{
1506 one dimensional axis/.style={
1507 new Cartesian axis=axis,
1508 axis={
1509 attribute=main,
1510 unit vector={(0pt,1pt)},
1511 visualize axis={style=->},
1512 visualize ticks={major={tick text at low},direction axis=perpendicular},
1513 length=3cm
1514 },
1515 new Cartesian axis=perpendicular,
1516 perpendicular={
1517 attribute=perp,
1518 unit vector={(1pt,0pt)},
1519 include value=0,
1520 include value=1
1521 }
1522 }
1523 }
1524
1525 \def\showstrategy#1{
1526 % Show the effect for the different strategies
1527 \medskip
1528 \begin{tikzpicture}
1529 \foreach \max/\about [count=\c] in {10/5,20/5,30/5,40/5,50/5,60/5,70/5,80/5,90/5,100/5,100/3,100/10}
1530 {
1531 \begin{scope}[xshift=\c pt*30]
1532 \datavisualization [#1,
1533 one dimensional axis,
1534 axis={
1535 ticks={about=\about},
1536 include value=0,
1537 include value=\max
1538 }
1539 ];
1540
1541 \node at (0,-5mm) [anchor=mid] {\texttt{\about}};
1542 \end{scope}
1543 }
1544
1545 \node at (30pt,-5mm) [anchor=mid east] {\texttt{about=\ \ }};
1546 \end{tikzpicture}
1547 }
1548
1549 The net effect of all this is that for the default strategy the only valid
1550 stepping are the values $1$, $2$, $2.5$ and $5$ and every value obtainable
1551 by multiplying one of these values by a power of ten. The following example
1552 shows the effects of, first, setting |about=5| (corresponding to the |some|
1553 option) and then having axes where the minimum value is always |0| and
1554 where the maximum value ranges from |10| to |100| and, second, setting
1555 |about| to the values from |3| (corresponding to the |few| option) and to
1556 |10| (corresponding to the |many| option) while having the minimum at |0|
1557 and the maximum at |100|:
1558
1559 \showstrategy{standard about strategy}
1560
1561 \medskip
1562 \textbf{Exponential steps.}
1563 For |exponential steps| the strategy for determining a good stepping value
1564 is similar to |linear steps|, but with the following differences:
1565 %
1566 \begin{itemize}
1567 \item Naturally, since the stepping value refers to the exponent, the
1568 whole computation of a good stepping value needs to be done ``in
1569 the exponent''. Mathematically spoken, instead of considering the
1570 difference $r = v_{\max} - v_{\min}$, we consider the difference $r
1571 = \log v_{\max} - \log v_{\min}$. With this difference, we still
1572 compute $s = r / \meta{number}$ and let $s = m \cdot 10^k$ with $1
1573 \le m < 10$.
1574 \item It makes no longer sense to use values like $2.5$ for $m'$ since
1575 this would yield a fractional exponent. Indeed, the only sensible
1576 values for $m'$ seem to be $1$, $3$, $6$, and $10$. Because of
1577 this, the |about strategy| is ignored and one of these values or a
1578 multiple of one of them by a power of ten is used.
1579 \end{itemize}
1580
1581 The following example shows the chosen steppings for a maximum varying from
1582 $10^1$ to $10^5$ and from $10^{10}$ to $10^{50}$ as well as for $10^{100}$
1583 for |about=3|:
1584
1585 \medskip
1586 \begin{tikzpicture}
1587 \foreach \max [count=\c] in {1,...,5,10,20,...,50,100}
1588 {
1589 \begin{scope}[xshift=\c pt*40]
1590 \datavisualization [
1591 one dimensional axis,
1592 axis={
1593 logarithmic,
1594 ticks={about=3},
1595 include value=1,
1596 include value=1e\max
1597 }
1598 ];
1599 \end{scope}
1600 }
1601 \end{tikzpicture}
1602
1603
1604 \medskip
1605 \textbf{Alternative strategies.}
1606
1607 In addition to the standard |about strategy|, there are some additional
1608 strategies that you might wish to use instead:
1609
1610 \begin{key}{/tikz/data visualization/standard about strategy}
1611 Permissible values for $m'$ are: $1$, $2$, $2.5$, and~$5$. This
1612 strategy is the default strategy.
1613 \end{key}
1614
1615 \begin{key}{/tikz/data visualization/euro about strategy}
1616 Permissible values for $m'$ are: $1$, $2$, and~$5$. These are the same
1617 values as for the Euro coins, hence the name.
1618
1619 \showstrategy{euro about strategy}
1620 \end{key}
1621
1622 \begin{key}{/tikz/data visualization/half about strategy}
1623 Permissible values for $m'$: $1$ and $5$. Use this strategy if only
1624 powers of $10$ or halves thereof seem logical.
1625
1626 \showstrategy{half about strategy}
1627 \end{key}
1628
1629 \begin{key}{/tikz/data visualization/decimal about strategy}
1630 The only permissible value for $m'$ is $1$. This is an even more
1631 radical version of the previous strategy.
1632
1633 \showstrategy{decimal about strategy}
1634 \end{key}
1635
1636 \begin{key}{/tikz/data visualization/quarter about strategy}
1637 Permissible values for $m'$ are: $1$, $2.5$, and $5$.
1638
1639 \showstrategy{quarter about strategy}
1640 \end{key}
1641
1642 \begin{key}{/tikz/data visualization/int about strategy}
1643 Permissible values for $m'$ are: $1$, $2$, $3$, $4$, and $5$.
1644
1645 \showstrategy{int about strategy}
1646 \end{key}
1647 \end{key}
1648
1649 \begin{key}{/tikz/data visualization/many}
1650 This is an abbreviation for |about=10|.
1651 \end{key}
1652
1653 \begin{key}{/tikz/data visualization/some}
1654 This is an abbreviation for |about=5|.
1655 \end{key}
1656
1657 \begin{key}{/tikz/data visualization/few}
1658 This is an abbreviation for |about=3|.
1659 \end{key}
1660
1661 \begin{key}{/tikz/data visualization/none}
1662 Switches off the automatic step computation. Unless you use |step=|
1663 explicitly to set a stepping, no ticks will be (automatically) added.
1664 \end{key}
1665
1666
1667 \subsubsection{Manual Specification of Tick and Grid Line Positions}
1668
1669 The automatic computation of ticks and grid lines will usually do a good job,
1670 but not always. For instance, you might wish to have ticks exactly at, say,
1671 prime numbers or at Fibonacci numbers or you might wish to have an additional
1672 tick at $\pi$. In these cases you need more direct control over the
1673 specification of tick positions.
1674
1675 First, it is important to understand that the data visualization system
1676 differentiates between three kinds of ticks and grid lines: major, minor, and
1677 subminor. The major ticks are the most prominent ticks where, typically, a
1678 textual representation of the tick is shown; and the major grid lines are the
1679 thickest. The minor ticks are smaller, more numerous, and lie between major
1680 ticks. They are used, for instance, to indicate positions in the middle between
1681 major ticks or at all integer positions between major ticks. Finally, subminor
1682 ticks are even smaller than minor ticks and they lie between minor ticks.
1683
1684 Four keys are used to configure the different kinds:
1685
1686 \begin{key}{/tikz/data visualization/major=\meta{options}}
1687 The key can be passed as an option to the |ticks| key and also to the
1688 |grid| key, which in turn is passed as an option to an axis. The
1689 \meta{options} passed to |major| specify at which positions major
1690 ticks/grid lines should be shown (using the |at| option and |also at|
1691 option) and also any special styling. The different possible options are
1692 described later in this section.
1693 %
1694 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1695 \tikz \datavisualization
1696 [ school book axes, visualize as smooth line,
1697 x axis={ticks={major={at={1, 1.5, 2}}}}]
1698 data [format=function] {
1699 var x : interval [-1.25:2];
1700 func y = \value x * \value x / 2;
1701 };
1702 \end{codeexample}
1703 %
1704 \end{key}
1705
1706 \begin{key}{/tikz/data visualization/minor=\meta{options}}
1707 Like |major|, only for minor ticks/grid lines.
1708 %
1709 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1710 \tikz \datavisualization
1711 [ school book axes, visualize as smooth line,
1712 x axis={grid={minor={at={1, 1.5, 2}}}}]
1713 data [format=function] {
1714 var x : interval [-1.25:2];
1715 func y = \value x * \value x / 2;
1716 };
1717 \end{codeexample}
1718 %
1719 \end{key}
1720
1721 \begin{key}{/tikz/data visualization/subminor=\meta{options}}
1722 Like |major|, only for subminor ticks/grid lines.
1723 \end{key}
1724
1725 \begin{key}{/tikz/data visualization/common=\meta{options}}
1726 This key allows you to specify \meta{options} that apply to |major|,
1727 |minor| and |subminor| alike. It does not make sense to use |common| to
1728 specify positions (since you typically do not want both a major and a minor
1729 tick at the same position), but it can be useful to configure, say, the
1730 size of all kinds of ticks:
1731 %
1732 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1733 \tikz \datavisualization
1734 [ school book axes, visualize as smooth line,
1735 x axis={ticks={minor steps between steps, common={low=0}}} ]
1736 data [format=function] {
1737 var x : interval [-1.25:2];
1738 func y = \value x * \value x / 2;
1739 };
1740 \end{codeexample}
1741 %
1742 \end{key}
1743
1744 The following keys can now be passed to the |major|, |minor|, and |subminor|
1745 keys to specify where ticks or grid lines should be shown:
1746
1747 \begin{key}{/tikz/data visualization/at=\meta{list}}
1748 Basically, the \meta{list} must be a list of values that is processed with
1749 the |\foreach| macro (thus, it can contain ellipses to specify ranges of
1750 value). Empty values are skipped.
1751
1752 The effect of passing |at| to a |major|, |minor|, or |subminor| key is that
1753 ticks or grid lines on the axis will be placed exactly at the values in
1754 \meta{list}. Here is an example:
1755 %
1756 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1757 \tikz \datavisualization
1758 [ school book axes, visualize as smooth line,
1759 x axis={ticks={major={at={-1,0.5,(pi/2)}}}}]
1760 data [format=function] {
1761 var x : interval [-1.25:2];
1762 func y = \value x * \value x / 2;
1763 };
1764 \end{codeexample}
1765 When this option is used, any previously specified tick positions are
1766 overwritten by the values in \meta{list}. Automatically computed ticks are
1767 also overwritten. Thus, this option gives you complete control over where
1768 ticks should be placed.
1769
1770 Normally, the individual values inside the \meta{list} are just numbers
1771 that are specified in the same way as an attribute value. However, such a
1772 value may also contain the keyword |as|, which allows you so specify the
1773 styling of the tick in detail. Section~\ref{section-dv-ticks-styling}
1774 details how this works.
1775
1776 It is often a bit cumbersome that one has to write things like
1777 %
1778 \begin{codeexample}[code only]
1779 some axis = {ticks = {major = {at = {...}}}}
1780 \end{codeexample}
1781 %
1782 A slight simplification is given by the following keys, which can be passed
1783 directly to |ticks| and |grid|:
1784 %
1785 \begin{key}{/tikz/data visualization/major at=\meta{list}}
1786 A shorthand for |major={at={|\meta{list}|}}|.
1787 \end{key}
1788 %
1789 \begin{key}{/tikz/data visualization/minor at=\meta{list}}
1790 A shorthand for |major={at={|\meta{list}|}}|.
1791 \end{key}
1792 %
1793 \begin{key}{/tikz/data visualization/subminor at=\meta{list}}
1794 A shorthand for |major={at={|\meta{list}|}}|.
1795 \end{key}
1796 \end{key}
1797
1798 \begin{key}{/tikz/data visualization/also at=\meta{list}}
1799 This key is similar to |at|, but it causes ticks or grid lines to be placed
1800 at the positions in the \meta{list} \emph{in addition} to the ticks that
1801 have already been specified either directly using |at| or indirectly using
1802 keys like |step| or |some|. The effect of multiple calls of this key
1803 accumulate. However, when |at| is used after an |also at| key, the |at| key
1804 completely resets the positions where ticks or grid lines are shown.
1805 %
1806 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1807 \tikz \datavisualization
1808 [ school book axes, visualize as smooth line,
1809 x axis={grid, ticks and grid={major={also at={0.5}}}}]
1810 data [format=function] {
1811 var x : interval [-1.25:2];
1812 func y = \value x * \value x / 2;
1813 };
1814 \end{codeexample}
1815 %
1816 As for |at|, there are some shorthands available:
1817 %
1818 \begin{key}{/tikz/data visualization/major also at=\meta{list}}
1819 A shorthand for |major={also at={|\meta{list}|}}|.
1820 \end{key}
1821 %
1822 \begin{key}{/tikz/data visualization/minor also at=\meta{list}}
1823 A shorthand for |major={also at={|\meta{list}|}}|.
1824 \end{key}
1825 %
1826 \begin{key}{/tikz/data visualization/subminor also at=\meta{list}}
1827 A shorthand for |major={also at={|\meta{list}|}}|.
1828 \end{key}
1829 \end{key}
1830
1831
1832 \subsubsection{Styling Ticks and Grid Lines: Introduction}
1833 \label{section-dv-ticks-styling}
1834
1835 When a tick, a tick label, or a grid line is visualized on the page, a whole
1836 regiment of styles influences the appearance. The reason for this large number
1837 of interdependent styles is the fact that we often wish to influence only a
1838 very certain part of how a tick is rendered while leaving the other aspects
1839 untouched: Sometimes we need to modify just the font of the tick label;
1840 sometimes we wish to change the length of the tick label and the tick label
1841 position at the same time; sometimes we wish to change the color of grid line,
1842 tick, and tick label; and sometimes we wish to generally change the thickness
1843 of all ticks.
1844
1845 Let us go over the different kinds of things that can be styled (grid lines,
1846 ticks, and tick labels) one by one and let us have a look at which styles are
1847 involved. We will start with the grid lines, since they turn out to be the most
1848 simple, but first let us have a look at the general |style| and |styling|
1849 mechanism that is used in many placed in the following:
1850
1851
1852 \subsubsection{Styling Ticks and Grid Lines: The Style and Node Style Keys}
1853 \label{section-dv-style}
1854
1855 All keys of the data visualization system have the path prefix
1856 |/tikz/data visualization|. This is not only true for the main keys like
1857 |scientific axes| or |visualize as line|, but also for keys that govern how
1858 ticks are visualized. In particular, a style like |every major grid| has the
1859 path prefix |/tikz/data visualization| and all keys stored in this style are
1860 also executed with this path prefix.
1861
1862 Normally, this does not cause any trouble since most of the keys and even
1863 styles used in a data visualization are intended to configure what is shown in
1864 the visualization. However, at some point, we may also with to specify options
1865 that no longer configure the visualization in general, but specify the
1866 appearance of a line or a node on the \tikzname\ layer.
1867
1868 Two keys are used to ``communicate'' with the \tikzname\ layer:
1869
1870 \begin{key}{/tikz/data visualization/style=\meta{\tikzname\ options}}
1871 This key takes options whose path prefix is |/tikz|, not
1872 |/tikz/data visualization|. These options will be \emph{appended} to a
1873 current list of such options (thus, multiple calls of this key accumulate).
1874 The resulting list of keys is not executed immediately, but it will be
1875 executed whenever the data visualization engine calls the \tikzname\ layer
1876 to draw something (this placed will be indicated in the following).
1877 %
1878 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1879 \tikz \datavisualization
1880 [scientific axes,
1881 all axes={ticks={style=blue}, length=3cm},
1882 y axis={grid, grid={minor steps between steps, major={style=red}}},
1883 visualize as line]
1884 data [format=function] {
1885 var x : interval [5:10];
1886 func y = \value x * \value x;
1887 };
1888 \end{codeexample}
1889 %
1890 \end{key}
1891
1892 \begin{key}{/tikz/data visualization/styling}
1893 Executing this key will cause all ``accumulated'' \tikzname\ options from
1894 previous calls to the key |/tikz/data visualization/style| to be executed.
1895 Thus, you use |style| to set \tikzname\ options, but you use |styling| to
1896 actually apply these options. Usually, you do not call this option directly
1897 since this application is only done deep inside the data visualization
1898 engine.
1899 \end{key}
1900
1901 Similar to |style| (and |styling|) there also exist the |node style| (and
1902 |node styling|) key that takes \tikzname\ options that apply to nodes only --
1903 in addition to the usual |style|.
1904
1905 \begin{key}{/tikz/data visualization/node style=\meta{\tikzname\ options}}
1906 This key works like |style|, but it has an effect only on nodes that are
1907 created during a data visualization. This includes tick labels and axis
1908 labels:
1909 %
1910 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1911 \tikz \datavisualization
1912 [scientific axes,
1913 all axes={ticks={node style=red}, length=3cm},
1914 visualize as line]
1915 data [format=function] {
1916 var x : interval [5:10];
1917 func y = \value x * \value x;
1918 };
1919 \end{codeexample}
1920 %
1921 Note that in the example the ticks themselves (the little thicker lines)
1922 are not red.
1923 \end{key}
1924
1925 \begin{key}{/tikz/data visualization/node styling}
1926 Executing this key will cause all ``accumulated'' node stylings to be
1927 executed.
1928 \end{key}
1929
1930
1931 \subsubsection{Styling Ticks and Grid Lines: Styling Grid Lines}
1932 \label{section-dv-styling-grid-lines}
1933
1934 When a grid line is visualized, see
1935 Section~\ref{section-dv-visualize-gridlines} for details on when this happens,
1936 the following styles are executed in the specified order.
1937 %
1938 \begin{enumerate}
1939 \item |grid layer|.
1940 \item |every grid|.
1941 \item |every major grid| or |every minor grid| or |every subminor grid|,
1942 depending on the kind of grid line.
1943 \item locally specified options for the individual grid line, see
1944 Section~\ref{section-dv-local-styles}.
1945 \item |styling|, see Section~\ref{section-dv-style}.
1946 \end{enumerate}
1947
1948 All of these keys have the path prefix |/tikz/data visualization|. However, the
1949 options stored in the first style (|grid layer|) and also in the last
1950 (|styling|) are executed with the path prefix |/tikz| (see
1951 Section~\ref{section-dv-style}).
1952
1953 Let us now have a look at these keys in detail:
1954
1955 \begin{stylekey}{/tikz/data visualization/grid layer (initially on background layer)}
1956 \label{section-dv-grid-layer}%
1957 This key is used to specified the \emph{layer} on which grid lines should
1958 be drawn (layers are explained in Section~\ref{section-tikz-backgrounds}).
1959 By default, all grid lines are placed on the |background| layer and thus
1960 behind the data visualization. This is a sensible strategy since it avoids
1961 obscuring the more important data with the far less important grid lines.
1962 However, you can change this style to ``get the grid lines to the front'':
1963 %
1964 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
1965 \tikz \datavisualization
1966 [scientific axes,
1967 all axes={
1968 length=3cm,
1969 grid,
1970 grid={minor steps between steps}
1971 },
1972 grid layer/.style=, % none, so on top of data (bad idea)
1973 visualize as line]
1974 data [format=function] {
1975 var x : interval [5:10];
1976 func y = \value x * \value x;
1977 };
1978 \end{codeexample}
1979 %
1980 When this style is executed, the keys stored in the style will be executed
1981 with the prefix |/tikz|. Normally, you should only set this style to be
1982 empty or to |on background layer|.
1983 \end{stylekey}
1984
1985 \begin{stylekey}{/tikz/data visualization/every grid}
1986 This style provides overall configuration options for grid lines. By
1987 default, it is set to the following:
1988 %
1989 \begin{codeexample}[code only]
1990 low=min, high=max
1991 \end{codeexample}
1992 %
1993 This causes grid lines to span all possible values when they are
1994 visualized, which is usually the desired behavior (the |low| and |high|
1995 keys are explained in Section~\ref{section-dv-visualize-ticks}. You can
1996 append the |style| key to this style to configure the overall appearance of
1997 grid lines. It should be noted that settings to |style| inside |every grid|
1998 will take precedence over ones in |every major grid| and |every minor grid|.
1999 In the following example we cause all grid lines to be dashed (which is not
2000 a good idea in general since it creates a distracting background pattern).
2001 %
2002 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2003 \tikz \datavisualization
2004 [scientific axes,
2005 all axes={length=3cm, grid},
2006 every grid/.append style={style=densely dashed},
2007 visualize as line]
2008 data [format=function] {
2009 var x : interval [5:10];
2010 func y = \value x * \value x;
2011 };
2012 \end{codeexample}
2013 %
2014 \end{stylekey}
2015
2016 \begin{stylekey}{/tikz/data visualization/every major grid}
2017 This style configures the appearance of major grid lines. It does so by
2018 calling the |style| key to setup appropriate \tikzname\ options for
2019 visualizing major grid lines. The default definition of this style is:
2020 %
2021 \begin{codeexample}[code only]
2022 style = {help lines, thin, black!25}
2023 \end{codeexample}
2024 %
2025 In the following example, we use thin major blue grid lines:
2026 %
2027 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2028 \tikz \datavisualization
2029 [scientific axes,
2030 all axes={
2031 length=3cm,
2032 grid,
2033 grid={minor steps between steps}
2034 },
2035 every major grid/.style = {style={blue, thin}},
2036 visualize as line]
2037 data [format=function] {
2038 var x : interval [5:10];
2039 func y = \value x * \value x;
2040 };
2041 \end{codeexample}
2042 %
2043 As can be seen, this is not exactly visually pleasing. The default settings
2044 for the grid lines should work in most situations; you may wish to increase
2045 the blackness level, however, when you experience trouble during printing
2046 or projecting graphics.
2047 \end{stylekey}
2048
2049 \begin{stylekey}{/tikz/data visualization/every minor grid}
2050 Works like |every major grid|. The default is
2051 %
2052 \begin{codeexample}[code only]
2053 style = {help lines, black!25}
2054 \end{codeexample}
2055 %
2056 \end{stylekey}
2057
2058 \begin{stylekey}{/tikz/data visualization/every subminor grid}
2059 Works like |every major grid|. The default is
2060 %
2061 \begin{codeexample}[code only]
2062 style = {help lines, black!10}
2063 \end{codeexample}
2064 %
2065 \end{stylekey}
2066
2067
2068 \subsubsection{Styling Ticks and Grid Lines: Styling Ticks and Tick Labels}
2069 \label{section-dv-styling-ticks}
2070
2071 Styling ticks and tick labels is somewhat similar to styling grid lines. Let us
2072 start with the tick \emph{mark}, that is, the small line that represents the
2073 tick. When this mark is drawn, the following styles are applied:
2074 %
2075 \begin{enumerate}
2076 \item |every ticks|.
2077 \item |every major ticks| or |every minor ticks| or |every subminor ticks|,
2078 depending on the kind of ticks to be visualized.
2079 \item locally specified options for the individual tick, see
2080 Section~\ref{section-dv-local-styles}.
2081 \item |tick layer|
2082 \item |every odd tick| or |every even tick|, see
2083 Section~\ref{section-dv-stacking}.
2084 \item |draw|
2085 \item |styling|, see Section~\ref{section-dv-style}.
2086 \end{enumerate}
2087
2088 For the tick label node (the node containing the textual representation of the
2089 attribute's value at the tick position), the following styles are applied:
2090 %
2091 \begin{enumerate}
2092 \item |every ticks|.
2093 \item |every major ticks| or |every minor ticks| or |every subminor ticks|,
2094 depending on the kind of ticks to be visualized.
2095 \item locally specified options for the individual tick, see
2096 Section~\ref{section-dv-local-styles}.
2097 \item |tick node layer|
2098 \item |every odd tick| or |every even tick|, see
2099 Section~\ref{section-dv-stacking}.
2100 \item |styling|, see Section~\ref{section-dv-style}.
2101 \item |node styling|, see Section~\ref{section-dv-style}.
2102 \end{enumerate}
2103
2104 \begin{stylekey}{/tikz/data visualization/every ticks}
2105 This style allows you to configure the appearance of ticks using the
2106 |style| and |node style| key. Here is (roughly) the default definition of
2107 this style:
2108 %
2109 \begin{codeexample}[code only]
2110 node style={
2111 font=\footnotesize,
2112 inner sep=1pt,
2113 outer sep=.1666em,
2114 rounded corners=1.5pt
2115 }
2116 \end{codeexample}
2117 %
2118 \end{stylekey}
2119
2120 \begin{stylekey}{/tikz/data visualization/every major ticks}
2121 The default is
2122 %
2123 \begin{codeexample}[code only]
2124 style={line cap=round}, tick length=2pt
2125 \end{codeexample}
2126 %
2127 \end{stylekey}
2128
2129 \begin{stylekey}{/tikz/data visualization/every minor ticks}
2130 The default is
2131 %
2132 \begin{codeexample}[code only]
2133 style={help lines,thin, line cap=round}, tick length=1.4pt
2134 \end{codeexample}
2135 %
2136 \end{stylekey}
2137
2138 \begin{stylekey}{/tikz/data visualization/every subminor ticks}
2139 The default is
2140 %
2141 \begin{codeexample}[code only]
2142 style={help lines, line cap=round}, tick length=0.8pt
2143 \end{codeexample}
2144 %
2145 \end{stylekey}
2146
2147 \begin{stylekey}{/tikz/data visualization/tick layer (initially on background layer)}
2148 Like |grid layer|, this key specifies on which layer the ticks should be
2149 placed.
2150 \end{stylekey}
2151
2152 \begin{stylekey}{/tikz/data visualization/tick node layer (initially \normalfont empty)}
2153 Like |tick layer|, but now for the nodes. By default, tick nodes are placed
2154 on the main layer and thus on top of the data in case that the tick nodes
2155 are inside the data.
2156 \end{stylekey}
2157
2158
2159 \subsubsection{Styling Ticks and Grid Lines: Exceptional Ticks}
2160
2161 You may sometimes wish to style a few ticks differently from the other ticks.
2162 For instance, in the axis system |school book axes| there should be a tick
2163 label at the |0| position only on one axis and then this label should be offset
2164 a bit. In many cases this is easy to achieve: When you add a tick ``by hand''
2165 using the |at| or |also at| option, you can add any special options in square
2166 brackets.
2167
2168 However, in some situations the special tick position has been computed
2169 automatically for you, for instance by the |step| key or by saying |tick=some|.
2170 In this case, adding a tick mark with the desired options using |also at| would
2171 cause the tick mark with the correct options to be shown in addition to the
2172 tick mark with the wrong options. In cases like this one, the following option
2173 may be helpful:
2174
2175 \begin{key}{/tikz/data visualization/options at=\meta{value} |as [|\meta{options}|]|}
2176 This key causes the \meta{options} to be executed for any tick mark(s) at
2177 \meta{value} in addition to any options given already for this position:
2178 %
2179 \begin{codeexample}[
2180 width=7cm,
2181 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2182 ]
2183 \tikz \datavisualization [
2184 scientific axes,
2185 visualize as smooth line,
2186 x axis={ticks={major={
2187 options at = 3 as [no tick text],
2188 also at = (pi) as
2189 [{tick text padding=1ex}] $\pi$}}}]
2190 data [format=function] {
2191 var x : interval[0:2*pi];
2192 func y = sin(\value x r);
2193 };
2194 \end{codeexample}
2195 %
2196 \end{key}
2197
2198 \begin{key}{/tikz/data visualization/no tick text at=\meta{value}}
2199 Shorthand for |options at=|\meta{value}| as [no tick text]|.
2200 \end{key}
2201
2202
2203 \subsubsection{Styling Ticks and Grid Lines: Styling and Typesetting a Value}
2204 \label{section-dv-local-styles}
2205 \label{section-dv-tick-labels}
2206
2207 The \todosp{why 2 labels?} |at| and |also at| key allow you to provide a
2208 comma-separated \meta{list} of \meta{value}s where ticks or grid lines should
2209 be placed. In the simplest case, the \meta{value} is simply a number. However,
2210 the general syntax allows three different kinds of \meta{value}s:
2211 %
2212 \begin{enumerate}
2213 \item \meta{value}
2214 \item \meta{value} |as| |[|\meta{local options}|]|
2215 \item \meta{value} |as| \opt{|[|\meta{local options}|]|} \meta{text}
2216 \end{enumerate}
2217
2218 In the first case, the \meta{value} is just a number that is interpreted like
2219 any other attribute value.
2220
2221 In the second case, where the keyword |as| is present, followed by some option
2222 in square brackets, but nothing following the closing square bracket, when the
2223 tick or grid line at position \meta{value} is shown, the \meta{local options}
2224 are executed first. These can use the |style| key or the |node style| key to
2225 configure the appearance of this single tick or grid line. You can also use
2226 keys like |low| or |high| to influence how large the grid lines or the ticks
2227 are or keys like |tick text at low| to explicitly hide or show a tick label.
2228
2229 In the third case, which is only important for |ticks| and not for |grid|, the
2230 same happens as in the second case, but the text that is shown as tick label is
2231 \meta{text} rather than the automatically generated tick label. This automatic
2232 generation of tick labels is explained in the following.
2233 %
2234 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2235 \tikz \datavisualization
2236 [scientific axes=clean,
2237 x axis={length=2.5cm, ticks={major at={
2238 5,
2239 6 as [style=red],
2240 7 as [{style=blue, low=-1em}],
2241 8 as [style=green] $2^3$,
2242 10 as ten
2243 }}},
2244 visualize as line]
2245 data [format=function] {
2246 var x : interval [5:10];
2247 func y = \value x * \value x;
2248 };
2249 \end{codeexample}
2250
2251 A value like ``2'' or ``17'' could just be used as \meta{text} to be displayed
2252 in the node of a tick label. However, things are more difficult when the
2253 to-be-shown value is $0.0000000015$, because we then would typically (but not
2254 always) prefer something like $1.5 \cdot 10^{-9}$ to be shown. Also, we might
2255 wish a unit to be added like $23\mathrm{m}/\mathrm{s}$. Finally, we might wish
2256 a number like $3.141$ to be replaced by $\pi$. For these reasons, the data
2257 visualization system does not simply put the to-be-shown value in a node as
2258 plain text. Instead, the number is passed to a \emph{typesetter} whose job it
2259 is to typeset this number nicely using \TeX's typesetting capabilities. The
2260 only exception is, as indicated above, the third syntax version of the |at| and
2261 |also at| keys, where \meta{text} is placed in the tick label's node,
2262 regardless of what the typesetting would usually do.
2263
2264 The text produced by the automatic typesetting is computed as follows:
2265 %
2266 \begin{enumerate}
2267 \item The current contents of the key |tick prefix| is put into the node.
2268 \item This is followed by a call of the key |tick typesetter| which gets
2269 the \meta{value} of the tick as its argument in scientific notation.
2270 \item This is followed by the contents of the key |tick suffix|.
2271 \end{enumerate}
2272
2273 Let us have a look at these keys in detail:
2274
2275 \begin{key}{/tikz/data visualization/tick prefix=\meta{text} (initially \normalfont empty)}
2276 The \meta{text} will be put in front of every typeset tick:
2277 %
2278 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2279 \tikz \datavisualization
2280 [scientific axes, all axes={ticks=few, length=2.5cm},
2281 x axis={ticks={tick prefix=$\langle$, tick suffix=$]$}},
2282 visualize as line]
2283 data [format=function] {
2284 var x : interval [5:10];
2285 func y = \value x * \value x;
2286 };
2287 \end{codeexample}
2288 %
2289 \end{key}
2290
2291 \begin{key}{/tikz/data visualization/tick suffix=\meta{text} (initially \normalfont empty)}
2292 Works like |tick prefix|. This key is especially useful for adding units
2293 like ``cm'' or ``$\mathrm m/\mathrm s$'' to every tick label. For this
2294 reason, there is a (near) alias that is easier to memorize:
2295 %
2296 \begin{key}{/tikz/data visualization/tick unit=\meta{roman math text}}
2297 A shorthand for |tick suffix={$\,\rm|\meta{roman math text}|$}|:
2298 %
2299 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2300 \tikz \datavisualization
2301 [scientific axes, all axes={length=3cm},
2302 x axis={ticks={tick unit=s}},
2303 y axis={ticks={tick unit=m/s^2}},
2304 visualize as line]
2305 data [format=function] {
2306 var x : interval [5:10];
2307 func y = \value x * \value x;
2308 };
2309 \end{codeexample}
2310 \end{key}
2311 \end{key}
2312
2313 \begin{key}{/tikz/data visualization/tick typesetter=\meta{value}}
2314 The key gets called for each number that should be typeset. The argument
2315 \meta{value} will be in scientific notation (like |1.0e1| for $10$). By
2316 default, this key applies |\pgfmathprintnumber| to its argument. This
2317 command is a powerful number printer whose configuration is documented in
2318 Section~\ref{pgfmath-numberprinting}.
2319
2320 You are invited to code underlying this key so that a different typesetting
2321 mechanism is used. Here is a (not quite finished) example that shows how,
2322 say, numbers could be printed in terms of multiples of $\pi$:
2323 %
2324 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2325 \def\mytypesetter#1{%
2326 \pgfmathparse{#1/pi}%
2327 \pgfmathprintnumber{\pgfmathresult}$\pi$%
2328 }
2329 \tikz \datavisualization
2330 [school book axes, all axes={unit length=1.25cm},
2331 x axis={ticks={step=(0.5*pi), tick typesetter/.code=\mytypesetter{##1}}},
2332 y axis={include value={-1,1}},
2333 visualize as smooth line]
2334 data [format=function] {
2335 var x : interval [0.5:7];
2336 func y = sin(\value x r);
2337 };
2338 \end{codeexample}
2339 %
2340 \end{key}
2341
2342
2343 \subsubsection{Stacked Ticks}
2344 \label{section-dv-stacking}
2345
2346 Sometimes, the text of tick labels are so long or so numerous that the text of
2347 adjacent tick labels overlap (or have too little padding):
2348 %
2349 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2350 \tikz \datavisualization [scientific axes,
2351 all axes={length=2.5cm},
2352 visualize as smooth line]
2353 data [format=function] {
2354 var y : interval[-100:100];
2355 func x = \value y*\value y;
2356 };
2357 \end{codeexample}
2358 %
2359 There are two ways to address this problem:
2360 %
2361 \begin{itemize}
2362 \item One can rotate the labels on horizontal axes:
2363 %
2364 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2365 \tikz \datavisualization [scientific axes,
2366 all axes={length=2.5cm},
2367 x axis={ticks={node style={rotate=90, anchor=east}}},
2368 visualize as smooth line]
2369 data [format=function] {
2370 var y : interval[-100:100];
2371 func x = \value y*\value y;
2372 };
2373 \end{codeexample}
2374 %
2375 This is often a good solution, but may be hard to read. Also consider
2376 rotating labels only by $45^\circ$ or $30^\circ$.
2377 \item One can specify different shifts of the nodes for the different
2378 ticks, whereby the ticks text no longer overlap.
2379 %
2380 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2381 \tikz \datavisualization [scientific axes,
2382 all axes={length=2.5cm},
2383 x axis={ticks={major at={0,4000,8000,
2384 2000 as [node style={yshift=-1em}],
2385 6000 as [node style={yshift=-1em}],
2386 10000 as [node style={yshift=-1em}]}}},
2387 visualize as smooth line]
2388 data [format=function] {
2389 var y : interval[-100:100];
2390 func x = \value y*\value y;
2391 };
2392 \end{codeexample}
2393 %
2394 However, specifying shifts ``by hand'' in the above way is not always
2395 an option, especially when the tick positions should be computed
2396 automatically. Instead, the |stack| option can be used, which is much
2397 easier to use and gives better results:
2398 %
2399 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2400 \tikz \datavisualization [scientific axes,
2401 all axes={length=2.5cm}, x axis={ticks=stack},
2402 visualize as smooth line]
2403 data [format=function] {
2404 var y : interval[-100:100];
2405 func x = \value y*\value y;
2406 };
2407 \end{codeexample}
2408 %
2409 \end{itemize}
2410
2411 The |stack| option is actually just a style that gives you access to the
2412 general even/odd mechanism for ticks with labels. Whenever a tick mark is
2413 created where a tick label is also to be drawn, two special things happen:
2414 %
2415 \begin{enumerate}
2416 \item For every odd tick mark, the |every odd tick| style is executed, for
2417 every even tick mark the |every even tick|. Here, ``odd'' and ``even''
2418 are with respect to the order in which the ticks have been added to the
2419 list of |at| positions for each major, minor, or subminor tick list,
2420 not with respect to the order in which they will appear on the axis.
2421 Thus, when you write
2422 %
2423 \begin{codeexample}[code only]
2424 ticks={major at={1,2,3,4}, major at={0,-1,-2}, minor at={9,8,7}}
2425 \end{codeexample}
2426 %
2427 then for |1|, |3|, |0|, and |-2| as well as |9| and |7| the key
2428 |every odd tick| will be executed, while |every even tick| will be
2429 executed for positions |2|, |4|, |-1|, and also |8|.
2430 \item When a tick node label is shown at the |low| position of the tick
2431 mark, the dimension stored in the key |tick text low even padding| is
2432 added to the |low| value. Provided that this padding is not zero (which
2433 is the default), the length of the even tick marks will be increased
2434 and the tick label node will be placed at a greater distance from the
2435 axis.
2436
2437 Similar keys exist for padding ticks with labels at high positions and
2438 also at even positions.
2439 \end{enumerate}
2440
2441 \begin{key}{/tikz/data visualization/tick text low even padding=\meta{dimension} (initially 0pt)}
2442 When a tick label is shown at the low position of an even tick, the
2443 \meta{distance} is added to the |low| value, see also
2444 Section~\ref{section-dv-visualize-ticks}.
2445 %
2446 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2447 \tikz \datavisualization [scientific axes,
2448 all axes={length=2.5cm},
2449 x axis={ticks={tick text low even padding=-1em}},
2450 visualize as smooth line]
2451 data [format=function] {
2452 var y : interval[-100:100];
2453 func x = \value y*\value y;
2454 };
2455 \end{codeexample}
2456 %
2457 Note that \meta{dimension} should usually be non-positive.
2458 \end{key}
2459
2460 The following keys work similarly:
2461 %
2462 \begin{key}{/tikz/data visualization/tick text low odd padding=\meta{dimension} (initially 0pt)}
2463 \end{key}
2464 %
2465 \begin{key}{/tikz/data visualization/tick text high even padding=\meta{dimension} (initially 0pt)}
2466 \end{key}
2467 %
2468 \begin{key}{/tikz/data visualization/tick text high odd padding=\meta{dimension} (initially 0pt)}
2469 \end{key}
2470
2471 \begin{key}{/tikz/data visualization/tick text odd padding=\meta{dimension}}
2472 A shorthand for setting |tick text odd low padding| and
2473 |tick text odd high padding| at the same time.
2474 \end{key}
2475
2476 \begin{key}{/tikz/data visualization/tick text even padding=\meta{dimension}}
2477 A shorthand for setting |tick text even low padding| and
2478 |tick text even high padding| at the same time.
2479 \end{key}
2480
2481 \begin{key}{/tikz/data visualization/tick text padding=\meta{dimension}}
2482 Sets all text paddings to \meta{dimension}.
2483 \end{key}
2484
2485 \begin{key}{/tikz/data visualization/stack=\meta{dimension} (default 1em)}
2486 Shorthand for |tick text even padding=|\meta{dimension}.
2487 %
2488 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2489 \tikz \datavisualization [scientific axes,
2490 all axes={length=2.5cm},
2491 x axis={ticks={stack=1.5em}},
2492 visualize as smooth line]
2493 data [format=function] {
2494 var y : interval[-100:100];
2495 func x = \value y*\value y;
2496 };
2497 \end{codeexample}
2498 %
2499 \end{key}
2500
2501 \begin{key}{/tikz/data visualization/stack'=\meta{dimension}}
2502 Shorthand for |tick text odd padding=|\meta{dimension}. The difference to
2503 |stack| is that the set of value that are ``lowered'' is exactly exchanged
2504 with the set of value ``lowered'' by |stack|.
2505 %
2506 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
2507 \tikz \datavisualization [scientific axes,
2508 all axes={length=2.5cm},
2509 x axis={ticks=stack'},
2510 visualize as smooth line]
2511 data [format=function] {
2512 var y : interval[-100:100];
2513 func x = \value y*\value y;
2514 };
2515 \end{codeexample}
2516 %
2517 \end{key}
2518
2519 Note that the above keys have an effect on all tick labels of an axis, also on
2520 special ticks that you may have added using the |also at| key. When using the
2521 |stack| key, you should specify a |tick text padding| explicitly for such keys:
2522 %
2523 \begin{codeexample}[
2524 width=7cm,
2525 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2526 ]
2527 \tikz \datavisualization
2528 [scientific axes,
2529 x axis={ticks={stack, many, major also at=
2530 {(pi) as [{tick text padding=2.5em}] $\pi$}}},
2531 visualize as smooth line]
2532 data [format=function] {
2533 var x : interval[0:(2*pi)];
2534 func y = sin(\value x r);
2535 };
2536 \end{codeexample}
2537
2538
2539 \subsubsection{Reference: Basic Strategies}
2540 \label{section-dv-strategies}
2541
2542 \begin{key}{/tikz/data visualization/axis options/linear steps}
2543 This strategy places ticks at positions that are evenly spaced by the
2544 current value of |step|.
2545
2546 In detail, the following happens: Let $a$ be the minimum value of the data
2547 values along the axis and let $b$ be the maximum. Let the current
2548 \emph{stepping} be $s$ (the stepping is set using the |step| option, see
2549 below) and let the current \emph{phasing} be $p$ (set using the |phase|)
2550 option. Then ticks are placed all positions $i\cdot s + p$ that lie in the
2551 interval $[a,b]$, where $i$ ranges over all integers.
2552
2553 The tick positions computed in the way described above are \emph{major}
2554 step positions. In addition to these, if the key
2555 |minor steps between steps| is set to some number $n$, then $n$ many minor
2556 ticks are introduced between each two major ticks (and also before and
2557 after the last major tick, provided the values still lie in the interval
2558 $[a,b]$). Note that is $n$ is $1$, then one minor tick will be added in the
2559 middle between any two major ticks. Use a value of $9$ (not $10$) to
2560 partition the interval between two major ticks into ten equally sized minor
2561 intervals.
2562 %
2563 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
2564 \begin{tikzpicture}
2565 \datavisualization
2566 [scientific axes={inner ticks, width=3cm},
2567 x axis={ticks={step=3, minor steps between steps=2}},
2568 y axis={ticks={step=.36}},
2569 visualize as scatter]
2570 data {
2571 x, y
2572 17, 30
2573 34, 32
2574 };
2575 \end{tikzpicture}
2576 \end{codeexample}
2577 %
2578 \end{key}
2579
2580 \label{section-dv-exponential-strategy}
2581
2582 \begin{key}{/tikz/data visualization/axis options/exponential steps}
2583 This strategy produces ticks at positions that are appropriate for
2584 logarithmic plots. It is automatically selected when you use the
2585 |logarithmic| option with an axis.
2586
2587 In detail, the following happens: As for |linear steps| let numbers $a$,
2588 $b$, $s$, and $p$ be given. Then, major ticks are placed at all positions
2589 $10^{i\cdot s+p}$ that lie in the interval $[a,b]$ for $i \in \mathbb{Z}$.
2590
2591 The minor steps are added in the same way as for |linear steps|. In
2592 particular, they interpolate \emph{linearly} between major steps.
2593 %
2594 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
2595 \begin{tikzpicture}
2596 \datavisualization
2597 [scientific axes,
2598 x axis={logarithmic, length=2cm, ticks={step=1.5}},
2599 y axis={logarithmic, ticks={step=1, minor steps between steps=9}},
2600 visualize as scatter]
2601 data {
2602 x, y
2603 1, 10
2604 1000, 1000000
2605 };
2606 \end{tikzpicture}
2607 \end{codeexample}
2608 %
2609 \end{key}
2610
2611
2612 \subsubsection{Advanced: Defining New Placement Strategies}
2613
2614 \begin{key}{/tikz/data visualization/axis options/tick placement strategy=\meta{macro}}
2615 This key can be used to install a so-called \emph{tick placement strategy}.
2616 Whenever |visualize ticks| is used to request some ticks to be visualized,
2617 it is checked whether some automatic ticks should be created. This is the
2618 case when the following key is set:
2619 %
2620 \begin{key}{/tikz/data visualization/compute step=\meta{code}}
2621 The \meta{code} should compute a suitable value for the stepping to be
2622 used by the \meta{macro} in the tick placement strategy.
2623
2624 For instance, the |step| key sets |compute step| to
2625 |\def\tikz@lib@dv@step{#1}|. Thus, when you say |step=5|, then the
2626 desired stepping of |5| is communicated to the \meta{macro} via the
2627 macro |\tikz@lib@dv@step|.
2628 \end{key}
2629
2630 Provided |compute step| is set to some nonempty value, upon visualization
2631 of ticks the \meta{macro} is executed. Typically, \meta{macro} will first
2632 call the \meta{code} stored in the key |compute step|. Then, it should
2633 implement some strategy then uses the value of the computed or desired
2634 stepping to create appropriate |at| commands. To be precise, it should set
2635 the keys |major|, |minor|, and/or |subminor| with some appropriate |at|
2636 values.
2637
2638 Inside the call of \meta{macro}, the macro |\tikzdvaxis| will have been set
2639 to the name of the axis for which default ticks need to be computed. This
2640 allows you to access the minimum and the maximum value stored in the
2641 |scaling mapper| of that axis.
2642 %
2643 \begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
2644 \def\silly{
2645 \tikzdatavisualizationset{major={at={
2646 2,3,5,7,11,13}}}
2647 }
2648 \begin{tikzpicture}
2649 \datavisualization [
2650 scientific axes, visualize as scatter,
2651 x axis={tick placement strategy=\silly}
2652 ]
2653 data {
2654 x, y
2655 0, 0
2656 15, 15
2657 };
2658 \end{tikzpicture}
2659 \end{codeexample}
2660 %
2661 \end{key}
2662
2663
2664 \subsection{Advanced: Creating New Axis Systems}
2665
2666 The |datavisualization| library comes with a number of predefined axis systems,
2667 like |scientific axes=clean|, but it is also possible and to define new axis
2668 systems. Doing so involves the following steps:
2669 %
2670 \begin{enumerate}
2671 \item Creating a number of axes.
2672 \item Configuring attributes of these axes like their length or default
2673 scaling.
2674 \item Creating visual representations of the axes.
2675 \item Creating visual representations of the ticks and grid lines.
2676 \end{enumerate}
2677
2678 The first step uses |new ... axis| keys to create new axes, the last steps use
2679 |visualize ...| keys to create the visual representations of the axes.
2680
2681 Note that the axis system has no control over the actual attribute value ranges
2682 and neither over which ticks need to be drawn. The axis system can only provide
2683 good defaults and then specify \emph{how} the ticks or labels should be drawn
2684 and \emph{where} on the page -- but not at which values.
2685
2686 In the following, as a running example let us develop an axis system
2687 |our system| that does the following: For the $x$-axis is looks like a normal
2688 scientific axis system, but there are actually two $y$-axes: One at the left
2689 and one at the right, each using a different attribute, but both coexisting in
2690 the same picture.
2691
2692
2693 \subsubsection{Creating the Axes}
2694
2695 A new axis system is created as a style key with the prefix
2696 |/tikz/data visualization|. Thus, we would write:
2697 %
2698 \begin{codeexample}[code only]
2699 \tikzset{
2700 data visualization/our system/.style={
2701 ...
2702 }
2703 }
2704 \end{codeexample}
2705
2706 In our system we need three axis: The $x$-axis, the left axis and the right
2707 axis. Since all of these axes are Cartesian axes, we write the following:
2708 %
2709 \begin{codeexample}[code only]
2710 \tikzset{
2711 data visualization/our system/.style={
2712 new Cartesian axis=x axis,
2713 new Cartesian axis=left axis,
2714 new Cartesian axis=right axis,
2715 x axis={attribute=x},
2716 left axis={unit vector={(0cm,1pt)}},
2717 right axis={unit vector={(0cm,1pt)}},
2718 }
2719 }
2720 \end{codeexample}
2721 %
2722 As can be seen, we also configure things so that the $x$-axis will use the |x|
2723 attribute by default (users can later change this by saying
2724 |x axis={attribute=|\meta{some other attribute}|}|), but we do not configure
2725 the attributes of the |left axis| nor the |right axis|. We also make the left
2726 and right axis point upward (the |x axis| needs no configuration here since a
2727 Cartesian axis points right by default). The reason is the |left| would not be
2728 a particularly good attribute name and this way we ensure that users have to
2729 pick names themselves (hopefully good ones).
2730
2731 The next step is to define a standard scaling for the axes. Here, we can use
2732 the same as for |scientific axes|, so we would add the following keys to the
2733 definition of |our system|:
2734 %
2735 \begin{codeexample}[code only]
2736 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
2737 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
2738 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
2739 \end{codeexample}
2740
2741 We now already have enough to try our system, although we will not yet see any
2742 axes or ticks, but we will see the correct scaling of the attributes. Let us
2743 first define a data group:
2744 %
2745 \begin{codeexample}[setup code]
2746 \tikz \datavisualization data group {people and money} = {
2747 data [set=people 1] {
2748 time, people
2749 1900, 1000000000
2750 1920, 1500000000
2751 1930, 2000000000
2752 1980, 3000000000
2753 }
2754 data [set=people 2] {
2755 time, people
2756 1900, 2000000000
2757 1920, 2500000000
2758 1940, 4000000000
2759 2000, 5700000000
2760 }
2761 data [set=money 1] {
2762 time, money
2763 1910, 1.1
2764 1920, 2
2765 1930, 5
2766 1980, 2
2767 }
2768 data [set=money 2] {
2769 time, money
2770 1950, 3
2771 1960, 3
2772 1970, 4
2773 1990, 3.5
2774 }
2775 };
2776 \end{codeexample}
2777
2778 \begin{codeexample}[setup code,hidden]
2779 \tikzdatavisualizationset{
2780 our system/.style={
2781 new Cartesian axis=x axis,
2782 new Cartesian axis=left axis,
2783 new Cartesian axis=right axis,
2784 x axis={attribute=x},
2785 left axis={unit vector={(0cm,1pt)}},
2786 right axis={unit vector={(0cm,1pt)}},
2787 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
2788 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
2789 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
2790 }
2791 }
2792 \end{codeexample}
2793 %
2794 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
2795 \tikz \datavisualization [
2796 our system,
2797 x axis={attribute=time, length=4cm},
2798 left axis ={attribute=money},
2799 right axis={attribute=people},
2800 visualize as line/.list={people 1, people 2, money 1, money 2},
2801 people 1={style={visualizer color=blue}},
2802 people 2={style={visualizer color=blue!50}},
2803 money 1={style={visualizer color=red}},
2804 money 2={style={visualizer color=red!50}}]
2805 data group {people and money};
2806 \end{codeexample}
2807
2808
2809 \subsubsection{Visualizing the Axes}
2810 \label{section-dv-visualize-axis}
2811
2812 We must now show the axes themselves. For this we can use the |visualize axis|
2813 key:
2814
2815 \begin{key}{/tikz/data visualization/axis options/visualize axis=\meta{options}}
2816 This key is passed to an axis as an option. It causes a visual
2817 representation of the axis to be created during the data visualization. The
2818 \meta{options} are used to determine where the axis should be drawn and how
2819 long it should be. We can specify, for instance, that an axis should be
2820 drawn at the minimum value of another axis or where another axis has the
2821 value |0|.
2822
2823
2824 \medskip
2825 \textbf{The goto, high, and low Keys.}
2826 In our example, the |left axis| should be shown at the left hand side. This
2827 is the position where the |x axis| has its minimum value. To specify this,
2828 we would use the following code:
2829 %
2830 \begin{codeexample}[code only]
2831 left axis={ visualize axis={ x axis={ goto=min } }
2832 \end{codeexample}
2833 %
2834 As can be seen, we can pass another axis as an \meta{option} to
2835 |visualize axis|, where we pass the following key to the axis in turn:
2836 %
2837 \begin{key}{/tikz/data visualization/axis options/goto=\meta{value}}
2838 The key can be passed to an axis. It will set the attribute monitored
2839 by the axis to the given \meta{value}, which is usually some number.
2840 However, \meta{value} may also be one of the following, which causes a
2841 special behavior:
2842 %
2843 \begin{itemize}
2844 \item |min|: The attribute is set to the minimal value that the
2845 attribute has attained along this axis.
2846 \item |max|: Like |min|.
2847 \item |padded min|: This will also set the \meta{attribute}
2848 monitored by the axis to the same value as |min|.
2849 Additionally, however, the subkey
2850 |/data point/|\meta{attribute}|/offset| is set to the current
2851 padding for the minimum, see the description of |padding min|
2852 later on. The effect of this is that the actual point ``meant''
2853 by the attribute is offset by this padding along the
2854 attribute's axis.
2855 \item |padded max|: Like |padded min|.
2856 \end{itemize}
2857 \end{key}
2858
2859 The |right axis| would be visualized the same way, only at |goto=max|. The
2860 $x$-axis actually needs to be visualized \emph{twice}: Once at the bottom
2861 and once at the top. Thus, we need to call |visualize axis| twice for this
2862 axis:
2863 %
2864 \tikzdatavisualizationset{
2865 our system/.style={
2866 new Cartesian axis=x axis,
2867 new Cartesian axis=left axis,
2868 new Cartesian axis=right axis,
2869 x axis={attribute=x},
2870 left axis={unit vector={(0cm,1pt)}},
2871 right axis={unit vector={(0cm,1pt)}},
2872 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
2873 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
2874 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
2875 }
2876 }
2877 \begin{codeexample}[
2878 preamble={\usetikzlibrary{datavisualization}},
2879 pre={\tikzdatavisualizationset{
2880 our system/.style={
2881 new Cartesian axis=x axis,
2882 new Cartesian axis=left axis,
2883 new Cartesian axis=right axis,
2884 x axis={attribute=x},
2885 left axis={unit vector={(0cm,1pt)}},
2886 right axis={unit vector={(0cm,1pt)}},
2887 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
2888 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
2889 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
2890 }
2891 }}]
2892 \tikzset{
2893 data visualization/our system/.append style={
2894 left axis= {visualize axis={x axis= {goto=min}}},
2895 right axis={visualize axis={x axis= {goto=max}}},
2896 x axis= {visualize axis={left axis={goto=min}},
2897 visualize axis={left axis={goto=max}}},
2898 }
2899 }
2900 \tikz \datavisualization [
2901 our system,
2902 x axis={attribute=time, length=4cm},
2903 left axis ={attribute=money},
2904 right axis={attribute=people},
2905 visualize as line/.list={people 1, people 2, money 1, money 2}]
2906 data group {people and money};
2907 \end{codeexample}
2908
2909 There is another key that is similar to |goto|, but has a slightly
2910 different semantics:
2911 %
2912 \begin{key}{/tikz/data visualization/axis options/goto pos=\meta{fraction}}
2913 The key works like |goto|, only the \meta{fraction} is not interpreted
2914 as a value but as a fraction of the way between the minimum and the
2915 maximum value for this axis.
2916
2917 Suppose that for an axis the attribute range interval is $[500,1000]$
2918 and the reasonable interval is $[1,3]$. Then for a \meta{fraction} of
2919 |0|, the mapping process would choose value $1$ from the reasonable
2920 interval, for a \meta{fraction} of |1| the position $3$ from the
2921 reasonable interval, and for a \meta{fraction} or |0.25| the position
2922 $1.5$ since it is one quarter at the distance from $1$ to $3$.
2923
2924 Note that neither the attribute range interval nor the transformation
2925 function for the attribute are important for the |goto pos| option --
2926 the \meta{fraction} is computed with respect to the reasonable
2927 interval. Also note that the values of the actual attribute
2928 corresponding to the fractional positions in the reasonable interval
2929 are not computed.
2930 %
2931 \begin{codeexample}[
2932 preamble={\usetikzlibrary{datavisualization}},
2933 pre={\tikzdatavisualizationset{
2934 our system/.style={
2935 new Cartesian axis=x axis,
2936 new Cartesian axis=left axis,
2937 new Cartesian axis=right axis,
2938 x axis={attribute=x},
2939 left axis={unit vector={(0cm,1pt)}},
2940 right axis={unit vector={(0cm,1pt)}},
2941 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
2942 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
2943 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
2944 }
2945 }}]
2946 \tikzset{
2947 data visualization/our system/.append style={
2948 x axis= {visualize axis={left axis={goto pos=0.25}},
2949 visualize axis={left axis={goto pos=0.5}}},
2950 }
2951 }
2952 \tikz \datavisualization [
2953 our system,
2954 x axis={attribute=time, length=4cm},
2955 left axis ={attribute=money},
2956 right axis={attribute=people},
2957 visualize as line/.list={people 1, people 2, money 1, money 2}]
2958 data group {people and money};
2959 \end{codeexample}
2960 \end{key}
2961
2962 By default, when an axis is visualized, it spans the set of all possible
2963 values for the monitored attribute, that is, from |min| to |max|. However,
2964 there are actually two keys that allow you to adjust this:
2965 %
2966 \begin{key}{/tikz/data visualization/low=\meta{value}}
2967 This is the attribute value where the axis visualization starts. The
2968 same special values as for |goto| are permissible (like |min| or
2969 |padded min|, but also |0| or |1|).
2970 \end{key}
2971 %
2972 \begin{key}{/tikz/data visualization/high=\meta{value}}
2973 Like |low|, only for where the axis ends.
2974 \end{key}
2975
2976 By default, |low=min| and |high=max| are set for an axis visualization.
2977 Another sensible setting is |low=padded min| and |high=padded max|. The
2978 following key provides a shorthand for this:
2979 %
2980 \begin{key}{/tikz/data visualization/padded}
2981 Shorthand for |low=padded min, high=padded max|.
2982 \end{key}
2983 %
2984 As an example, consider the |scientific axes=clean|. Here, each axis is
2985 actually drawn three times: Once at the minimum, once at the maximum and
2986 then once more at the padded minimum.
2987
2988
2989 \medskip
2990 \textbf{The axis line.}
2991 When an axis is drawn, \tikzname\ does not simply draw a straight line from
2992 the |low| position to the |high| position. In reality, the data
2993 visualization system uses the two commands |\pgfpathdvmoveto| and
2994 |\pgfpathdvlineto| internally. These will replace the straight line by a
2995 curve in certain situations. For instance, in a polar coordinate system, if
2996 an axis should be drawn along an angle axis for a fixed radius, an arc will
2997 be used instead of a straight line.
2998
2999
3000 \medskip
3001 \textbf{Styling the axis.}
3002 As can be seen, we now get the axis we want (but without the ticks,
3003 visualizing them will be explained later). The axis is, however, simply a
3004 black line. We can \emph{style} the axis in a manner similar to styling
3005 ticks and grid lines, see Section~\ref{section-dv-style}. In detail, the
3006 following styles get executed:
3007 %
3008 \begin{enumerate}
3009 \item |axis layer|
3010 \item |every axis|
3011 \item |styling|
3012 \end{enumerate}
3013 %
3014 Additionally, even before |every axis| is executed, |low=min| and
3015 |high=max| are executed.
3016
3017 \begin{stylekey}{/tikz/data visualization/axis layer (initially on background layer)}
3018 The layer on which the axis is drawn. See the description of
3019 |grid layer| on page~\pageref{section-dv-grid-layer} for details.
3020 \end{stylekey}
3021
3022 \begin{stylekey}{/tikz/data visualization/every axis}
3023 Put styling of the axis here. It is usually a good idea to set this
3024 style to |style={black!50}|.
3025 \end{stylekey}
3026
3027 Recall that the |styling| key is set using the |style| key, see
3028 Section~\ref{section-dv-style}.
3029 %
3030 % TODOsp: codeexamples: What is this empty `\tikzset` good for?
3031 \tikzset{
3032 }
3033 \begin{codeexample}[
3034 preamble={\usetikzlibrary{datavisualization}},
3035 pre={\tikzdatavisualizationset{
3036 our system/.style={
3037 new Cartesian axis=x axis,
3038 new Cartesian axis=left axis,
3039 new Cartesian axis=right axis,
3040 x axis={attribute=x},
3041 left axis={unit vector={(0cm,1pt)}},
3042 right axis={unit vector={(0cm,1pt)}},
3043 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
3044 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
3045 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
3046 }
3047 }}]
3048 \tikzset{
3049 data visualization/our system/.append style={
3050 every axis/.style={style=black!50}, % make this the default
3051 left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
3052 right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
3053 x axis= {visualize axis={left axis={goto=min}},
3054 visualize axis={left axis={goto=max}}},
3055 }
3056 }
3057 \tikz \datavisualization [
3058 our system,
3059 x axis={attribute=time, length=4cm},
3060 left axis ={attribute=money},
3061 right axis={attribute=people},
3062 visualize as line/.list={people 1, people 2, money 1, money 2}]
3063 data group {people and money};
3064 \end{codeexample}
3065 \tikzset{
3066 data visualization/our system/.append style={
3067 every axis/.style={style=black!50}, % make this the default
3068 left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
3069 right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
3070 x axis= {visualize axis={left axis={goto=min}},
3071 visualize axis={left axis={goto=max}}},
3072 }
3073 }
3074
3075
3076 \medskip
3077 \textbf{Padding the Axis.}
3078 When an axis is visualized, it is often a good idea to make it ``a little
3079 bit longer'' or to ``remove it a bit from the border'', because the
3080 visualization of an axis should not interfere with the actual data. For
3081 this reason, a \emph{padding} can be specified for axes:
3082
3083 \begin{key}{/tikz/data visualization/axis options/padding min=\meta{dimension}}
3084 This is the dimension that is used whenever |goto=padded min| is used.
3085 The \meta{dimension} is then put into the |offset| subkey of the
3086 attribute monitored by the axis. When a data point is transformed by a
3087 linear transformer and when this subkey is nonzero, this offset is
3088 added. (For an angle axis of a polar transformer, the \meta{dimension}
3089 is interpreted as an additional angle rather than as an additional
3090 distance). Note that \meta{dimension} should typically be negative
3091 since ``adding the \meta{dimension}'' will then make the axis longer
3092 (because it starts at a smaller value). The standard axis systems set
3093 the padding to some default and take its value into account:
3094 %
3095 \begin{codeexample}[
3096 width=8cm,
3097 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3098 ]
3099 \begin{tikzpicture}
3100 \datavisualization [scientific axes=clean,
3101 x axis={padding min=-1cm},
3102 visualize as smooth line]
3103 data [format=function] {
3104 var x : interval [-3:5];
3105 func y = \value x * \value x;
3106 };
3107 \end{tikzpicture}
3108 \end{codeexample}
3109
3110 Using padded and using the |padded| key, we can visualize our axis ``a
3111 little removed from the actual data'':
3112 %
3113 \begin{codeexample}[
3114 preamble={\usetikzlibrary{datavisualization}},
3115 pre={\tikzdatavisualizationset{
3116 our system/.style={
3117 new Cartesian axis=x axis,
3118 new Cartesian axis=left axis,
3119 new Cartesian axis=right axis,
3120 x axis={attribute=x},
3121 left axis={unit vector={(0cm,1pt)}},
3122 right axis={unit vector={(0cm,1pt)}},
3123 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
3124 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
3125 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
3126 }
3127 }%
3128 \tikzset{
3129 data visualization/our system/.append style={
3130 every axis/.style={style=black!50}, % make this the default
3131 left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
3132 right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
3133 x axis= {visualize axis={left axis={goto=min}},
3134 visualize axis={left axis={goto=max}}},
3135 }
3136 }}]
3137 \tikzset{
3138 data visualization/our system/.append style={
3139 all axes= {padding=.5em},
3140 left axis= {visualize axis={x axis= {goto=padded min}, padded}},
3141 right axis={visualize axis={x axis= {goto=padded max}, padded}},
3142 x axis= {visualize axis={left axis={goto=padded min}, padded},
3143 visualize axis={left axis={goto=padded max}, padded}},
3144 }
3145 }
3146 \tikz \datavisualization [
3147 our system,
3148 x axis={attribute=time, length=3cm},
3149 left axis ={attribute=money},
3150 right axis={attribute=people},
3151 visualize as line/.list={people 1, people 2, money 1, money 2}]
3152 data group {people and money};
3153 \end{codeexample}
3154 \end{key}
3155
3156 \begin{key}{/tikz/data visualization/axis options/padding max=\meta{dimension}}
3157 Works like |padding min|, but \meta{dimension} should typically be
3158 positive.
3159 \end{key}
3160
3161 \begin{key}{/tikz/data visualization/axis options/padding=\meta{dimension}}
3162 Sets both |padding min| to the negated value of \meta{dimension} and
3163 |padding max| to \meta{dimension}.
3164 \end{key}
3165 \end{key}
3166
3167
3168 \subsubsection{Visualizing Grid Lines}
3169 \label{section-dv-visualize-gridlines}
3170
3171 As explained earlier, the |grid| key is used to specify at which positions grid
3172 lines should be drawn in principle. However, this key does not actually cause
3173 any grid lines to be drawn. Instead, the |visualize grid| key is used by the
3174 axis system to specify how grid lines are drawn.
3175
3176 \begin{key}{/tikz/data visualization/axis options/visualize grid=\meta{options}}
3177 This key is passed to an axis. It causes grid lines to be drawn at the
3178 positions specified by the |grid| key for this axis. The \meta{options}
3179 govern where and how the grid lines will be drawn.
3180
3181
3182 \medskip
3183 \textbf{The direction axis.}
3184 At first sight, one might expect that the grid lines for an axis should
3185 simply be drawn perpendicular to the axis between the minimum and maximum
3186 value of the axis. However, things are somewhat more difficult in reality:
3187 %
3188 \begin{enumerate}
3189 \item A grid line is supposed to indicate all positions where a certain
3190 attribute attains a fixed value. But, then, a grid line does not
3191 really need to be a grid \emph{line}. Consider for instance a three
3192 dimensional axis system. A ``grid line'' for the $x$-coordinate |3|
3193 would actually be a ``grid plane''.
3194 \item For a polar coordinate system and a fixed radius, this set of
3195 positions at a certain radius is not a straight line, but an arc.
3196 For more complicated coordinate systems such as the one arising
3197 from three-dimensional spherical projections, a grid line may well
3198 be a fairly involved curve.
3199 \end{enumerate}
3200 %
3201 The |visualize grid| command addresses these complications as follows:
3202 %
3203 \begin{enumerate}
3204 \item A grid line is always a line, not a plane or a volume. This means
3205 that in the example of a three dimensional axis system and the
3206 $x$-attribute being |3|, one would have to choose whether the grid
3207 line should go ``along'' the $y$-axis or ``along'' the $z$-axis for
3208 this position. One can, however, call the |visualize grid| command
3209 twice, once for each direction, to cause grid lines to be shown for
3210 both directions.
3211 \item A grid line is created by moving to a start position and then
3212 doing a lineto to the target position. However, the ``moveto'' and
3213 ``lineto'' are done by calling special commands of the data
3214 visualization system. These special commands allow coordinate
3215 system to ``notice'' that the line is along an axis and will allow
3216 them to replace the straight line by an appropriate curve. The
3217 polar axes systems employ this strategy, for instance.
3218 \end{enumerate}
3219
3220 By the above discussion, in order to create a grid line for attribute $a$
3221 having value $v$, we need to specify an axis ``along'' which the line
3222 should be drawn. When there are only two axes, this is usually ``the other
3223 axis''. This ``other axis'' is specified using the following key:
3224 %
3225 \begin{key}{/tikz/data visualization/direction axis=\meta{axis name}}
3226 You must pass this key as an \meta{option} each time you use
3227 |visualize axis|. When the grid line is drawn, the attribute $a$ is set
3228 to $v$ and the axis \meta{axis name}'s attribute is set once to the
3229 current value of |low| and once to |high|. Then a line is drawn between
3230 these two positions using |\pgfpathdvlineto|.
3231 \end{key}
3232 %
3233 The |low| and |high| keys are the same as the ones used in the
3234 |visualize axis| key.
3235 %
3236 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
3237 \tikz \datavisualization [
3238 xyz Cartesian cabinet,
3239 all axes={visualize axis={low=0, style=->}},
3240 x axis={visualize grid={direction axis=y axis}, grid=many},
3241 visualize as scatter]
3242 data {
3243 x, y, z
3244 0, 0, 1
3245 0, 1, 0
3246 2, 2, 2
3247 };
3248 \end{codeexample}
3249 %
3250 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
3251 \tikz \datavisualization [
3252 xyz Cartesian cabinet,
3253 all axes={visualize axis={low=0, style=->}, grid=many},
3254 x axis={visualize grid={direction axis=z axis}},
3255 z axis={visualize grid={direction axis=x axis},
3256 visualize grid={direction axis=y axis},},
3257 visualize as scatter]
3258 data {
3259 x, y, z
3260 0, 0, 1
3261 0, 1, 0
3262 2, 2, 2
3263 };
3264 \end{codeexample}
3265
3266
3267 \medskip
3268 \textbf{Styling the grid lines.}
3269 When a grid line is draw, styles are applied as described in
3270 Section~\ref{section-dv-styling-grid-lines}.
3271
3272
3273 \medskip
3274 \textbf{The major, minor, and subminor grid lines.}
3275 The |grid| option allows you to specify for each kind of grid line (major,
3276 minor, or subminor) a set of different values for which these grid lines
3277 should be drawn. Correspondingly, it is also possible to configure for each
3278 kind of grid line how it should be drawn. For this, the |major|, |minor|,
3279 |subminor|, and also the |common| keys can be used inside the
3280 \meta{options} of |visualize grid|. While as option to |grid| these keys
3281 are used to specify |at| values, as options of |visualize grid| they are
3282 used to configure the different kinds of grid lines.
3283
3284 Most of the time, no special configuration is necessary since all styling
3285 is best done by configuring keys like |every major grid|. You need to use a
3286 key like |major| only if you wish to configure for instance the |low| or
3287 |high| values of a |major| grid line differently from those of |minor| grid
3288 lines -- are rather unlikely setting -- or when the styling should deviate
3289 from the usual settings.
3290 %
3291 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
3292 \tikz \datavisualization [
3293 xy Cartesian,
3294 all axes={visualize axis={low=0, style=->},
3295 grid={some, minor steps between steps}},
3296 x axis= {visualize grid={
3297 direction axis=y axis,
3298 minor={low=0.25, high=1.75, style=red!50}}},
3299 visualize as scatter]
3300 data {
3301 x, y
3302 0, 0
3303 3, 3
3304 };
3305 \end{codeexample}
3306 %
3307 \end{key}
3308
3309 Returning to the example of |our system| with the two axis systems, it is
3310 straight-forward to configure the grid lines of the $x$-axis: The direction
3311 axis is either of the other two axis (they point in the same direction and they
3312 have the same range). For the other two axes, we visualize one grid
3313 independently of the other, using different colors.
3314 %
3315 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
3316 \tikzset{
3317 data visualization/our system/.append style={
3318 x axis= {visualize grid={direction axis=left axis}},
3319 left axis= {visualize grid={direction axis=x axis,
3320 common={style=red!50}}},
3321 right axis={visualize grid={direction axis=x axis,
3322 common={style=blue!50}}},
3323 }
3324 }
3325 \tikz \datavisualization [
3326 our system,
3327 x axis={attribute=time, length=3cm, grid=many},
3328 left axis ={attribute=money, grid=some},
3329 right axis={attribute=people, grid=few},
3330 visualize as line/.list={people 1, people 2, money 1, money 2}]
3331 data group {people and money};
3332 \end{codeexample}
3333
3334
3335 \subsubsection{Visualizing the Ticks and Tick Labels}
3336 \label{section-dv-visualize-ticks}
3337
3338 \begin{key}{/tikz/data visualization/axis options/visualize ticks=\meta{options}}
3339 Visualizing a tick involves (possibly) drawing a tick mark and adding
3340 (possibly) the tick node. The process is similar to |visualize grid|: Users
3341 use the |ticks| key to configure how many ticks they would like for an axis
3342 and at which positions. The axis system uses the |visualize ticks| key to
3343 specify where these ticks should actually be shown.
3344
3345 Unlike grid lines, which are typically only visualized once for each
3346 combination of an axis and a direction axis, tick marks might be visualized
3347 at different places for the same axis. Consider for instance the
3348 |scientific axes|:
3349 %
3350 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
3351 \tikz \datavisualization [scientific axes, all axes={length=3cm},
3352 x axis={ticks={stack}},
3353 visualize as smooth line]
3354 data [format=function] {
3355 var x : interval [0:2];
3356 func y = \value x*\value x;
3357 };
3358 \end{codeexample}
3359 %
3360 Have a look at the ticks on the $y$-axis: There are ticks at values |0|,
3361 |1|, |2|, |3|, and~|4|. These are visualized both at the left side (where
3362 the tick nodes are also shown) and additionally also at the right side, but
3363 only as small marks. Similarly, the ticks on the $x$-axis appear at the
3364 bottom, but also (in much simpler versions) at the top. Both for the
3365 $x$-axis and for the $y$-axis the |visualize ticks| key was called twice.
3366
3367
3368 \medskip
3369 \textbf{The tick marks.}
3370 Drawing a tick mark is quite similar to visualizing a grid line; indeed a
3371 tick mark can be thought of as a ``mini grid line'': Just like a grid line
3372 it ``points a long an axis''. However, a tick will always be a short
3373 straight line -- even when the coordinate system is actually twisted
3374 (experimentation has shown that ticks that follow the curvature of the
3375 coordinate system like grid lines are hard to recognize). For this reason,
3376 the |low| and |high| keys have a different meaning from the one used with
3377 the |visualize grid| key. In detail to configure the size and position of a
3378 tick mark for the value $v$ of attribute $a$, proceed as follows:
3379 %
3380 \begin{itemize}
3381 \item The |visualize ticks| key will have setup attribute $a$ to be
3382 equal to $v$.
3383 \item You should now use the |goto| or |goto pos| key together with all
3384 \emph{other} axes to configure at which position with respect to
3385 these other options the tick mark should be shown. For instance,
3386 suppose we want tick marks in |our system| for the $x$-axis at the
3387 bottom and at the top. This corresponds to once setting the
3388 |left axis| to its minimal value and once to its maximal value:
3389 %
3390 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
3391 \tikzset{
3392 data visualization/our system/.append style={
3393 x axis={visualize ticks={direction axis=left axis, left axis={goto=min}},
3394 visualize ticks={direction axis=left axis, left axis={goto=max}},
3395 }
3396 }
3397 }
3398 \tikz \datavisualization [
3399 our system,
3400 x axis={attribute=time, length=3cm, ticks=many},
3401 left axis ={attribute=money},
3402 right axis={attribute=people},
3403 visualize as line/.list={people 1, people 2, money 1, money 2}]
3404 data group {people and money};
3405 \end{codeexample}
3406 %
3407 \item In the above example, we may wish to shorten the ticks a bit at
3408 the bottom and at the top. For this, we use the |low| and |high|
3409 key:
3410 %
3411 \begin{key}{/tikz/data visualization/low=\meta{dimension}}
3412 When used with the |visualize ticks| option, the |low| key
3413 contains a dimension that specifies the extend of the tick
3414 going ``toward the minimum'' of the direction axis. More
3415 precisely, when a tick mark is visualized, a unit tangent
3416 vector at the current data point in the direction of the
3417 |direction axis| is computed and this vector is multiplied by
3418 \meta{dimension} to compute the start position of the tick
3419 line. The end position is given by this vector times the |high|
3420 value.
3421
3422 Note that the \meta{dimension} should usually be negative for
3423 the |low| key and positive for the |high| key.
3424
3425 For tick marks where a tick label node is shown, the
3426 \meta{dimension} is increased by the current values of keys
3427 like |tick text even low padding|, see
3428 Section~\ref{section-dv-stacking} for details.
3429 \end{key}
3430 %
3431 \begin{key}{/tikz/data visualization/high=\meta{dimension}}
3432 Like |low|.
3433 \end{key}
3434 %
3435 \begin{key}{/tikz/data visualization/tick length=\meta{dimension}}
3436 Shorthand for |low=-|\meta{dimension}|, high=|\meta{dimension}.
3437 \end{key}
3438
3439 What we want to happen is that in the upper visualization of the
3440 ticks the |low| value is |0pt|, while in the lower one the |high|
3441 value is |0pt|:
3442 %
3443 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
3444 \tikzset{
3445 data visualization/our system/.append style={
3446 x axis={
3447 visualize ticks={direction axis=left axis,high=0pt,left axis={goto=min}},
3448 visualize ticks={direction axis=left axis,low=0pt,left axis={goto=max}},
3449 }
3450 }
3451 }
3452 \tikz \datavisualization [
3453 our system,
3454 x axis={attribute=time, length=3cm, ticks=many},
3455 left axis ={attribute=money},
3456 right axis={attribute=people},
3457 visualize as line/.list={people 1, people 2, money 1, money 2}]
3458 data group {people and money};
3459 \end{codeexample}
3460 %
3461 \end{itemize}
3462 %
3463 In order to style the tick mark, use the styling mechanism that is detailed
3464 in Section~\ref{section-dv-styling-ticks}.
3465
3466
3467 \medskip
3468 \textbf{The tick label node.}
3469 At certain tick positions, we may wish to add a node indicating the value
3470 of the attribute at the given position. The |visualize ticks| command has
3471 no influence over which text should be shown at a node -- the text is
3472 specified and typeset as explained in Section~\ref{section-dv-tick-labels}.
3473
3474 Each time |visualize ticks|, for each tick position up to two tick label
3475 nodes will be created: One at the |low| position and one at the |high|
3476 position. The following keys are used to configure which of these cases
3477 happen:
3478 %
3479 \begin{key}{/tikz/data visualization/tick text at low=\opt{\meta{true or false}} (default true)}
3480 Pass this option to |visualize ticks| when you want tick label nodes to
3481 be placed at the |low| position of each tick mark.
3482 %
3483 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
3484 \tikzset{
3485 data visualization/our system/.append style={
3486 x axis={
3487 visualize ticks={direction axis=left axis, left axis={goto=min},
3488 high=0pt, tick text at low, stack},
3489 visualize ticks={direction axis=left axis, left axis={goto=max},
3490 low=0pt, tick text at high, stack}
3491 }
3492 }
3493 }
3494 \tikz \datavisualization [
3495 our system,
3496 x axis={attribute=time, length=3cm, ticks=some},
3497 left axis ={attribute=money},
3498 right axis={attribute=people},
3499 visualize as line/.list={people 1, people 2, money 1, money 2}]
3500 data group {people and money};
3501 \end{codeexample}
3502 \end{key}
3503 %
3504 \begin{key}{/tikz/data visualization/tick text at high=\opt{\meta{true or false}} (default true)}
3505 Like |tick text at low|.
3506 \end{key}
3507
3508 \begin{key}{/tikz/data visualization/no tick text}
3509 Shorthand for |tick text at low=false, tick text at high=false|.
3510 %
3511 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
3512 \tikz \datavisualization [scientific axes, all axes={length=3cm},
3513 x axis={ticks={
3514 major also at={6.5 as [no tick text]}}},
3515 visualize as smooth line]
3516 data [format=function] {
3517 var x : interval [5:10];
3518 func y = \value x * \value x;
3519 };
3520 \end{codeexample}
3521 \end{key}
3522
3523 When a tick label node is to be placed at the low or the high position, the
3524 next step is to determine the exact position and the correct anchor of the
3525 node. This is done as follows:
3526 %
3527 \begin{itemize}
3528 \item In order to compute an appropriate |anchor|, the tick mark is
3529 considered: This is a short line pointing in a certain direction.
3530 For a tick label node at the |low| position, the |anchor| attribute
3531 is setup in such a way that the node label will be below the |low|
3532 position when the tick mark direction points up, it will be to the
3533 right when the direction points left, above when it points down,
3534 and so on also for diagonal directions. Similarly, for the |high|
3535 position, when the direction points up, the node will be placed
3536 above the tick mark and so on.
3537
3538 This computation is done automatically.
3539 \item The tick label node is styled. The styles that are applied are
3540 described in Section~\ref{section-dv-styling-ticks}.
3541 \item A tick label node for the |low| position is usually anchored at
3542 this |low| position, but an additional padding will be added as
3543 described in Section~\ref{section-dv-stacking}.
3544 \end{itemize}
3545 \end{key}
3546
3547
3548 \subsubsection{Visualizing the Axis Labels}
3549 \label{section-dv-visualize-label}
3550
3551 The |label| option can be used with an axis to specify a text should be shown
3552 next to the axis to indicates which attribute this axis refers to. Like |ticks|
3553 or |grid|, the |label| option does not actually draw the label, this is the job
3554 of the |visualize label| key, which is configured by the axis system.
3555
3556 \begin{key}{/tikz/data visualization/axis options/visualize label=\meta{options}}
3557 The \meta{options} should be used to configure a ``good place'' for the
3558 axis label. Usually, you will use the |goto| or the |goto pos| key.
3559
3560 For the example of |our system|, we would like the label of the |x axis| to
3561 be placed below at the middle of the axis, so we use |goto pos=.5| to
3562 determine this position. Concerning the other axes, we want it to be placed
3563 at the minimum position of the |left axis| with a lot of padding.
3564 %
3565 \begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
3566 \tikzdatavisualizationset{
3567 our system/.append style={
3568 x axis={visualize label={
3569 x axis={goto pos=.5},
3570 left axis={padding=1.5em, goto=padded min}}}
3571 }
3572 }
3573 \tikz \datavisualization [
3574 our system,
3575 x axis={attribute=time, ticks=some, label},
3576 left axis ={attribute=money},
3577 right axis={attribute=people},
3578 visualize as line/.list={
3579 people 1, people 2, money 1, money 2}]
3580 data group {people and money};
3581 \end{codeexample}
3582
3583 In the above example, the |padding| of |1.5em| was rather arbitrary and
3584 ``suboptimal''. It would be outright wrong if the labels on the |x axis|
3585 were larger or if they were missing. It would be better if the vertical
3586 position of the |x axis| label were always ``below'' all other options. For
3587 such cases a slightly strange approach is useful: You position the node
3588 using |node style={at=...}| where |at| is now the normal \tikzname\ option
3589 that is used to specify the position of a node. Inside the |...|, you
3590 specify that the horizontal position should be the bottom of
3591 up-to-now-constructed data visualization and the vertical position should
3592 be at the ``origin'', which is, however, the position computed by the
3593 |goto| keys for the axes:
3594 %
3595 \begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
3596 \tikzdatavisualizationset{
3597 our system/.append style={
3598 x axis={visualize label={
3599 x axis={goto pos=.5},
3600 node style={
3601 at={(0,0 |- data visualization bounding box.south)},
3602 below
3603 } } } } }
3604 \tikz \datavisualization [
3605 our system,
3606 x axis={attribute=time, ticks=some, label=Year},
3607 left axis ={attribute=money},
3608 right axis={attribute=people},
3609 visualize as line/.list={
3610 people 1, people 2, money 1, money 2}]
3611 data group {people and money};
3612 \end{codeexample}
3613
3614 Two additional keys are useful for positioning axis labels:
3615 %
3616 \begin{key}{/tikz/data visualization/axis option/anchor at min}
3617 When passed to an axis, this key sets the |anchor| so that a node
3618 positioned at either the |min| or the |padded min| value of the axis
3619 will be placed ``nicely'' with respect to the axis. For instance, if
3620 the axis points upwards from the |min| value to the |max| value, the
3621 |anchor| would be set to |north| since this gives a label below the
3622 axis's start. Similarly, if the axis points right, the anchor would be
3623 set to |east|, and so on.
3624 \end{key}
3625 %
3626 \begin{key}{/tikz/data visualization/axis option/anchor at max}
3627 Like |anchor at min|.
3628 \end{key}
3629 \end{key}
3630
3631
3632 \subsubsection{The Complete Axis System}
3633
3634 Here is the code for the complete axis system developed above and an example of
3635 how it is used:
3636 %
3637 \begin{codeexample}[code only]
3638 \tikzdatavisualizationset{ our system/.style={
3639 % The axes
3640 new Cartesian axis=x axis, new Cartesian axis=left axis, new Cartesian axis=right axis,
3641 % The directions of the axes
3642 all axes={padding=.5em}, left axis={unit vector={(0cm,1pt)}}, right axis={unit vector={(0cm,1pt)}},
3643 % The default attributes, other attributes must be configured
3644 x axis={attribute=x},
3645 % The lengths of the axes
3646 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
3647 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
3648 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
3649 % The styling of the axes
3650 every axis/.style={style=black!50}, % make this the default
3651 % Visualizing the axes themselves
3652 left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}},
3653 right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}},
3654 x axis= {visualize axis={left axis={goto=padded min}, padded},
3655 visualize axis={left axis={goto=padded max}, padded}},
3656 % Visualizing the grid, when requested
3657 x axis= {visualize grid={direction axis=left axis}},
3658 left axis= {visualize grid={direction axis=x axis, common={style=red!50}}},
3659 right axis={visualize grid={direction axis=x axis, common={style=blue!50}}},
3660 % Visualizing the ticks, when requested
3661 left axis={visualize ticks={style={red!50!black}, direction axis=x axis,
3662 x axis={goto=padded min}, high=0pt, tick text at low}},
3663 right axis={visualize ticks={style={blue!80!black}, direction axis=x axis,
3664 x axis={goto=padded max}, low=0pt, tick text at high}},
3665 x axis={visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt,
3666 tick text at low},
3667 visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt}},
3668 % By default, there are ticks on all axes
3669 all axes={ticks},
3670 % Visualizing the axis labels, when requested
3671 x axis={visualize label={x axis={goto pos=.5}, node style={
3672 at={(0,0 |- data visualization bounding box.south)}, below}}},
3673 left axis={visualize label={left axis={goto pos=.5}, node style={
3674 at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}},
3675 right axis={visualize label={right axis={goto pos=.5}, node style={
3676 at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}},
3677 }}
3678 \end{codeexample}
3679
3680 \begin{codeexample}[
3681 preamble={\usetikzlibrary{datavisualization}},
3682 pre={\tikzdatavisualizationset{
3683 our system/.style={
3684 % The axes
3685 new Cartesian axis=x axis,
3686 new Cartesian axis=left axis,
3687 new Cartesian axis=right axis,
3688 % The default attributes, other attributes must be configured
3689 x axis={attribute=x},
3690 % The directions of the axes
3691 all axes={padding=.5em},
3692 left axis={unit vector={(0cm,1pt)}},
3693 right axis={unit vector={(0cm,1pt)}},
3694 % The lengths of the axes
3695 x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
3696 left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
3697 right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
3698 % The styling of the axes
3699 every axis/.style={style=black!50}, % make this the default
3700 % Visualizing the axes themselves
3701 left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}},
3702 right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}},
3703 x axis= {visualize axis={left axis={goto=padded min}, padded},
3704 visualize axis={left axis={goto=padded max}, padded}},
3705 % Visualizing the grid, when requested
3706 x axis= {visualize grid={direction axis=left axis, padded}},
3707 left axis= {visualize grid={direction axis=x axis, padded, common={style=red!50}}},
3708 right axis={visualize grid={direction axis=x axis, padded, common={style=blue!50}}},
3709 % Visualizing the ticks, when requested
3710 left axis={
3711 visualize ticks={style={red!50!black}, direction axis=x axis, x axis={goto=padded min}, high=0pt, tick text at low}},
3712 right axis={
3713 visualize ticks={style={blue!80!black}, direction axis=x axis, x axis={goto=padded max}, low=0pt, tick text at high}},
3714 x axis={
3715 visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt, tick text at low},
3716 visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt}
3717 },
3718 % By default, there are ticks on all axes
3719 all axes={ticks},
3720 % Visualizing the axis labels, when requested
3721 x axis={visualize label={
3722 x axis={goto pos=.5}, node style={at={(0,0 |- data visualization bounding box.south)}, below}}},
3723 left axis={visualize label={
3724 left axis={goto pos=.5}, node style={
3725 at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}},
3726 right axis={visualize label={
3727 right axis={goto pos=.5}, node style={
3728 at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}},
3729 }
3730 }}]
3731 \tikz \datavisualization [
3732 our system,
3733 x axis={attribute=time, label=Year,
3734 ticks={tick text padding=2pt, style={/pgf/number format/set thousands separator=}}},
3735 left axis={attribute=money, label=Spending,
3736 padding min=0, include value=0, grid,
3737 ticks={tick prefix=\$, style={/pgf/number format/fixed,
3738 /pgf/number format/fixed zerofill, /pgf/number format/precision=2}}},
3739 right axis={attribute=people,
3740 label=Population,
3741 padding min=0, include value=0,
3742 ticks={style=/pgf/number format/fixed}},
3743 visualize as line/.list={
3744 people 1, people 2, money 1, money 2},
3745 people 1={style={visualizer color=blue}},
3746 people 2={style={visualizer color=blue!50}},
3747 money 1={style={visualizer color=red}},
3748 money 2={style={visualizer color=red!50}} ]
3749 data group {people and money};
3750 \end{codeexample}
3751
3752
3753 \subsubsection{Using the New Axis System Key}
3754
3755 The axis system |our system| that we developed in the course of the previous
3756 section is not yet ``configurable''. The only configuration that was possible
3757 was to ``misuse'' the |width| and |height| keys of the |scientific axes|.
3758
3759 In order to make |our system| configurable so that we can say
3760 |our system=|\meta{options}, where \meta{options} are executed with the path
3761 prefix
3762 %
3763 \begin{codeexample}[code only]
3764 /tikz/data visualization/our system
3765 \end{codeexample}
3766 %
3767 we can use the following key:
3768
3769 \begin{key}{/tikz/data visualization/new axis system=\marg{axis system
3770 name}\marg{axis setup}\marg{default options}\\ \marg{application
3771 options}%
3772 }
3773 The |new axis system| key takes four parameters. The first one,
3774 \meta{system name}, is the name of the to-be-created axis system,
3775 |our system| in our case. The |new axis system| will create the following
3776 new key:
3777 %
3778 \begin{key}{/tikz/data visualization/\meta{axis system name}=\opt{\meta{options}}}
3779 When the key \meta{axis system name} is used, the following keys will be
3780 executed in the following order:
3781 %
3782 \begin{enumerate}
3783 \item The \meta{axis setup} with the path prefix
3784 |/tikz/data visualization/|.
3785 \item The \meta{default options} with the same path prefix.
3786 \item The following style:
3787 %
3788 \begin{stylekey}{/tikz/data visualization/every \meta{axis system name}}
3789 Even though this style has the path prefix
3790 |/tikz/data visualization| itself, the keys stored in this
3791 style will be executed with the path prefix
3792 |/tikz/data visualization/|\meta{axis system name}.
3793 \end{stylekey}
3794 \item The \meta{options} with the path prefix
3795 |/tikz/data visualization/|\meta{axis system name}.
3796 \item The \meta{application options} with the path prefix
3797 |/tikz/data visualization/|
3798 \end{enumerate}
3799 \end{key}
3800
3801 Let us now have a look at what all of this means. First, the \meta{axis
3802 setup} will contain all options that setup the axis system in all ways that
3803 need not be configured. For instance, the \meta{axis setup} for the
3804 |scientific axes| will create an |x axis| and also a |y axis| (because
3805 these are always present), but will not setup the label visualization
3806 (because this can be configured in different ways). For |our system|, which
3807 cannot be configured at all, we would place all of our configuration in the
3808 \meta{axis setup}.
3809
3810 The \meta{default options} can be used to pick default values that would
3811 usually be passed to the \meta{options} of the newly created axis system.
3812 For instance, for |scientific axis|, the \meta{default options} are set to
3813 |outer ticks,standard labels|, because these are the defaults.
3814
3815 Finally, the \meta{application options} can be used to actually apply the
3816 configuration that has been chosen by the \meta{options}. The idea is that
3817 \meta{default options}, \meta{options}, and also |every| \meta{axis system
3818 name} all have a chance of changing, re-changing and re-setting all sorts
3819 of styles and keys. Then, with the last change ``winning'', the resulting
3820 setting of a style can be executed, which may then cause a label
3821 visualization to be installed.
3822 \end{key}