Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-dv-visualizers.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{Visualizers}
12 \label{section-dv-visualizers}
13
14 \subsection{Overview}
15
16 In a data visualization a long stream of data points is \emph{visualized} using
17 \emph{visualizers}. Recall that it is the job of the axis systems as described
18 in Section~\ref{section-dv-axes} to determine \emph{where} data points are
19 visualized. It is the job of the visualizers to determine \emph{how} they are
20 visualized.
21
22 The most basic and common visualizer is the \emph{line visualizer}. It simply
23 connects subsequent data points by straight lines to indicate either that the
24 points on these lines interpolate between the real data points or the straight
25 lines are used to indicate the order in which the data points appear. A
26 different, more ``conservative'' visualizer is the \emph{scatter visualizer} or
27 \emph{mark visualizer}, which just places a small mark at each data point. Such
28 a visualizer does not imply any interpolation or ordering between the data
29 points.
30
31 Visualizers may, however, also be more complicated. For instance, a visualizer
32 used for a box plot could visualize a data point as a box with a median value,
33 standard deviation, outliers, and other information; a rectangle visualizer
34 might visualize data points as larger areas; a projection visualizer might
35 visualize the projection of data points onto different axes; and so.
36
37 Creating a new visualizer is not quite trivial since a new \pgfname\ class
38 needs to be implemented. Fortunately, using visualizers is much simpler: For
39 each kind of visualizer there is a key that allows you to create such a
40 visualizer. You can then use further keys to configure the visualizer and to
41 connect it to the data.
42
43 In a data visualization multiple visualizers may exist at the same time. This
44 happens in different situations:
45 %
46 \begin{itemize}
47 \item A data visualization may contain several independent data sets that
48 are to be visualized. There might be a line plot, for which a line
49 visualizer is used, and also a scatter plot, for which a scatter
50 visualizer would be used.
51
52 In this case, for each data point only one visualizer will do anything.
53 To achieve this, each data point has an attribute called |visualizer|
54 which tells the visualizer objects whether they should ``react'' to the
55 data point or not.
56 \item A single data point might be visualized several times. For instance,
57 a scatter visualizer might draw a mark at the data point's position on
58 the page and a projection visualizer might draw, additionally, a mark
59 at the projected position.
60 \end{itemize}
61
62
63 \subsection{Usage}
64
65 \subsubsection{Using a Single Visualizer}
66
67 The simplest scenario for using visualizers are data visualizations in which
68 there is only a single data set that is visualized in one style. In this case,
69 all that needs to be done in order to choose a visualizer is use one of the
70 options starting with |visualize as ...| together with the |\datavisualization|
71 command:
72 %
73 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
74 % Define a data set:
75 \tikz \datavisualization data group {example} = {
76 data {
77 x, y
78 0, 0
79 0.5, 2
80 1, 2
81 1.5, 1.5
82 2, 0.5
83 }};
84 \tikz \datavisualization [school book axes, visualize as line] data group {example};
85 \qquad
86 \tikz \datavisualization [school book axes, visualize as smooth line] data group {example};
87 \qquad
88 \tikz \datavisualization [school book axes, visualize as scatter] data group {example};
89 \end{codeexample}
90
91 Methods for styling visualizers are discussed in
92 Section~\ref{section-dv-visualizer-styling}.
93
94
95 \subsubsection{Using Multiple Visualizers}
96
97 A data visualization may contain multiple data groups and for each data set we
98 might wish to use a different visualizer. In this case, we need some way of
99 telling the data visualization engine to which visualizer should be used with
100 the different data points.
101
102 To solve this problem, you can \emph{name} a visualizer. The visualizer's name
103 can then both be used to configure the visualizer and also to indicate that
104 data points ``belong'' to the visualizer.
105
106 Naming a visualizer is quite simple: The |visualize as ...| keys actually take
107 a single parameter, which is the name of the visualizer. For instance, the
108 following code creates three visualizers, named |sin|, |cos|, and |tan|:
109 %
110 \begin{codeexample}[code only]
111 visualize as line=sin,
112 visualize as line=cos,
113 visualize as scatter=tan
114 \end{codeexample}
115
116 (When you just say |visualize as line| without providing a name, the name
117 |line| is chosen as a default, for |visualize as scatter| the name |scatter| is
118 the default and so.)
119
120 In order to indicate which data points should be visualized by which of these
121 visualizers, the following key is important:
122
123 \begin{key}{/data point/set}
124 A visualizer will only act on a data point when its name matches the value
125 of this key. Initially, this key is set to the last visualizer created, so
126 if there is only one, there is no need to set or worry about this key.
127 \end{key}
128
129 Since the |set| key has the path prefix |/data point|, it can be set like any
130 other attribute of a data key:
131 %
132 \begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
133 \tikz \datavisualization
134 [scientific axes=clean,
135 visualize as line=sin,
136 visualize as line=cos,
137 visualize as scatter=tan]
138 data {
139 x, y, set
140 0, 0, sin
141 1, 1, sin
142 2, 0, sin
143 3, -1, sin
144 4, 0, sin
145 0, 1, cos
146 1, 0, cos
147 0, 0, tan
148 1, 1, tan
149 2, 2, tan
150 3, 4, tan
151 2, -1, cos
152 3, 0, cos
153 4, 1, cos
154 };
155 \end{codeexample}
156
157 As can be seen, the data points with the same |set| attribute do not need to be
158 consecutive.
159
160 The above method of specifying the visualizer works nicely, but in most cases
161 it would be more natural to keep the |set| attribute out of the table. This is
162 easy to achieve by using multiple |data| and using the following key:
163
164 \begin{key}{/pgf/data/set=\meta{name}}
165 Shorthand for |/data point/set=|\meta{name}.
166 %
167 \begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
168 \tikz \datavisualization
169 [scientific axes=clean,
170 visualize as line=sin,
171 visualize as line=cos]
172 data [set=sin] {
173 x, y
174 0, 0
175 1, 1
176 2, 0
177 3, -1
178 4, 0
179 }
180 data [set=cos] {
181 x, y
182 0, 1
183 1, 0
184 2, -1
185 3, 0
186 4, 1
187 };
188 \end{codeexample}
189 %
190 \end{key}
191
192 When you need to visualize several similar things in a single plot (like ten
193 lines that all get visualized by |visualize as line|), it is somewhat
194 cumbersome having to write this ten times. In this case you can shorten your
195 code by making use of the |.list| key handler: When you add it to a key, the
196 ``value'' passed to the key is parsed as a list of values. The key is then
197 executed once for each of these values:
198 %
199 \begin{codeexample}[
200 width=7cm,
201 preamble={\usetikzlibrary{datavisualization.formats.functions}},
202 ]
203 \tikz \datavisualization
204 [scientific axes=clean,
205 visualize as line/.list={sin, cos, tan}]
206 data [set=sin, format=function] {
207 var x : interval[0:3*pi];
208 func y = sin(\value x r);
209 }
210 data [set=cos, format=function] {
211 var x : interval[0:3*pi];
212 func y = cos(\value x r);
213 }
214 data [set=tan, format=function] {
215 var x : interval[0:pi/2.2];
216 func y = tan(\value x r);
217 };
218 \end{codeexample}
219
220
221 \subsubsection{Styling a Visualizer}
222 \label{section-dv-visualizer-styling}
223
224 In order to style a visualizer that has been created using for instance
225 |visualize as line=|\meta{visualizer name}, you can use the following key:
226
227 \begin{key}{/tikz/data visualization/\meta{visualizer name}=\meta{options}}
228 For each visualizer, a key of the same name is created with the path prefix
229 |/tikz/data visualization|. This key takes the \meta{options} and executes
230 them with the path prefix
231 %
232 \begin{codeexample}[code only]
233 /tikz/data visualization/visualizer options/
234 \end{codeexample}
235 %
236 These options are then used to configure the appearance of the current
237 visualizer. (This is quite similar to the way options are passed to an axis
238 in order to configure the axis.) Possible options include |style|, but also
239 |label in legend| and |label in data|. The latter two options are discussed
240 in Section~\ref{section-dv-labels-in}, the first option below.
241 %
242 \begin{codeexample}[
243 width=7cm,
244 preamble={\usetikzlibrary{datavisualization.formats.functions}},
245 ]
246 \tikz \datavisualization
247 [scientific axes=clean,
248 visualize as smooth line/.list={sin, cos},
249 sin={style=red},
250 cos={style=blue}]
251 data [set=sin, format=function] {
252 var x : interval[0:3*pi];
253 func y = sin(\value x r);
254 }
255 data [set=cos, format=function] {
256 var x : interval[0:3*pi];
257 func y = cos(\value x r);
258 };
259 \end{codeexample}
260 %
261 \end{key}
262
263 \begin{key}{/tikz/data visualization/visualizer options/style=\meta{options}}
264 The \meta{options} given to this key should be normal \tikzname\ options.
265 They will be executed when the visualizer is used.
266 %
267 \begin{codeexample}[
268 width=7cm,
269 preamble={\usetikzlibrary{datavisualization.formats.functions}},
270 ]
271 \tikz \datavisualization
272 [scientific axes=clean,
273 visualize as smooth line=sin,
274 sin={style={red, densely dotted}},
275 visualize as smooth line=cos,
276 cos={style={mark=x}},
277 ]
278 data [set=sin, format=function] {
279 var x : interval[0:3*pi];
280 func y = sin(\value x r);
281 }
282 data [set=cos, format=function] {
283 var x : interval[0:3*pi];
284 func y = cos(\value x r);
285 };
286 \end{codeexample}
287
288 When you have multiple visualizers in a single data visualization, you can
289 use the |style| option with each visualizer to configure their different
290 appearances as in the above example. However, it is usually much better
291 (and easier) to use a style sheet, see
292 Section~\ref{section-dv-style-sheets}.
293 %
294 \begin{codeexample}[
295 width=7cm,
296 preamble={\usetikzlibrary{datavisualization.formats.functions}},
297 ]
298 \tikz \datavisualization
299 [scientific axes={clean, end labels},
300 x axis={label=$x$}, y axis={grid={major also at=0}},
301 visualize as smooth line/.list={sin,cos,sin 2,cos 2},
302 legend={below, rows=2},
303 sin={label in legend={text=$\sin x$}},
304 cos={label in legend={text=$\cos x$}},
305 sin 2={label in legend={text=$\sin 2x$}},
306 cos 2={label in legend={text=$\cos 2x$}},
307 style sheet=strong colors]
308 data [set=sin, format=function] {
309 var x : interval[0:3*pi];
310 func y = sin(\value x r);
311 }
312 data [set=cos, format=function] {
313 var x : interval[0:3*pi];
314 func y = cos(\value x r);
315 }
316 data [set=sin 2, format=function] {
317 var x : interval[0:3*pi];
318 func y = sin(2*\value x r);
319 }
320 data [set=cos 2, format=function] {
321 var x : interval[0:3*pi];
322 func y = cos(2*\value x r);
323 };
324 \end{codeexample}
325 %
326 \end{key}
327
328 \begin{key}{/tikz/data visualization/visualizer options/ignore style sheets}
329 This option, which should be passed to a visualizer after its creation
330 before another visualizer is created, causes style sheets \emph{not} to
331 apply to the visualizer (but the |style| option will still have an effect).
332 This allows you to create visualizers that are used for special purposes
333 and that do not ``take part'' in the usual styling. For instance, a
334 visualizer might be used internally to depict a regression line, even
335 though the regression line itself should not participate in the usual
336 styling by, say, dashing or different coloring.
337 \end{key}
338
339 In addition to the options passed to a visualizer via |style|, the following
340 also gets executed when a visualizer is used:
341
342 \begin{stylekey}{/tikz/data visualization/every visualizer}
343 This style is used with every visualizer. Note that it should contain
344 normal \tikzname\ keys.
345 %
346 \begin{codeexample}[
347 width=7cm,
348 preamble={\usetikzlibrary{datavisualization.formats.functions}},
349 ]
350 \tikz \datavisualization
351 [scientific axes=clean,
352 every visualizer/.style={dashed},
353 visualize as smooth line]
354 data [format=function] {
355 var x : interval[0:3*pi];
356 func y = sin(\value x r);
357 };
358 \end{codeexample}
359 %
360 \end{stylekey}
361
362
363 \subsection{Reference: Basic Visualizers}
364
365 \subsubsection{Visualizing Data Points Using Lines}
366
367 \begin{key}{/tikz/data visualizers/visualize as line=\meta{visualizer name} (default line)}
368 Creates a new visualizer named \meta{visualizer name}. Basically, this
369 visualizer connects all data points for which the |/data point/set|
370 attribute equals \meta{visualizer name} by a line that is styled by the
371 visualizer's style.
372
373 In more detail, the following happens:
374 %
375 \begin{enumerate}
376 \item A new object is created (of class |plot handler visualizer|) that
377 is configured to collect the canvas positions of all data points
378 whose |set| attribute equals \meta{visualizer name}.
379 \item During the end of the data visualization, \pgfname's plotting
380 mechanism (see Section~\ref{section-plots}) is used to plot the
381 stream of recorded data points.
382
383 This means that, in principle, all of the plot handlers available
384 in \tikzname\ could be used for the visualization (such as the
385 |smooth| handler). However, some plot handlers such as, say, the
386 |xcomb| are unsuitable as plot handlers since they do not support
387 the advanced axis handling done by the data visualization engine.
388 Because of this (and also for other reasons), you cannot set the
389 plot handler directly, but must use one of the options like
390 |straight line|, |smooth line| and others, documented in a moment.
391 \item Additionally, plot marks can be drawn at the collected data
392 points. Here, all of the options available to \tikzname\ for
393 drawing plot marks are available. To configure them, all options
394 offered by \tikzname\ for configuring marks are available such as
395 |mark repeat|:
396 %
397 \begin{codeexample}[
398 width=7cm,
399 preamble={\usetikzlibrary{datavisualization.formats.functions}},
400 ]
401 \tikz \datavisualization
402 [scientific axes=clean,
403 visualize as line=my data,
404 my data={style={mark=x, mark repeat=3}}]
405 data [format=function] {
406 var x : interval [0:pi] samples 10;
407 func y = sin(\value x r);
408 };
409 \end{codeexample}
410 \end{enumerate}
411
412 The line visualizer also provides a method of dealing with gaps in a line.
413 Take for instance the function $f(x) = \tan x$. When this function is
414 plotted over the interval $[0,\pi]$, then the function will go to $\pm
415 \infty$ at $\pi/2$. When we plot this, we might plot the function in the
416 interval $[0,\frac{\pi}{2}-\epsilon]$ and then continue in the interval
417 $[\frac{\pi}{2}+\epsilon,\pi]$. However, we do not want the point at
418 coordinate $\bigl(\frac{\pi}{2}- \epsilon, \tan(\frac{\pi}{2}-
419 \epsilon)\bigr)$ to be connected to the coordinate $\bigl(\frac{\pi}{2}+
420 \epsilon, \tan(\frac{\pi}{2}+ \epsilon)\bigr)$ by a line. Rather, there
421 should be a ``gap'' or a ``jump'' between these coordinates. To achieve
422 this, the following key can be used:
423 %
424 \begin{key}{/data point/outlier=\meta{value} (default true, initially \normalfont empty)}
425 When this key is set to anything non-empty value, a visualizer will
426 consider this data point to be an ``outlier''. For a line visualizer
427 this means that the point is not shown and that the current line ends
428 at the previous data point and a new line starts at the next data
429 point.
430 %
431 \begin{codeexample}[
432 width=7cm,
433 preamble={\usetikzlibrary{datavisualization.formats.functions}},
434 ]
435 \tikz \datavisualization
436 [scientific axes=clean, x axis={grid={major at=(pi/2)}},
437 visualize as smooth line]
438 data [format=function] {
439 var x : interval[0:pi/2-0.1];
440 func y = tan(\value x r);
441 }
442 data point [outlier]
443 data [format=function] {
444 var x : interval[pi/2+0.1:pi];
445 func y = tan(\value x r);
446 };
447 \end{codeexample}
448 \end{key}
449 \end{key}
450
451 \begin{key}{/tikz/data visualizers/visualize as smooth line=\meta{visualizer name} (default line)}
452 A shorthand |visualize as line=|\meta{visualizer name} followed
453 \meta{visualizer name}|=smooth line|.
454 \end{key}
455
456 \begin{key}{/tikz/data visualization/visualizer options/straight line}
457 Causes the data points to be connected by straight lines.
458 %
459 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
460 \tikz [scale=.55] \datavisualization
461 [scientific axes=clean, all axes={ticks=few},
462 visualize as smooth line=my data, my data={straight line}]
463 data [format=function] {
464 var t : interval [0:4] samples 5;
465 func x = cos(\value t r);
466 func y = sin(\value t r);
467 };
468 \end{codeexample}
469 %
470 \end{key}
471
472 \begin{key}{/tikz/data visualization/visualizer options/straight cycle}
473 Causes the data points to be connected by a polygon.
474 %
475 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
476 \tikz [scale=.55] \datavisualization
477 [scientific axes=clean, all axes={ticks=few},
478 visualize as smooth line=my data, my data={straight cycle}]
479 data [format=function] {
480 var t : interval [0:4] samples 5;
481 func x = cos(\value t r);
482 func y = sin(\value t r);
483 };
484 \end{codeexample}
485 %
486 \end{key}
487
488 \begin{key}{/tikz/data visualization/visualizer options/polygon}
489 This is an alias for |straight cycle|.
490 \end{key}
491
492 \begin{key}{/tikz/data visualization/visualizer options/smooth line}
493 Causes the data points to be connected by a line that is smoothed at the
494 joins:
495 %
496 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
497 \tikz [scale=.55] \datavisualization
498 [scientific axes=clean, all axes={ticks=few},
499 visualize as smooth line=my data, my data={smooth line}]
500 data [format=function] {
501 var t : interval [0:4] samples 5;
502 func x = cos(\value t r);
503 func y = sin(\value t r);
504 };
505 \end{codeexample}
506 %
507 \end{key}
508
509 \begin{key}{/tikz/data visualization/visualizer options/smooth cycle}
510 Causes the data points to be connected by a circular line that is smoothed
511 at the joins:
512 %
513 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
514 \tikz [scale=.55] \datavisualization
515 [scientific axes=clean, all axes={ticks=few},
516 visualize as smooth line=my data, my data={smooth cycle}]
517 data [format=function] {
518 var t : interval [0:4] samples 5;
519 func x = cos(\value t r);
520 func y = sin(\value t r);
521 };
522 \end{codeexample}
523 %
524 \end{key}
525
526 \begin{key}{/tikz/data visualization/visualizer options/gap line}
527 This key causes the data points to be connected by lines that ``do not
528 quite touch'' the data points. This is implemented by using the
529 |\pgfplothandlergaplineto|, see Section~\ref{section-plot-gapped}.
530 %
531 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
532 \tikz [scale=.55] \datavisualization
533 [scientific axes=clean, all axes={ticks=few},
534 visualize as smooth line=my data, my data={gap line}]
535 data [format=function] {
536 var t : interval [0:4] samples 5;
537 func x = cos(\value t r);
538 func y = sin(\value t r);
539 };
540 \end{codeexample}
541 %
542 \end{key}
543
544 \begin{key}{/tikz/data visualization/visualizer options/gap cycle}
545 Like |gapped line|, only with a cycle:
546 %
547 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
548 \tikz [scale=.55] \datavisualization
549 [scientific axes=clean, all axes={ticks=few},
550 visualize as smooth line=my data, my data={gap cycle}]
551 data [format=function] {
552 var t : interval [0:4] samples 5;
553 func x = cos(\value t r);
554 func y = sin(\value t r);
555 };
556 \end{codeexample}
557 %
558 \end{key}
559
560 \begin{key}{/tikz/data visualization/visualizer options/no lines}
561 Suppresses the line. This option only makes sense when the |mark| option is
562 used.
563 %
564 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
565 \tikz [scale=.55] \datavisualization
566 [scientific axes=clean, all axes={ticks=few},
567 visualize as smooth line=my data, my data={no lines, style={mark=x}}]
568 data [format=function] {
569 var t : interval [0:4] samples 5;
570 func x = cos(\value t r);
571 func y = sin(\value t r);
572 };
573 \end{codeexample}
574 %
575 \end{key}
576
577
578 \subsubsection{Visualizing Data Points Using Marks}
579
580 \begin{key}{/tikz/data visualizers/visualize as scatter=\meta{visualizer name} (default scatter)}
581 A shorthand |visualize as line=|\meta{visualizer name} followed
582 \meta{visualizer name}|=no lines| and setting the |style| of the visualizer
583 so that is will use |mark=x| (plus some size adjustments) to draw marks at
584 the data points.
585 %
586 \begin{codeexample}[
587 width=7cm,
588 preamble={\usetikzlibrary{datavisualization.formats.functions}},
589 ]
590 \tikz \datavisualization
591 [scientific axes=clean,
592 visualize as scatter]
593 data [format=function] {
594 var x : interval [0:pi] samples 10;
595 func y = sin(\value x r);
596 };
597 \end{codeexample}
598 %
599 \end{key}
600
601
602 \subsection{Advanced: Creating New Visualizers}
603
604 Creating a new visualizer is a two-stage process that does, unfortunately,
605 require in-depth knowledge of the data visualization backend:
606 %
607 \begin{enumerate}
608 \item First, you need to create a new class using |\pgfooclass| whose
609 instances react to the signal |visualize datapoint signal|. This
610 requires detailed knowledge of the data visualization engine, see
611 Section~\ref{section-dv-backend}.
612 \item Second, you should provide keys on the \tikzname\ level for creating
613 the necessary objects. These keys invoke the key |new visualizer|
614 internally.
615 \end{enumerate}
616
617 \begin{key}{/tikz/data visualization/new visualizer=\marg{name}\marg{options}\marg{legend entry options}}
618 This key configures a new visualizer named \meta{name}. This entails the
619 following actions:
620 %
621 \begin{itemize}
622 \item The key |/tikz/data visualization/|\meta{name} is created. As
623 described earlier, this key can be used to pass for instance
624 |style| options to the visualizer.
625 \item The style key
626 |/tikz/data visualization/visualizers/|\meta{name}|/styling| is
627 created and made empty. This is the key in which the |style| key
628 will store the options passed to the visualizer.
629 \item The style key
630 |/tikz/data visualization/visualizers/|\meta{name}|/label in legend options|
631 is set to \meta{legend entry options}. These options are used to
632 configure how the visualizer should be rendered in a legend, see
633 Section~\ref{section-dv-legend-entries} for details.
634 \item The key |/data point/set/|\meta{name} is set to a number that is
635 increased for each visualizer in the current data visualization.
636 This number is important for style sheets, see
637 Section~\ref{section-dv-style-sheets}.
638 \item The key |/data point/|\meta{name}|/execute at begin| is set to
639 code that creates a |{scope}| that executes the following styles as
640 options:
641 %
642 \begin{enumerate}
643 \item The \meta{options} passed to the |new visualizer| key.
644 \item The |every visualizer| style.
645 \item The styling from the currently active style sheets, see
646 Section~\ref{section-dv-style-sheets}.
647 \item The styling stored in the |styling| key mentioned above.
648 \end{enumerate}
649 %
650 \item The key |/data point/|\meta{name}|/execute at end| is set to code
651 that will finish all paths that may have been created by the
652 visualizer and closes the scope.
653 \end{itemize}
654
655 All of the above mean the following in practice:
656 %
657 \begin{itemize}
658 \item Inside a new |visualize as ...| key, you pass the name of the
659 to-be-created to |new visualizer| as the first parameter and any
660 special default styling setup of the visualizer as the second
661 parameter.
662 \item The new |visualize as ...| key should also create a visualizer
663 object using |new object|.
664 \item When this object finally is about to create the actual
665 visualization, it should surround the code by invoking the code
666 stored in the |execute at begin| and the |execute at end| keys of
667 the visualizer.
668 \end{itemize}
669
670 Everything else is usually taken care of by the |new visualizer| key
671 automatically.
672 \end{key}
673
674 As an example, let us create a simple visualizer that creates a circle whose
675 radius is dictated by the |radius| attribute. To keep things simple in this
676 example, this attribute cannot be configured.
677
678 First, we need the visualizer class. For this example I have boiled it down to
679 a minimum:
680 %
681 \begin{codeexample}[code only]
682 \pgfooclass{circle visualizer}
683 {
684 % Stores the name of the visualizer. This is needed for filtering and configuration
685 \attribute name;
686
687 % The constructor. Just setup the attribute.
688 \method circle visualizer(#1) { \pgfooset{name}{#1} }
689
690 % Connect to visualize signal.
691 \method default connects() {
692 \pgfoothis.get handle(\me)
693 \pgfkeysvalueof{/pgf/data visualization/obj}.connect(\me,visualize,visualize datapoint signal)
694 }
695
696 % This method is invoked for each data point. It checks whether the data point belongs to the correct
697 % visualizer and, if so, calls the macro \dovisualization to do the actual visualization.
698 \method visualize() {
699 \pgfdvfilterpassedtrue
700 \pgfdvnamedvisualizerfilter
701 \ifpgfdvfilterpassed
702 \dovisualization
703 \fi
704 }
705 }
706 \end{codeexample}
707
708 The |\dovisualization| method must now do the correct visualization.
709 %
710 \begin{codeexample}[code only]
711 \def\dovisualization{
712 \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin}
713 \pgfpathcircle{\pgfpointdvdatapoint}{\pgfkeysvalueof{/data point/radius}}
714 % \pgfusepath is done by |execute at end|
715 \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at end}
716 }
717 \end{codeexample}
718
719 Finally, we create a |visualize as| key:
720 %
721 \begin{codeexample}[code only]
722 \tikzdatavisualizationset{
723 visualize as circle/.style={
724 new object={
725 when=after survey,
726 store=/tikz/data visualization/visualizers/#1,
727 class=circle visualizer,
728 arg1=#1
729 },
730 new visualizer={#1}{%
731 color=visualizer color, % a color setup by the style sheet
732 every path/.style={fill,draw}, % fill and draw the circle by default,
733 }{}, % let's ignore legends in this example
734 /data point/set=#1
735 },
736 visualize as circle/.default=circle
737 }
738 \end{codeexample}
739
740 Now, let's see how this works:
741
742 % TODOsp: codeexamples: This stuff is all needed for the next `codeexample`
743 % but cannot be stored (simply) in `setup code`, `preamble` or `pre`
744 \pgfooclass{circle visualizer} {
745 % Stores the name of the visualizer. This is needed for filtering
746 % and configuration
747 \attribute name;
748
749 % The constructor. Just setup the attribute.
750 \method circle visualizer(#1) { \pgfooset{name}{#1} }
751
752 % Connect to visualize signal.
753 \method default connects() {
754 \pgfoothis.get handle(\me)
755 \pgfkeysvalueof{/pgf/data visualization/obj}.connect(\me,visualize,visualize datapoint signal)
756 }
757
758 % This method is invoked for each data point. It checks whether the
759 % data point belongs to the correct visualizer and, if so, calls the
760 % macro \dovisualization to do the actual visualization.
761 \method visualize() {
762 \pgfdvfilterpassedtrue
763 \pgfdvnamedvisualizerfilter
764 \ifpgfdvfilterpassed
765 \dovisualization
766 \fi
767 }
768 }
769
770 \def\dovisualization{
771 \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin}
772 \pgfpathcircle{\pgfpointdvdatapoint}{\pgfkeysvalueof{/data point/radius}}
773 % \pgfusepath is done by |execute at end|
774 \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at end}
775 }
776
777 \tikzdatavisualizationset{
778 visualize as circle/.style={
779 new object={
780 when=after survey,
781 store=/tikz/data visualization/visualizers/#1,
782 class=circle visualizer,
783 arg1=#1
784 },
785 new visualizer={#1}{%
786 color=visualizer color, % a color setup by the style sheet
787 every path/.style={fill,draw}, % fill and draw the circle by default,
788 }{},
789 /data point/set=#1
790 },
791 visualize as circle/.default=circle
792 }
793
794 \begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
795 \tikz \datavisualization [
796 scientific axes=clean,
797 visualize as circle/.list={a, b, c},
798 style sheet=strong colors]
799 data [set=a] {
800 x, y, radius
801 0, 0, 2pt
802 1, 1, 3pt
803 1, 2, 3pt
804 2, 0, 1pt
805 }
806 data [set=b] {
807 x, y, radius
808 0.5, 0.5, 5pt
809 1, 1.5, 2pt
810 1, 2.5, 3pt
811 0, 2, 4pt
812 }
813 data [set=c] {
814 x, y, radius
815 3, 2, 3pt
816 2.5, 0.5, 4pt
817 };
818 \end{codeexample}