Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-dv-main.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{Creating Data Visualizations}
12 \label{section-dv-main}
13 \label{section-dv-main-setup}
14
15 \subsection{Overview}
16
17 The \todosp{why two labels? The first doesn't seem to be used.} present section
18 explains how a data visualization is created in \tikzname. For this, you need
19 to include the |datavisualization| library and then use the command
20 |\datavisualization| whose syntax is explained in the rest of the present
21 section. This command is part of the following library:
22
23 \begin{tikzlibrary}{datavisualization}
24 This library must be loaded if you wish to use the |\datavisualization|
25 command. It defines all styles needed to create basic data visualizations;
26 additional, more specialized libraries need to be loaded for more advanced
27 features.
28 \end{tikzlibrary}
29
30 In order to visualize, you basically need to do three things:
31 %
32 \begin{enumerate}
33 \item You need to select what kind of plot you would like to have (a
34 ``school book plot'' or a ``scientific 2d plot'' or a ``scientific
35 spherical plot'' etc.). This is done by passing an option to the
36 |\datavisualization| command that selects this kind of plot.
37 \item You need to provide data points, which is done using the |data|
38 command.
39 \item Additionally, you can add options that give you more fine-grained
40 control over the way the visualization will look. You can configure the
41 number of ticks and grid lines, where the labels are placed, the
42 colors, or the fonts. Indeed, since the data visualization engine
43 internally uses \tikzname-styles, you can have extremely fine-grained
44 control over how a plot will look like.
45 \end{enumerate}
46
47 The syntax of the |\datavisualization| command is designed in such a way that
48 you only need to provide very few options to create plots that ``look good by
49 default''.
50
51 This section is structured as follows: First, the philosophy behind concepts
52 like ``data points'', ``axes'', or ``visualizers'' is explained. Each of these
53 concepts is further detailed in later section. Then, the syntax of the
54 |\datavisualization| command is covered. The reference sections explain which
55 predefined plot kinds are available.
56
57
58 \subsection{Concept: Data Points and Data Formats}
59
60 As explained in Section~\ref{section-dv-intro-data-points}, data points are the
61 basic entities that are processed by the data visualization engine. In order to
62 specify data points, you use the |data| command, whose syntax is explained in
63 more detail in Section~\ref{section-dv-data-syntax}. The |data| command allows
64 you to either specify points ``inline'', directly inside your \TeX-file; or you
65 can specify the name of file that contains the data points.
66
67 \medskip
68 \textbf{Specifying data points.}
69 Data points can be formatted in different ways. For instance, in the so called
70 \emph{comma separated values} format, there is one line for each data point and
71 the different attributes of a data point are separated by commas. Another
72 common format is to specify data points using the so called \emph{key--value}
73 format, where on each line the different attributes of a data point are set
74 using a comma-separated list of strings of the form |attribute=value|.
75
76 Here are two examples, where similar data is given in different formats:
77 %
78 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
79 \begin{tikzpicture}
80 \datavisualization [school book axes, visualize as smooth line]
81 data {
82 x, y
83 -1.5, 2.25
84 -1, 1
85 -.5, .25
86 0, 0
87 .5, .25
88 1, 1
89 1.5, 2.25
90 };
91 \end{tikzpicture}
92 \end{codeexample}
93
94 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
95 \begin{tikzpicture}
96 \datavisualization [school book axes, visualize as smooth line]
97 data [format=function] {
98 var x : interval [-1.5:1.5] samples 7;
99 func y = \value x*\value x;
100 };
101 \end{tikzpicture}
102 \end{codeexample}
103
104 In the first example, no format needed to be specified explicitly since the
105 default format is the one used for the data following the |data| keyword: A
106 list of comma-separated values, where each line represents a data point.
107
108 \medskip
109 \textbf{Number accuracy.}\label{section-dv-expressions}
110 Data visualizations typically demand a much higher accuracy and range of values
111 than \TeX\ provides: \TeX\ numbers are limited to 13 bits for the integer part
112 and 16 bits for the fractional part. Because of this, the data visualization
113 engine does not use \pgfname's standard representation of numbers and \TeX\
114 dimensions and does not use the standard parser when reading numbers in a
115 data point. Instead, the |fpu| library, described in
116 Section~\ref{section-library-fpu}, is used to handle numbers.
117
118 This use of the |fpu| library has several effects that users of the data
119 visualization system should be aware of:
120 %
121 \begin{enumerate}
122 \item You can use numbers like |100000000000000| or |0.00000000001| in
123 data points.
124 \item Since the |fpu| library does not support advanced parsing, you
125 currently \emph{cannot} write things like |3+2| in a data point number.
126 This will result in an error.
127 \item However, there is a loop-hole: If a ``number'' in a data point starts
128 with a parenthesis, the value between the parentheses \emph{is} parsed
129 using the normal parser:
130 %
131 \begin{itemize}
132 \item |100000| is allowed.
133 \item |2+3| yields an error.
134 \item |(2+3)| is allowed and evaluates to |5|.
135 \item |(100000)| yields an error since $100\,000$ is beyond the
136 normal parser's precision.
137 \end{itemize}
138 %
139 The bottom line is that any normal calculations should be set inside
140 round parentheses, while large numbers should not be surrounded by
141 parentheses. Hopefully, in the future, these restrictions will be
142 lifted.
143 \end{enumerate}
144
145 Section~\ref{section-dv-formats} gives an in-depth coverage of the available
146 data formats and explains how new data formats can be defined.
147
148
149 \subsection{Concept: Axes, Ticks, and Grids}
150
151 Most plots have two or three axes: A horizontal axis usually called the
152 $x$-axis, a vertical axis called the $y$-axis, and possibly some axis pointing
153 in a sloped direction called the $z$-axis. Axes are usually drawn as lines with
154 \emph{ticks} indicating interesting positions on the axes. The data
155 visualization engine gives you detailed control over where these ticks are
156 rendered and how many of them are used. Great care is taken to ensure that the
157 position of ticks are chosen well by default.
158
159 From the point of view of the data visualization engine, axes are a somewhat
160 more general concept than ``just'' lines that point ``along'' some dimension:
161 The data visualization engine uses axes to visualize any change of an attribute
162 by varying the position of data points in the plane. For instance, in a polar
163 plot, there is an ``axis'' for the angle and another ``axis'' for the distance
164 if the point from the center. Clearly these axes vary the position of data
165 points in the plane according to some attribute of the data points; but just as
166 clearly they do not point in any ``direction''.
167
168 A great benefit of this approach is that the powerful methods for specifying
169 and automatic inference of ``good'' positions for ticks or grid lines apply to
170 all sorts of situations. For instance, you can use it to automatically put
171 ticks and grid lines at well-chosen angles of a polar plot.
172
173 Typically, you will not need to specify axes explicitly. Rather, predefined
174 styles take care of this for you:
175 %
176 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
177 \begin{tikzpicture}
178 \datavisualization [
179 scientific axes,
180 x axis={length=3cm, ticks=few},
181 visualize as smooth line
182 ]
183 data [format=function] {
184 var x : interval [-1.5:1.5] samples 7;
185 func y = \value x*\value x;
186 };
187 \end{tikzpicture}
188 \end{codeexample}
189
190 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
191 \begin{tikzpicture}
192 \datavisualization [
193 scientific axes=clean,
194 x axis={length=3cm, ticks=few},
195 all axes={grid},
196 visualize as smooth line
197 ]
198 data [format=function] {
199 var x : interval [-1.5:1.5] samples 7;
200 func y = \value x*\value x;
201 };
202 \end{tikzpicture}
203 \end{codeexample}
204
205 Section~\ref{section-dv-axes} explains in more detail how axes, ticks, and grid
206 lines can be chosen and configured.
207
208
209 \subsection{Concept: Visualizers}
210
211 Data points and axes specify \emph{what} is visualized and \emph{where}. A
212 \emph{visualizer} specifies \emph{how} they are visualized. One of the most
213 common visualizers is a \emph{line visualizer} which connects the positions of
214 the data points in the plane using a line. Another common visualizer is the
215 \emph{scatter plot visualizer} where small marks are drawn at the positions of
216 the data points. More advanced visualizers include, say, box plot visualizers
217 or pie chart visualizers.
218 %
219 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
220 \begin{tikzpicture}
221 \datavisualization [
222 scientific axes=clean,
223 x axis={length=3cm, ticks=few},
224 visualize as smooth line
225 ]
226 data [format=function] {
227 var x : interval [-1.5:1.5] samples 7;
228 func y = \value x*\value x;
229 };
230 \end{tikzpicture}
231 \end{codeexample}
232 %
233 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
234 \begin{tikzpicture}
235 \datavisualization [
236 scientific axes=clean,
237 x axis={length=3cm, ticks=few},
238 visualize as scatter
239 ]
240 data [format=function] {
241 var x : interval [-1.5:1.5] samples 7;
242 func y = \value x*\value x;
243 };
244 \end{tikzpicture}
245 \end{codeexample}
246
247 Section~\ref{section-dv-visualizers} provides more information on visualizers
248 as well as reference lists.
249
250
251 \subsection{Concept: Style Sheets and Legends}
252
253 A single data visualizations may use more than one visualizer. For instance, if
254 you wish to create a plot containing several lines, a separate visualizer is
255 used for each line. In this case, two problems arise:
256 %
257 \begin{enumerate}
258 \item You may wish to make it easy for the reader to differentiate between
259 the different visualizers. For instance, one line should be black,
260 another should be red, and another blue. Alternatively, you might wish
261 one line to be solid, another to be dashed, and a third to be dotted.
262
263 Specifying such styles is trickier than one might expect; experience
264 shows that many plots use ill-chosen and inconsistent styling. For this
265 reason, the data visualization introduces the notion of \emph{style
266 sheets} for visualizers and comes with some well-designed predefined
267 style sheets.
268 \item You may wish to add information concerning what the different
269 visualizers represent. This is typically done using a legend, but it is
270 even better to add labels directly inside the visualization. Both
271 approaches are supported.
272 \end{enumerate}
273
274 An example where three functions are plotted and a legend is added is shown
275 below. Two style sheets are used so that \emph{both} the coloring and the
276 dashing is varied.
277 %
278 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
279 \begin{tikzpicture}[baseline]
280 \datavisualization [ scientific axes=clean,
281 y axis=grid,
282 visualize as smooth line/.list={sin,cos,tan},
283 style sheet=strong colors,
284 style sheet=vary dashing,
285 sin={label in legend={text=$\sin x$}},
286 cos={label in legend={text=$\cos x$}},
287 tan={label in legend={text=$\tan x$}},
288 data/format=function ]
289 data [set=sin] {
290 var x : interval [-0.5*pi:4];
291 func y = sin(\value x r);
292 }
293 data [set=cos] {
294 var x : interval [-0.5*pi:4];
295 func y = cos(\value x r);
296 }
297 data [set=tan] {
298 var x : interval [-0.3*pi:.3*pi];
299 func y = tan(\value x r);
300 };
301 \end{tikzpicture}
302 \end{codeexample}
303
304 Section~\ref{section-dv-style-sheets} details style sheets and legends.
305
306
307 \subsection{Usage}
308 \label{section-dv-data-syntax}
309
310 Inside a \tikzname\ picture you can use the |\datavisualization| command to
311 create a data visualization. You can use this command several times in a
312 picture to create pictures containing multiple data visualizations.
313
314 \begin{command}{\datavisualization\opt{\oarg{data visualization options}}\meta{data specification}|;|}
315 This command is available only inside a |{tikzpicture}| environment.
316
317 The \meta{data visualization options} are used to configure the data
318 visualization, that is, how the data is to be depicted. The options are
319 executed with the path prefix |/tikz/data visualization|. This means that
320 normal \tikzname\ options like |thin| or |red| cannot be used here. Rather,
321 a large number of options specific to data visualizations are available.
322
323 As a minimum, you should specify at least two options: First, you should
324 use an option that selects an axis system that is appropriate for your
325 plot. Typical possible keys are |school book axes| or |scientific axes|,
326 detailed information on them can be found in Section~\ref{section-dv-axes}.
327
328 Second, you use an option to select \emph{how} the data should be
329 visualized. This is done using a key like |visualize as line| which will,
330 as the name suggests, visualize the data by connecting data points in the
331 plane using a line. Similarly, |visualize as smooth cycle| will try to fit
332 a smooth cycle through the data points. Detailed information on possible
333 visualizers can be found in Section~\ref{section-dv-visualizers}.
334
335 Following these options, the \meta{data specification} is used to provide
336 the actual to-be-visualized data. The syntax is somewhat similar to
337 commands like |\path|: The \meta{data specification} is a sequence of
338 keywords followed by local options and parameters, terminated with a
339 semicolon. (Indeed, like for the |\path| command, the \meta{data
340 visualizers options} need not be specified at the beginning, but additional
341 option surrounded by square brackets may be given anywhere inside the
342 \meta{data specification}.)
343
344 The different possible keywords inside the \meta{data specification} are
345 explained in the following.
346 \end{command}
347
348 \begin{datavisualizationoperation}{data}{\opt{\oarg{options}}\opt{\marg{inline data}}}
349 This command is used to specify data for the data visualization. It can be
350 used several times inside a single visualization and each time the
351 to-be-read data may have a different format, but the data will be
352 visualized as if it have been specified inside a single |data| command.
353
354 The behavior of the |data| command depends on whether the \meta{inline
355 data} is present. If it is not present, the \meta{options} must be used to
356 specify a source file from which the data is read; if the \meta{inline
357 data} is present no file will be used, instead the data should directly
358 reside inside the \TeX-file and be given between the curly braces
359 surrounding the \meta{inline data}.
360
361 The \meta{options} are executed with the prefix |/pgf/data|. The following
362 options are always available:
363 %
364 \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)}
365 If you set the |source| attribute to a non-empty \meta{filename}, the
366 data will be read from this file. In this case, no \meta{inline data}
367 may be present, not even empty curly braces should be provided.
368 %
369 \begin{codeexample}[code only]
370 \datavisualization ...
371 data [read from file=file1.csv]
372 data [read from file=file2.csv];
373 \end{codeexample}
374 %
375 The other way round, if |read from file| is empty, the data must
376 directly follow as \meta{inline data}.
377 %
378 \begin{codeexample}[code only]
379 \datavisualization ...
380 data {
381 x, y
382 1, 2
383 2, 3
384 };
385 \end{codeexample}
386 \end{key}
387 %
388 The second important key is |format|, which is used to specify the data
389 format:
390 %
391 \begin{key}{/pgf/data/format=\meta{format} (initially table)}
392 Use this key to locally set the format used for parsing the data, see
393 Section~\ref{section-dv-formats} for a list of predefined formats.
394
395 The default format is the |table|-format, also known as
396 ``comma-separated values''. The first line contains names of attributes
397 separated by commas, all following lines constitute a data point where
398 the attributes are given by the comma-separated values in that line.
399 \end{key}
400
401
402 \medskip
403 \textbf{Presetting attributes.}
404 Normally, the inline data or the external data contains for each data point
405 the values of the different attributes. However, sometimes you may also
406 wish to set an attribute to a fixed value for all data points of a data
407 set. Suppose, for instance, that you have to source files
408 |experiment007.csv| and |experiment023.csv| and you would like that for all
409 data points of the first file the attribute |/data point/experiment id| is
410 set to 7 while for the data points of the second file they are set to 23.
411 In this case, you can specify the desired settings using an absolute path
412 inside the \meta{options}. The effect will be local to the current |data|
413 command:
414 %
415 \begin{codeexample}[code only]
416 \datavisualization...
417 data [/data point/experiment=7, read from file=experiment007.csv]
418 data [/data point/experiment=23, read from file=experiment023.csv];
419 \end{codeexample}
420
421 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
422 \tikz
423 \datavisualization [school book axes, visualize as line]
424 data [/data point/x=1] {
425 y
426 1
427 2
428 }
429 data [/data point/x=2] {
430 y
431 2
432 0.5
433 };
434 \end{codeexample}
435
436
437 \medskip
438 \textbf{Setting options for multiple |data| commands.}
439 You may wish to generally set the format once and for all. This can be done
440 by using the following key:
441 %
442 \begin{stylekey}{/tikz/every data}
443 This key is executed for every |data| command.
444 \end{stylekey}
445
446 Another way of passing options to multiple |data| commands is to use the
447 following facility: Whenever an option with the path
448 |/tikz/data visualization/data| is used, the path will be remapped to
449 |/pgf/data|. This means, in particular, that you can pass an option like
450 |data/format=table| to the |\datavisualization| command to set the data
451 format for all |data| commands of the data visualization.
452
453
454 \medskip
455 \textbf{Parsing inline data.}
456 When you specify data inline, \TeX\ needs to read the data
457 ``line-by-line'', while \TeX\ normally largely ignores end-of-line
458 characters. For this reason, the data visualization system temporarily
459 changes the meaning of the end-of-line character. This is only possible if
460 \TeX\ has not already processed the data in some other way (namely as the
461 parameter to some macro).
462
463 The bottom line is that you cannot use inline data when the whole
464 |\datavisualization| command is passed as a parameter to some macro that is
465 not setup to handle ``fragile'' code. For instance, in a \textsc{beamer}
466 |frame| you need to add the |fragile| option when a data visualization
467 contains inline data.
468
469 The problem does not arise when an external data |source| is specified.
470 \end{datavisualizationoperation}
471
472 \begin{datavisualizationoperation}{data point}{\opt{\oarg{options}}}
473 This command is used to specify data a single data point. The
474 \meta{options} are simply executed with the path |/data point| and then a
475 data point is created. This means that inside the \meta{options} you just
476 specify the values of all attributes in key--value syntax.
477 %
478 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
479 \tikz \datavisualization [school book axes, visualize as line]
480 data point [x=1, y=1] data point [x=1, y=2]
481 data point [x=2, y=2] data point [x=2, y=0.5];
482 \end{codeexample}
483 %
484 \end{datavisualizationoperation}
485
486 \begin{key}{/tikz/data visualization/data point=\meta{options}}
487 This key is the ``key version'' of the previous command. The difference is
488 that this key can be used internally inside styles.
489 %
490 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
491 \tikzdatavisualizationset{
492 horizontal/.style={
493 data point={x=#1, y=1}, data point={x=#1, y=2}},
494 }
495 \tikz \datavisualization
496 [ school book axes, visualize as line,
497 horizontal=1,
498 horizontal=2 ];
499 \end{codeexample}
500 %
501 \end{key}
502
503 \begin{datavisualizationoperation}{data group}{\opt{\oarg{options}}\marg{name}\opt{|+=|\marg{data specifications}}}
504 You can store a whole \meta{data specification} in a \emph{data group}.
505 This allows you to reuse data in multiple places without having to write
506 the data to an external file.
507
508 The syntax of this command comes in the following three variants:
509 %
510 \begin{itemize}
511 \item |data group| \opt{\oarg{options}} \marg{name} |=| \marg{data
512 specifications}
513 \item |data group| \opt{\oarg{options}} \marg{name} |+=| \marg{data
514 specifications}
515 \item |data group| \opt{\oarg{options}} \marg{name}
516 \end{itemize}
517 %
518 In the first case, a new data group called \meta{name} is created (an
519 existing data group of the same name will be erased) and the following
520 \meta{data specifications} is stored in this data group. The data group
521 will not be fed to the rendering pipeline, but it is parsed at this point
522 as if it were. The defined data group is defined globally, so you can used
523 it in subsequent visualizations. The \meta{options} are saved with the
524 parsed \meta{data specifications}.
525
526 In the second case, an already existing data group is extended by adding
527 the \meta{data specifications} to it.
528
529 In the third case (detected by noting that the \meta{name} is neither
530 followed by an equal sign nor a plus sign), the contents of the previously
531 defined data group \meta{name} is inserted. The \meta{options} are also
532 executed.
533
534 Let us now first create a data group. Note that nothing is drawn since the
535 ``dummy'' data visualization is empty and used only for the definition of
536 the data group.
537 %
538 \begin{codeexample}[setup code]
539 \tikz \datavisualization data group {points} = {
540 data {
541 x, y
542 0, 1
543 1, 2
544 2, 2
545 5, 1
546 2, 0
547 1, 1
548 }
549 };
550 \end{codeexample}
551
552 We can now use this data in different plots:
553 %
554 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
555 \tikz \datavisualization [school book axes, visualize as line] data group {points};
556 \qquad
557 \tikz \datavisualization [scientific axes=clean, visualize as line] data group {points};
558 \end{codeexample}
559 %
560 \end{datavisualizationoperation}
561
562 \begin{datavisualizationoperation}{scope}{\opt{\oarg{options}}\marg{data specification}}
563 Scopes can be used to nest hierarchical data sets. The \meta{options} will
564 be executed with the path |/pgf/data| and will only apply to the data sets
565 specified inside the \meta{data specification}, which may contain |data| or
566 |scope| commands once more:
567 %
568 \begin{codeexample}[code only]
569 \datavisualization...
570 scope [/data point/experiment=7]
571 {
572 data [read from file=experiment007-part1.csv]
573 data [read from file=experiment007-part2.csv]
574 data [read from file=experiment007-part3.csv]
575 }
576 scope [/data point/experiment=23, format=foo]
577 {
578 data [read from file=experiment023-part1.foo]
579 data [read from file=experiment023-part2.foo]
580 };
581 \end{codeexample}
582 %
583 \end{datavisualizationoperation}
584
585 \begin{datavisualizationoperation}{info}{\opt{\oarg{options}}\marg{code}}
586 This command will execute normal \tikzname\ \meta{code} at the end of a
587 data visualization. The \meta{options} are executed with the normal path
588 |/tikz/|.
589
590 The only difference between this command and just giving the \meta{code}
591 directly following the data visualization is that inside the \meta{code}
592 following an |info| command you still have access to the coordinate system
593 of the data visualization. In sharp contrast, \tikzname\ code given after a
594 data visualization can no longer access this coordinate system.
595 %
596 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
597 \begin{tikzpicture}[baseline]
598 \datavisualization [ school book axes, visualize as line ]
599 data [format=function] {
600 var x : interval [-0.1*pi:2];
601 func y = sin(\value x r);
602 }
603 info {
604 \draw [red] (visualization cs: x={(.5*pi)}, y=1) circle [radius=1pt]
605 node [above,font=\footnotesize] {extremal point};
606 };
607 \end{tikzpicture}
608 \end{codeexample}
609
610 As can be seen, inside a data visualization a special coordinate system is
611 available:
612
613 \begin{coordinatesystem}{visualization}
614 As for other coordinate systems, the syntax is
615 \declare{|(visualization cs:|\meta{list of attribute-value pairs}|)|}.
616 The effect is the following: For each pair
617 \meta{attribute}|=|\meta{value} in the \meta{list} the key
618 |/data point/|\meta{attribute} is set to \meta{value}. Then, it is
619 computed where the resulting data point ``would lie'' on the canvas
620 (however, no data point is passed to the visualizers).
621 \end{coordinatesystem}
622 \end{datavisualizationoperation}
623
624 \begin{datavisualizationoperation}{info'}{\opt{\oarg{options}}\marg{code}}
625 This command works like |info|, only the \meta{code} will be executed just
626 before the visualization is done. This allows you to draw things
627 \emph{behind} the visualization.
628 %
629 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
630 \begin{tikzpicture}[baseline]
631 \datavisualization [ school book axes, visualize as line ]
632 data [format=function] {
633 var x : interval [-0.1*pi:2];
634 func y = sin(\value x r);
635 }
636 info' {
637 \fill [red] (visualization cs: x={(.5*pi)}, y=1) circle [radius=2mm];
638 };
639 \end{tikzpicture}
640 \end{codeexample}
641 %
642 \end{datavisualizationoperation}
643
644 \label{section-dv-bounding-box}%
645 \begin{predefinednode}{data visualization bounding box}
646 This rectangle node stores a bounding box of the data visualization that is
647 currently being constructed. This node can be useful inside |info| commands
648 or when labels need to be added.
649 \end{predefinednode}
650
651 \begin{predefinednode}{data bounding box}
652 This rectangle node is similar to |data visualization bounding box|, but it
653 keeps track only of the actual data. The spaces needed for grid lines,
654 ticks, axis labels, tick labels, and all other information that is not part
655 of the actual data is not part of this box.
656 \end{predefinednode}
657
658
659 \subsection{Advanced: Executing User Code During a Data Visualization}
660 \label{section-dv-user-code}
661
662 The following keys can be passed to the |\datavisualization| command and allow
663 you to execute some code at some special time during the data visualization
664 process. For details of the process and on which signals are emitted when, see
665 Section~\ref{section-dv-backend}.
666
667 \begin{key}{/tikz/data visualization/before survey=\meta{code}}
668 The \meta{code} is passed to the |before survey| method of the data
669 visualization object and then executed at the appropriate time (see
670 Section~\ref{section-dv-backend} for details).
671
672 The following commands work likewise:
673 \end{key}
674 %
675 \begin{key}{/tikz/data visualization/at start survey=\meta{code}}
676 \end{key}
677 %
678 \begin{key}{/tikz/data visualization/at end survey=\meta{code}}
679 \end{key}
680 %
681 \begin{key}{/tikz/data visualization/after survey=\meta{code}}
682 \end{key}
683 %
684 \begin{key}{/tikz/data visualization/before visualization=\meta{code}}
685 \end{key}
686 %
687 \begin{key}{/tikz/data visualization/at start visualization=\meta{code}}
688 \end{key}
689 %
690 \begin{key}{/tikz/data visualization/at end visualization=\meta{code}}
691 \end{key}
692 %
693 \begin{key}{/tikz/data visualization/after visualization=\meta{code}}
694 \end{key}
695
696
697 \subsection{Advanced: Creating New Objects}
698
699 You will need the following key only when you wish to create new rendering
700 pipelines from scratch -- instead of modifying an existing pipeline as you
701 would normally do. In the following it is assumed that you are familiar with
702 the concepts of Section~\ref{section-dv-backend}.
703
704 \begin{key}{/tikz/data visualization/new object=\meta{options}}
705 This key serves two purposes:
706 %
707 \begin{enumerate}
708 \item This method makes it easy to create a new object as part of the
709 rendering pipeline, using \meta{options} to specify arguments
710 rather that directly calling |\pgfoonew|. Since you have the full
711 power of the keys mechanism at your disposal, it is easy, for
712 instance, to control whether or not parameters to the constructor
713 are expanded or not.
714 \item The object is not created immediately, but only just before the
715 visualization starts. This allows you to specify that an object
716 must be created, but the parameter values of for its constructor
717 may depend on keys that are not yet set. A typical application is
718 the creating of an axis object: When you say |scientific axes|, the
719 |new object| command is used internally to create two objects
720 representing these axes. However, keys like |x={length=5cm}| can
721 only \emph{later} be used to specify the parameters that need to be
722 passed to the constructor of the objects.
723 \end{enumerate}
724
725 The following keys may be used inside the \meta{options}:
726 %
727 \begin{key}{/tikz/data visualization/class=\meta{class name}}
728 The class of the to-be-created object.
729 \end{key}
730 %
731 \begin{key}{/tikz/data visualization/when=\meta{phase name} (initially before survey)}
732 This key is used to specify when the object is to be created. As
733 described above, the object is not created immediately, but at some
734 time during the rendering process. You can specify any of the phases
735 defined by the data visualization object, see
736 Section~\ref{section-dv-backend} for details.
737 \end{key}
738 %
739 \begin{key}{/tikz/data visualization/store=\meta{key name}}
740 If the \meta{key name} is not empty, once the object has been created,
741 a handle to the object will be stored in \meta{key name}. If a handle
742 is already stored in \meta{key name}, the object is not created twice.
743 \end{key}
744 %
745 \begin{key}{/tikz/data visualization/before creation=\meta{code}}
746 This code is executed right before the object is finally created. It
747 can be used to compute values that are then passed to the constructor.
748 \end{key}
749 %
750 \begin{key}{/tikz/data visualization/after creation=\meta{code}}
751 This code is executed right after the object has just been created. A
752 handle to the just-created object is available in |\tikzdvobj|.
753 \end{key}
754 %
755 \begin{key}{/tikz/data visualization/arg1=\meta{value}}
756 The value to be passed as the first parameter to the constructor.
757 Similarly, the keys |arg2| to |arg8| specify further parameters passed.
758 Naturally, only as many arguments are passed as parameters are set.
759 Here is an example:
760 %
761 \begin{codeexample}[code only]
762 \tikzdatavisualizationset{
763 new object={
764 class = example class,
765 arg1 = foo,
766 arg2 = \bar
767 }
768 }
769 \end{codeexample}
770 %
771 causes the following object creation code to be executed later on:
772 %
773 \begin{codeexample}[code only]
774 \pgfoonew \tikzdvobj=new example class(foo,\bar)
775 \end{codeexample}
776 %
777 Note that you key mechanisms like |.expand once| to pass the value of a
778 macro instead of the macro itself:
779 %
780 \begin{codeexample}[code only]
781 \tikzdatavisualizationset{
782 new object={
783 class = example class,
784 arg1 = foo,
785 arg2/.expand once = \bar
786 }
787 }
788 \end{codeexample}
789 %
790 Now, if |\bar| is set to |This \emph{is} it.|\@ at the moment to object
791 is created later on, the following object creation code is executed:
792 %
793 \begin{codeexample}[code only]
794 \pgfoonew \tikzdvobj=new example class(foo,This \emph{is} it)
795 \end{codeexample}
796 \end{key}
797
798 \begin{key}{/tikz/data visualization/arg1 from key=\meta{key}}
799 Works like the |arg1|, only the value that is passed to the constructor
800 is the current value of the specified \meta{key} at the moment when the
801 object is created.
802 %
803 \begin{codeexample}[code only]
804 \tikzdatavisualizationset{
805 new object={
806 class = example class,
807 arg1 from key = /tikz/some key
808 }
809 }
810 \tikzset{some key/.initial=foobar}
811 \end{codeexample}
812 %
813 causes the following to be executed:
814 %
815 \begin{codeexample}[code only]
816 \pgfoonew \tikzdvobj=new example class(foobar)
817 \end{codeexample}
818 %
819 Naturally, the keys |arg2 from key| to |arg8 from key| are also
820 provided.
821 \end{key}
822
823 \begin{key}{/tikz/data visualization/arg1 handle from key=\meta{key}}
824 Works like the |arg1 from key|, only the key must store an object and
825 instead of the object a handle to the object is passed to the
826 constructor.
827 \end{key}
828 \end{key}