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


\section{Creating Data Visualizations}
\label{section-dv-main}
\label{section-dv-main-setup}

\subsection{Overview}

The \todosp{why two labels? The first doesn't seem to be used.} present section
explains how a data visualization is created in \tikzname. For this, you need
to include the |datavisualization| library and then use the command
|\datavisualization| whose syntax is explained in the rest of the present
section. This command is part of the following library:

\begin{tikzlibrary}{datavisualization}
    This library must be loaded if you wish to use the |\datavisualization|
    command. It defines all styles needed to create basic data visualizations;
    additional, more specialized libraries need to be loaded for more advanced
    features.
\end{tikzlibrary}

In order to visualize, you basically need to do three things:
%
\begin{enumerate}
    \item You need to select what kind of plot you would like to have (a
        ``school book plot'' or a ``scientific 2d plot'' or a ``scientific
        spherical plot'' etc.). This is done by passing an option to the
        |\datavisualization| command that selects this kind of plot.
    \item You need to provide data points, which is done using the |data|
        command.
    \item Additionally, you can add options that give you more fine-grained
        control over the way the visualization will look. You can configure the
        number of ticks and grid lines, where the labels are placed, the
        colors, or the fonts. Indeed, since the data visualization engine
        internally uses \tikzname-styles, you can have extremely fine-grained
        control over how a plot will look like.
\end{enumerate}

The syntax of the |\datavisualization| command is designed in such a way that
you only need to provide very few options to create plots that ``look good by
default''.

This section is structured as follows: First, the philosophy behind concepts
like ``data points'', ``axes'', or ``visualizers'' is explained. Each of these
concepts is further detailed in later section. Then, the syntax of the
|\datavisualization| command is covered. The reference sections explain which
predefined plot kinds are available.


\subsection{Concept: Data Points and Data Formats}

As explained in Section~\ref{section-dv-intro-data-points}, data points are the
basic entities that are processed by the data visualization engine. In order to
specify data points, you use the |data| command, whose syntax is explained in
more detail in Section~\ref{section-dv-data-syntax}. The |data| command allows
you to either specify points ``inline'', directly inside your \TeX-file; or you
can specify the name of file that contains the data points.

\medskip
\textbf{Specifying data points.}
Data points can be formatted in different ways. For instance, in the so called
\emph{comma separated values} format, there is one line for each data point and
the different attributes of a data point are separated by commas. Another
common format is to specify data points using the so called \emph{key--value}
format, where on each line the different attributes of a data point are set
using a comma-separated list of strings of the form |attribute=value|.

Here are two examples, where similar data is given in different formats:
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\begin{tikzpicture}
  \datavisualization [school book axes, visualize as smooth line]
    data {
      x, y
      -1.5, 2.25
      -1, 1
      -.5, .25
      0, 0
      .5, .25
      1, 1
      1.5, 2.25
    };
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}
  \datavisualization [school book axes, visualize as smooth line]
    data [format=function] {
      var x : interval [-1.5:1.5] samples 7;
      func y = \value x*\value x;
    };
\end{tikzpicture}
\end{codeexample}

In the first example, no format needed to be specified explicitly since the
default format is the one used for the data following the |data| keyword: A
list of comma-separated values, where each line represents a data point.

\medskip
\textbf{Number accuracy.}\label{section-dv-expressions}
Data visualizations typically demand a much higher accuracy and range of values
than \TeX\ provides: \TeX\ numbers are limited to 13 bits for the integer part
and 16 bits for the fractional part. Because of this, the data visualization
engine does not use \pgfname's standard representation of numbers and \TeX\
dimensions and is does not use the standard parser when reading numbers in a
data point. Instead, the |fpu| library, described in
Section~\ref{section-library-fpu}, is used to handle numbers.

This use of the |fpu| library has several effects that users of the data
visualization system should be aware of:
%
\begin{enumerate}
    \item You can use numbers like |100000000000000| or |0.00000000001| in a
        data points.
    \item Since the |fpu| library does not support advanced parsing, you
        currently \emph{cannot} write things like |3+2| in a data point number.
        This will result in an error.
    \item However, there is a loop-hole: If a ``number'' in a data point starts
        with a parenthesis, the value between the parentheses \emph{is} parsed
        using the normal parser:
        %
        \begin{itemize}
            \item |100000| is allowed.
            \item |2+3| yields an error.
            \item |(2+3)| is allowed and evaluates to |5|.
            \item |(100000)| yields an error since $100\,000$ is beyond the
                normal parser's precision.
        \end{itemize}
        %
        The bottom line is that any normal calculations should be set inside
        round parentheses, while large numbers should not be surrounded by
        parentheses. Hopefully, in the future, these restrictions will be
        lifted.
\end{enumerate}

Section~\ref{section-dv-formats} gives an in-depth coverage of the available
data formats and explains how new data formats can be defined.


\subsection{Concept: Axes, Ticks, and Grids}

Most plots have two or three axes: A horizontal axis usually called the
$x$-axis, a vertical axis called the $y$-axis, and possibly some axis pointing
in a sloped direction called the $z$-axis. Axes are usually drawn as lines with
\emph{ticks} indicating interesting positions on the axes. The data
visualization engine gives you detailed control over where these ticks are
rendered and how many of them are used. Great care is taken to ensure that the
position of ticks are chosen well by default.

From the point of view of the data visualization engine, axes are a somewhat
more general concept than ``just'' lines that point ``along'' some dimension:
The data visualization engine uses axes to visualize any change of an attribute
by varying the position of data points in the plane. For instance, in a polar
plot, there is an ``axis'' for the angle and another ``axis'' for the distance
if the point from the center. Clearly these axes vary the position of data
points in the plane according to some attribute of the data points; but just as
clearly they do not point in any ``direction''.

A great benefit of this approach is that the powerful methods for specifying
and automatic inference of ``good'' positions for ticks or grid lines apply to
all sorts of situations. For instance, you can use it to automatically put
ticks and grid lines at well-chosen angles of a polar plot.

Typically, you will not need to specify axes explicitly. Rather, predefined
styles take care of this for you:
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}
  \datavisualization [
    scientific axes,
    x axis={length=3cm, ticks=few},
    visualize as smooth line
  ]
    data [format=function] {
      var x : interval [-1.5:1.5] samples 7;
      func y = \value x*\value x;
    };
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}
  \datavisualization [
    scientific axes=clean,
    x axis={length=3cm, ticks=few},
    all axes={grid},
    visualize as smooth line
  ]
    data [format=function] {
      var x : interval [-1.5:1.5] samples 7;
      func y = \value x*\value x;
    };
\end{tikzpicture}
\end{codeexample}

Section~\ref{section-dv-axes} explains in more detail how axes, ticks, and grid
lines can be chosen and configured.


\subsection{Concept: Visualizers}

Data points and axes specify \emph{what} is visualized and \emph{where}. A
\emph{visualizer} specifies \emph{how} they are visualized. One of the most
common visualizers is a \emph{line visualizer} which connects the positions of
the data points in the plane using a line. Another common visualizer is the
\emph{scatter plot visualizer} where small marks are drawn at the positions of
the data points. More advanced visualizers include, say, box plot visualizers
or pie chart visualizers.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}
  \datavisualization [
    scientific axes=clean,
    x axis={length=3cm, ticks=few},
    visualize as smooth line
  ]
    data [format=function] {
      var x : interval [-1.5:1.5] samples 7;
      func y = \value x*\value x;
    };
\end{tikzpicture}
\end{codeexample}
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}
  \datavisualization [
    scientific axes=clean,
    x axis={length=3cm, ticks=few},
    visualize as scatter
  ]
    data [format=function] {
      var x : interval [-1.5:1.5] samples 7;
      func y = \value x*\value x;
    };
\end{tikzpicture}
\end{codeexample}

Section~\ref{section-dv-visualizers} provides more information on visualizers
as well as reference lists.


\subsection{Concept: Style Sheets and Legends}

A single data visualizations may use more than one visualizer. For instance, if
you wish to create a plot containing several lines, a separate visualizer is
used for each line. In this case, two problems arise:
%
\begin{enumerate}
    \item You may wish to make it easy for the reader to differentiate between
        the different visualizers. For instance, one line should be black,
        another should be red, and another blue. Alternatively, you might wish
        one line to be solid, another to be dashed, and a third to be dotted.

        Specifying such styles is trickier than one might expect; experience
        shows that many plots use ill-chosen and inconsistent styling. For this
        reason, the data visualization introduces the notion of \emph{style
        sheets} for visualizers and comes with some well-designed predefined
        style sheets.
    \item You may wish to add information concerning what the different
        visualizers represent. This is typically done using a legend, but it is
        even better to add labels directly inside the visualization. Both
        approaches are supported.
\end{enumerate}

An example where three functions are plotted and a legend is added is shown
below. Two style sheets are used so that \emph{both} the coloring and the
dashing is varied.
%
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}[baseline]
  \datavisualization [ scientific axes=clean,
                       y axis=grid,
                       visualize as smooth line/.list={sin,cos,tan},
                       style sheet=strong colors,
                       style sheet=vary dashing,
                       sin={label in legend={text=$\sin x$}},
                       cos={label in legend={text=$\cos x$}},
                       tan={label in legend={text=$\tan x$}},
                       data/format=function ]
  data [set=sin] {
    var x : interval [-0.5*pi:4];
    func y = sin(\value x r);
  }
  data [set=cos] {
    var x : interval [-0.5*pi:4];
    func y = cos(\value x r);
  }
  data [set=tan] {
    var x : interval [-0.3*pi:.3*pi];
    func y = tan(\value x r);
  };
\end{tikzpicture}
\end{codeexample}

Section~\ref{section-dv-style-sheets} details style sheets and legends.


\subsection{Usage}
\label{section-dv-data-syntax}

Inside a \tikzname\ picture you can use the |\datavisualization| command to
create a data visualization. You can use this command several times in a
picture to create pictures containing multiple data visualizations.

\begin{command}{\datavisualization\opt{\oarg{data visualization options}}\meta{data specification}|;|}
    This command is available only inside a |{tikzpicture}| environment.

    The \meta{data visualization options} are used to configure the data
    visualization, that is, how the data is to be depicted. The options are
    executed with the path prefix |/tikz/data visualization|. This means that
    normal \tikzname\ options like |thin| or |red| cannot be used here. Rather,
    a large number of options specific to data visualizations are available.

    As a minimum, you should specify at least two options: First, you should
    use an option that selects an axis system that is appropriate for your
    plot. Typical possible keys are |school book axes| or |scientific axes|,
    detailed information on them can be found in Section~\ref{section-dv-axes}.

    Second, you use an option to select \emph{how} the data should be
    visualized. This is done using a key like |visualize as line| which will,
    as the name suggests, visualize the data by connecting data points in the
    plane using a line. Similarly, |visualize as smooth cycle| will try to fit
    a smooth cycle through the data points. Detailed information on possible
    visualizers can be found in Section~\ref{section-dv-visualizers}.

    Following these options, the \meta{data specification} is used to provide
    the actual to-be-visualized data. The syntax is somewhat similar to
    commands like |\path|: The \meta{data specification} is a sequence of
    keywords followed by local options and parameters, terminated with a
    semicolon. (Indeed, like for the |\path| command, the \meta{data
    visualizers options} need not be specified at the beginning, but additional
    option surrounded by square brackets may be given anywhere inside the
    \meta{data specification}.)

    The different possible keywords inside the \meta{data specification} are
    explained in the following.
\end{command}

\begin{datavisualizationoperation}{data}{\opt{\oarg{options}}\opt{\marg{inline data}}}
    This command is used to specify data for the data visualization. It can be
    used several times inside a single visualization and each time the
    to-be-read data may have a different format, but the data will be
    visualized as if it have been specified inside a single |data| command.

    The behavior of the |data| command depends on whether the \meta{inline
    data} is present. If it is not present, the \meta{options} must be used to
    specify a source file from which the data is read; if the \meta{inline
    data} is present no file will be used, instead the data should directly
    reside inside the \TeX-file and be given between the curly braces
    surrounding the \meta{inline data}.

    The \meta{options} are executed with the prefix |/pgf/data|. The following
    options are always available:
    %
    \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)}
        If you set the |source| attribute to a non-empty \meta{filename}, the
        data will be read from this file. In this case, no \meta{inline data}
        may be present, not even empty curly braces should be provided.
        %
\begin{codeexample}[code only]
\datavisualization ...
  data [read from file=file1.csv]
  data [read from file=file2.csv];
\end{codeexample}
        %
        The other way round, if |read from file| is empty, the  data must
        directly follow as \meta{inline data}.
        %
\begin{codeexample}[code only]
\datavisualization ...
  data {
    x, y
    1, 2
    2, 3
  };
\end{codeexample}
    \end{key}
    %
    The second important key is |format|, which is used to specify the data
    format:
    %
    \begin{key}{/pgf/data/format=\meta{format} (initially table)}
        Use this key to locally set the format used for parsing the data, see
        Section~\ref{section-dv-formats} for a list of predefined formats.

        The default format is the |table|-format, also known as
        ``comma-separated values''. The first line contains names of attributes
        separated by commas, all following lines constitute a data point where
        the attributes are given by the comma-separated values in that line.
    \end{key}


    \medskip
    \textbf{Presetting attributes.}
    Normally, the inline data or the external data contains for each data point
    the values of the different attributes. However, sometimes you may also
    wish to set an attribute to a fixed value for all data points of a data
    set. Suppose, for instance, that you have to source files
    |experiment007.csv| and |experiment023.csv| and you would like that for all
    data points of the first file the attribute |/data point/experiment id| is
    set to 7 while for the data points of the second file they are set to 23.
    In this case, you can specify the desired settings using an absolute path
    inside the \meta{options}. The effect will be local to the current |data|
    command:
    %
\begin{codeexample}[code only]
\datavisualization...
  data [/data point/experiment=7,  read from file=experiment007.csv]
  data [/data point/experiment=23, read from file=experiment023.csv];
\end{codeexample}

\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz
  \datavisualization [school book axes, visualize as line]
    data [/data point/x=1] {
      y
      1
      2
    }
    data [/data point/x=2] {
      y
      2
      0.5
    };
\end{codeexample}


    \medskip
    \textbf{Setting options for multiple |data| commands.}
    You may wish to generally set the format once and for all. This can be done
    by using the following key:
    %
    \begin{stylekey}{/tikz/every data}
        This key is executed for every |data| command.
    \end{stylekey}

    Another way of passing options to multiple |data| commands is to use the
    following facility: Whenever an option with the path
    |/tikz/data visualization/data| is used, the path will be remapped to
    |/pgf/data|. This means, in particular, that you can pass an option like
    |data/format=table| to the |\datavisualization| command to set the data
    format for all |data| commands of the data visualization.


    \medskip
    \textbf{Parsing inline data.}
    When you specify data inline, \TeX\ needs to read the data
    ``line-by-line'', while \TeX\ normally largely ignores end-of-line
    characters. For this reason, the data visualization system temporarily
    changes the meaning of the end-of-line character. This is only possible if
    \TeX\ has not already processed the data in some other way (namely as the
    parameter to some macro).

    The bottom line is that you cannot use inline data when the whole
    |\datavisualization| command is passed as a parameter to some macro that is
    not setup to handle ``fragile'' code. For instance, in a \textsc{beamer}
    |frame| you need to add the |fragile| option when a data visualization
    contains inline data.

    The problem does not arise when an external data |source| is specified.
\end{datavisualizationoperation}

\begin{datavisualizationoperation}{data point}{\opt{\oarg{options}}}
    This command is used to specify data a single data point. The
    \meta{options} are simply executed with the path |/data point| and then a
    data point is created. This means that inside the \meta{options} you just
    specify the values of all attributes in key--value syntax.
    %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization [school book axes, visualize as line]
  data point [x=1, y=1]    data point [x=1, y=2]
  data point [x=2, y=2]    data point [x=2, y=0.5];
\end{codeexample}
    %
\end{datavisualizationoperation}

\begin{key}{/tikz/data visualization/data point=\meta{options}}
    This key is the ``key version'' of the previous command. The difference is
    that this key can be used internally inside styles.
    %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikzdatavisualizationset{
  horizontal/.style={
    data point={x=#1, y=1}, data point={x=#1, y=2}},
}
\tikz \datavisualization
[ school book axes, visualize as line,
  horizontal=1,
  horizontal=2 ];
\end{codeexample}
    %
\end{key}

\begin{datavisualizationoperation}{data group}{\opt{\oarg{options}}\marg{name}\opt{|+=|\marg{data specifications}}}
    You can store a whole \meta{data specification} in a \emph{data group}.
    This allows you to reuse data in multiple places without having to write
    the data to an external file.

    The syntax of this command comes in the following three variants:
    %
    \begin{itemize}
        \item |data group| \opt{\oarg{options}} \marg{name} |=| \marg{data
            specifications}
        \item |data group| \opt{\oarg{options}} \marg{name} |+=| \marg{data
            specifications}
        \item |data group| \opt{\oarg{options}} \marg{name}
    \end{itemize}
    %
    In the first case, a new data group called \meta{name} is created (an
    existing data group of the same name will be erased) and the following
    \meta{data specifications} is stored in this data group. The data group
    will not be fed to the rendering pipeline, but it is parsed at this point
    as if it were. The defined data group is defined globally, so you can used
    it in subsequent visualizations. The \meta{options} are saved with the
    parsed \meta{data specifications}.

    In the second case, an already existing data group is extended by adding
    the \meta{data specifications} to it.

    In the third case (detected by noting that the \meta{name} is neither
    followed by an equal sign nor a plus sign), the contents of the previously
    defined data group \meta{name} is inserted. The \meta{options} are also
    executed.

    Let is now first create a data group. Note that nothing is drawn since the
    ``dummy'' data visualization is empty and used only for the definition of
    the data group.
    %
\begin{codeexample}[setup code]
\tikz \datavisualization data group {points} = {
  data {
    x, y
    0, 1
    1, 2
    2, 2
    5, 1
    2, 0
    1, 1
  }
};
\end{codeexample}

    We can now use this data in different plots:
    %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
\tikz \datavisualization [school book axes,      visualize as line] data group {points};
\qquad
\tikz \datavisualization [scientific axes=clean, visualize as line] data group {points};
\end{codeexample}
    %
\end{datavisualizationoperation}

\begin{datavisualizationoperation}{scope}{\opt{\oarg{options}}\marg{data specification}}
    Scopes can be used to nest hierarchical data sets. The \meta{options} will
    be executed with the path |/pgf/data| and will only apply to the data sets
    specified inside the \meta{data specification}, which may contain |data| or
    |scope| commands once more:
    %
\begin{codeexample}[code only]
\datavisualization...
  scope [/data point/experiment=7]
  {
    data [read from file=experiment007-part1.csv]
    data [read from file=experiment007-part2.csv]
    data [read from file=experiment007-part3.csv]
  }
  scope [/data point/experiment=23, format=foo]
  {
    data [read from file=experiment023-part1.foo]
    data [read from file=experiment023-part2.foo]
  };
\end{codeexample}
    %
\end{datavisualizationoperation}

\begin{datavisualizationoperation}{info}{\opt{\oarg{options}}\marg{code}}
    This command will execute normal \tikzname\ \meta{code} at the end of a
    data visualization. The \meta{options} are executed with the normal path
    |/tikz/|.

    The only difference between this command and just giving the \meta{code}
    directly following the data visualization is that inside the \meta{code}
    following an |info| command you still have access to the coordinate system
    of the data visualization. In sharp contrast, \tikzname\ code given after a
    data visualization can no longer access this coordinate system.
    %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}[baseline]
  \datavisualization [ school book axes, visualize as line ]
  data [format=function] {
    var x : interval [-0.1*pi:2];
    func y = sin(\value x r);
  }
  info {
    \draw [red] (visualization cs: x={(.5*pi)}, y=1) circle [radius=1pt]
      node [above,font=\footnotesize] {extremal point};
  };
\end{tikzpicture}
\end{codeexample}

    As can be seen, inside a data visualization a special coordinate system is
    available:

    \begin{coordinatesystem}{visualization}
        As for other coordinate systems, the syntax is
        \declare{|(visualization cs:|\meta{list of attribute-value pairs}|)|}.
        The effect is the following: For each pair
        \meta{attribute}|=|\meta{value} in the \meta{list} the key
        |/data point/|\meta{attribute} is set to \meta{value}. Then, it is
        computed where the resulting data point ``would lie'' on the canvas
        (however, no data point is passed to the visualizers).
    \end{coordinatesystem}
\end{datavisualizationoperation}

\begin{datavisualizationoperation}{info'}{\opt{\oarg{options}}\marg{code}}
    This command works like |info|, only the \meta{code} will be executed just
    before the visualization is done. This allows you to draw things
    \emph{behind} the visualization.
    %
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
\begin{tikzpicture}[baseline]
  \datavisualization [ school book axes, visualize as line ]
  data [format=function] {
    var x : interval [-0.1*pi:2];
    func y = sin(\value x r);
  }
  info' {
    \fill [red] (visualization cs: x={(.5*pi)}, y=1) circle [radius=2mm];
  };
\end{tikzpicture}
\end{codeexample}
    %
\end{datavisualizationoperation}

\label{section-dv-bounding-box}%
\begin{predefinednode}{data visualization bounding box}
    This rectangle node stores a bounding box of the data visualization that is
    currently being constructed. This node can be useful inside |info| commands
    or when labels need to be added.
\end{predefinednode}

\begin{predefinednode}{data bounding box}
    This rectangle node is similar to |data visualization bounding box|, but it
    keeps track only of the actual data. The spaces needed for grid lines,
    ticks, axis labels, tick labels, and other all other information that is
    not part of the actual data is not part of this box.
\end{predefinednode}


\subsection{Advanced: Executing User Code During a Data Visualization}
\label{section-dv-user-code}

The following keys can be passed to the |\datavisualization| command and allow
you to execute some code at some special time during the data visualization
process. For details of the process and on which signals are emitted when, see
Section~\ref{section-dv-backend}.

\begin{key}{/tikz/data visualization/before survey=\meta{code}}
    The \meta{code} is passed to the |before survey| method of the data
    visualization object and then executed at the appropriate time (see
    Section~\ref{section-dv-backend} for details).

    The following commands work likewise:
\end{key}
%
\begin{key}{/tikz/data visualization/at start survey=\meta{code}}
\end{key}
%
\begin{key}{/tikz/data visualization/at end survey=\meta{code}}
\end{key}
%
\begin{key}{/tikz/data visualization/after survey=\meta{code}}
\end{key}
%
\begin{key}{/tikz/data visualization/before visualization=\meta{code}}
\end{key}
%
\begin{key}{/tikz/data visualization/at start visualization=\meta{code}}
\end{key}
%
\begin{key}{/tikz/data visualization/at end visualization=\meta{code}}
\end{key}
%
\begin{key}{/tikz/data visualization/after visualization=\meta{code}}
\end{key}


\subsection{Advanced: Creating New Objects}

You will need the following key only when you wish to create new rendering
pipelines from scratch -- instead of modifying an existing pipeline as you
would normally do. In the following it is assumed that you are familiar with
the concepts of Section~\ref{section-dv-backend}.

\begin{key}{/tikz/data visualization/new object=\meta{options}}
    This key serves two purposes:
    %
    \begin{enumerate}
        \item This method makes it easy to create a new object as part of the
            rendering pipeline, using \meta{options} to specify arguments
            rather that directly calling |\pgfoonew|. Since you have the full
            power of the keys mechanism at your disposal, it is easy, for
            instance, to control whether or not parameters to the constructor
            are expanded or not.
        \item The object is not created immediately, but only just before the
            visualization starts. This allows you to specify that an object
            must be created, but the parameter values of for its constructor
            may depend on keys that are not yet set. A typical application is
            the creating of an axis object: When you say |scientific axes|, the
            |new object| command is used internally to create two objects
            representing these axes. However, keys like |x={length=5cm}| can
            only \emph{later} be used to specify the parameters that need to be
            passed to the constructor of the objects.
  \end{enumerate}

    The following keys may be used inside the \meta{options}:
    %
    \begin{key}{/tikz/data visualization/class=\meta{class name}}
        The class of the to-be-created object.
    \end{key}
    %
    \begin{key}{/tikz/data visualization/when=\meta{phase name} (initially before survey)}
        This key is used to specify when the object is to be created. As
        described above, the object is not created immediately, but at some
        time during the rendering process. You can specify any of the phases
        defined by the data visualization object, see
        Section~\ref{section-dv-backend} for details.
    \end{key}
    %
    \begin{key}{/tikz/data visualization/store=\meta{key name}}
        If the \meta{key name} is not empty, once the object has been created,
        a handle to the object will be stored in \meta{key name}. If a handle
        is already stored in \meta{key name}, the object is not created twice.
    \end{key}
    %
    \begin{key}{/tikz/data visualization/before creation=\meta{code}}
        This code is executed right before the object is finally created. It
        can be used to compute values that are then passed to the constructor.
    \end{key}
    %
    \begin{key}{/tikz/data visualization/after creation=\meta{code}}
        This code is executed right after the object has just been created. A
        handle to the just-created object is available in |\tikzdvobj|.
    \end{key}
    %
    \begin{key}{/tikz/data visualization/arg1=\meta{value}}
        The value to be passed as the first parameter to the constructor.
        Similarly, the keys |arg2| to |arg8| specify further parameters passed.
        Naturally, only as many arguments are passed as parameters are set.
        Here is an example:
        %
\begin{codeexample}[code only]
\tikzdatavisualizationset{
  new object={
    class = example class,
    arg1  = foo,
    arg2  = \bar
  }
}
\end{codeexample}
        %
        causes the following object creation code to be executed later on:
        %
\begin{codeexample}[code only]
\pgfoonew \tikzdvobj=new example class(foo,\bar)
\end{codeexample}
        %
        Note that you key mechanisms like |.expand once| to pass the value of a
        macro instead of the macro itself:
        %
\begin{codeexample}[code only]
\tikzdatavisualizationset{
  new object={
    class              = example class,
    arg1               = foo,
    arg2/.expand once  = \bar
  }
}
\end{codeexample}
        %
        Now, if |\bar| is set to |This \emph{is} it.|\@ at the moment to object
        is created later on, the following object creation code is executed:
        %
\begin{codeexample}[code only]
\pgfoonew \tikzdvobj=new example class(foo,This \emph{is} it)
\end{codeexample}
    \end{key}

    \begin{key}{/tikz/data visualization/arg1 from key=\meta{key}}
        Works like the |arg1|, only the value that is passed to the constructor
        is the current value of the specified \meta{key} at the moment when the
        object is created.
        %
\begin{codeexample}[code only]
\tikzdatavisualizationset{
  new object={
    class              = example class,
    arg1 from key      = /tikz/some key
  }
}
\tikzset{some key/.initial=foobar}
\end{codeexample}
        %
        causes the following to be executed:
        %
\begin{codeexample}[code only]
\pgfoonew \tikzdvobj=new example class(foobar)
\end{codeexample}
        %
        Naturally, the keys |arg2 from key| to |arg8 from key| are also
        provided.
    \end{key}

    \begin{key}{/tikz/data visualization/arg1 handle from key=\meta{key}}
        Works like the |arg1 from key|, only the key must store an object and
        instead of the object a handle to the object is passed to the
        constructor.
    \end{key}
\end{key}