| 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} |