/
pgfmanual-en-dv-axes.tex
3821 lines (3458 loc) · 152 KB
/
pgfmanual-en-dv-axes.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% Copyright 2010 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.
\section{Axes}
\label{section-dv-axes}
\subsection{Overview}
When a data point is visualized, the most obvious way of creating a visual
representation of its many attributes is to vary \emph{where} the data point is
shown. The data visualization system uses \emph{axes} to turn data point
attributes into positions on a page. The simplest -- and most common -- use of
axes is to vary the horizontal position of data points according to one
attribute and to vary the vertical position according to another attribute. In
contrast, in a polar plot one attribute dictates the distance of the data point
from the origin and another attribute describes the angle. From the data
visualization engine's point of view, in both cases two \emph{axes} are
involved.
In addition to specifying how the value of a certain attribute is converted
into a displacement on the page, an axis is also typically (but not always)
visualized (``drawn'') somewhere on the page. In this case, it is also
customary to add a visual representation on this axis of which attribute values
correspond to which positions on the page -- something commonly known as
\emph{ticks}. Similar to ticks, \emph{grid lines} also indicate positions where
a certain attribute has a certain value, but instead of just indicating a
single position on an axis, a grid line goes through all points that share an
attribute value.
In the following, in Section~\ref{section-dv-axes-main} we first have a look at
how axes can be defined and configured. As you will see, a lot of powerful
configurations are available, but you will rarely define and configure an axis
from scratch. Rather, it is more common to use a preconfigured axis instead.
Section~\ref{section-dv-axis-systems} introduces \emph{axis systems}, which are
predefined bundles of axes. You can define your own axis systems, but, again,
in most cases it will suffice to just use one of the many preconfigured axis
systems and use a few options to configure it so that it fits your need.
Section~\ref{section-dv-ticks-and-grids} explains how ticks and grid lines can
be configured. Again, several layers of options allow you to configure the way
ticks look and where they are placed in great detail.
This section documents the standard axis systems that are always available. For
polar axis systems, a special library needs to be loaded, which is documented
in Section~\ref{section-dv-polar}.
\subsection{Basic Configuration of Axes}
\label{section-dv-axes-main}
Inside the data visualization system, an \emph{axis} is roughly a ``systematic,
named way of mapping an attribute to a position on a page''. For instance, the
classical ``$x$-axis'' is the ``systematic way of mapping the value of the |x|
attribute of data points to a horizontal position on the page''. An axis is
\emph{not} its visual representation (such as the horizontal line with the
ticks drawn to represent the $x$-axis), but a visual representation can be
created once an axis has been defined.
The transformation of an attribute value (such as the value |1000000000| for
the |x| attribute) to a specific displacement of the corresponding data point
on the page involves two steps:
%
\begin{enumerate}
\item First, the range of possible values such as $[-5.6\cdot
10^{12},7.8\cdot 10^{12}]$ must be mapped to a ``reasonable'' interval
such as $[0\mathrm{cm},5\mathrm{cm}]$ or $[0^\circ,180^\circ]$.
\tikzname's drawing routines will only be able to cope with values from
such a ``reasonable'' interval.
\item Second, the values from the reasonable interval must be mapped to a
transformation.
\end{enumerate}
%
The first step is always the same for all axes, while the second requires
different strategies. For this reason, the command |new axis base| is used to
create a ``basic'' axis that has a ``scaling mapper'', whose job it is to map
the range of values of a specific attribute to a reasonable interval, but such
a basic axis does not define an actual transformation object. For this second
step, additional objects such as a |linear transformer| need to be created
separately.
\subsubsection{Usage}
To create an axis, the key |new axis base| is used first. Since this key does
not create a transformation object, users typically do not use this key
directly. Rather, it is used internally by other keys that create ``real''
axes. These keys are listed in Section~\ref{section-dv-reference-axis-types}.
\begin{key}{/tikz/data visualization/new axis base=\meta{axis name}}
This key defines a new axis for the current data visualization called
\meta{name}. This has two effects:
%
\begin{enumerate}
\item A so called \emph{scaling mapper} is created that will monitor a
certain attribute, rescale it, and map it to another attribute.
(This will be explained in detail in a moment.)
\item The \meta{axis name} is made available as a key that can be used
to configure the axis:
%
\begin{key}{/tikz/data visualization/\meta{axis name}=\meta{options}}
This key becomes available once |new axis base=|meta{axis name}
has been called. It will execute the \meta{options} with the
path prefix |/tikz/data visualization/axis options|.
%
\begin{codeexample}[code only]
[new axis base=my axis,
my axis={attribute=some attribute}]
\end{codeexample}
\end{key}
\item The \meta{axis name} becomes part of the current set of axes.
This set can be accessed through the following key:
%
\begin{key}{/tikz/data visualization/all axes=\meta{options}}
This key passes the \meta{options} to all axes inside the
current scope, just as if you had written \meta{some axis
name}|=|\meta{options} for each \meta{some axis name} in the
current scope, including the just-created name \meta{axis
name}.
\end{key}
\end{enumerate}
%
There are many \meta{options} that can be passed to a newly created axis.
They are explained in the rest of this section.
\end{key}
Note the |new axis base| does \emph{not} cause attributes to be mapped to
positions on a page. Rather, special keys like |new Cartesian axis| first use
|new axis base| to create an axis and then create an internal object that
performs a linear mapping of the attribute to positions along a vectors.
\subsubsection{The Axis Attribute}
\label{section-dv-axis-attribute}
The first main job of an axis is to map the different values of some attribute
to a reasonable interval. To achieve this, the following options are important
(recall that these options are passed to the key whose name is the name of the
axis):
\begin{key}{/tikz/data visualization/axis options/attribute=\meta{attribute}}
Specifies that the axis is used to transform the data points according the
different values of the key |/data point/|\meta{attribute}. For instance,
when we create a classical two-dimensional Cartesian coordinate system,
then there are two axes called |x axis| and |y axis| that monitor the
values of the attributes |/data point/x| and |/data point/y|, respectively:
%
\begin{codeexample}[code only]
[new axis base=x axis,
new axis base=y axis,
x axis={attribute=x},
y axis={attribute=y}]
\end{codeexample}
%
In another example, we also create an |x axis| and a |y axis|. However,
this time, we want to plot the values of the |/data point/time| attribute
on the $x$-axis and, say, the value of the |height| attribute on the
$y$-axis:
%
\begin{codeexample}[code only]
[new axis base=x axis,
new axis base=y axis,
x axis={attribute=time},
y axis={attribute=height}]
\end{codeexample}
%
During the data visualization, the \meta{attribute} will be ``monitored''
during the survey phase. This means that for each data point, the current
value of |/data point/|\meta{attribute} is examined and the minimum value
of all of these values as well as the maximum value is recorded internally.
Note that this works even when very large numbers like |100000000000| are
involved.
Here is a real-life example. The |scientific axes| create two axes, called
|x axis| and |y axis|, respectively.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization [scientific axes,
x axis={attribute=people, length=2.5cm, ticks=few},
y axis={attribute=year},
visualize as scatter]
data {
year, people
1900, 100
1910, 200
1950, 200
1960, 250
2000, 150
};
\end{codeexample}
%
\end{key}
\subsubsection{The Axis Attribute Range Interval}
Once an attribute has been specified for an axis, the data visualization engine
will start monitoring this value. This means that before anything actual
visualization is done, a ``survey phase'' is used to determine the range of
values encountered for the attribute for all data points. This range of values
results in what is called the \emph{attribute range interval}. Its minimum is
the smallest value encountered in the data and its maximum is the largest
value.
Even though the attribute range interval is computed automatically and even
though you typically do not need to worry about it, there are some situations
where you may wish to set or enlarge the attribute range interval:
%
\begin{itemize}
\item You may wish to start the interval with $0$, even though the range of
values contains only positive values.
\item You may wish to slightly enlarge the interval so that, say, the
maximum is some ``nice'' value like |100| or |60|.
\end{itemize}
The following keys can be used to influence the size of the attribute range
interval:
%
\begin{key}{/tikz/data visualization/axis options/include value=\meta{list of value}}
This key ``fakes'' data points for which the attribute's values are in the
comma-separated \meta{list of values}. For instance, when you write
|include value=0|, then the attribute range interval is guaranteed to
contain |0| -- even if the actual data points are all positive or all
negative.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\tikz \datavisualization [scientific axes, all axes={length=3cm},
visualize as line]
data [format=function] {
var x : interval [5:10];
func y = \value x * \value x;
};
\end{codeexample}
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\tikz \datavisualization [scientific axes, all axes={length=3cm},
visualize as line,
x axis={include value=20},
y axis={include value=0}]
data [format=function] {
var x : interval [5:10];
func y = \value x * \value x;
};
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/data visualization/axis options/min value=\meta{value}}
This key allows you to simply set the minimum value, regardless of which
values are present in the actual data. This key should be used with care:
If there are data points for which the attribute's value is less than
\meta{value}, they will still be depicted, but typically outside the normal
visualization area. Usually, saying |include value=|\meta{value} will
achieve the same as saying |min value=|\meta{value}, but with less danger
of creating ill-formed visualizations.
\end{key}
\begin{key}{/tikz/data visualization/axis options/max value=\meta{value}}
Works like |min value|.
\end{key}
\subsubsection{Scaling: The General Mechanism}
The above key allows us specify which attribute should be ``monitored''. The
next key is used to specify what should happen with the observed values.
\begin{key}{/tikz/data visualization/axis options/scaling=\meta{scaling spec}}
The \meta{scaling spec} must have the following form:
%
\begin{quote}
\meta{$s_1$}| at |\meta{$t_1$}| and |\meta{$s_2$}| at |\meta{$t_2$}
\end{quote}
%
This means that monitored values in the interval $[s_1,s_2]$ should be
mapped to values the ``reasonable'' interval $[t_1,t_2]$, instead. For
instance, we might write
%
\begin{codeexample}[code only]
[y axis = {scaling = 1900 at 0cm and 2000 at 5cm}]
\end{codeexample}
%
in order to map dates between 1900 and 2000 to the dimension interval
$[0\mathrm{cm},5\mathrm{cm}]$.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization
[scientific axes,
x axis={attribute=people, length=2.5cm, ticks=few},
y axis={attribute=year, scaling=1900 at 0cm and 2000 at 5cm},
visualize as scatter]
data {
year, people
1900, 100
1910, 200
1950, 200
1960, 250
2000, 150
};
\end{codeexample}
%
So much for the basic idea. Let us now have a detailed look at what
happens.
\medskip
\textbf{Number format and the min and max keywords.}
The source values $s_1$ and $s_2$ are typically just numbers like |3.14| or
|10000000000|. However, as described in
Section~\ref{section-dv-expressions}, you can also specify expressions like
|(pi/2)|, provided that (currently) you put them in parentheses.
Instead of a number, you may alternatively also use the two key words |min|
and |max| for $s_1$ and/or $s_2$. In this case, |min| evaluates to the
smallest value observed for the attribute in the data, symmetrically |max|
evaluates to the largest values. For instance, in the above example with
the |year| attribute ranging from |1900| to |2000|, the keyword |min| would
stand for |1900| and |max| for |2000|. Similarly, for the |people|
attribute |min| stands for |100| and |max| for |250|. Note that |min| and
|max| can only be used for $s_1$ and $s_2$, not for $t_1$ and $t_2$.
A typical use of the |min| and |max| keywords is to say
%
\begin{codeexample}[code only]
scaling = min at 0cm and max at 5cm
\end{codeexample}
%
to map the complete range of values into an interval of length of 5cm.
The interval $[s_1,s_2]$ need not contain all values that the
\meta{attribute} may attain. It is permissible that values are less than
$s_1$ or more than $s_2$.
\medskip
\textbf{Linear transformation of the attribute.}
As indicated earlier, the main job of an axis is to map values from a
``large'' interval $[s_1,s_2]$ to a more reasonable interval $[t_1,t_2]$.
Suppose that for the current data point the value of the key
|/data point/|\meta{attribute} is the number $v$. In the simplest case, the
following happens: A new value $v'$ is computed so that $v' = t_1$ when
$v=s_1$ and $v'=t_2$ when $v=s_2$ and $v'$ is some value in between $t_1$
and $t_2$ then $v$ is some value in between $s_1$ and $s_2$. (Formally, in
this basic case $v' = t_1 + (v-s_1)\frac{t_2-t_1}{s_2-s_1}$.)
Once $v'$ has been computed, it is stored in the key
|/data point/|\meta{attribute}|/scaled|. Thus, the ``reasonable'' value
$v'$ does not replace the value of the attribute, but it is placed in a
different key. This means that both the original value and the more
``scaled'' values are available when the data point is visualized.
As an example, suppose you have written
%
\begin{codeexample}[code only]
[x axis = {attribute = x, scaling=1000 at 20 and 2000 at 30}]
\end{codeexample}
%
Now suppose that |/data point/x| equals |1200| for a data point. Then the
key |/data point/x/scaled| will be set to |22| when the data point is being
visualized.
\medskip
\textbf{Nonlinear transformations of the attribute.}
By default, the transformation of $[s_1,s_2]$ to $[t_1,t_2]$ is the linear
transformation described above. However, in some case you may be interested
in a different kind of transformation: For example, in a logarithmic plot,
values of an attribute may range between, say, |1| and |1000| and we want
an axis of length |3cm|. So, we would write
%
\begin{codeexample}[code only]
[x axis = {attribute = x, scaling=1 at 0cm and 1000 at 3cm}]
\end{codeexample}
%
Indeed, |1| will now be mapped to position |0cm| and |1000| will be mapped
to position |3cm|. Now, the value |10| will be mapped to approximately
|0.03cm| because it is (almost) at one percent between |1| and |1000|.
However, in a logarithmic plot we actually want |10| to be mapped to the
position |1cm| rather than |0.03cm| and we want |100| to be mapped to the
position |2cm|. Such a mapping a \emph{nonlinear} mapping between the
intervals.
In order to achieve such a nonlinear mapping, the |function| key can be
used, whose syntax is described in a moment. The effect of this key is to
specify a function $f \colon \mathbb{R} \to \mathbb{R}$ like, say, the
logarithm function. When such a function is specified, the mapping of $v$
to $v'$ is computed as follows:
%
\begin{align*}
v' = t_1 + (f(s_2) - f(v))\frac{t_2 - t_1}{f(s_2)-f(s_1)}.
\end{align*}
The syntax of the |function| key is described next, but you typically will
not call this key directly. Rather, you will use a key like |logarithmic|
that installs appropriate code for the |function| key for you.
%
\begin{key}{/tikz/data visualization/axis options/function=\meta{code}}
The \meta{code} should specify a function $f$ that is applied during
the transformation of the interval $[s_1,s_2]$ to the interval
$[t_1,t_2]$ in the following way: When the \meta{code} is called, the
macro |\pgfvalue| will have been set to an internal representation of
the to-be-transformed value~$v$. You can then call the commands of the
math-micro-kernel of the data visualization system, see
Section~\ref{section-dv-math-kernel}, to compute a new value. This new
value must once more be stored in |\pgfvalue|.
The most common use of this key is to say
%
\begin{codeexample}[code only]
some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}}
\end{codeexample}
%
This specifies that the function $f$ is the logarithm function.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization
[scientific axes,
x axis={ticks={major={at={1,10,100,1000}}},
scaling=1 at 0cm and 1000 at 3cm,
function=\pgfdvmathln{\pgfvalue}{\pgfvalue}},
visualize as scatter]
data [format=named] {
x={1,100,...,1000}, y={1,2,3}
};
\end{codeexample}
%
Another possibility might be to use the square-root function, instead:
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization
[scientific axes,
x axis={ticks=few,
scaling=1 at 0cm and 1000 at 3cm,
function=\pgfdvmathunaryop{\pgfvalue}{sqrt}{\pgfvalue}},
visualize as scatter]
data [format=named] {
x={0,100,...,1000}, y={1,2,3}
};
\end{codeexample}
\end{key}
\medskip
\textbf{Default scaling.}
When no scaling is specified, it may seem natural to use $[0,1]$ both as
the source and the target interval. However, this would not work when the
logarithm function is used as transformations: In this case the logarithm
of zero would be computed, leading to an error. Indeed, for a logarithmic
axis it is far more natural to use $[1,10]$ as the source interval and
$[0,1]$ as the target interval.
For these reasons, the default value for the |scaling| that is used when no
value is specified explicitly can be set using a special key:
%
\begin{key}{/tikz/data visualization/axis options/scaling/default=\meta{text}}
The \meta{text} is used as |scaling| whenever no other scaling is
specified. This key is mainly used when a transformation function is
set using |function|; normally, you will not use this key directly.
\end{key}
\end{key}
Most of the time, you will not use neither the |scaling| nor the |function| key
directly, but rather you will use one of the following predefined styles
documented in the following.
\subsubsection{Scaling: Logarithmic Axes}
\begin{key}{/tikz/data visualization/axis options/logarithmic}
When this key is used with an axis, three things happen:
%
\begin{enumerate}
\item The transformation |function| of the axis is setup to the
logarithm.
\item The strategy for automatically generating ticks and grid lines is
set to the |exponential strategy|, see
Section~\ref{section-dv-exponential-strategy} for details.
\item The default scaling is setup sensibly.
\end{enumerate}
%
All told, to turn an axis into a logarithmic axis, you just need to add
this option to the axis.
%
\begin{codeexample}[
width=8cm,
preamble={\usetikzlibrary{datavisualization.formats.functions}},
]
\tikz \datavisualization [scientific axes,
x axis={logarithmic},
y axis={logarithmic},
visualize as line]
data [format=function] {
var x : interval [0.01:100];
func y = \value x * \value x;
};
\end{codeexample}
%
Note that this will work with any axis, including, say, the degrees on a
polar axis:
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
\tikz \datavisualization
[new polar axes,
angle axis={logarithmic, scaling=1 at 0 and 90 at 90},
radius axis={scaling=0 at 0cm and 100 at 3cm},
visualize as scatter]
data [format=named] {
angle={1,10,...,90}, radius={1,10,...,100}
};
\end{codeexample}
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
\tikz \datavisualization
[new polar axes,
angle axis={degrees},
radius axis={logarithmic, scaling=1 at 0cm and 100 at 3cm},
visualize as scatter]
data [format=named] {
angle={1,10,...,90}, radius={1,10,...,100}
};
\end{codeexample}
%
\end{key}
\subsubsection{Scaling: Setting the Length or Unit Length}
\begin{key}{/tikz/data visualization/axis options/length=\meta{dimension}}
Sets |scaling| to |min at 0cm and max at |\meta{dimension}. The effect is
that the range of all values of the axis's attribute will be mapped to an
interval of exact length \meta{dimension}.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization [scientific axes,
x axis={length=3cm},
y axis={length=2cm},
all axes={ticks=few},
visualize as line]
data {
x, y
10, 10
20, 20
15, 30
13, 20
};
\end{codeexample}
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization [scientific axes,
x axis={length=3cm},
y axis={length=4cm},
all axes={ticks=few},
visualize as line]
data {
x, y
10, 10
20, 20
15, 30
13, 20
};
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/data visualization/axis options/unit length=\meta{dimension}\opt{| per |\meta{number}| units|}}
Sets |scaling| to |0 at 0cm and 1 at |\meta{dimension}. In other words,
this key allows you to specify how long a single unit should be. This key
is particularly useful when you wish to ensure that the same scaling is
used across multiple axes or pictures.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization [scientific axes,
all axes={ticks=few, unit length=1mm},
visualize as line]
data {
x, y
10, 10
40, 20
15, 30
13, 20
};
\end{codeexample}
%
The optional |per |\meta{number}| units| allows you to apply more drastic
scaling. Suppose that you want to plot a graph where one billion
corresponds to one centimeter. Then the unit length would be need to be set
to a hundredth of a nanometer -- much too small for \TeX\ to handle as a
dimension. In this case, you can write
|unit length=1cm per 1000000000 units|:
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization
[scientific axes,
x axis={unit length=1mm per 1000000000 units, ticks=few},
visualize as line]
data {
x, y
10000000000, 10
40000000000, 20
15000000000, 30
13000000000, 20
};
\end{codeexample}
%
\end{key}
%
\begin{key}{/tikz/data visualization/axis options/power unit length=\meta{dimension}}
This key is used in conjunction with the |logarithmic| setting. It cases
the |scaling| to be set to |1 at 0cm and 10 at |\meta{dimension}. This
causes a ``power unit'', that is, one power of ten in a logarithmic plot,
to get a length of \meta{dimension}. Again, this key is useful for ensuring
that the same scaling is used across multiple axes or pictures.
%
\begin{codeexample}[width=8cm,preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization
[scientific axes,
y axis={logarithmic, power unit length=1mm, grid},
visualize as line]
data {
x, y
0, 0.0000000001
1, 1
2, 100000
3, 100000000000
4, 10000000000000000000000000000000
5, 500000000
6, 5000000000000000000
};
\end{codeexample}
%
\end{key}
\subsubsection{Axis Label}
An axis can have a \emph{label}, which is a textual representation of the
attribute according to which the axis varies the position of the page. You can
set the attribute using the following key:
\begin{key}{/tikz/data visualization/axis options/label=\opt{|\char`\{[|\meta{options}|]|}\meta{text}\opt{|\char`\}|}
(default \normalfont axis's label in math mode)%
}
This key sets the label of an axis to \meta{text}. This text will typically
be placed inside a |node| and the \meta{options} can be used to further
configure the way this node is rendered. The \meta{options} will be
executed with the path prefix |/tikz/data visualization/|, so you need to
say |node style| to configure the styling of a node, see
Section~\ref{section-dv-style}.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\tikz \datavisualization [
scientific axes,
x axis = {label, length=2.5cm},
y axis = {label={[node style={fill=blue!20}]{$x^2$}}},
visualize as smooth line]
data [format=function] {
var x : interval [-3:5];
func y = \value x * \value x;
};
\end{codeexample}
%
\end{key}
Note that using the |label| key does not actually cause a node to be created,
because it is somewhat unclear where the label should be placed. Instead, the
|visualize label| key is used (typically internally by an axis system) to show
the label at some sensible position. This key is documented in
Section~\ref{section-dv-visualize-label}.
\subsubsection{Reference: Axis Types}
\label{section-dv-reference-axis-types}
As explained earlier, when you use |new axis base| to create a new axis, a
powerful scaling and attribute mapping mechanism is installed, but no mapping
of values to positions on the page is performed. For this, a
\emph{transformation object} must be installed. The following keys take care of
this for you. Note, however, that even these keys do not cause a visual
representation of the axis to be added to the visualization -- this is the job
of an axis system, see Section~\ref{section-dv-axis-systems}.
\begin{key}{/tikz/data visualization/new Cartesian axis=\meta{name}}
This key creates a new ``Cartesian'' axis, named \meta{name}. For such an
axis, the (scaled) values of the axis's attribute are transformed into a
displacement on the page along a straight line. The following key is used
to configure in which ``direction'' the axis points:
%
\begin{key}{/tikz/data visualization/axis options/unit vector=\meta{coordinate} (initially {(1pt,0pt)})}
Recall that an axis takes the values of an attribute and rescales them
so that they fit into a ``reasonable'' interval $[t_1,t_2]$. Suppose
that $v'$ is the rescaled dimension in (\TeX) points. Then when the
data point is visualized, the coordinate system will be shifted by $v'$
times the \meta{coordinate}.
As an example, suppose that you have said
|scaling=0 and 10pt and 50 and 20pt|. Then when the underlying
attribute has the value |25|, it will be mapped to a $v'$ of $15$
(because |25| lies in the middle of |0| and |50| and |15pt| lies in the
middle of |10pt| and |20pt|). This, in turn, causes the data point to
be displaced by $15$ times the \meta{coordinate}.
The bottom line is that the \meta{coordinate} should usually denote a
point that is at distance |1pt| from the origin and that points into
the direction of the axis.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\datavisualization
[new Cartesian axis=x axis, x axis={attribute=x},
new Cartesian axis=y axis, y axis={attribute=y},
x axis={unit vector=(0:1pt)},
y axis={unit vector=(60:1pt)},
visualize as scatter]
data {
x, y
0, 0
1, 0
2, 0
1, 1
2, 1
1, 1.5
2, 1.5
};
\end{tikzpicture}
\end{codeexample}
\end{key}
\end{key}
\subsection{Axis Systems}
\label{section-dv-axis-systems}
An \emph{axis system} is, as the name suggests, a whole family of axes that act
in concert. For example, in the ``standard'' axis system there is a horizontal
axis called the $x$-axis that monitors the |x| attribute (by default, you can
change this easily) and a vertical axis called the $y$-axis. Furthermore, a
certain number of ticks are added and labels are placed at sensible positions.
\subsubsection{Usage}
Using an axis system is usually pretty easy: You just specify a key like
|scientific axes| and the necessary axes get initialized with sensible default
values. You can then start to modify these default values, if necessary.
First, you can (and should) set the attributes to which the difference axes
refer. For instance, if the |time| attribute is plotted along the $x$-axis, you
would write
%
\begin{codeexample}[code only]
x axis = {attribute = time}
\end{codeexample}
Second, you may wish to modify the lengths of the axes. For this, you can use
keys like |length| or further keys as described in the references later on.
Third, you may often wish to modify how many ticks and grid lines are shown. By
default, no grid lines are shown, but you can say the following in order to
cause grid lines to be shown:
%
\begin{codeexample}[code only]
all axes={grid}
\end{codeexample}
%
Naturally, instead of |all axes| you can also specify a single axis, causing
only grid lines to be shown for this axis. In order to change the number of
ticks that are shown, you can say
%
\begin{codeexample}[code only]
all axes={ticks=few}
\end{codeexample}
%
or also |many| instead of |few| or even |none|. Far more fine-grained control
over the tick placement and rendering is possible, see
Section~\ref{section-dv-ticks-and-grids} for details.
Fourth, consider adding units (like ``cm'' for centimeters or
``$\mathrm{m}/\mathrm{s}^2$'' for acceleration) to your ticks:
%
\begin{codeexample}[code only]
x axis={ticks={tick unit=cm}}, y axis={ticks={tick unit=m/s^2}}
\end{codeexample}
Finally, consider adding labels to your axes. For this, use the label option:
%
\begin{codeexample}[code only]
x axes={time $t$ (ms)}, y axis={distance $d$ (mm)}
\end{codeexample}
Here is an example that employs most of the above features:
%
\begin{codeexample}[width=8.5cm,preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization [
scientific axes=clean,
x axis={attribute=time, ticks={tick unit=ms},
label={elapsed time}},
y axis={attribute=v, ticks={tick unit=m/s},
label={speed of disc}},
all axes=grid,
visualize as line]
data {
time, v
0, 0
1, 0.001
2, 0.002
3, 0.004
4, 0.0035
5, 0.0085
6, 0.0135
};
\end{codeexample}
\subsubsection{Reference: Scientific Axis Systems}
\begin{key}{/tikz/data visualization/scientific axes=\opt{\meta{options}}}
This key installs a two-dimensional coordinate system based on the
attributes |/data point/x| and |/data point/y|.
%
\begin{codeexample}[
width=7cm,
preamble={\usetikzlibrary{datavisualization.formats.functions}},
]
\begin{tikzpicture}
\datavisualization [scientific axes,
visualize as smooth line]
data [format=function] {
var x : interval [0:100];
func y = sqrt(\value x);
};
\end{tikzpicture}
\end{codeexample}
This axis system is usually a good choice to depict ``arbitrary two
dimensional data''. Because the axes are automatically scaled, you do not
need to worry about how large or small the values will be. The name
|scientific axes| is intended to indicate that this axis system is often
used in scientific publications.
You can use the \meta{options} to fine tune the axis system. The
\meta{options} will be executed with the following path prefix:
%
\begin{codeexample}[code only]
/tikz/data visualization/scientific axes
\end{codeexample}
%
All keys with this prefix can thus be passed as \meta{options}.
This axis system will always distort the relative magnitudes of the units
on the two axis. If you wish the units on both axes to be equal, consider
directly specifying the unit length ``by hand'':
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}
\datavisualization [visualize as smooth line,
scientific axes,
all axes={unit length=1cm per 10 units, ticks={few}}]
data [format=function] {
var x : interval [0:100];
func y = sqrt(\value x);
};
\end{tikzpicture}
\end{codeexample}
The |scientific axes| have the following properties:
%
\begin{itemize}
\item The |x|-values are surveyed and the $x$-axis is then scaled and
shifted so that it has the length specified by the following key.
%
\begin{key}{/tikz/data visualization/scientific axes/width=\meta{dimension} (initially 5cm)}
\end{key}
%
The minimum value is at the left end of the axis and at the canvas
origin. The maximum value is at the right end of the axis. \item
The |y|-values are surveyed and the $y$-axis is then scaled so that
is has the length specified by the following key.
%
\begin{key}{/tikz/data visualization/scientific axes/height=\meta{dimension}}
By default, the |height| is the golden ratio times the |width|.
\end{key}
%
The minimum value is at the bottom of the axis and at the canvas
origin. The maximum value is at the top of the axis.
\item Lines (forming a frame) are depicted at the minimum and maximum
values of the axes in 50\% black.
\end{itemize}
The following keys are executed by default as options: |outer ticks| and
|standard labels|.
You can use the following style to overrule the defaults:
\begin{stylekey}{/tikz/data visualization/every scientific axes}
\end{stylekey}
\end{key}
The keys described in the following can be used to fine-tune the way the
scientific axis system is rendered.
\begin{key}{/tikz/data visualization/scientific axes/outer ticks}
This causes the ticks to be drawn `` on the outside'' of the frame so that
they interfere as little as possible with the data. It is the default.
%
\begin{codeexample}[
width=7cm,
preamble={\usetikzlibrary{datavisualization.formats.functions}},
]
\begin{tikzpicture}
\datavisualization [scientific axes=outer ticks,
visualize as smooth line]
data [format=function] {
var x : interval [-12:12];
func y = \value x*\value x*\value x;
};
\end{tikzpicture}
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/data visualization/scientific axes/inner ticks}
This axis system works like |scientific axes|, only the ticks are on the
``inside'' of the frame.
%
\begin{codeexample}[
width=7cm,
preamble={\usetikzlibrary{datavisualization.formats.functions}},
]
\begin{tikzpicture}
\datavisualization [scientific axes=inner ticks,
visualize as smooth line]
data [format=function] {
var x : interval [-12:12];
func y = \value x*\value x*\value x;
};
\end{tikzpicture}
\end{codeexample}
This axis system is also common in publications, but the ticks tend to
interfere with marks if they are near to the border as can be seen in the
following example:
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\begin{tikzpicture}
\datavisualization [scientific axes={inner ticks, width=3.2cm},
style sheet=cross marks,
visualize as scatter/.list={a,b}]
data [set=a] {
x, y
0, 0
1, 1
0.5, 0.5
2, 1
}
data [set=b] {
x, y
0.05, 0
1.5, 1
0.5, 0.75
2, 0.5
};
\end{tikzpicture}
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/data visualization/scientific axes/clean}
The axes and the ticks are completely removed from the actual data, making
this axis system especially useful for scatter plots, but also for most
other scientific plots.
%
\begin{codeexample}[
width=7.5cm,
preamble={\usetikzlibrary{datavisualization.formats.functions}},
]
\tikz \datavisualization [
scientific axes=clean,
visualize as smooth line]
data [format=function] {
var x : interval [-12:12];
func y = \value x*\value x*\value x;
};
\end{codeexample}
The distance of the axes from the actual plot is given by the padding of
the axes.
\end{key}
For all scientific axis systems, different label placement strategies can be
specified. They are discussed in the following.
\begin{key}{/tikz/data visualization/scientific axes/standard labels}
As the name suggests, this is the standard placement strategy. The label of