Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-dv-stylesheets.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{Style Sheets and Legends}
12 \label{section-dv-style-sheets}
13
14 \subsection{Overview}
15
16 In many data visualizations, different sets of data need to be visualized in a
17 single visualization. For instance, in a plot there might be a line for the
18 sine of~$x$ and another line for the cosine of~$x$; in another visualization
19 there might be a set of points representing data from a first experiment and
20 another set of points representing data from a second experiment; and so on. In
21 order to indicate to which data set a data point belongs, one might plot the
22 curve of the sine in, say, black, and the curve of the cosine in red; we might
23 plot the data from the first experiment using stars and the data from the second
24 experiment using circles; and so on. Finally, at some place in the
25 visualization -- either inside the data or in a legend next to it -- the
26 meaning of the colors or symbols need to be explained.
27
28 Just as you would like \tikzname\ to map the data points automatically onto the
29 axes, you will also typically wish \tikzname\ to choose for instance the
30 coloring of the lines automatically for you. This is done using \emph{style
31 sheets}. There are at least two good reasons why you should prefer style sheets
32 over configuring the styling of each visualizer ``by hand'' using the |style|
33 key:
34 %
35 \begin{enumerate}
36 \item It is far more convenient to just say |style sheet=strong colors|
37 than having to individually picking the different colors.
38 \item The style sheets were chosen and constructed rather carefully.
39
40 For instance, the |strong colors| style sheet does not pick colors like
41 pure green or pure yellow, which have very low contrast with respect to
42 a white background and which often lead to unintelligible graphics.
43 Instead, opposing primary colors with maximum contrast on a white
44 background were picked that are visually quite pleasing.
45
46 Similarly, the different dashing style sheets are constructed in such a
47 way that there are only few and small gaps in the dashing so that no
48 data points get lost because the dashes are spaced too far apart. Also
49 dashing patterns were chosen that have a maximum optical difference.
50
51 As a final example, style sheets for plot marks are constructed in such
52 a way that even when two plot marks lie directly on top of each other,
53 they are still easily distinguishable.
54 \end{enumerate}
55 %
56 The bottom line is that whenever possible, you should use one of the predefined
57 style sheets rather than picking colors or dashings at random.
58
59
60 \subsection{Concepts: Style Sheets}
61
62 A \emph{style sheet} is a predefined list of styles such as a list of colors, a
63 list of dashing pattern, a list of plot marks, or a combinations thereof. A
64 style sheet can be \emph{attached} to a data point attribute. Then, the value
65 of this attribute is used with data points to choose which style in the list
66 should be chosen to visualize the data point.
67
68 In most cases, there is just one attribute to which style sheets get attached:
69 the |/data point/visualizer| attribute. The effect of attaching a style sheet
70 to this attribute is that each visualizer is styled differently.
71
72 For the following examples, let us first define a simple data set:
73 %
74 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
75 \tikz \datavisualization data group {function classes} = {
76 data [set=log, format=function] {
77 var x : interval [0.2:2.5];
78 func y = ln(\value x);
79 }
80 data [set=lin, format=function] {
81 var x : interval [-2:2.5];
82 func y = 0.5*\value x;
83 }
84 data [set=squared, format=function] {
85 var x : interval [-1.5:1.5];
86 func y = \value x*\value x;
87 }
88 data [set=exp, format=function] {
89 var x : interval [-2.5:1];
90 func y = exp(\value x);
91 }
92 };
93 \end{codeexample}
94
95 \begin{codeexample}[
96 width=6cm,
97 preamble={\usetikzlibrary{datavisualization.formats.functions}},
98 pre={\tikz \datavisualization data group {function classes} = {
99 data [set=log, format=function] {
100 var x : interval [0.2:2.5];
101 func y = ln(\value x);
102 }
103 data [set=lin, format=function] {
104 var x : interval [-2:2.5];
105 func y = 0.5*\value x;
106 }
107 data [set=squared, format=function] {
108 var x : interval [-1.5:1.5];
109 func y = \value x*\value x;
110 }
111 data [set=exp, format=function] {
112 var x : interval [-2.5:1];
113 func y = exp(\value x);
114 }
115 };}]
116 \tikz \datavisualization [
117 school book axes, all axes={unit length=7.5mm},
118 visualize as smooth line/.list={log, lin, squared, exp},
119 style sheet=strong colors]
120 data group {function classes};
121 \end{codeexample}
122
123 \begin{codeexample}[
124 width=6cm,
125 preamble={\usetikzlibrary{datavisualization.formats.functions}},
126 pre={\tikz \datavisualization data group {function classes} = {
127 data [set=log, format=function] {
128 var x : interval [0.2:2.5];
129 func y = ln(\value x);
130 }
131 data [set=lin, format=function] {
132 var x : interval [-2:2.5];
133 func y = 0.5*\value x;
134 }
135 data [set=squared, format=function] {
136 var x : interval [-1.5:1.5];
137 func y = \value x*\value x;
138 }
139 data [set=exp, format=function] {
140 var x : interval [-2.5:1];
141 func y = exp(\value x);
142 }
143 };}]
144 \tikz \datavisualization [
145 school book axes, all axes={unit length=7.5mm},
146 visualize as smooth line/.list={log, lin, squared, exp},
147 style sheet=vary dashing]
148 data group {function classes};
149 \end{codeexample}
150
151
152 \subsection{Concepts: Legends}
153 \label{section-dv-labels-in}
154
155 A \emph{legend} is a box that is next to a data visualization (or inside it at
156 some otherwise empty position) that contains a textual explanation of the
157 different colors or styles used in a data visualization.
158
159 Just as it is difficult to get colors and dashing patterns right ``by hand'',
160 it is also difficult to get a legend right. For instance, when a small line is
161 shown in the legend that represents the actual line in the data visualization,
162 if the line is too short and the dashing is too large, it may be impossible to
163 discern which dashing is actually meant. Similarly, when plot marks are shown
164 on such a short line, using a simple straight line may make it hard to read the
165 plot marks correctly.
166
167 The data visualization engine makes some effort to make it easy to create
168 high-quality legends. Additionally, it also offers ways of easily adding labels
169 for visualizers directly inside the data visualization, which is even better
170 than adding a legend, in general.
171 %
172 \begin{codeexample}[
173 width=7cm,
174 preamble={\usetikzlibrary{datavisualization.formats.functions}},
175 pre={\tikz \datavisualization data group {function classes} = {
176 data [set=log, format=function] {
177 var x : interval [0.2:2.5];
178 func y = ln(\value x);
179 }
180 data [set=lin, format=function] {
181 var x : interval [-2:2.5];
182 func y = 0.5*\value x;
183 }
184 data [set=squared, format=function] {
185 var x : interval [-1.5:1.5];
186 func y = \value x*\value x;
187 }
188 data [set=exp, format=function] {
189 var x : interval [-2.5:1];
190 func y = exp(\value x);
191 }
192 };}]
193 \tikz \datavisualization [
194 school book axes, all axes={unit length=7.5mm},
195 x axis={label=$x$},
196 visualize as smooth line/.list={log, lin, squared, exp},
197 log= {label in legend={text=$\log x$}},
198 lin= {label in legend={text=$x/2$}},
199 squared={label in legend={text=$x^2$}},
200 exp= {label in legend={text=$e^x$}},
201 style sheet=vary dashing]
202 data group {function classes};
203 \end{codeexample}
204
205 \begin{codeexample}[
206 width=6.3cm,
207 preamble={\usetikzlibrary{datavisualization.formats.functions}},
208 pre={\tikz \datavisualization data group {function classes} = {
209 data [set=log, format=function] {
210 var x : interval [0.2:2.5];
211 func y = ln(\value x);
212 }
213 data [set=lin, format=function] {
214 var x : interval [-2:2.5];
215 func y = 0.5*\value x;
216 }
217 data [set=squared, format=function] {
218 var x : interval [-1.5:1.5];
219 func y = \value x*\value x;
220 }
221 data [set=exp, format=function] {
222 var x : interval [-2.5:1];
223 func y = exp(\value x);
224 }
225 };}]
226 \tikz \datavisualization [
227 school book axes,
228 x axis={label=$x$},
229 visualize as smooth line/.list={log, lin, squared, exp},
230 every data set label/.append style={text colored},
231 log= {pin in data={text'=$\log x$, when=y is -1}},
232 lin= {pin in data={text=$x/2$, when=x is 2,
233 pin length=1ex}},
234 squared={pin in data={text=$x^2$, when=x is 1.1,
235 pin angle=230}},
236 exp= {label in data={text=$e^x$, when=x is -2}},
237 style sheet=vary hue]
238 data group {function classes};
239 \end{codeexample}
240
241
242 \subsection{Usage: Style Sheets}
243
244 \subsubsection{Picking a Style Sheet}
245
246 To use a style sheet, you need to \emph{attach} it to an attribute. You can
247 attach multiple style sheets to an attribute and in this case all of these
248 style sheets can influence the appearance of the data points.
249
250 Most of the time, you will attach a style sheet to the |set| attribute. This
251 has the effect that each different data set inside the same visualization is
252 rendered in a different way. Since this use of style sheets is the most common,
253 there is a special, easy-to-remember option for this:
254
255 \begin{key}{/tikz/data visualization/style sheet=\meta{style sheet}}
256 Adds the \meta{style sheet} to the list of style sheets attached to the
257 |set| attribute.
258 %
259 \begin{codeexample}[
260 width=6cm,
261 preamble={\usetikzlibrary{datavisualization.formats.functions}},
262 pre={\tikz \datavisualization data group {function classes} = {
263 data [set=log, format=function] {
264 var x : interval [0.2:2.5];
265 func y = ln(\value x);
266 }
267 data [set=lin, format=function] {
268 var x : interval [-2:2.5];
269 func y = 0.5*\value x;
270 }
271 data [set=squared, format=function] {
272 var x : interval [-1.5:1.5];
273 func y = \value x*\value x;
274 }
275 data [set=exp, format=function] {
276 var x : interval [-2.5:1];
277 func y = exp(\value x);
278 }
279 };},
280 ]
281 \tikz \datavisualization [
282 school book axes, all axes={unit length=7.5mm},
283 visualize as smooth line/.list={log, lin, squared, exp},
284 style sheet=vary thickness and dashing,
285 style sheet=vary hue]
286 data group {function classes};
287 \end{codeexample}
288 %
289 \end{key}
290
291 While the |style sheet| key will attach a style sheet only to the |set|
292 attribute, the following key handler can be used to attach a style sheet to an
293 arbitrary attribute:
294
295 \begin{handler}{{.style sheet}=\meta{style sheet}}
296 Inside a data visualization you can use this key handler together with an
297 attribute, that is, with a key having the path prefix |/data point|. For
298 instance, in order to attach the \meta{style sheet} |strong colors| to the
299 attribute |set|, you could write
300 %
301 \begin{codeexample}[code only]
302 /data point/set/.style sheet=strong colors
303 \end{codeexample}
304 %
305 Indeed, the |style sheet| key is just a shorthand for the above.
306
307 The effect of attaching a style sheet is the following:
308 %
309 \begin{itemize}
310 \item A new object is created that will monitor the attribute.
311 \item Each time a special \emph{styling key} is emitted by the data
312 visualization engine, this object will inspect the current value of
313 the attribute to which it is attached.
314 \item Depending on this value, one of the styles stored in the style
315 sheet is chosen (how this works, exactly, will be explained in a
316 moment).
317 \item The chosen style is then locally applied.
318 \end{itemize}
319
320 In reality, things are a bit more complicated: If the attribute of the data
321 point happens to have a subkey named in the same way as the value, then the
322 value of is this subkey is used instead of the value itself. This allows
323 you to ``rename'' a value.
324
325 In a sense, a style sheet behaves much like a visualizer (see
326 Section~\ref{section-dv-visualizers}): In accordance with the value of a
327 certain attribute, the appearance of data points change. However, there are
328 a few differences: First, the styling of a data point needs to be triggered
329 explicitly and this triggering is not necessarily done for each data point
330 individually, but only for a whole visualizer. Second, styles can be
331 computed even when no data point is present. This is useful for instance in
332 a legend since, here, a visual representation of a visualizer needs to be
333 created independently of the actual data points.
334 \end{handler}
335
336
337 \subsubsection{Creating a New Style Sheet}
338
339 Creating a style sheet works as follows: For each possible value that an
340 attribute can attain we must specify a style. This is done by creating a style
341 key for each such possible value with a special path prefix and setting this
342 style key to the desired value. The special path prefix is
343 |/pgf/data visualization/style sheets| followed by the name of the style sheet.
344
345 As an example, suppose we wish to create a style sheet |test| that makes styled
346 data points |red| when the attribute has value |foo| and |green| when the
347 attribute has value |bar| and |dashed, blue| when the attribute is |foobar|. We
348 could then write
349 %
350 \begin{codeexample}[code only]
351 /pgf/data visualization/style sheets/test/foo/.style={red},
352 /pgf/data visualization/style sheets/test/bar/.style={green},
353 /pgf/data visualization/style sheets/test/foobar/.style={dashed, blue},
354 \end{codeexample}
355
356 We could then attach this style sheet to the attribute |code| as follows:
357 %
358 \begin{codeexample}[code only]
359 /data point/code/.style sheet=test
360 \end{codeexample}
361
362 Then, when |/data point/code=foobar| holds when the styling signal is raised,
363 the style |dashed, blue| will get executed.
364
365 A natural question arises concerning the situation that the value of the
366 attribute is not defined as a subkey of the style sheet. In this case, a
367 special key gets executed:
368
369 \begin{stylekey}{/pgf/data visualization/style sheets/\meta{style sheet}/default style=\meta{value}}
370 This key gets during styling whenever
371 |/pgf/data visualization/style sheet/|\meta{style sheet}|/|\meta{value} is
372 not defined.
373 \end{stylekey}
374
375 Let us put all of this together in a real-life example. Suppose we wish to
376 create a style sheet that makes the first data set |green|, the second |yellow|
377 and the third one |red|. Further data sets should be, say, |black|. The
378 attribute that we intend to style is the |set| attribute. For the moment, we
379 assume that the data sets will be named |1|, |2|, |3|, and so on (instead of,
380 say, |experiment 1| or |sin| or something more readable -- we will get rid of
381 this restriction in a minute).
382
383 We would now write:
384 %
385 \begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
386 \pgfkeys{
387 /pgf/data visualization/style sheets/traffic light/.cd,
388 % All these styles have the above prefix.
389 1/.style={green!50!black},
390 2/.style={yellow!90!black},
391 3/.style={red!80!black},
392 default style/.style={black}
393 }
394 \tikz \datavisualization [
395 school book axes,
396 visualize as line=1,
397 visualize as line=2,
398 visualize as line=3,
399 style sheet=traffic light]
400 data point [x=0, y=0, set=1]
401 data point [x=2, y=2, set=1]
402 data point [x=0, y=1, set=2]
403 data point [x=2, y=1, set=2]
404 data point [x=0.5, y=1.5, set=3]
405 data point [x=2.25, y=1.75, set=3];
406 \end{codeexample}
407
408 In the above example, we have to name the visualizers |1|, |2|, |3| and so one
409 since the value of the |set| attribute is used both assign data points to
410 visualizers and also pick a style sheet. However, it would be much nicer if we
411 could name any way we want. To achieve this, we use the special rule for style
412 sheets that says that if there is a subkey of an attribute whose name is the
413 same name as the value, then the value of this key is used instead. This
414 slightly intimidating definition is much easier to understand when we have a
415 look at an example:
416 %
417 \pgfkeys{
418 /pgf/data visualization/style sheets/traffic light/.cd,
419 % All these styles have the above prefix.
420 1/.style={green!50!black},
421 2/.style={yellow!90!black},
422 3/.style={red!80!black},
423 default style/.style={black}
424 }
425 \begin{codeexample}[
426 preamble={\usetikzlibrary{datavisualization}},
427 pre={\pgfkeys{
428 /pgf/data visualization/style sheets/traffic light/.cd,
429 % All these styles have the above prefix.
430 1/.style={green!50!black},
431 2/.style={yellow!90!black},
432 3/.style={red!80!black},
433 default style/.style={black}
434 }},
435 ]
436 % Definition of traffic light keys as above
437 \begin{tikzpicture}
438 \datavisualization data group {lines} = {
439 data point [x=0, y=0, set=normal]
440 data point [x=2, y=2, set=normal]
441 data point [x=0, y=1, set=heated]
442 data point [x=2, y=1, set=heated]
443 data point [x=0.5, y=1.5, set=critical]
444 data point [x=2.25, y=1.75, set=critical]
445 };
446 \datavisualization [
447 school book axes,
448 visualize as line=normal,
449 visualize as line=heated,
450 visualize as line=critical,
451 /data point/set/normal/.initial=1,
452 /data point/set/heated/.initial=2,
453 /data point/set/critical/.initial=3,
454 style sheet=traffic light]
455 data group {lines};
456 \end{tikzpicture}
457 \end{codeexample}
458
459 Now, it is a bit bothersome that we have to set all these |/data point/set/...|
460 keys by hand. It turns out that this is not necessary: Each time a visualizer
461 is created, a subkey of |/data point/set| with the name of the visualizer is
462 created automatically and a number is stored that is increased for each new
463 visualizer in a data visualization. This means that the three lines starting
464 with |/data point| are inserted automatically for you, so they can be left out.
465 However, you would need them for instance when you would like several different
466 data sets to use the same styling:
467 %
468 \begin{codeexample}[
469 preamble={\usetikzlibrary{datavisualization}},
470 pre={\pgfkeys{
471 /pgf/data visualization/style sheets/traffic light/.cd,
472 % All these styles have the above prefix.
473 1/.style={green!50!black},
474 2/.style={yellow!90!black},
475 3/.style={red!80!black},
476 default style/.style={black}
477 }%
478 \tikz \datavisualization data group {lines} = {
479 data point [x=0, y=0, set=normal]
480 data point [x=2, y=2, set=normal]
481 data point [x=0, y=1, set=heated]
482 data point [x=2, y=1, set=heated]
483 data point [x=0.5, y=1.5, set=critical]
484 data point [x=2.25, y=1.75, set=critical]
485 };},
486 ]
487 % Definition of traffic light keys as above
488 \tikz \datavisualization [
489 school book axes,
490 visualize as line=normal,
491 visualize as line=heated,
492 visualize as line=critical,
493 /data point/set/critical/.initial=1, % same styling as first set
494 style sheet=traffic light]
495 data group {lines};
496 \end{codeexample}
497
498 We can a command that slightly simplifies the definition of style sheets:
499
500 \begin{command}{\pgfdvdeclarestylesheet\marg{name}\marg{keys}}
501 This command executes the \meta{keys} with the path prefix
502 |/pgf/data visualization/style sheets/|\penalty0\meta{name}. The above
503 definition of the traffic light style sheet could be rewritten as follows:
504 %
505 \begin{codeexample}[code only]
506 \pgfdvdeclarestylesheet{traffic light}{
507 1/.style={green!50!black},
508 2/.style={yellow!90!black},
509 3/.style={red!80!black},
510 default style/.style={black}
511 }
512 \end{codeexample}
513 %
514 \end{command}
515
516 As a final example, let us create a style sheet that changes the dashing
517 pattern according to the value of the attribute. We do not need to define an
518 large number of styles in this case, but can use the |default style| key to
519 ``calculate'' the correct dashing.
520
521 \begin{codeexample}[
522 preamble={\usetikzlibrary{datavisualization}},
523 pre={\tikz \datavisualization data group {lines} = {
524 data point [x=0, y=0, set=normal]
525 data point [x=2, y=2, set=normal]
526 data point [x=0, y=1, set=heated]
527 data point [x=2, y=1, set=heated]
528 data point [x=0.5, y=1.5, set=critical]
529 data point [x=2.25, y=1.75, set=critical]
530 };},
531 ]
532 \pgfdvdeclarestylesheet{my dashings}{
533 default style/.style={dash pattern={on #1pt off 1pt}}
534 }
535 \tikz \datavisualization [
536 school book axes,
537 visualize as line=normal,
538 visualize as line=heated,
539 visualize as line=critical,
540 style sheet=my dashings]
541 data group {lines};
542 \end{codeexample}
543
544
545 \subsubsection{Creating a New Color Style Sheet}
546
547 Creating a style sheet that varies colors according to an attribute works the
548 same way as creating a normal style sheet: Subkeys lies |1|, |2|, and so on use
549 the |style| attribute to setup a color. However, instead of using the |color|
550 attribute to set the color, you should use the |visualizer color| key to set
551 the color:
552
553 \begin{key}{/tikz/visualizer color=\meta{color}}
554 This key is used to set the color |visualizer color| to \meta{color}. This
555 color is used by visualizers to color the data they visualize, rather than
556 the current ``standard color''. The reason for not using the normal current
557 color is simply that it makes many internals of the data visualization
558 engine a bit simpler.
559 %
560 \begin{codeexample}[
561 preamble={\usetikzlibrary{datavisualization}},
562 pre={\tikz \datavisualization data group {lines} = {
563 data point [x=0, y=0, set=normal]
564 data point [x=2, y=2, set=normal]
565 data point [x=0, y=1, set=heated]
566 data point [x=2, y=1, set=heated]
567 data point [x=0.5, y=1.5, set=critical]
568 data point [x=2.25, y=1.75, set=critical]
569 };},
570 ]
571 \pgfdvdeclarestylesheet{my colors}
572 {
573 default style/.style={visualizer color=black},
574 1/.style={visualizer color=black},
575 2/.style={visualizer color=red!80!black},
576 3/.style={visualizer color=blue!80!black},
577 }
578 \tikz \datavisualization [
579 school book axes,
580 visualize as line=normal,
581 visualize as line=heated,
582 visualize as line=critical,
583 style sheet=my colors]
584 data group {lines};
585 \end{codeexample}
586 %
587 \end{key}
588
589 There is an additional command that makes it easy to define a style sheet based
590 on a \emph{color series}. Color series are a concept from the |xcolor| package:
591 The idea is that we start with a certain color for the first data set and then
592 add a certain ``color offset'' for each next data point. Please consult the
593 documentation of the |xcolor| package for details.
594
595 \begin{command}{\tikzdvdeclarestylesheetcolorseries\marg{name}\marg{color model}\marg{initial color}\marg{step}}
596 This command creates a new style sheet using |\pgfdvdeclarestylesheet|.
597 This style sheet will only have a default style setup that maps numbers to
598 the color in the color series starting with \meta{initial color} and having
599 a stepping of \meta{step}. Note that when the value of the attribute is
600 |1|, which it is the first data set, the \emph{second} color in the color
601 series is used (since counting starts at |0| for color series). Thus, in
602 general, you need to start the \meta{initial color} ``one early''.
603 %
604 \begin{codeexample}[
605 preamble={\usetikzlibrary{datavisualization}},
606 pre={\tikz \datavisualization data group {lines} = {
607 data point [x=0, y=0, set=normal]
608 data point [x=2, y=2, set=normal]
609 data point [x=0, y=1, set=heated]
610 data point [x=2, y=1, set=heated]
611 data point [x=0.5, y=1.5, set=critical]
612 data point [x=2.25, y=1.75, set=critical]
613 };},
614 ]
615 \tikzdvdeclarestylesheetcolorseries{greens}{hsb}{0.3,1.3,0.8}{0,-.4,-.1}
616 \tikz \datavisualization [
617 school book axes,
618 visualize as line=normal,
619 visualize as line=heated,
620 visualize as line=critical,
621 style sheet=greens]
622 data group {lines};
623 \end{codeexample}
624 %
625 \end{command}
626
627
628 \subsection{Reference: Style Sheets for Lines}
629
630 The following style sheets can be applied to visualizations that use the
631 |visualize as line| and related keys. For the examples, the following style and
632 data set are used:
633 %
634 \begin{codeexample}[code only]
635 \tikzdatavisualizationset {
636 example visualization/.style={
637 scientific axes=clean,
638 y axis={ticks={style={
639 /pgf/number format/fixed,
640 /pgf/number format/fixed zerofill,
641 /pgf/number format/precision=2}}},
642 x axis={ticks={tick suffix=${}^\circ$}},
643 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
644 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
645 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
646 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
647 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
648 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
649 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
650 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
651 }
652 }
653 \end{codeexample}
654 \tikzdatavisualizationset {
655 example visualization/.style={
656 scientific axes=clean,
657 y axis={ticks={style={
658 /pgf/number format/fixed,
659 /pgf/number format/fixed zerofill,
660 /pgf/number format/precision=2}}},
661 x axis={ticks={tick suffix=${}^\circ$}},
662 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
663 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
664 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
665 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
666 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
667 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
668 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
669 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
670 }
671 }
672
673 \begin{codeexample}[code only]
674 \tikz \datavisualization data group {sin functions} = {
675 data [format=function] {
676 var set : {1,...,8};
677 var x : interval [0:50];
678 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
679 }
680 };
681 \end{codeexample}
682 \tikz \datavisualization data group {sin functions} = {
683 data [format=function] {
684 var set : {1,...,8};
685 var x : interval [0:50];
686 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
687 }
688 };
689
690 \begin{stylesheet}{vary thickness}
691 This style varies the thickness of lines. It should be used only when there
692 are only two or three lines, and even then it is not particularly pleasing
693 visually.
694 %
695 \begin{codeexample}[
696 width=10cm,
697 preamble={\usetikzlibrary{datavisualization.formats.functions}},
698 pre={\tikz \datavisualization data group {sin functions} = {
699 data [format=function] {
700 var set : {1,...,8};
701 var x : interval [0:50];
702 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
703 }
704 };%
705 \tikzdatavisualizationset {
706 example visualization/.style={
707 scientific axes=clean,
708 y axis={ticks={style={
709 /pgf/number format/fixed,
710 /pgf/number format/fixed zerofill,
711 /pgf/number format/precision=2}}},
712 x axis={ticks={tick suffix=${}^\circ$}},
713 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
714 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
715 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
716 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
717 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
718 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
719 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
720 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
721 }
722 }},
723 ]
724 \tikz \datavisualization [
725 visualize as smooth line/.list=
726 {1,2,3,4,5,6,7,8},
727 example visualization,
728 style sheet=vary thickness]
729 data group {sin functions};
730 \end{codeexample}
731 %
732 \end{stylesheet}
733
734 \begin{stylesheet}{vary dashing}
735 This style varies the dashing of lines. Although it is not particularly
736 pleasing visually and although visualizations using this style sheet tend
737 to look ``excited'' (but not necessarily ``exciting''), this style sheet is
738 often the best choice when the visualization is to be printed in black and
739 white.
740 %
741 \begin{codeexample}[
742 width=10cm,
743 preamble={\usetikzlibrary{datavisualization.formats.functions}},
744 pre={\tikz \datavisualization data group {sin functions} = {
745 data [format=function] {
746 var set : {1,...,8};
747 var x : interval [0:50];
748 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
749 }
750 };%
751 \tikzdatavisualizationset {
752 example visualization/.style={
753 scientific axes=clean,
754 y axis={ticks={style={
755 /pgf/number format/fixed,
756 /pgf/number format/fixed zerofill,
757 /pgf/number format/precision=2}}},
758 x axis={ticks={tick suffix=${}^\circ$}},
759 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
760 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
761 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
762 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
763 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
764 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
765 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
766 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
767 }
768 }},
769 ]
770 \tikz \datavisualization [
771 visualize as smooth line/.list=
772 {1,2,3,4,5,6,7,8},
773 example visualization,
774 style sheet=vary dashing]
775 data group {sin functions};
776 \end{codeexample}
777 %
778 As can be seen, there are only seven distinct dashing patterns. The eighth
779 and further lines will use a solid line once more. You will then have to
780 specify the dashing ``by hand'' using the |style| option together with the
781 visualizer.
782 \end{stylesheet}
783
784 \begin{stylesheet}{vary thickness and dashing}
785 This style alternates between varying the thickness and the dashing of
786 lines. The difference to just using both the |vary thickness| and
787 |vary dashing| is that too thick lines are avoided. Instead, this style
788 creates clearly distinguishable line styles for many lines (up to 14) with
789 a minimum of visual clutter. This style is the most useful for
790 visualizations when many different lines (ten or more) should be printed in
791 black and white.
792 %
793 \begin{codeexample}[
794 width=10cm,
795 preamble={\usetikzlibrary{datavisualization.formats.functions}},
796 pre={\tikz \datavisualization data group {sin functions} = {
797 data [format=function] {
798 var set : {1,...,8};
799 var x : interval [0:50];
800 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
801 }
802 };%
803 \tikzdatavisualizationset {
804 example visualization/.style={
805 scientific axes=clean,
806 y axis={ticks={style={
807 /pgf/number format/fixed,
808 /pgf/number format/fixed zerofill,
809 /pgf/number format/precision=2}}},
810 x axis={ticks={tick suffix=${}^\circ$}},
811 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
812 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
813 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
814 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
815 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
816 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
817 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
818 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
819 }
820 }},
821 ]
822 \tikz \datavisualization [
823 visualize as smooth line/.list=
824 {1,2,3,4,5,6,7,8},
825 example visualization,
826 style sheet=vary thickness
827 and dashing]
828 data group {sin functions};
829 \end{codeexample}
830 %
831 For comparison, here is the must-less-than-satisfactory result of combining
832 the two independent style sheets:
833 %
834 \begin{codeexample}[
835 width=10cm,
836 preamble={\usetikzlibrary{datavisualization.formats.functions}},
837 pre={\tikz \datavisualization data group {sin functions} = {
838 data [format=function] {
839 var set : {1,...,8};
840 var x : interval [0:50];
841 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
842 }
843 };%
844 \tikzdatavisualizationset {
845 example visualization/.style={
846 scientific axes=clean,
847 y axis={ticks={style={
848 /pgf/number format/fixed,
849 /pgf/number format/fixed zerofill,
850 /pgf/number format/precision=2}}},
851 x axis={ticks={tick suffix=${}^\circ$}},
852 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
853 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
854 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
855 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
856 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
857 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
858 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
859 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
860 }
861 }},
862 ]
863 \tikz \datavisualization [
864 visualize as smooth line/.list=
865 {1,2,3,4,5,6,7,8},
866 example visualization,
867 style sheet=vary thickness,
868 style sheet=vary dashing]
869 data group {sin functions};
870 \end{codeexample}
871 %
872 \end{stylesheet}
873
874
875 \subsection{Reference: Style Sheets for Scatter Plots}
876
877 The following style sheets can be used both for scatter plots and also with
878 lines. In the latter case, the marks are added to the lines.
879
880 \begin{stylesheet}{cross marks}
881 This style uses different crosses to distinguish between the data points of
882 different data sets. The crosses were chosen in such a way that when two
883 different cross marks lie at the same coordinate, their overall shape
884 allows one to still uniquely determine which marks are on top of each
885 other.
886
887 This style supports only up to six different data sets and requires the
888 |plotmarks| library.
889 %
890 \begin{codeexample}[
891 width=10cm,
892 preamble={\usetikzlibrary{datavisualization.formats.functions}},
893 pre={\tikz \datavisualization data group {sin functions} = {
894 data [format=function] {
895 var set : {1,...,8};
896 var x : interval [0:50];
897 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
898 }
899 };%
900 \tikzdatavisualizationset {
901 example visualization/.style={
902 scientific axes=clean,
903 y axis={ticks={style={
904 /pgf/number format/fixed,
905 /pgf/number format/fixed zerofill,
906 /pgf/number format/precision=2}}},
907 x axis={ticks={tick suffix=${}^\circ$}},
908 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
909 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
910 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
911 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
912 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
913 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
914 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
915 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
916 }
917 }},
918 ]
919 \tikz \datavisualization [
920 visualize as scatter/.list=
921 {1,2,3,4,5,6,7,8},
922 example visualization,
923 style sheet=cross marks]
924 data group {sin functions};
925 \end{codeexample}
926 %
927 \begin{codeexample}[
928 width=10cm,
929 preamble={\usetikzlibrary{datavisualization.formats.functions}},
930 pre={\tikz \datavisualization data group {sin functions} = {
931 data [format=function] {
932 var set : {1,...,8};
933 var x : interval [0:50];
934 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
935 }
936 };%
937 \tikzdatavisualizationset {
938 example visualization/.style={
939 scientific axes=clean,
940 y axis={ticks={style={
941 /pgf/number format/fixed,
942 /pgf/number format/fixed zerofill,
943 /pgf/number format/precision=2}}},
944 x axis={ticks={tick suffix=${}^\circ$}},
945 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
946 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
947 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
948 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
949 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
950 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
951 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
952 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
953 }
954 }},
955 ]
956 \tikz \datavisualization [
957 visualize as smooth line/.list=
958 {1,2,3,4,5,6,7,8},
959 example visualization,
960 style sheet=cross marks]
961 data group {sin functions};
962 \end{codeexample}
963 %
964 \end{stylesheet}
965
966
967 \subsection{Reference: Color Style Sheets}
968
969 Color style sheets are very useful for creating visually pleasing data
970 visualizations that contain multiple data sets. However, there are two things
971 to keep in mind:
972 %
973 \begin{itemize}
974 \item At some point, every data visualization is printed or photo copied in
975 black and white by someone. In this case, data sets can often no longer
976 be distinguished.
977 \item A few people are color blind. They will not be able to distinguish
978 between red and green lines (and some people are not even able to
979 distinguish colors at all).
980 \end{itemize}
981
982 For these reasons, if there is any chance that the data visualization will be
983 printed in black and white at some point, consider combining color style sheets
984 with style sheets like |vary dashing| to make data sets distinguishable in all
985 situations.
986
987 \begin{stylesheet}{strong colors}
988 This style sheets uses pure primary colors that can very easily be
989 distinguished. Although not as visually pleasing as the |vary hue| style
990 sheet, the visualizations are easier to read when this style sheet is used.
991 Up to six different data sets are supported.
992 %
993 \begin{codeexample}[
994 width=10cm,
995 preamble={\usetikzlibrary{datavisualization.formats.functions}},
996 pre={\tikz \datavisualization data group {sin functions} = {
997 data [format=function] {
998 var set : {1,...,8};
999 var x : interval [0:50];
1000 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
1001 }
1002 };%
1003 \tikzdatavisualizationset {
1004 example visualization/.style={
1005 scientific axes=clean,
1006 y axis={ticks={style={
1007 /pgf/number format/fixed,
1008 /pgf/number format/fixed zerofill,
1009 /pgf/number format/precision=2}}},
1010 x axis={ticks={tick suffix=${}^\circ$}},
1011 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
1012 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
1013 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
1014 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
1015 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
1016 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
1017 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
1018 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
1019 }
1020 }},
1021 ]
1022 \tikz \datavisualization [
1023 visualize as smooth line/.list=
1024 {1,2,3,4,5,6,7,8},
1025 example visualization,
1026 style sheet=strong colors]
1027 data group {sin functions};
1028 \end{codeexample}
1029 %
1030 \begin{codeexample}[
1031 width=10cm,
1032 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1033 pre={\tikz \datavisualization data group {sin functions} = {
1034 data [format=function] {
1035 var set : {1,...,8};
1036 var x : interval [0:50];
1037 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
1038 }
1039 };%
1040 \tikzdatavisualizationset {
1041 example visualization/.style={
1042 scientific axes=clean,
1043 y axis={ticks={style={
1044 /pgf/number format/fixed,
1045 /pgf/number format/fixed zerofill,
1046 /pgf/number format/precision=2}}},
1047 x axis={ticks={tick suffix=${}^\circ$}},
1048 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
1049 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
1050 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
1051 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
1052 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
1053 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
1054 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
1055 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
1056 }
1057 }},
1058 ]
1059 \tikz \datavisualization [
1060 visualize as smooth line/.list=
1061 {1,2,3,4,5,6,7,8},
1062 example visualization,
1063 style sheet=strong colors,
1064 style sheet=vary dashing]
1065 data group {sin functions};
1066 \end{codeexample}
1067 %
1068 \end{stylesheet}
1069
1070
1071 Unlike |strong colors|, the following style sheets support, in principle, an
1072 unlimited number of data set. In practice, as always, more than four or five
1073 data sets lead to nearly indistinguishable data sets.
1074
1075 \begin{stylesheet}{vary hue}
1076 This style uses a different hue for each data set.
1077 %
1078 \begin{codeexample}[
1079 width=10cm,
1080 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1081 pre={\tikz \datavisualization data group {sin functions} = {
1082 data [format=function] {
1083 var set : {1,...,8};
1084 var x : interval [0:50];
1085 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
1086 }
1087 };%
1088 \tikzdatavisualizationset {
1089 example visualization/.style={
1090 scientific axes=clean,
1091 y axis={ticks={style={
1092 /pgf/number format/fixed,
1093 /pgf/number format/fixed zerofill,
1094 /pgf/number format/precision=2}}},
1095 x axis={ticks={tick suffix=${}^\circ$}},
1096 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
1097 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
1098 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
1099 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
1100 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
1101 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
1102 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
1103 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
1104 }
1105 }},
1106 ]
1107 \tikz \datavisualization [
1108 visualize as smooth line/.list=
1109 {1,2,3,4,5,6,7,8},
1110 example visualization,
1111 style sheet=vary hue]
1112 data group {sin functions};
1113 \end{codeexample}
1114 %
1115 \end{stylesheet}
1116
1117 \begin{stylesheet}{shades of blue}
1118 As the name suggests, different shades of blue are used for different data
1119 sets.
1120 \begin{codeexample}[
1121 width=10cm,
1122 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1123 pre={\tikz \datavisualization data group {sin functions} = {
1124 data [format=function] {
1125 var set : {1,...,8};
1126 var x : interval [0:50];
1127 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
1128 }
1129 };%
1130 \tikzdatavisualizationset {
1131 example visualization/.style={
1132 scientific axes=clean,
1133 y axis={ticks={style={
1134 /pgf/number format/fixed,
1135 /pgf/number format/fixed zerofill,
1136 /pgf/number format/precision=2}}},
1137 x axis={ticks={tick suffix=${}^\circ$}},
1138 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
1139 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
1140 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
1141 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
1142 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
1143 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
1144 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
1145 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
1146 }
1147 }},
1148 ]
1149 \tikz \datavisualization [
1150 visualize as smooth line/.list=
1151 {1,2,3,4,5,6,7,8},
1152 example visualization,
1153 style sheet=shades of blue]
1154 data group {sin functions};
1155 \end{codeexample}
1156 %
1157 \end{stylesheet}
1158
1159 \begin{stylesheet}{shades of red}
1160 \begin{codeexample}[
1161 width=10cm,
1162 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1163 pre={\tikz \datavisualization data group {sin functions} = {
1164 data [format=function] {
1165 var set : {1,...,8};
1166 var x : interval [0:50];
1167 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
1168 }
1169 };%
1170 \tikzdatavisualizationset {
1171 example visualization/.style={
1172 scientific axes=clean,
1173 y axis={ticks={style={
1174 /pgf/number format/fixed,
1175 /pgf/number format/fixed zerofill,
1176 /pgf/number format/precision=2}}},
1177 x axis={ticks={tick suffix=${}^\circ$}},
1178 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
1179 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
1180 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
1181 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
1182 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
1183 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
1184 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
1185 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
1186 }
1187 }},
1188 ]
1189 \tikz \datavisualization [
1190 visualize as smooth line/.list=
1191 {1,2,3,4,5,6,7,8},
1192 example visualization,
1193 style sheet=shades of red]
1194 data group {sin functions};
1195 \end{codeexample}
1196 \end{stylesheet}
1197
1198 \begin{stylesheet}{gray scale}
1199 For once, this style sheet can also be used when the visualization is
1200 printed in black and white.
1201 %
1202 \begin{codeexample}[
1203 width=10cm,
1204 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1205 pre={\tikz \datavisualization data group {sin functions} = {
1206 data [format=function] {
1207 var set : {1,...,8};
1208 var x : interval [0:50];
1209 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
1210 }
1211 };%
1212 \tikzdatavisualizationset {
1213 example visualization/.style={
1214 scientific axes=clean,
1215 y axis={ticks={style={
1216 /pgf/number format/fixed,
1217 /pgf/number format/fixed zerofill,
1218 /pgf/number format/precision=2}}},
1219 x axis={ticks={tick suffix=${}^\circ$}},
1220 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
1221 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
1222 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
1223 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
1224 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
1225 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
1226 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
1227 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
1228 }
1229 }},
1230 ]
1231 \tikz \datavisualization [
1232 visualize as smooth line/.list=
1233 {1,2,3,4,5,6,7,8},
1234 example visualization,
1235 style sheet=gray scale]
1236 data group {sin functions};
1237 \end{codeexample}
1238 %
1239 \end{stylesheet}
1240
1241
1242 \subsection{Usage: Labeling Data Sets Inside the Visualization}
1243
1244 In a visualization that contains multiple data sets, it is often necessary to
1245 clearly point out which line or mark type corresponds to which data set. This
1246 can be done in the main text via a sentence like ``the normal data (black) lies
1247 clearly below the critical values (red)'', but it often a good idea to indicate
1248 data sets ideally directly inside the data visualization or directly next to it
1249 in a so-called legend.
1250
1251 The data visualization engine has direct support both for indicating data sets
1252 directly inside the visualization and also for indicating them in a legend.
1253
1254 The ``best'' way of indicating where a data set lies or which color is used for
1255 it is to put a label directly inside the data visualization. The reason this is
1256 the ``best'' way is that people do not have to match the legend entries against
1257 the data, let alone having to look up the meaning of line styles somewhere in
1258 the text. However, adding a label directly inside the visualization is also the
1259 most tricky way of indicating data sets since it is hard to compute good
1260 positions for the labels automatically and since there needs to be some empty
1261 space where the label can be put.
1262
1263
1264 \subsubsection{Placing a Label Next to a Data Set}
1265
1266 The following key is used to create a label inside the data visualization for a
1267 data set:
1268
1269 \begin{key}{/tikz/data visualization/visualizer options/label in data=\meta{options}}
1270 This key is passed to a visualizer that has previously been created using
1271 keys starting |visualize as ...|. It will create a label inside the data
1272 visualization ``next'' to the visualizer (the details are explained in a
1273 moment). You can use this key multiple times with a visualizer to create
1274 multiple labels at different points with different texts.
1275
1276 The \meta{options} determine which text is shown and where it is shown.
1277 They are executed with the following path prefix:
1278 %
1279 \begin{codeexample}[code only]
1280 /tikz/data visualization/visualizer label options
1281 \end{codeexample}
1282
1283 In order to configure which text is shown and where, use the following keys
1284 inside the \meta{options}:
1285
1286 \begin{key}{/tikz/data visualization/visualizer label options/text=\meta{text}}
1287 This is the text that will be displayed next to the data. It will be to
1288 the ``left'' of the data, see the description below.
1289 \end{key}
1290 %
1291 \begin{key}{/tikz/data visualization/visualizer label options/text'=\meta{text}}
1292 Like |text|, only the text will be to the ``right'' of the data.
1293 \end{key}
1294
1295 The following keys are used to configure where the label will be shown.
1296 They use different strategies to specify one data point where the label
1297 will be anchored. The coordinate of this data point will be stored in
1298 |(label| |visualizer| |coordinate)|. Independently of the strategy, once
1299 the data point has been chosen, the coordinate of the next data point is
1300 stored in |(label| |visualizer| |coordinate')|. Then, a (conceptual) line
1301 is created from the first coordinate to the second and a node is placed at
1302 the beginning of this line to its ``left'' or, for the |text'| option, on
1303 its ``right''. More precisely, an automatic anchor is computed for a node
1304 placed implicitly on this line using the |auto| option or, for the |text'|
1305 option, using |auto,swap|.
1306
1307 The node placed at the position computed in this way will have the
1308 \meta{text} set by the |text| or |text'| option and its styling is
1309 determined by the current |node style|.
1310
1311 Let us now have a look at the different ways of determining the data point
1312 at which the label in anchored:
1313 %
1314 \begin{key}{/tikz/data visualization/visualizer label options/when=\meta{attribute}| is|\meta{number}}
1315 This key causes the value of the \meta{attribute} to be monitored in
1316 the stream of data points. The chosen is data point is the first data
1317 point where the \meta{attribute} is at least \meta{number} (if this
1318 never happens, the last data point is used).
1319 %
1320 \begin{codeexample}[
1321 width=6.3cm,
1322 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1323 pre={\tikz \datavisualization data group {function classes} = {
1324 data [set=log, format=function] {
1325 var x : interval [0.2:2.5];
1326 func y = ln(\value x);
1327 }
1328 data [set=lin, format=function] {
1329 var x : interval [-2:2.5];
1330 func y = 0.5*\value x;
1331 }
1332 data [set=squared, format=function] {
1333 var x : interval [-1.5:1.5];
1334 func y = \value x*\value x;
1335 }
1336 data [set=exp, format=function] {
1337 var x : interval [-2.5:1];
1338 func y = exp(\value x);
1339 }
1340 };},
1341 ]
1342 \tikz \datavisualization [
1343 school book axes,
1344 x axis={label=$x$},
1345 visualize as smooth line/.list={log, lin, squared, exp},
1346 log= {label in data={text'=$\log x$, when=y is -1,
1347 text colored}},
1348 lin= {label in data={text=$x/2$, when=x is 2}},
1349 squared={label in data={text=$x^2$, when=x is 1.1}},
1350 exp= {label in data={text=$e^x$, when=x is -2,
1351 text colored}},
1352 style sheet=vary hue]
1353 data group {function classes};
1354 \end{codeexample}
1355 \end{key}
1356 %
1357 \begin{key}{/tikz/data visualization/visualizer label options/index=\meta{number}}
1358 This key chooses the \meta{number}th data point belonging to the
1359 visualizer's data set.
1360 %
1361 \begin{codeexample}[
1362 width=6.3cm,
1363 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1364 pre={\tikz \datavisualization data group {function classes} = {
1365 data [set=log, format=function] {
1366 var x : interval [0.2:2.5];
1367 func y = ln(\value x);
1368 }
1369 data [set=lin, format=function] {
1370 var x : interval [-2:2.5];
1371 func y = 0.5*\value x;
1372 }
1373 data [set=squared, format=function] {
1374 var x : interval [-1.5:1.5];
1375 func y = \value x*\value x;
1376 }
1377 data [set=exp, format=function] {
1378 var x : interval [-2.5:1];
1379 func y = exp(\value x);
1380 }
1381 };},
1382 ]
1383 \tikz \datavisualization [
1384 school book axes,
1385 x axis={label=$x$},
1386 visualize as smooth line/.list={exp},
1387 exp= {label in data={text=$5$, index=5},
1388 label in data={text=$10$, index=10},
1389 label in data={text=$20$, index=20},
1390 style={mark=x}},
1391 style sheet=vary hue]
1392 data group {function classes};
1393 \end{codeexample}
1394 \end{key}
1395 %
1396 \begin{key}{/tikz/data visualization/visualizer label options/pos=\meta{fraction}}
1397 This key chooses the first data point belonging to the data set whose
1398 index is at least \meta{fraction} times the number of all data points
1399 in the data set.
1400 %
1401 \begin{codeexample}[
1402 width=6.3cm,
1403 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1404 pre={\tikz \datavisualization data group {function classes} = {
1405 data [set=log, format=function] {
1406 var x : interval [0.2:2.5];
1407 func y = ln(\value x);
1408 }
1409 data [set=lin, format=function] {
1410 var x : interval [-2:2.5];
1411 func y = 0.5*\value x;
1412 }
1413 data [set=squared, format=function] {
1414 var x : interval [-1.5:1.5];
1415 func y = \value x*\value x;
1416 }
1417 data [set=exp, format=function] {
1418 var x : interval [-2.5:1];
1419 func y = exp(\value x);
1420 }
1421 };},
1422 ]
1423 \tikz \datavisualization [
1424 school book axes,
1425 x axis={label=$x$},
1426 visualize as smooth line=exp,
1427 exp= {label in data={text=$.2$, pos=0.2},
1428 label in data={text=$.5$, pos=0.5},
1429 label in data={text=$.95$, pos=0.95},
1430 style={mark=x}},
1431 style sheet=vary hue]
1432 data group {function classes};
1433 \end{codeexample}
1434 \end{key}
1435 %
1436 \begin{key}{/tikz/data visualization/visualizer label options/auto}
1437 This key is executed automatically by default. It works like the |pos|
1438 option, where the \meta{fraction} is set to $(\meta{data set's
1439 index}-1/2)/\meta{number of data sets}$. For instance, when there are
1440 $10$ data sets, the fraction for the first one will be $5\%$, the
1441 fraction for the second will be $15\%$, for the third it will be
1442 $25\%$, ending with $95\%$ for the last one.
1443
1444 The net effect of all this is that when there are several lines, labels
1445 will be placed at different positions along the lines with hopefully
1446 only little overlap.
1447 %
1448 \begin{codeexample}[
1449 width=6.3cm,
1450 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1451 ]
1452 \tikz \datavisualization [
1453 scientific axes=clean,
1454 visualize as smooth line/.list={linear, squared, cubed},
1455 linear ={label in data={text=$2x$}},
1456 squared={label in data={text=$x^2$}},
1457 cubed ={label in data={text=$x^3$}}]
1458 data [set=linear, format=function] {
1459 var x : interval [0:1.5];
1460 func y = 2*\value x;
1461 }
1462 data [set=squared, format=function] {
1463 var x : interval [0:1.5];
1464 func y = \value x * \value x;
1465 }
1466 data [set=cubed, format=function] {
1467 var x : interval [0:1.5];
1468 func y = \value x * \value x * \value x;
1469 };
1470 \end{codeexample}
1471 %
1472 As can be seen in the example, the result is not always satisfactory.
1473 In this case, the |pin in data| option might be preferable, see below.
1474 \end{key}
1475
1476 The following keys allow you to style labels.
1477
1478 \begin{key}{/tikz/data visualization/visualizer label options/node style=\meta{options}}
1479 Just passes the options to |/tikz/data visualization/node style|.
1480 \end{key}
1481 %
1482 \begin{key}{/tikz/data visualization/visualizer label options/text colored}
1483 Causes the |node style| to set the text color to |visualizer color|.
1484 The effect of this is that the label's text will have the same color as
1485 the data set to which it is attached.
1486 \end{key}
1487
1488 \begin{stylekey}{/tikz/data visualization/every data set label}
1489 This style is executed with every label that represents a data set.
1490 Inside this style, use |node style| to change the appearance of nodes.
1491 This style has a default definition, usually you should just append
1492 things to this style.
1493 %
1494 \begin{codeexample}[
1495 width=6.3cm,
1496 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1497 pre={\tikz \datavisualization data group {function classes} = {
1498 data [set=log, format=function] {
1499 var x : interval [0.2:2.5];
1500 func y = ln(\value x);
1501 }
1502 data [set=lin, format=function] {
1503 var x : interval [-2:2.5];
1504 func y = 0.5*\value x;
1505 }
1506 data [set=squared, format=function] {
1507 var x : interval [-1.5:1.5];
1508 func y = \value x*\value x;
1509 }
1510 data [set=exp, format=function] {
1511 var x : interval [-2.5:1];
1512 func y = exp(\value x);
1513 }
1514 };},
1515 ]
1516 \tikz \datavisualization [
1517 school book axes,
1518 x axis={label=$x$},
1519 visualize as smooth line/.list={log, lin, squared, exp},
1520 every data set label/.append style={text colored},
1521 log= {label in data={text'=$\log x$, when=y is -1}},
1522 lin= {label in data={text=$x/2$,
1523 node style=sloped, when=x is 2}},
1524 squared={label in data={text=$x^2$, when=x is 1.1}},
1525 exp= {label in data={text=$e^x$,
1526 node style=sloped, when=x is -2}},
1527 style sheet=vary hue]
1528 data group {function classes};
1529 \end{codeexample}
1530 \end{stylekey}
1531
1532 \begin{stylekey}{/tikz/data visualization/every label in data}
1533 Like |every data set label|, this key is also executed with labels.
1534 However, this key is executed after the style sheets have been
1535 executed, giving you a chance to overrule their styling.
1536 \end{stylekey}
1537 \end{key}
1538
1539
1540 \subsubsection{Connecting a Label to a Data Set via a Pin}
1541
1542 \begin{key}{/tikz/data visualization/visualizer options/pin in data=\meta{options}}
1543 This key is a variant of the |label in data| key and takes the same
1544 options, plus two additional ones. The difference to |label in data| is
1545 that the label node is shown a bit removed from the data set, but connected
1546 to it via a small line (this is like the difference between the |label| and
1547 |pin| options).
1548 %
1549 \begin{codeexample}[
1550 width=6.3cm,
1551 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1552 ]
1553 \tikz \datavisualization [
1554 scientific axes=clean,
1555 visualize as smooth line/.list={linear, squared, cubed},
1556 linear ={pin in data={text=$2x$}},
1557 squared={pin in data={text=$x^2$}},
1558 cubed ={pin in data={text=$x^3$}}]
1559 data [set=linear, format=function] {
1560 var x : interval [0:1.5];
1561 func y = \value x;
1562 }
1563 data [set=squared, format=function] {
1564 var x : interval [0:1.5];
1565 func y = \value x * \value x;
1566 }
1567 data [set=cubed, format=function] {
1568 var x : interval [0:1.5];
1569 func y = \value x * \value x * \value x;
1570 };
1571 \end{codeexample}
1572 %
1573 The following keys can be used additionally:
1574 %
1575 \begin{key}{/tikz/data visualization/visualizer label options/pin angle=\meta{angle}}
1576 The position of the label of a |pin in data| is mainly computed in the
1577 same way as for a |label in data|. However, once the position has been
1578 computed, the label is shifted as follows:
1579 %
1580 \begin{itemize}
1581 \item When an \meta{angle} is specified using the present key, the
1582 shift is by the current value of |pin length| in the direction
1583 of \meta{angle}.
1584 \item When \meta{angle} is empty (which is the default), then the
1585 shift is also by the current value of |pin length|, but now in
1586 the direction that is orthogonal and to the left of the line
1587 between the coordinate of the data point and the coordinate of
1588 the next data point. When |text'| is used, the direction is to
1589 the right instead of the left.
1590 \end{itemize}
1591 \end{key}
1592
1593 \begin{key}{/tikz/data visualization/visualizer label options/pin length=\meta{dimension}}
1594 See the description of |pin angle|.
1595 \end{key}
1596 %
1597 \begin{codeexample}[
1598 width=6.3cm,
1599 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1600 pre={\tikz \datavisualization data group {function classes} = {
1601 data [set=log, format=function] {
1602 var x : interval [0.2:2.5];
1603 func y = ln(\value x);
1604 }
1605 data [set=lin, format=function] {
1606 var x : interval [-2:2.5];
1607 func y = 0.5*\value x;
1608 }
1609 data [set=squared, format=function] {
1610 var x : interval [-1.5:1.5];
1611 func y = \value x*\value x;
1612 }
1613 data [set=exp, format=function] {
1614 var x : interval [-2.5:1];
1615 func y = exp(\value x);
1616 }
1617 };},
1618 ]
1619 \tikz \datavisualization [
1620 school book axes,
1621 x axis={label=$x$},
1622 visualize as smooth line/.list={log, lin, squared, exp},
1623 every data set label/.append style={text colored},
1624 log= {pin in data={text'=$\log x$, when=y is -1}},
1625 lin= {pin in data={text=$x/2$, when=x is 2,
1626 pin length=1ex}},
1627 squared={pin in data={text=$x^2$, when=x is 1.1,
1628 pin angle=230}},
1629 exp= {label in data={text=$e^x$, when=x is -2}},
1630 style sheet=vary hue]
1631 data group {function classes};
1632 \end{codeexample}
1633 \end{key}
1634
1635
1636 \subsection{Usage: Labeling Data Sets Inside a Legend}
1637
1638 The ``classical'' way of indicating the style used for the different data sets
1639 inside a visualization is a \emph{legend}. It is a description next to or even
1640 inside the visualization that contains one line for each data set and displays
1641 an iconographic version of the data set next to some text labeling the data
1642 set. Note, however, that even though legend are quite common, also consider
1643 using a |label in data| or a |pin in data| instead.
1644
1645 Creating a high-quality legend is by no means simple. A legend should not
1646 distract the reader, so aggressive borders should definitively be avoided. A
1647 legend should make it easy to match the actual styling of a data set (like,
1648 say, using a red, dashed line) to the ``iconographic'' representation of this
1649 styling. An example of what can go wrong here is using short lines to represent
1650 lines dashed in different way where the lines are so short that the differences
1651 in the dashing cannot be discerned. Another example is showing straight lines
1652 with plot marks on them where the plot marks are obscured by the horizontal
1653 line itself, while the plot marks are clearly visible in the actual
1654 visualization since no horizontal lines occur.
1655
1656 The data visualization engine comes with a large set of options for creating
1657 and placing high-quality legends next or inside data visualizations.
1658
1659
1660 \subsubsection{Creating Legends and Legend Entries}
1661
1662 A data visualization can be accompanied by one or more legends. In order to
1663 create a legend, the following key can be used (although, in practice, you will
1664 usually use the |legend| key instead, see below):
1665
1666 \begin{key}{/tikz/data visualization/new legend=\meta{legend name} (default main legend)}
1667 This key is used to create a new legend named \meta{legend name}. The
1668 legend is empty by default and further options are needed to add entries to
1669 it. When the key is called a second time for the same \meta{legend name}
1670 nothing happens.
1671
1672 When a legend is created, a new key is created that can subsequently be
1673 used to configure the legend:
1674 %
1675 \begin{key}{/tikz/data visualization/\meta{legend name}=\meta{options}}
1676 When this key is used, the \meta{options} are executed with the path
1677 prefix
1678 %
1679 \begin{codeexample}[code only]
1680 /tikz/data visualization/legend options
1681 \end{codeexample}
1682 %
1683 The different keys with this path prefix allow you to change the
1684 position where the legend is shown and how it is organised (for
1685 instance, whether legend entries are shown in a row or in a column or
1686 in a square).
1687
1688 The different possible keys will be explained in the course of this
1689 section.
1690 \end{key}
1691
1692 In the end, the legend is just a \tikzname\ node, a |matrix| node, to be
1693 precise. The following key is used to style this node:
1694
1695 \begin{key}{/tikz/data visualization/legend options/matrix node style=\meta{options}}
1696 Adds the \meta{options} to the list of options that will be executed
1697 when the legend's node is created.
1698 %
1699 \begin{codeexample}[
1700 width=8cm,
1701 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1702 pre={\tikz \datavisualization data group {function classes} = {
1703 data [set=log, format=function] {
1704 var x : interval [0.2:2.5];
1705 func y = ln(\value x);
1706 }
1707 data [set=lin, format=function] {
1708 var x : interval [-2:2.5];
1709 func y = 0.5*\value x;
1710 }
1711 data [set=squared, format=function] {
1712 var x : interval [-1.5:1.5];
1713 func y = \value x*\value x;
1714 }
1715 data [set=exp, format=function] {
1716 var x : interval [-2.5:1];
1717 func y = exp(\value x);
1718 }
1719 };},
1720 ]
1721 \tikz \datavisualization [
1722 scientific axes,
1723 visualize as smooth line/.list=
1724 {log, lin, squared, exp},
1725 legend={matrix node style={fill=black!25}},
1726 log= {label in legend={text=$\log x$}},
1727 lin= {label in legend={text=$x/2$}},
1728 squared={label in legend={text=$x^2$}},
1729 exp= {label in legend={text=$e^x$}},
1730 style sheet=vary dashing]
1731 data group {function classes};
1732 \end{codeexample}
1733 \end{key}
1734
1735 The following style allows you to configure the default appearance of every
1736 newly created legend:
1737 %
1738 \begin{stylekey}{/tikz/data visualization/legend options/every new legend}
1739 This key defaults to |east outside, label style=text right|. This means
1740 that by default a legend is placed to the right of the data
1741 visualization and that in the individual legend entries the text is to
1742 the right of the data set visualization.
1743 \end{stylekey}
1744 %
1745 \begin{codeexample}[
1746 width=6cm,
1747 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1748 pre={\tikz \datavisualization data group {function classes} = {
1749 data [set=log, format=function] {
1750 var x : interval [0.2:2.5];
1751 func y = ln(\value x);
1752 }
1753 data [set=lin, format=function] {
1754 var x : interval [-2:2.5];
1755 func y = 0.5*\value x;
1756 }
1757 data [set=squared, format=function] {
1758 var x : interval [-1.5:1.5];
1759 func y = \value x*\value x;
1760 }
1761 data [set=exp, format=function] {
1762 var x : interval [-2.5:1];
1763 func y = exp(\value x);
1764 }
1765 };},
1766 ]
1767 \tikz \datavisualization [
1768 scientific axes, x axis={label=$x$},
1769 visualize as smooth line/.list={log, lin, squared, exp},
1770 new legend={upper legend},
1771 new legend={lower legend},
1772 upper legend=above,
1773 lower legend=below,
1774 log= {label in legend={text=$\log x$, legend=upper legend}},
1775 lin= {label in legend={text=$x/2$, legend=upper legend}},
1776 squared={label in legend={text=$x^2$, legend=lower legend}},
1777 exp= {label in legend={text=$e^x$, legend=lower legend}},
1778 style sheet=vary dashing]
1779 data group {function classes};
1780 \end{codeexample}
1781 %
1782 \end{key}
1783
1784 \begin{key}{/tikz/data visualization/legend=\meta{options}}
1785 This is a shorthand for
1786 |new legend=main legend, main legend=|\meta{options}. In other words, this
1787 key creates a new |main legend| and immediately passes the configuration
1788 \meta{options} to this legend.
1789 %
1790 \begin{codeexample}[
1791 width=7cm,
1792 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1793 pre={\tikz \datavisualization data group {function classes} = {
1794 data [set=log, format=function] {
1795 var x : interval [0.2:2.5];
1796 func y = ln(\value x);
1797 }
1798 data [set=lin, format=function] {
1799 var x : interval [-2:2.5];
1800 func y = 0.5*\value x;
1801 }
1802 data [set=squared, format=function] {
1803 var x : interval [-1.5:1.5];
1804 func y = \value x*\value x;
1805 }
1806 data [set=exp, format=function] {
1807 var x : interval [-2.5:1];
1808 func y = exp(\value x);
1809 }
1810 };},
1811 ]
1812 \tikz \datavisualization [
1813 scientific axes, x axis={label=$x$},
1814 visualize as smooth line/.list={log, lin, squared, exp},
1815 legend=below,
1816 log= {label in legend={text=$\log x$}},
1817 lin= {label in legend={text=$x/2$}},
1818 squared={label in legend={text=$x^2$}},
1819 exp= {label in legend={text=$e^x$}},
1820 style sheet=vary dashing]
1821 data group {function classes};
1822 \end{codeexample}
1823 %
1824 \end{key}
1825
1826 As pointed out above, a legend is empty by default. In particular, the
1827 different data sets are not automatically inserted into the legend. Instead,
1828 the key |label in legend| must be used together with a data set:
1829
1830 \begin{key}{/tikz/data visualization/visualizer options/label in legend=\meta{options}}
1831 This key is passed to a data set, similar to options like |pin in data| or
1832 |smooth line|. The \meta{options} are used to configure the following:
1833 %
1834 \begin{itemize}
1835 \item The legend in which the data set should be visualized.
1836 \item The text that is to be shown in the legend for the data set.
1837 \item The appearance of the legend entries.
1838 \end{itemize}
1839 %
1840 In detail, the \meta{options} are executed with the path prefix
1841 %
1842 \begin{codeexample}[code only]
1843 /tikz/data visualization/legend entry options
1844 \end{codeexample}
1845 %
1846 To configure in which legend the label should appear, use the
1847 following key:
1848 %
1849 \begin{key}{/tikz/data visualization/legend entry options/legend=\meta{name} (initially main legend)}
1850 Set this key to the name of a legend that has previously been created
1851 using |new legend|. The label will then be shown in this legend.
1852
1853 In most cases, there is only one legend (namely |main legend|) and
1854 there is no need to set this key since it defaults to the main legend.
1855
1856 Also note that the legend \meta{name} is automatically created if it
1857 nodes not yet exist.
1858 \end{key}
1859
1860 \begin{key}{/tikz/data visualization/legend entry options/text=\meta{text}}
1861 Use this key to setup the \meta{text} that is shown as the label of the
1862 data set.
1863 %
1864 \begin{codeexample}[
1865 width=8cm,
1866 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1867 pre={\tikz \datavisualization data group {function classes} = {
1868 data [set=log, format=function] {
1869 var x : interval [0.2:2.5];
1870 func y = ln(\value x);
1871 }
1872 data [set=lin, format=function] {
1873 var x : interval [-2:2.5];
1874 func y = 0.5*\value x;
1875 }
1876 data [set=squared, format=function] {
1877 var x : interval [-1.5:1.5];
1878 func y = \value x*\value x;
1879 }
1880 data [set=exp, format=function] {
1881 var x : interval [-2.5:1];
1882 func y = exp(\value x);
1883 }
1884 };},
1885 ]
1886 \tikz \datavisualization [
1887 scientific axes, x axis={label=$x$},
1888 visualize as smooth line/.list=
1889 {log, lin, squared, exp},
1890 log= {label in legend={text=$\log x$}},
1891 lin= {label in legend={text=$x/2$}},
1892 squared={pin in data ={text=$x^2$, pos=0.1}},
1893 exp= {label in data ={text=$e^x$}},
1894 style sheet=vary dashing]
1895 data group {function classes};
1896 \end{codeexample}
1897 \end{key}
1898
1899 In addition to the two keys described above, there are further keys that
1900 are described in Section~\ref{section-dv-label-legend-entry-options}.
1901 \end{key}
1902
1903
1904 \subsubsection{Rows and Columns of Legend Entries}
1905
1906 In a legend, the different legend entries are arranged in a matrix, which
1907 typically has only one row or one column. For the impatient reader: Say
1908 |rows=1| to get everything in a row, say |columns=1| to get everything in a
1909 single column, and skip the rest of this section.
1910
1911 The more patient reader will appreciate that when there are very many different
1912 data sets in a single visualization, it may be necessary to use more than one
1913 row or column inside the legend. \tikzname\ comes with a rather powerful
1914 mechanism for distributing the multiple legend entries over the matrix.
1915
1916 The first thing to decide is in which ``direction'' the entries should be
1917 inserted into the matrix. Suppose we have a $3 \times 3$ matrix and our entries
1918 are $a$, $b$, $c$, and so on. Then, one might place the $a$ in the upper left
1919 corner of the matrix, $b$ in the upper middle position, $c$ in the upper right
1920 position, and $d$ in the middle left position. This is a ``first right, then
1921 down'' strategy. A different strategy might be to place the $a$ in the upper
1922 left corner, but $b$ in the middle left position, $c$ in the lower left
1923 position, and $d$ then in the upper middle position. This is a ``first down,
1924 then right'' strategy. In certain situations it might even make sense to place
1925 $a$ in the lower right corner and then go ``first up, then left''.
1926
1927 All of these strategies are supported by the |legend| command. You can
1928 configure which strategy is used using the following keys:
1929
1930 \tikzdatavisualizationset {
1931 legend example/.style={
1932 scientific axes, all axes={length=1cm, ticks=none},
1933 1={label in legend={text=1}},
1934 2={label in legend={text=2}},
1935 3={label in legend={text=3}},
1936 4={label in legend={text=4}},
1937 5={label in legend={text=5}},
1938 6={label in legend={text=6}},
1939 7={label in legend={text=7}},
1940 8={label in legend={text=8}}
1941 }
1942 }
1943
1944 \begin{key}{/tikz/data visualization/legend options/down then right}
1945 Causes the legend entries to fill the legend matrix first downward and,
1946 once a column is full, the next column is begun to the right of the
1947 previous one. This is the default.
1948 %
1949 \begin{codeexample}[
1950 width=6cm,
1951 preamble={\usetikzlibrary{datavisualization.formats.functions}},
1952 pre={\tikz \datavisualization data group {sin functions} = {
1953 data [format=function] {
1954 var set : {1,...,8};
1955 var x : interval [0:50];
1956 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
1957 }
1958 };%
1959 \tikzdatavisualizationset {
1960 legend example/.style={
1961 scientific axes, all axes={length=1cm, ticks=none},
1962 1={label in legend={text=1}},
1963 2={label in legend={text=2}},
1964 3={label in legend={text=3}},
1965 4={label in legend={text=4}},
1966 5={label in legend={text=5}},
1967 6={label in legend={text=6}},
1968 7={label in legend={text=7}},
1969 8={label in legend={text=8}}
1970 }
1971 }},
1972 ]
1973 \tikz \datavisualization [
1974 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
1975 legend example, style sheet=vary hue,
1976 main legend={down then right, columns=3}]
1977 data group {sin functions};
1978 \end{codeexample}
1979 %
1980 In the example, the |legend example| is the following style:
1981 %
1982 \begin{codeexample}[code only]
1983 \tikzdatavisualizationset {
1984 legend example/.style={
1985 scientific axes, all axes={length=1cm, ticks=none},
1986 1={label in legend={text=1}},
1987 2={label in legend={text=2}},
1988 3={label in legend={text=3}},
1989 4={label in legend={text=4}},
1990 5={label in legend={text=5}},
1991 6={label in legend={text=6}},
1992 7={label in legend={text=7}},
1993 8={label in legend={text=8}}
1994 }
1995 }
1996 \end{codeexample}
1997 %
1998 \end{key}
1999
2000 \begin{key}{/tikz/data visualization/legend options/down then left}
2001 \begin{codeexample}[
2002 width=6cm,
2003 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2004 pre={\tikz \datavisualization data group {sin functions} = {
2005 data [format=function] {
2006 var set : {1,...,8};
2007 var x : interval [0:50];
2008 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2009 }
2010 };%
2011 \tikzdatavisualizationset {
2012 legend example/.style={
2013 scientific axes, all axes={length=1cm, ticks=none},
2014 1={label in legend={text=1}},
2015 2={label in legend={text=2}},
2016 3={label in legend={text=3}},
2017 4={label in legend={text=4}},
2018 5={label in legend={text=5}},
2019 6={label in legend={text=6}},
2020 7={label in legend={text=7}},
2021 8={label in legend={text=8}}
2022 }
2023 }},
2024 ]
2025 \tikz \datavisualization [
2026 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2027 legend example, style sheet=vary hue,
2028 main legend={down then left, columns=3}]
2029 data group {sin functions};
2030 \end{codeexample}
2031 \end{key}
2032
2033 \begin{key}{/tikz/data visualization/legend options/up then right}
2034 \begin{codeexample}[
2035 width=6cm,
2036 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2037 pre={\tikz \datavisualization data group {sin functions} = {
2038 data [format=function] {
2039 var set : {1,...,8};
2040 var x : interval [0:50];
2041 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2042 }
2043 };%
2044 \tikzdatavisualizationset {
2045 legend example/.style={
2046 scientific axes, all axes={length=1cm, ticks=none},
2047 1={label in legend={text=1}},
2048 2={label in legend={text=2}},
2049 3={label in legend={text=3}},
2050 4={label in legend={text=4}},
2051 5={label in legend={text=5}},
2052 6={label in legend={text=6}},
2053 7={label in legend={text=7}},
2054 8={label in legend={text=8}}
2055 }
2056 }},
2057 ]
2058 \tikz \datavisualization [
2059 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2060 legend example, style sheet=vary hue,
2061 main legend={up then right, columns=3}]
2062 data group {sin functions};
2063 \end{codeexample}
2064 \end{key}
2065
2066 \begin{key}{/tikz/data visualization/legend options/up then left}
2067 \begin{codeexample}[
2068 width=6cm,
2069 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2070 pre={\tikz \datavisualization data group {sin functions} = {
2071 data [format=function] {
2072 var set : {1,...,8};
2073 var x : interval [0:50];
2074 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2075 }
2076 };%
2077 \tikzdatavisualizationset {
2078 legend example/.style={
2079 scientific axes, all axes={length=1cm, ticks=none},
2080 1={label in legend={text=1}},
2081 2={label in legend={text=2}},
2082 3={label in legend={text=3}},
2083 4={label in legend={text=4}},
2084 5={label in legend={text=5}},
2085 6={label in legend={text=6}},
2086 7={label in legend={text=7}},
2087 8={label in legend={text=8}}
2088 }
2089 }},
2090 ]
2091 \tikz \datavisualization [
2092 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2093 legend example, style sheet=vary hue,
2094 main legend={up then left, columns=3}]
2095 data group {sin functions};
2096 \end{codeexample}
2097 \end{key}
2098
2099 \begin{key}{/tikz/data visualization/legend options/left then up}
2100 \begin{codeexample}[
2101 width=6cm,
2102 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2103 pre={\tikz \datavisualization data group {sin functions} = {
2104 data [format=function] {
2105 var set : {1,...,8};
2106 var x : interval [0:50];
2107 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2108 }
2109 };%
2110 \tikzdatavisualizationset {
2111 legend example/.style={
2112 scientific axes, all axes={length=1cm, ticks=none},
2113 1={label in legend={text=1}},
2114 2={label in legend={text=2}},
2115 3={label in legend={text=3}},
2116 4={label in legend={text=4}},
2117 5={label in legend={text=5}},
2118 6={label in legend={text=6}},
2119 7={label in legend={text=7}},
2120 8={label in legend={text=8}}
2121 }
2122 }},
2123 ]
2124 \tikz \datavisualization [
2125 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2126 legend example, style sheet=vary hue,
2127 main legend={left then up, columns=3}]
2128 data group {sin functions};
2129 \end{codeexample}
2130 \end{key}
2131
2132 \begin{key}{/tikz/data visualization/legend options/left then down}
2133 \begin{codeexample}[
2134 width=6cm,
2135 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2136 pre={\tikz \datavisualization data group {sin functions} = {
2137 data [format=function] {
2138 var set : {1,...,8};
2139 var x : interval [0:50];
2140 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2141 }
2142 };%
2143 \tikzdatavisualizationset {
2144 legend example/.style={
2145 scientific axes, all axes={length=1cm, ticks=none},
2146 1={label in legend={text=1}},
2147 2={label in legend={text=2}},
2148 3={label in legend={text=3}},
2149 4={label in legend={text=4}},
2150 5={label in legend={text=5}},
2151 6={label in legend={text=6}},
2152 7={label in legend={text=7}},
2153 8={label in legend={text=8}}
2154 }
2155 }},
2156 ]
2157 \tikz \datavisualization [
2158 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2159 legend example, style sheet=vary hue,
2160 main legend={left then down, columns=3}]
2161 data group {sin functions};
2162 \end{codeexample}
2163 \end{key}
2164
2165 \begin{key}{/tikz/data visualization/legend options/right then up}
2166 \begin{codeexample}[
2167 width=6cm,
2168 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2169 pre={\tikz \datavisualization data group {sin functions} = {
2170 data [format=function] {
2171 var set : {1,...,8};
2172 var x : interval [0:50];
2173 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2174 }
2175 };%
2176 \tikzdatavisualizationset {
2177 legend example/.style={
2178 scientific axes, all axes={length=1cm, ticks=none},
2179 1={label in legend={text=1}},
2180 2={label in legend={text=2}},
2181 3={label in legend={text=3}},
2182 4={label in legend={text=4}},
2183 5={label in legend={text=5}},
2184 6={label in legend={text=6}},
2185 7={label in legend={text=7}},
2186 8={label in legend={text=8}}
2187 }
2188 }},
2189 ]
2190 \tikz \datavisualization [
2191 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2192 legend example, style sheet=vary hue,
2193 main legend={right then up, columns=3}]
2194 data group {sin functions};
2195 \end{codeexample}
2196 \end{key}
2197
2198 \begin{key}{/tikz/data visualization/legend options/right then down}
2199 \begin{codeexample}[
2200 width=6cm,
2201 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2202 pre={\tikz \datavisualization data group {sin functions} = {
2203 data [format=function] {
2204 var set : {1,...,8};
2205 var x : interval [0:50];
2206 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2207 }
2208 };%
2209 \tikzdatavisualizationset {
2210 legend example/.style={
2211 scientific axes, all axes={length=1cm, ticks=none},
2212 1={label in legend={text=1}},
2213 2={label in legend={text=2}},
2214 3={label in legend={text=3}},
2215 4={label in legend={text=4}},
2216 5={label in legend={text=5}},
2217 6={label in legend={text=6}},
2218 7={label in legend={text=7}},
2219 8={label in legend={text=8}}
2220 }
2221 }},
2222 ]
2223 \tikz \datavisualization [
2224 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2225 legend example, style sheet=vary hue,
2226 main legend={right then down, columns=3}]
2227 data group {sin functions};
2228 \end{codeexample}
2229 \end{key}
2230
2231 Having configured the directions in which the matrix is being filled, you must
2232 next setup the number of rows or columns that are to be shown. There are
2233 actually two different ways of doing so. The first way is to specify a maximum
2234 number of rows or columns. For instance, you might specify that there should be
2235 at most ten rows to a column and when there are more, a new column should be
2236 begun. This is achieved using the following keys:
2237
2238 \begin{key}{/tikz/data visualization/legend options/max rows=\meta{number}}
2239 As the legend matrix is being filled, whenever the number of rows in the
2240 current column would exceed \meta{number}, a new column is started.
2241 %
2242 \begin{codeexample}[
2243 width=7cm,
2244 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2245 pre={\tikz \datavisualization data group {sin functions} = {
2246 data [format=function] {
2247 var set : {1,...,8};
2248 var x : interval [0:50];
2249 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2250 }
2251 };%
2252 \tikzdatavisualizationset {
2253 legend example/.style={
2254 scientific axes, all axes={length=1cm, ticks=none},
2255 1={label in legend={text=1}},
2256 2={label in legend={text=2}},
2257 3={label in legend={text=3}},
2258 4={label in legend={text=4}},
2259 5={label in legend={text=5}},
2260 6={label in legend={text=6}},
2261 7={label in legend={text=7}},
2262 8={label in legend={text=8}}
2263 }
2264 }},
2265 ]
2266 \tikz \datavisualization [
2267 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2268 legend example, style sheet=vary hue,
2269 main legend={max rows=3}]
2270 data group {sin functions};
2271 \end{codeexample}
2272 %
2273 \begin{codeexample}[
2274 width=7cm,
2275 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2276 pre={\tikz \datavisualization data group {sin functions} = {
2277 data [format=function] {
2278 var set : {1,...,8};
2279 var x : interval [0:50];
2280 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2281 }
2282 };%
2283 \tikzdatavisualizationset {
2284 legend example/.style={
2285 scientific axes, all axes={length=1cm, ticks=none},
2286 1={label in legend={text=1}},
2287 2={label in legend={text=2}},
2288 3={label in legend={text=3}},
2289 4={label in legend={text=4}},
2290 5={label in legend={text=5}},
2291 6={label in legend={text=6}},
2292 7={label in legend={text=7}},
2293 8={label in legend={text=8}}
2294 }
2295 }},
2296 ]
2297 \tikz \datavisualization [
2298 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2299 legend example, style sheet=vary hue,
2300 main legend={max rows=4}]
2301 data group {sin functions};
2302 \end{codeexample}
2303 %
2304 \begin{codeexample}[
2305 width=7cm,
2306 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2307 pre={\tikz \datavisualization data group {sin functions} = {
2308 data [format=function] {
2309 var set : {1,...,8};
2310 var x : interval [0:50];
2311 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2312 }
2313 };%
2314 \tikzdatavisualizationset {
2315 legend example/.style={
2316 scientific axes, all axes={length=1cm, ticks=none},
2317 1={label in legend={text=1}},
2318 2={label in legend={text=2}},
2319 3={label in legend={text=3}},
2320 4={label in legend={text=4}},
2321 5={label in legend={text=5}},
2322 6={label in legend={text=6}},
2323 7={label in legend={text=7}},
2324 8={label in legend={text=8}}
2325 }
2326 }},
2327 ]
2328 \tikz \datavisualization [
2329 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2330 legend example, style sheet=vary hue,
2331 main legend={max rows=5}]
2332 data group {sin functions};
2333 \end{codeexample}
2334 %
2335 \end{key}
2336
2337 \begin{key}{/tikz/data visualization/legend options/max columns=\meta{number}}
2338 This key works like |max rows|, only now the number of columns is
2339 monitored. Note that this strategy only really makes sense when the when
2340 you use this key with a strategy that first goes left or right and then up
2341 or down.
2342 %
2343 \begin{codeexample}[
2344 width=7cm,
2345 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2346 pre={\tikz \datavisualization data group {sin functions} = {
2347 data [format=function] {
2348 var set : {1,...,8};
2349 var x : interval [0:50];
2350 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2351 }
2352 };%
2353 \tikzdatavisualizationset {
2354 legend example/.style={
2355 scientific axes, all axes={length=1cm, ticks=none},
2356 1={label in legend={text=1}},
2357 2={label in legend={text=2}},
2358 3={label in legend={text=3}},
2359 4={label in legend={text=4}},
2360 5={label in legend={text=5}},
2361 6={label in legend={text=6}},
2362 7={label in legend={text=7}},
2363 8={label in legend={text=8}}
2364 }
2365 }},
2366 ]
2367 \tikz \datavisualization [
2368 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2369 legend example, style sheet=vary hue,
2370 main legend={right then down, max columns=2}]
2371 data group {sin functions};
2372 \end{codeexample}
2373 %
2374 \begin{codeexample}[
2375 width=7cm,
2376 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2377 pre={\tikz \datavisualization data group {sin functions} = {
2378 data [format=function] {
2379 var set : {1,...,8};
2380 var x : interval [0:50];
2381 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2382 }
2383 };%
2384 \tikzdatavisualizationset {
2385 legend example/.style={
2386 scientific axes, all axes={length=1cm, ticks=none},
2387 1={label in legend={text=1}},
2388 2={label in legend={text=2}},
2389 3={label in legend={text=3}},
2390 4={label in legend={text=4}},
2391 5={label in legend={text=5}},
2392 6={label in legend={text=6}},
2393 7={label in legend={text=7}},
2394 8={label in legend={text=8}}
2395 }
2396 }},
2397 ]
2398 \tikz \datavisualization [
2399 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2400 legend example, style sheet=vary hue,
2401 main legend={right then down,max columns=3}]
2402 data group {sin functions};
2403 \end{codeexample}
2404 %
2405 \begin{codeexample}[
2406 width=7cm,
2407 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2408 pre={\tikz \datavisualization data group {sin functions} = {
2409 data [format=function] {
2410 var set : {1,...,8};
2411 var x : interval [0:50];
2412 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2413 }
2414 };%
2415 \tikzdatavisualizationset {
2416 legend example/.style={
2417 scientific axes, all axes={length=1cm, ticks=none},
2418 1={label in legend={text=1}},
2419 2={label in legend={text=2}},
2420 3={label in legend={text=3}},
2421 4={label in legend={text=4}},
2422 5={label in legend={text=5}},
2423 6={label in legend={text=6}},
2424 7={label in legend={text=7}},
2425 8={label in legend={text=8}}
2426 }
2427 }},
2428 ]
2429 \tikz \datavisualization [
2430 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2431 legend example, style sheet=vary hue,
2432 main legend={right then down,max columns=4}]
2433 data group {sin functions};
2434 \end{codeexample}
2435 %
2436 \end{key}
2437
2438 The second way of specifying the number of entries in a row or column is to
2439 specify an ``ideal number of rows or columns''. The idea is as follows: Suppose
2440 that we use the standard strategy and would like to have everything in two
2441 columns. Then if there are eight entries, the first four should go to the first
2442 column, while the next four should go to the second column. If we have 20
2443 entries, the first ten should go the first column and the next ten to the
2444 second, and so on. So, in general, the objective is to distribute the entries
2445 evenly so the this ``ideal number of columns'' is reached. Only when there are
2446 too few entries to achieve this or when the number of entries per column would
2447 exceed the |max rows| value, will the number of columns deviate from this ideal
2448 value.
2449
2450 \begin{key}{/tikz/data visualization/legend options/ideal number of columns=\meta{number}}
2451 Specifies, that the entries should be split into \meta{number} different
2452 columns, whenever possible. However, when there would be more than the
2453 |max rows| value of rows per column, more columns than the ideal number are
2454 created.
2455 %
2456 \begin{codeexample}[
2457 width=7cm,
2458 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2459 pre={\tikz \datavisualization data group {sin functions} = {
2460 data [format=function] {
2461 var set : {1,...,8};
2462 var x : interval [0:50];
2463 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2464 }
2465 };%
2466 \tikzdatavisualizationset {
2467 legend example/.style={
2468 scientific axes, all axes={length=1cm, ticks=none},
2469 1={label in legend={text=1}},
2470 2={label in legend={text=2}},
2471 3={label in legend={text=3}},
2472 4={label in legend={text=4}},
2473 5={label in legend={text=5}},
2474 6={label in legend={text=6}},
2475 7={label in legend={text=7}},
2476 8={label in legend={text=8}}
2477 }
2478 }},
2479 ]
2480 \tikz \datavisualization [
2481 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2482 legend example, style sheet=vary hue,
2483 main legend={ideal number of columns=2}]
2484 data group {sin functions};
2485 \end{codeexample}
2486 %
2487 \begin{codeexample}[
2488 width=7cm,
2489 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2490 pre={\tikz \datavisualization data group {sin functions} = {
2491 data [format=function] {
2492 var set : {1,...,8};
2493 var x : interval [0:50];
2494 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2495 }
2496 };%
2497 \tikzdatavisualizationset {
2498 legend example/.style={
2499 scientific axes, all axes={length=1cm, ticks=none},
2500 1={label in legend={text=1}},
2501 2={label in legend={text=2}},
2502 3={label in legend={text=3}},
2503 4={label in legend={text=4}},
2504 5={label in legend={text=5}},
2505 6={label in legend={text=6}},
2506 7={label in legend={text=7}},
2507 8={label in legend={text=8}}
2508 }
2509 }},
2510 ]
2511 \tikz \datavisualization [
2512 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2513 legend example, style sheet=vary hue,
2514 main legend={ideal number of columns=4}]
2515 data group {sin functions};
2516 \end{codeexample}
2517 %
2518 \begin{codeexample}[
2519 width=7cm,
2520 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2521 pre={\tikz \datavisualization data group {sin functions} = {
2522 data [format=function] {
2523 var set : {1,...,8};
2524 var x : interval [0:50];
2525 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2526 }
2527 };%
2528 \tikzdatavisualizationset {
2529 legend example/.style={
2530 scientific axes, all axes={length=1cm, ticks=none},
2531 1={label in legend={text=1}},
2532 2={label in legend={text=2}},
2533 3={label in legend={text=3}},
2534 4={label in legend={text=4}},
2535 5={label in legend={text=5}},
2536 6={label in legend={text=6}},
2537 7={label in legend={text=7}},
2538 8={label in legend={text=8}}
2539 }
2540 }},
2541 ]
2542 \tikz \datavisualization [
2543 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2544 legend example, style sheet=vary hue,
2545 main legend={max rows=3,ideal number of columns=2}]
2546 data group {sin functions};
2547 \end{codeexample}
2548 %
2549 \end{key}
2550
2551 \begin{key}{/tikz/data visualization/legend options/rows=\meta{number}}
2552 Shorthand for |ideal number of rows=|\meta{number}.
2553 \end{key}
2554
2555 \begin{key}{/tikz/data visualization/legend options/ideal number of rows=\meta{number}}
2556 Works like |ideal number of columns|.
2557 %
2558 \begin{codeexample}[
2559 width=7cm,
2560 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2561 pre={\tikz \datavisualization data group {sin functions} = {
2562 data [format=function] {
2563 var set : {1,...,8};
2564 var x : interval [0:50];
2565 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2566 }
2567 };%
2568 \tikzdatavisualizationset {
2569 legend example/.style={
2570 scientific axes, all axes={length=1cm, ticks=none},
2571 1={label in legend={text=1}},
2572 2={label in legend={text=2}},
2573 3={label in legend={text=3}},
2574 4={label in legend={text=4}},
2575 5={label in legend={text=5}},
2576 6={label in legend={text=6}},
2577 7={label in legend={text=7}},
2578 8={label in legend={text=8}}
2579 }
2580 }},
2581 ]
2582 \tikz \datavisualization [
2583 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2584 legend example, style sheet=vary hue,
2585 main legend={ideal number of rows=2}]
2586 data group {sin functions};
2587 \end{codeexample}
2588 %
2589 \begin{codeexample}[
2590 width=7cm,
2591 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2592 pre={\tikz \datavisualization data group {sin functions} = {
2593 data [format=function] {
2594 var set : {1,...,8};
2595 var x : interval [0:50];
2596 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2597 }
2598 };%
2599 \tikzdatavisualizationset {
2600 legend example/.style={
2601 scientific axes, all axes={length=1cm, ticks=none},
2602 1={label in legend={text=1}},
2603 2={label in legend={text=2}},
2604 3={label in legend={text=3}},
2605 4={label in legend={text=4}},
2606 5={label in legend={text=5}},
2607 6={label in legend={text=6}},
2608 7={label in legend={text=7}},
2609 8={label in legend={text=8}}
2610 }
2611 }},
2612 ]
2613 \tikz \datavisualization [
2614 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2615 legend example, style sheet=vary hue,
2616 main legend={ideal number of rows=4}]
2617 data group {sin functions};
2618 \end{codeexample}
2619 %
2620 \begin{codeexample}[
2621 width=7cm,
2622 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2623 pre={\tikz \datavisualization data group {sin functions} = {
2624 data [format=function] {
2625 var set : {1,...,8};
2626 var x : interval [0:50];
2627 func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
2628 }
2629 };%
2630 \tikzdatavisualizationset {
2631 legend example/.style={
2632 scientific axes, all axes={length=1cm, ticks=none},
2633 1={label in legend={text=1}},
2634 2={label in legend={text=2}},
2635 3={label in legend={text=3}},
2636 4={label in legend={text=4}},
2637 5={label in legend={text=5}},
2638 6={label in legend={text=6}},
2639 7={label in legend={text=7}},
2640 8={label in legend={text=8}}
2641 }
2642 }},
2643 ]
2644 \tikz \datavisualization [
2645 visualize as smooth line/.list={1,2,3,4,5,6,7,8},
2646 legend example, style sheet=vary hue,
2647 main legend={max columns=3,ideal number of rows=2}]
2648 data group {sin functions};
2649 \end{codeexample}
2650 %
2651 \end{key}
2652
2653 \begin{key}{/tikz/data visualization/legend options/columns=\meta{number}}
2654 Shorthand for |ideal number of columns=|\meta{number}.
2655 \end{key}
2656
2657
2658 \subsubsection{Legend Placement: The General Mechanism}
2659
2660 A legend can either be placed next to the data visualization or inside the data
2661 visualization at some place where there are no data entries. Both approached
2662 have advantages: Placing the legend next to the visualization minimises the
2663 ``cluttering'' by keeping all the extra information apart from the actual data,
2664 while placing the legend inside the visualization minimises the distance
2665 between the data sets and their explanations, making it easier for the eye to
2666 connect them.
2667
2668 For both approaches there are options that make the placement easier, see
2669 Sections \ref{section-dv-legend-outside} and~\ref{section-dv-legend-inside},
2670 but these options internally just map to the following two options:
2671
2672 \begin{key}{/tikz/data visualization/legend options/anchor=\meta{anchor}}
2673 The whole legend is a \tikzname-matrix internally. Thus, in particular, it
2674 is stored in a node, which has anchors. Like for any other node, when the
2675 node is shown, the node is shifted in such a way that the \meta{anchor} of
2676 the node lies at the current |at| position.
2677 \end{key}
2678
2679 \begin{key}{/tikz/data visualization/legend options/at=\meta{coordinate}}
2680 Configures the \meta{coordinate} at which the \meta{anchor} of the legend's
2681 node should lie.
2682
2683 It may seem hard to predict a good \meta{coordinate} for a legend since,
2684 depending of the size of the axis, different positions need to the chosen
2685 for the legend. However, it turns out that one can often use the
2686 coordinates of the special nodes |data bounding box| and
2687 |data visualization bounding box|, documented in
2688 Section~\ref{section-dv-bounding-box}.
2689
2690 As an example, let us put a legend to the right of the visualization, but
2691 so that the first entry starts at the top of the visualization:
2692 %
2693 \begin{codeexample}[
2694 width=8cm,
2695 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2696 pre={\tikz \datavisualization data group {function classes} = {
2697 data [set=log, format=function] {
2698 var x : interval [0.2:2.5];
2699 func y = ln(\value x);
2700 }
2701 data [set=lin, format=function] {
2702 var x : interval [-2:2.5];
2703 func y = 0.5*\value x;
2704 }
2705 data [set=squared, format=function] {
2706 var x : interval [-1.5:1.5];
2707 func y = \value x*\value x;
2708 }
2709 data [set=exp, format=function] {
2710 var x : interval [-2.5:1];
2711 func y = exp(\value x);
2712 }
2713 };},
2714 ]
2715 \tikz \datavisualization [
2716 scientific axes, x axis={label=$x$},
2717 visualize as smooth line/.list=
2718 {log, lin, squared, exp},
2719 legend={anchor=north west, at=
2720 (data visualization bounding box.north east)},
2721 log= {label in legend={text=$\log x$}},
2722 lin= {label in legend={text=$x/2$}},
2723 squared={label in legend={text=$x^2$}},
2724 exp= {label in legend={text=$e^x$}},
2725 style sheet=vary dashing]
2726 data group {function classes};
2727 \end{codeexample}
2728 %
2729 As can be seen, a bit of an additional shift might have been in order, but
2730 the result is otherwise quite satisfactory.
2731 \end{key}
2732
2733
2734 \subsubsection{Legend Placement: Outside to the Data Visualization}
2735 \label{section-dv-legend-outside}
2736
2737 The following keys make it easy to place a legend outside the data
2738 visualization.
2739
2740 \begin{key}{/tikz/data visualization/legend options/east outside}
2741 Placing the legend to the right of the data visualization is the default:
2742 %
2743 \begin{codeexample}[
2744 width=8cm,
2745 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2746 pre={\tikz \datavisualization data group {function classes} = {
2747 data [set=log, format=function] {
2748 var x : interval [0.2:2.5];
2749 func y = ln(\value x);
2750 }
2751 data [set=lin, format=function] {
2752 var x : interval [-2:2.5];
2753 func y = 0.5*\value x;
2754 }
2755 data [set=squared, format=function] {
2756 var x : interval [-1.5:1.5];
2757 func y = \value x*\value x;
2758 }
2759 data [set=exp, format=function] {
2760 var x : interval [-2.5:1];
2761 func y = exp(\value x);
2762 }
2763 };},
2764 ]
2765 \tikz \datavisualization [
2766 scientific axes,
2767 visualize as smooth line/.list=
2768 {log, lin, squared, exp},
2769 legend=east outside,
2770 log= {label in legend={text=$\log x$}},
2771 lin= {label in legend={text=$x/2$}},
2772 squared={label in legend={text=$x^2$}},
2773 exp= {label in legend={text=$e^x$}},
2774 style sheet=strong colors]
2775 data group {function classes};
2776 \end{codeexample}
2777
2778 \begin{key}{/tikz/data visualization/legend options/right}
2779 This is an easier-to-remember alias.
2780 \end{key}
2781 \end{key}
2782
2783 \begin{key}{/tikz/data visualization/legend options/north east outside}
2784 A variant, where the legend is to the right, but aligned with the northern
2785 end of the data visualization:
2786 %
2787 \begin{codeexample}[
2788 width=8cm,
2789 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2790 pre={\tikz \datavisualization data group {function classes} = {
2791 data [set=log, format=function] {
2792 var x : interval [0.2:2.5];
2793 func y = ln(\value x);
2794 }
2795 data [set=lin, format=function] {
2796 var x : interval [-2:2.5];
2797 func y = 0.5*\value x;
2798 }
2799 data [set=squared, format=function] {
2800 var x : interval [-1.5:1.5];
2801 func y = \value x*\value x;
2802 }
2803 data [set=exp, format=function] {
2804 var x : interval [-2.5:1];
2805 func y = exp(\value x);
2806 }
2807 };},
2808 ]
2809 \tikz \datavisualization [
2810 scientific axes,
2811 visualize as smooth line/.list=
2812 {log, lin, squared, exp},
2813 legend=north east outside,
2814 log= {label in legend={text=$\log x$}},
2815 lin= {label in legend={text=$x/2$}},
2816 squared={label in legend={text=$x^2$}},
2817 exp= {label in legend={text=$e^x$}},
2818 style sheet=strong colors]
2819 data group {function classes};
2820 \end{codeexample}
2821 %
2822 \end{key}
2823
2824 \begin{key}{/tikz/data visualization/legend options/south east outside}
2825 \begin{codeexample}[
2826 width=8cm,
2827 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2828 pre={\tikz \datavisualization data group {function classes} = {
2829 data [set=log, format=function] {
2830 var x : interval [0.2:2.5];
2831 func y = ln(\value x);
2832 }
2833 data [set=lin, format=function] {
2834 var x : interval [-2:2.5];
2835 func y = 0.5*\value x;
2836 }
2837 data [set=squared, format=function] {
2838 var x : interval [-1.5:1.5];
2839 func y = \value x*\value x;
2840 }
2841 data [set=exp, format=function] {
2842 var x : interval [-2.5:1];
2843 func y = exp(\value x);
2844 }
2845 };},
2846 ]
2847 \tikz \datavisualization [
2848 scientific axes,
2849 visualize as smooth line/.list=
2850 {log, lin, squared, exp},
2851 legend=south east outside,
2852 log= {label in legend={text=$\log x$}},
2853 lin= {label in legend={text=$x/2$}},
2854 squared={label in legend={text=$x^2$}},
2855 exp= {label in legend={text=$e^x$}},
2856 style sheet=strong colors]
2857 data group {function classes};
2858 \end{codeexample}
2859 \end{key}
2860
2861 \begin{key}{/tikz/data visualization/legend options/west outside}
2862 The legend is placed left. Note that the text also swaps its position.
2863 %
2864 \begin{codeexample}[
2865 width=8cm,
2866 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2867 pre={\tikz \datavisualization data group {function classes} = {
2868 data [set=log, format=function] {
2869 var x : interval [0.2:2.5];
2870 func y = ln(\value x);
2871 }
2872 data [set=lin, format=function] {
2873 var x : interval [-2:2.5];
2874 func y = 0.5*\value x;
2875 }
2876 data [set=squared, format=function] {
2877 var x : interval [-1.5:1.5];
2878 func y = \value x*\value x;
2879 }
2880 data [set=exp, format=function] {
2881 var x : interval [-2.5:1];
2882 func y = exp(\value x);
2883 }
2884 };},
2885 ]
2886 \tikz \datavisualization [
2887 scientific axes,
2888 visualize as smooth line/.list=
2889 {log, lin, squared, exp},
2890 legend=west outside,
2891 log= {label in legend={text=$\log x$}},
2892 lin= {label in legend={text=$x/2$}},
2893 squared={label in legend={text=$x^2$}},
2894 exp= {label in legend={text=$e^x$}},
2895 style sheet=strong colors]
2896 data group {function classes};
2897 \end{codeexample}
2898 %
2899 \begin{key}{/tikz/data visualization/legend options/left}
2900 This is an easier-to-remember alias.
2901 \end{key}
2902 \end{key}
2903
2904 \begin{key}{/tikz/data visualization/legend options/north west outside}
2905 \begin{codeexample}[
2906 width=8cm,
2907 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2908 pre={\tikz \datavisualization data group {function classes} = {
2909 data [set=log, format=function] {
2910 var x : interval [0.2:2.5];
2911 func y = ln(\value x);
2912 }
2913 data [set=lin, format=function] {
2914 var x : interval [-2:2.5];
2915 func y = 0.5*\value x;
2916 }
2917 data [set=squared, format=function] {
2918 var x : interval [-1.5:1.5];
2919 func y = \value x*\value x;
2920 }
2921 data [set=exp, format=function] {
2922 var x : interval [-2.5:1];
2923 func y = exp(\value x);
2924 }
2925 };},
2926 ]
2927 \tikz \datavisualization [
2928 scientific axes,
2929 visualize as smooth line/.list=
2930 {log, lin, squared, exp},
2931 legend=north west outside,
2932 log= {label in legend={text=$\log x$}},
2933 lin= {label in legend={text=$x/2$}},
2934 squared={label in legend={text=$x^2$}},
2935 exp= {label in legend={text=$e^x$}},
2936 style sheet=strong colors]
2937 data group {function classes};
2938 \end{codeexample}
2939 \end{key}
2940
2941 \begin{key}{/tikz/data visualization/legend options/south west outside}
2942 \begin{codeexample}[
2943 width=8cm,
2944 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2945 pre={\tikz \datavisualization data group {function classes} = {
2946 data [set=log, format=function] {
2947 var x : interval [0.2:2.5];
2948 func y = ln(\value x);
2949 }
2950 data [set=lin, format=function] {
2951 var x : interval [-2:2.5];
2952 func y = 0.5*\value x;
2953 }
2954 data [set=squared, format=function] {
2955 var x : interval [-1.5:1.5];
2956 func y = \value x*\value x;
2957 }
2958 data [set=exp, format=function] {
2959 var x : interval [-2.5:1];
2960 func y = exp(\value x);
2961 }
2962 };},
2963 ]
2964 \tikz \datavisualization [
2965 scientific axes,
2966 visualize as smooth line/.list=
2967 {log, lin, squared, exp},
2968 legend=south west outside,
2969 log= {label in legend={text=$\log x$}},
2970 lin= {label in legend={text=$x/2$}},
2971 squared={label in legend={text=$x^2$}},
2972 exp= {label in legend={text=$e^x$}},
2973 style sheet=strong colors]
2974 data group {function classes};
2975 \end{codeexample}
2976 \end{key}
2977
2978
2979 \begin{key}{/tikz/data visualization/legend options/north outside}
2980 The legend is placed above the data. Note that the legend entries now for a
2981 row rather than a column.
2982 %
2983 \begin{codeexample}[
2984 width=8cm,
2985 preamble={\usetikzlibrary{datavisualization.formats.functions}},
2986 pre={\tikz \datavisualization data group {function classes} = {
2987 data [set=log, format=function] {
2988 var x : interval [0.2:2.5];
2989 func y = ln(\value x);
2990 }
2991 data [set=lin, format=function] {
2992 var x : interval [-2:2.5];
2993 func y = 0.5*\value x;
2994 }
2995 data [set=squared, format=function] {
2996 var x : interval [-1.5:1.5];
2997 func y = \value x*\value x;
2998 }
2999 data [set=exp, format=function] {
3000 var x : interval [-2.5:1];
3001 func y = exp(\value x);
3002 }
3003 };},
3004 ]
3005 \tikz \datavisualization [
3006 scientific axes,
3007 visualize as smooth line/.list=
3008 {log, lin, squared, exp},
3009 legend=north outside,
3010 log= {label in legend={text=$\log x$}},
3011 lin= {label in legend={text=$x/2$}},
3012 squared={label in legend={text=$x^2$}},
3013 exp= {label in legend={text=$e^x$}},
3014 style sheet=strong colors]
3015 data group {function classes};
3016 \end{codeexample}
3017 %
3018 \begin{key}{/tikz/data visualization/legend options/above}
3019 This is an easier-to-remember alias.
3020 \end{key}
3021 \end{key}
3022
3023 \begin{key}{/tikz/data visualization/legend options/south outside}
3024 \begin{codeexample}[
3025 width=8cm,
3026 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3027 pre={\tikz \datavisualization data group {function classes} = {
3028 data [set=log, format=function] {
3029 var x : interval [0.2:2.5];
3030 func y = ln(\value x);
3031 }
3032 data [set=lin, format=function] {
3033 var x : interval [-2:2.5];
3034 func y = 0.5*\value x;
3035 }
3036 data [set=squared, format=function] {
3037 var x : interval [-1.5:1.5];
3038 func y = \value x*\value x;
3039 }
3040 data [set=exp, format=function] {
3041 var x : interval [-2.5:1];
3042 func y = exp(\value x);
3043 }
3044 };},
3045 ]
3046 \tikz \datavisualization [
3047 scientific axes,
3048 visualize as smooth line/.list=
3049 {log, lin, squared, exp},
3050 legend=south outside,
3051 log= {label in legend={text=$\log x$}},
3052 lin= {label in legend={text=$x/2$}},
3053 squared={label in legend={text=$x^2$}},
3054 exp= {label in legend={text=$e^x$}},
3055 style sheet=strong colors]
3056 data group {function classes};
3057 \end{codeexample}
3058 %
3059 \begin{key}{/tikz/data visualization/legend options/below}
3060 This is an easier-to-remember alias.
3061 \end{key}
3062 \end{key}
3063
3064
3065 \subsubsection{Legend Placement: Inside to the Data Visualization}
3066 \label{section-dv-legend-inside}
3067
3068 There are two sets of options for placing a legend directly inside a data
3069 visualization: First, there are options for placing it inside, but next to some
3070 part of the border. Second, there are options for positioning it relative to a
3071 coordinate given by a certain data point.
3072
3073 \begin{key}{/tikz/data visualization/legend options/south east inside}
3074 Puts the legend in the upper right corner of the data.
3075 %
3076 \begin{codeexample}[
3077 width=8cm,
3078 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3079 pre={\tikz \datavisualization data group {function classes} = {
3080 data [set=log, format=function] {
3081 var x : interval [0.2:2.5];
3082 func y = ln(\value x);
3083 }
3084 data [set=lin, format=function] {
3085 var x : interval [-2:2.5];
3086 func y = 0.5*\value x;
3087 }
3088 data [set=squared, format=function] {
3089 var x : interval [-1.5:1.5];
3090 func y = \value x*\value x;
3091 }
3092 data [set=exp, format=function] {
3093 var x : interval [-2.5:1];
3094 func y = exp(\value x);
3095 }
3096 };},
3097 ]
3098 \tikz \datavisualization [
3099 scientific axes,
3100 visualize as smooth line/.list=
3101 {log, lin},
3102 legend=south east inside,
3103 log= {label in legend={text=$\log x$}},
3104 lin= {label in legend={text=$x/2$}},
3105 style sheet=strong colors]
3106 data group {function classes};
3107 \end{codeexample}
3108
3109 Note that the text is now a little smaller since there tends to be much
3110 less space inside the data visualization than next to it. Also, the
3111 legend's node is filled in white by default to ensures that the legend is
3112 clearly legible even in the presence of, say, a grid or data points behind
3113 it. This behavior is triggered by the following style key:
3114
3115 \begin{stylekey}{/tikz/data visualization/legend options/every legend inside}
3116 Executed the keys |opaque| by default and sets the text size to the
3117 size of footnotes.
3118 \end{stylekey}
3119 \end{key}
3120
3121 In order to further configure the default appearance of an inner legend, the
3122 following keys might be useful:
3123
3124 \begin{key}{/tikz/data visualization/legend options/opaque=\meta{color} (default white)}
3125 When this key is used, the legend's node will be filled with the
3126 \meta{color} and its corners will be rounded. Additionally, the inner and
3127 outer separations will be set to sensible values.
3128 \end{key}
3129 %
3130 \begin{key}{/tikz/data visualization/legend options/transparent}
3131 Sets the filling of the legend node to |none|.
3132 \end{key}
3133
3134 The following keys work much the same way as |south east inside|:
3135
3136 \begin{key}{/tikz/data visualization/legend options/east inside}
3137 \end{key}
3138 %
3139 \begin{key}{/tikz/data visualization/legend options/north east inside}
3140 \end{key}
3141 %
3142 \begin{key}{/tikz/data visualization/legend options/south west inside}
3143 \end{key}
3144 %
3145 \begin{key}{/tikz/data visualization/legend options/west inside}
3146 \end{key}
3147 %
3148 \begin{key}{/tikz/data visualization/legend options/north west inside}
3149 \end{key}
3150
3151 The keys |south inside| and |north inside| are a bit different: They use a row
3152 rather than a column for the legend entries:
3153
3154 \begin{key}{/tikz/data visualization/legend options/south inside}
3155 Puts the legend in the upper right corner of the data. Note that the text
3156 is now a little smaller since there tends to be much less space inside the
3157 data visualization than next to it.
3158 %
3159 \begin{codeexample}[
3160 width=8cm,
3161 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3162 pre={\tikz \datavisualization data group {function classes} = {
3163 data [set=log, format=function] {
3164 var x : interval [0.2:2.5];
3165 func y = ln(\value x);
3166 }
3167 data [set=lin, format=function] {
3168 var x : interval [-2:2.5];
3169 func y = 0.5*\value x;
3170 }
3171 data [set=squared, format=function] {
3172 var x : interval [-1.5:1.5];
3173 func y = \value x*\value x;
3174 }
3175 data [set=exp, format=function] {
3176 var x : interval [-2.5:1];
3177 func y = exp(\value x);
3178 }
3179 };},
3180 ]
3181 \tikz \datavisualization [
3182 scientific axes,
3183 visualize as smooth line/.list={log, lin},
3184 legend=south inside,
3185 log= {label in legend={text=$\log x$}},
3186 lin= {label in legend={text=$x/2$}},
3187 style sheet=strong colors]
3188 data group {function classes};
3189 \end{codeexample}
3190 %
3191 \end{key}
3192
3193 \begin{key}{/tikz/data visualization/legend options/north inside}
3194 As above.
3195 \end{key}
3196
3197 The above keys do not always give you as fine a control as you may need over
3198 the placement of the legend. In such cases, the following keys may help (or you
3199 can revert to directly setting the |at| and the |anchor| keys):
3200
3201 \begin{key}{/tikz/data visualization/legend options/at values=\meta{data point}}
3202 This key allows you to specify the desired center of the legend in terms of
3203 a data point. The \meta{data point} should be a list of comma-separated
3204 key--value pairs that specify a data point. The legend will then be
3205 centered at this data point.
3206 %
3207 \begin{codeexample}[
3208 width=6cm,
3209 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3210 pre={\tikz \datavisualization data group {function classes} = {
3211 data [set=log, format=function] {
3212 var x : interval [0.2:2.5];
3213 func y = ln(\value x);
3214 }
3215 data [set=lin, format=function] {
3216 var x : interval [-2:2.5];
3217 func y = 0.5*\value x;
3218 }
3219 data [set=squared, format=function] {
3220 var x : interval [-1.5:1.5];
3221 func y = \value x*\value x;
3222 }
3223 data [set=exp, format=function] {
3224 var x : interval [-2.5:1];
3225 func y = exp(\value x);
3226 }
3227 };},
3228 ]
3229 \tikz \datavisualization [
3230 scientific axes,
3231 visualize as smooth line/.list={log, lin},
3232 legend={at values={x=-1, y=2}},
3233 log= {label in legend={text=$\log x$}},
3234 lin= {label in legend={text=$x/2$}},
3235 style sheet=strong colors]
3236 data group {function classes};
3237 \end{codeexample}
3238 %
3239 \end{key}
3240
3241 \begin{key}{/tikz/data visualization/legend options/right of=\meta{data point}}
3242 Works like |at values|, but the anchor is set to |west|:
3243 %
3244 \begin{codeexample}[
3245 width=6cm,
3246 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3247 pre={\tikz \datavisualization data group {function classes} = {
3248 data [set=log, format=function] {
3249 var x : interval [0.2:2.5];
3250 func y = ln(\value x);
3251 }
3252 data [set=lin, format=function] {
3253 var x : interval [-2:2.5];
3254 func y = 0.5*\value x;
3255 }
3256 data [set=squared, format=function] {
3257 var x : interval [-1.5:1.5];
3258 func y = \value x*\value x;
3259 }
3260 data [set=exp, format=function] {
3261 var x : interval [-2.5:1];
3262 func y = exp(\value x);
3263 }
3264 };},
3265 ]
3266 \tikz \datavisualization [
3267 scientific axes,
3268 visualize as smooth line/.list={log, lin},
3269 legend={right of={x=-1, y=2}},
3270 log= {label in legend={text=$\log x$}},
3271 lin= {label in legend={text=$x/2$}},
3272 style sheet=strong colors]
3273 data group {function classes};
3274 \end{codeexample}
3275 %
3276 \end{key}
3277
3278 The following keys work similarly:
3279 %
3280 \begin{key}{/tikz/data visualization/legend options/above right of=\meta{data point}}
3281 \end{key}
3282 %
3283 \begin{key}{/tikz/data visualization/legend options/above of=\meta{data point}}
3284 \end{key}
3285 %
3286 \begin{key}{/tikz/data visualization/legend options/above left of=\meta{data point}}
3287 \end{key}
3288 %
3289 \begin{key}{/tikz/data visualization/legend options/left of=\meta{data point}}
3290 \end{key}
3291 %
3292 \begin{key}{/tikz/data visualization/legend options/below left of=\meta{data point}}
3293 \end{key}
3294 %
3295 \begin{key}{/tikz/data visualization/legend options/below of=\meta{data point}}
3296 \end{key}
3297 %
3298 \begin{key}{/tikz/data visualization/legend options/below right of=\meta{data point}}
3299 \end{key}
3300
3301
3302 \subsubsection{Legend Entries: General Styling}
3303 \label{section-dv-label-legend-entry-options}
3304
3305 The entries in a legend can be styled in several ways:
3306 %
3307 \begin{itemize}
3308 \item You can configure the styling of the text node.
3309 \item You can configure the relative placement of the text node and the
3310 little picture depicting the data set's styling.
3311 \item You can configure how the data set's styling is depicted.
3312 \end{itemize}
3313
3314 Before we have look at how each of these are configured, in detail, let us
3315 first have a look at the keys that allow us to save a set of such styles:
3316
3317 \begin{stylekey}{/tikz/data visualization/every label in legend}
3318 This key is executed with every label in a legend. However, the options
3319 stored in this style are executed with the path prefix
3320 |/tikz/data visualization/legend entry options|. Thus, this key can use
3321 keys like |node style| to configure the styling of all text nodes:
3322 %
3323 \begin{codeexample}[
3324 width=8cm,
3325 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3326 pre={\tikz \datavisualization data group {function classes} = {
3327 data [set=log, format=function] {
3328 var x : interval [0.2:2.5];
3329 func y = ln(\value x);
3330 }
3331 data [set=lin, format=function] {
3332 var x : interval [-2:2.5];
3333 func y = 0.5*\value x;
3334 }
3335 data [set=squared, format=function] {
3336 var x : interval [-1.5:1.5];
3337 func y = \value x*\value x;
3338 }
3339 data [set=exp, format=function] {
3340 var x : interval [-2.5:1];
3341 func y = exp(\value x);
3342 }
3343 };},
3344 ]
3345 \tikz \datavisualization [
3346 scientific axes,
3347 every label in legend/.style={node style=
3348 {fill=red!30}},
3349 visualize as smooth line/.list=
3350 {log, lin, squared, exp},
3351 legend=north east outside,
3352 log= {label in legend={text=$\log x$}},
3353 lin= {label in legend={text=$x/2$,
3354 node style={circle, draw=red}}},
3355 squared={label in legend={text=$x^2$}},
3356 exp= {label in legend={text=$e^x$}},
3357 style sheet=strong colors]
3358 data group {function classes};
3359 \end{codeexample}
3360 %
3361 \end{stylekey}
3362
3363 \begin{key}{/tikz/data visualization/legend options/label style=\meta{options}}
3364 This key can be used with a legend. It will simply add the \meta{options}
3365 to the |every label in legend| style for the given legend.
3366 %
3367 \begin{codeexample}[
3368 width=8cm,
3369 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3370 pre={\tikz \datavisualization data group {function classes} = {
3371 data [set=log, format=function] {
3372 var x : interval [0.2:2.5];
3373 func y = ln(\value x);
3374 }
3375 data [set=lin, format=function] {
3376 var x : interval [-2:2.5];
3377 func y = 0.5*\value x;
3378 }
3379 data [set=squared, format=function] {
3380 var x : interval [-1.5:1.5];
3381 func y = \value x*\value x;
3382 }
3383 data [set=exp, format=function] {
3384 var x : interval [-2.5:1];
3385 func y = exp(\value x);
3386 }
3387 };},
3388 ]
3389 \tikz \datavisualization [
3390 scientific axes,
3391 visualize as smooth line/.list=
3392 {log, lin, squared, exp},
3393 legend={label style={node style=draw}},
3394 log= {label in legend={text=$\log x$}},
3395 lin= {label in legend={text=$x/2$,
3396 node style={circle, draw=red}}},
3397 squared={label in legend={text=$x^2$}},
3398 exp= {label in legend={text=$e^x$}},
3399 style sheet=strong colors]
3400 data group {function classes};
3401 \end{codeexample}
3402 %
3403 \end{key}
3404
3405
3406 \subsubsection{Legend Entries: Styling the Text Node}
3407
3408 The appearance of the text nodes is easy to configure.
3409
3410 \begin{key}{/tikz/data visualization/legend entry options/node style=\meta{options}}
3411 This key adds \meta{options} to the styling of the text nodes of the label.
3412 %
3413 \begin{codeexample}[
3414 width=8cm,
3415 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3416 pre={\tikz \datavisualization data group {function classes} = {
3417 data [set=log, format=function] {
3418 var x : interval [0.2:2.5];
3419 func y = ln(\value x);
3420 }
3421 data [set=lin, format=function] {
3422 var x : interval [-2:2.5];
3423 func y = 0.5*\value x;
3424 }
3425 data [set=squared, format=function] {
3426 var x : interval [-1.5:1.5];
3427 func y = \value x*\value x;
3428 }
3429 data [set=exp, format=function] {
3430 var x : interval [-2.5:1];
3431 func y = exp(\value x);
3432 }
3433 };},
3434 ]
3435 \tikz \datavisualization [
3436 scientific axes,
3437 visualize as smooth line/.list=
3438 {log, lin, squared, exp},
3439 legend=north east outside,
3440 log= {label in legend={text=$\log x$}},
3441 lin= {label in legend={text=$x/2$,
3442 node style={circle, draw=red}}},
3443 squared={label in legend={text=$x^2$}},
3444 exp= {label in legend={text=$e^x$}},
3445 style sheet=strong colors]
3446 data group {function classes};
3447 \end{codeexample}
3448 %
3449 \end{key}
3450
3451 \begin{key}{/tikz/data visualization/legend entry options/text colored}
3452 Causes the |node style| to set the text color to |visualizer color|. The
3453 effect of this is that the label's text will have the same color as the
3454 data set to which it is attached.
3455 %
3456 \begin{codeexample}[
3457 width=8cm,
3458 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3459 pre={\tikz \datavisualization data group {function classes} = {
3460 data [set=log, format=function] {
3461 var x : interval [0.2:2.5];
3462 func y = ln(\value x);
3463 }
3464 data [set=lin, format=function] {
3465 var x : interval [-2:2.5];
3466 func y = 0.5*\value x;
3467 }
3468 data [set=squared, format=function] {
3469 var x : interval [-1.5:1.5];
3470 func y = \value x*\value x;
3471 }
3472 data [set=exp, format=function] {
3473 var x : interval [-2.5:1];
3474 func y = exp(\value x);
3475 }
3476 };},
3477 ]
3478 \tikz \datavisualization [
3479 scientific axes,
3480 visualize as smooth line/.list=
3481 {log, lin, squared, exp},
3482 legend={label style=text colored},
3483 log= {label in legend={text=$\log x$}},
3484 lin= {label in legend={text=$x/2$}},
3485 squared={label in legend={text=$x^2$}},
3486 exp= {label in legend={text=$e^x$}},
3487 style sheet=strong colors]
3488 data group {function classes};
3489 \end{codeexample}
3490 %
3491 \end{key}
3492
3493
3494 \subsubsection{Legend Entries: Text Placement}
3495
3496 Three keys govern where the text will be placed relative to the data set style
3497 visualization.
3498
3499 \begin{key}{/tikz/data visualization/legend entry options/text right}
3500 Placed the text node to the right of the data set style visualization. This
3501 is the default for most, but not all, legends.
3502 \end{key}
3503 %
3504 \begin{key}{/tikz/data visualization/legend entry options/text left}
3505 Placed the text node to the left of the data set style visualization.
3506 %
3507 \begin{codeexample}[
3508 width=8cm,
3509 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3510 pre={\tikz \datavisualization data group {function classes} = {
3511 data [set=log, format=function] {
3512 var x : interval [0.2:2.5];
3513 func y = ln(\value x);
3514 }
3515 data [set=lin, format=function] {
3516 var x : interval [-2:2.5];
3517 func y = 0.5*\value x;
3518 }
3519 data [set=squared, format=function] {
3520 var x : interval [-1.5:1.5];
3521 func y = \value x*\value x;
3522 }
3523 data [set=exp, format=function] {
3524 var x : interval [-2.5:1];
3525 func y = exp(\value x);
3526 }
3527 };},
3528 ]
3529 \tikz \datavisualization [
3530 scientific axes,
3531 visualize as smooth line/.list=
3532 {log, lin, squared, exp},
3533 legend={label style=text left},
3534 log= {label in legend={text=$\log x$}},
3535 lin= {label in legend={text=$x/2$}},
3536 squared={label in legend={text=$x^2$}},
3537 exp= {label in legend={text=$e^x$}},
3538 style sheet=strong colors]
3539 data group {function classes};
3540 \end{codeexample}
3541 %
3542 \end{key}
3543 %
3544 \begin{key}{/tikz/data visualization/legend entry options/text only}
3545 Shows only the text nodes and no data set style visualization at all. This
3546 options only makes sense in conjunction with the |text colored| options,
3547 which is why this options is also selected implicitly.
3548 %
3549 \begin{codeexample}[
3550 width=8cm,
3551 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3552 pre={\tikz \datavisualization data group {function classes} = {
3553 data [set=log, format=function] {
3554 var x : interval [0.2:2.5];
3555 func y = ln(\value x);
3556 }
3557 data [set=lin, format=function] {
3558 var x : interval [-2:2.5];
3559 func y = 0.5*\value x;
3560 }
3561 data [set=squared, format=function] {
3562 var x : interval [-1.5:1.5];
3563 func y = \value x*\value x;
3564 }
3565 data [set=exp, format=function] {
3566 var x : interval [-2.5:1];
3567 func y = exp(\value x);
3568 }
3569 };},
3570 ]
3571 \tikz \datavisualization [
3572 scientific axes,
3573 visualize as smooth line/.list=
3574 {log, lin, squared, exp},
3575 legend={south east inside, rows=2,
3576 label style=text only},
3577 log= {label in legend={text=$\log x$}},
3578 lin= {label in legend={text=$x/2$}},
3579 squared={label in legend={text=$x^2$}},
3580 exp= {label in legend={text=$e^x$}},
3581 style sheet=strong colors]
3582 data group {function classes};
3583 \end{codeexample}
3584 %
3585 \end{key}
3586
3587
3588 \subsubsection{Advanced: Labels in Legends and Their Visualizers}
3589 \label{section-dv-legend-entries}
3590
3591 The following explanations are important only for you if you intend to create a
3592 new visualizer and an accompanying label in legend visualizer; otherwise you
3593 can safely proceed with the next section.
3594
3595 A legend entry consists not only of some explaining text, but, even more
3596 importantly, of a visual representation of the style used for the data points,
3597 created by a \emph{label in legend visualizer}. For instance, when data points
3598 are visualized as lines in different colors, the legend entry for the first
3599 line might consist of the text ``first experiment'' and a short line in black
3600 and the second entry might consist of ``failed experiment'' and a short line in
3601 red -- assuming, of course, that the style sheet makes the first line black and
3602 the second line blue. As another example, when data sets are visualized as
3603 clouds of plot marks, the texts in the legend would be accompanied by the plot
3604 marks used to visualize the data sets.
3605
3606 For every visualizer, the \emph{label in legend visualizer} creates an
3607 appropriate visualization of the data set's styling. There may be more than one
3608 possible such label in legend visualizer that is appropriate, in which case
3609 options are used to choose between them.
3610
3611 Let us start with the key for creating a new legend entry. This key gets called
3612 for instance by |label in legend|:
3613
3614 \begin{key}{/tikz/data visualization/new legend entry=\meta{options}}
3615 This key will add a new entry to the legend that is identified by the
3616 \meta{options}. For this, the \meta{options} are executed once with the
3617 path prefix |/tikz/data visualization/legend entry options| and the
3618 resulting setting of the |legend| key is used to pick which legend the new
3619 entry should belong to. Then, the \meta{options} are stored away for the
3620 time being.
3621
3622 Later, when the legend is created, the \meta{options} get executed once
3623 more. This time, however, the |legend| key is no longer important. Instead,
3624 the \meta{options} that setup keys like |text| or |visualizer in legend|
3625 now play a role.
3626
3627 In detail, the following happens:
3628 %
3629 \begin{itemize}
3630 \item For the legend entry, a little cell picture is created in the
3631 matrix of the legend (see Section~\ref{section-tikz-cell-pictures}
3632 for details on cell pictures).
3633 \item Inside this picture, a node is created whose text is taken from
3634 the key
3635 %
3636 \begin{codeexample}[code only]
3637 /tikz/data visualization/legend entry options/text
3638 \end{codeexample}
3639 %
3640 \item Also inside the picture, the code stored in the following key
3641 gets executed:
3642 %
3643 \begin{key}{/tikz/data visualization/legend entry options/visualizer in legend}
3644 Set this key to some code that paints something in the cell
3645 picture. Typically, this will be a visual representation of the
3646 data set styling, but it could also be something different.
3647 %
3648 \begin{codeexample}[width=6cm,preamble={\usetikzlibrary{datavisualization}}]
3649 \tikz \datavisualization [
3650 school book axes, visualize as line/.list={a,b},
3651 style sheet=vary dashing,
3652 a={label in legend={text=a}},
3653 new legend entry={
3654 text=spacer,
3655 visualizer in legend={\draw[solid] (0,0) circle[radius=2pt];}
3656 },
3657 b={label in legend={text=b}}]
3658 data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
3659 data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
3660 \end{codeexample}
3661 \end{key}
3662 \end{itemize}
3663 %
3664 The following styles are applied in the following order before the cell
3665 picture is filled:
3666 %
3667 \begin{enumerate}
3668 \item |/tikz/data visualization/every data set label| with path
3669 |/tikz/data visualization|
3670 \item |/tikz/data visualization/every label in legend| with path\\
3671 |/tikz/data visualization/legend entry options|.
3672 \item The \meta{options}.
3673 \item The code in the following key:
3674 %
3675 \begin{key}{/tikz/data visualization/legend entry options/setup}
3676 Some code to be executed at this point. Mostly, it is used to
3677 setup attributes for style sheets.
3678 \end{key}
3679 \item A styling signal is emitted.
3680 \item Only for the node: The current value of |node style|.
3681 \item Only for the visualizer in legend: The styling that has been
3682 accumulated by calls to the following key:
3683 %
3684 \begin{stylekey}{/tikz/data visualization/legend entry options/visualizer in legend style=\\\marg{options}}
3685 Calls to this key accumulate \meta{options} that will be
3686 executed with the path prefix |/tikz| at this point.
3687 \end{stylekey}
3688 \end{enumerate}
3689 \end{key}
3690
3691 As indicated earlier, the |new legend entry| key is called by the
3692 |label in legend=|\meta{options} key internally. In this case, the following
3693 extra \meta{extra options} are passed to |new legend entry| key:
3694 %
3695 \begin{itemize}
3696 \item The styling of the visualizer.
3697 \item The |/tikz/data visualization/every label in legend| style.
3698 \item The |/tikz/every label| style with path |/tikz|.
3699 \item Setting |setup| to |/data point/set=|\meta{name of the visualizer}.
3700 \item The value of the |label legend options| that are stored in the
3701 visualizer. These options can be changed using the following key:
3702 %
3703 \begin{key}{/tikz/data visualization/visualizer options/label in legend options=\meta{options}}
3704 Use this key with a visualizer to configure the label in legend
3705 options. Typically, this key is used only internally by a
3706 visualizer upon its creating to set the \meta{options} to setup the
3707 |visualizer in legend| key.
3708 \end{key}
3709 \end{itemize}
3710
3711
3712 \subsubsection{Reference: Label in Legend Visualizers for Lines and Scatter Plots}
3713
3714 Visualizers like |visualize as line| or |visualize as smooth line| use a label
3715 in legend visualizer that draws a short line to represent the data set inside
3716 the legend. However, this line needs not be a simple straight line, but can be
3717 a little curve or a small circle -- indeed, even the default line is not a
3718 simple straight line but rather a small zig-zag curve. To configure this line,
3719 the two keys are used, although you will only rarely use them directly, but
3720 rather use one of the predefined styles mentioned later on.
3721
3722 Before we go into the glorious details of all of these keys, let us first have
3723 a look at the keys you are most likely to use in practice: The keys for
3724 globally reconfiguring the default label in legend visualizers:
3725 %
3726 \begin{stylekey}{/tikz/data visualization/legend entry options/default label in legend path}
3727 This style is set, by default, to |zig zag label in legend line|. It is
3728 installed by the styles |straight line|, |smooth line|, and |gap line|, so
3729 changing this style will change the appearance of lines in legends. The
3730 main other sensible option for this key is |straight label in legend line|.
3731 %
3732 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3733 \tikz \datavisualization [
3734 school book axes, visualize as line/.list={a,b},
3735 style sheet=vary dashing,
3736 a={label in legend={text=a}}, b={label in legend={text=b}}]
3737 data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
3738 data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
3739 \end{codeexample}
3740 %
3741 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3742 \tikz \datavisualization [
3743 school book axes, visualize as line/.list={a,b},
3744 legend entry options/default label in legend path/.style=
3745 straight label in legend line,
3746 style sheet=vary dashing,
3747 a={label in legend={text=a}}, b={label in legend={text=b}}]
3748 data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
3749 data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
3750 \end{codeexample}
3751 %
3752 \end{stylekey}
3753 %
3754 \begin{stylekey}{/tikz/data visualization/legend entry options/default label in legend closed path}
3755 This style is executed by |smooth cycle| and |straight cycle|. There are
3756 (currently) no other predefined sets of coordinates that can be used
3757 instead of the default value |circular label in legend line|.
3758 \end{stylekey}
3759
3760 \begin{stylekey}{/tikz/data visualization/legend entry options/default label in legend mark}
3761 This style is executed by |no lines| and, implicitly, by scatter plots. The
3762 default is to use |label in legend line one mark|. Another possible value
3763 is |label in legend line three marks|.
3764 %
3765 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3766 \tikz \datavisualization [
3767 visualize as scatter/.list={a,b,c},
3768 style sheet=cross marks,
3769 legend entry options/default label in legend mark/.style=
3770 label in legend three marks,
3771 a={label in legend={text=example a}},
3772 b={label in legend={text=example b}},
3773 c={label in legend={text=example c}}];
3774 \end{codeexample}
3775 %
3776 \end{stylekey}
3777
3778 \begin{key}{/tikz/data visualization/legend entry options/label in legend line coordinates=\\\marg{list of coordinates}}
3779 This key takes a \meta{list of coordinates}, which are
3780 \tikzname-coordinates separated by commas like |(0,0),|\penalty0|(1,1)|.
3781 The effect of setting the key is the following: The label in legend
3782 visualizer used by, for instance, |visualize as line| will draw a path
3783 going through these points. When the line is drawn, the exact same style
3784 will be used as was used for the data set. For instance, if the
3785 |smooth line| key was used and also the |style=red| key, the line through
3786 the \meta{list of coordinates} will also be red and smooth. When the
3787 |straight cycle| key was used, the coordinates will also be connected by a
3788 cycle, and so on.
3789
3790 When the line connecting the \meta{list of coordinates} is drawn, the
3791 coordinate system will have been shifted and transformed in such a way that
3792 |(0,0)| lies to the left of the text and at half the height of the
3793 character ``x''. This means that the right-most-point in the list should
3794 usually be |(0,0)| and all other $x$-coordinates should usually be
3795 negative. When the |text left| options is used, the coordinate system will
3796 have been flipped, so the \meta{list of coordinates} is independent of
3797 whether the text is to the right or to the left of the line.
3798
3799 Let us now have a look at a first, simple example. We create a legend entry
3800 that is just a straight line, so it should start somewhere to the left of
3801 the origin at height $0$ and go to the origin:
3802 %
3803 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3804 \tikz \datavisualization [
3805 school book axes, visualize as line/.list={a,b},
3806 style sheet=vary dashing,
3807 a={label in legend={text=a,
3808 label in legend line coordinates={(-1em,0), (0,0)}}},
3809 b={label in legend={text=b,
3810 label in legend line coordinates={(-2em,0), (0,0)}}}]
3811 data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
3812 data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
3813 \end{codeexample}
3814
3815 Now let us make this a bit more fancy and useful by using shifted lines:
3816 %
3817 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3818 \tikz \datavisualization [
3819 school book axes, visualize as line/.list={a,b},
3820 legend={up then right}, style sheet=vary dashing,
3821 a={label in legend={text=a,
3822 label in legend line coordinates={(-2em,-.25ex), (0,0)}}},
3823 b={label in legend={text=b,
3824 label in legend line coordinates={(-2em,.25ex), (0,0)}}}]
3825 data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
3826 data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
3827 \end{codeexample}
3828
3829 In the final example, we use a little ``hat'' to represent lines:
3830 %
3831 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3832 \tikz \datavisualization [
3833 school book axes, visualize as line/.list={a,b},
3834 legend={up then right}, style sheet=vary dashing,
3835 a={label in legend={text=a,
3836 label in legend line coordinates={
3837 (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}}},
3838 b={label in legend={text=b,
3839 label in legend line coordinates={
3840 (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}}}]
3841 data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
3842 data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
3843 \end{codeexample}
3844 %
3845 \end{key}
3846
3847 \begin{key}{/tikz/data visualization/legend entry options/label in legend mark coordinates=\\\marg{list of coordinates}}
3848 This key is similar to |label in legend line coordinates|, but now the
3849 \meta{list of coordinates} is used as the positions where plot marks are
3850 shown. Naturally, plot marks are only shown there if they are also shown by
3851 the visualizer in the actual data -- just like the line through the
3852 coordinates of the previous key is only shown when there is a line.
3853
3854 The \meta{list of coordinates} may be the same as the one used for lines,
3855 but usually it is not. In general, it is better to have marks for instance
3856 not at the ends of the line.
3857 %
3858 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3859 \tikz \datavisualization [
3860 school book axes, visualize as line/.list={a,b},
3861 legend={up then right},
3862 style sheet=vary dashing,
3863 style sheet=cross marks,
3864 a={label in legend={text=a,
3865 label in legend line coordinates={
3866 (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)},
3867 label in legend mark coordinates={
3868 (-1em,.2ex)}}},
3869 b={label in legend={text=b,
3870 label in legend line coordinates={
3871 (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)},
3872 label in legend mark coordinates={
3873 (-2em,-.2ex), (0,-.2ex)}}}]
3874 data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
3875 data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
3876 \end{codeexample}
3877 %
3878 \end{key}
3879
3880
3881 Naturally, you typically will not give coordinates explicitly for each label,
3882 but use one of the following styles:
3883
3884 \begin{key}{/tikz/data visualization/legend entry options/straight label in legend line}
3885 Just gives a straight line and two plot marks.
3886 %
3887 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3888 \tikz \datavisualization [visualize as line,
3889 line={style={mark=x}, label in legend={text=example,
3890 straight label in legend line}}];
3891 \end{codeexample}
3892 %
3893 This style might seem like a good idea to use in general, but it does have
3894 a huge drawback: Some commonly used plot marks will be impossible to
3895 distinguish -- even though there is no problem distinguishing them in a
3896 graph.
3897 %
3898 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3899 \tikz \datavisualization [visualize as line/.list={a,b,c},
3900 legend entry options/default label in legend path/.style=
3901 straight label in legend line,
3902 a={style={mark=+}, label in legend={text=bad example a}},
3903 b={style={mark=-}, label in legend={text=bad example b}},
3904 c={style={mark=|}, label in legend={text=bad example c}}];
3905 \end{codeexample}
3906 %
3907 For this reason, this option is not the default, but rather the next one.
3908 \end{key}
3909
3910 \begin{key}{/tikz/data visualization/legend entry options/zig zag label in legend line}
3911 Uses a small up-down-up line as the label in legend visualizer. The two
3912 plot marks are at the extremal points of the line. It works pretty well in
3913 almost all situations and is the default.
3914 %
3915 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3916 \tikz \datavisualization [
3917 visualize as line=a,
3918 visualize as smooth line/.list={b,c},
3919 a={style={mark=+}, label in legend={text=better example a}},
3920 b={style={mark=-}, label in legend={text=better example b}},
3921 c={style={mark=|}, label in legend={text=better example c}}];
3922 \end{codeexample}
3923 %
3924 Even though the above example shows that the marks are easier to
3925 distinguish than with a straight line, the chosen marks are still not
3926 optimal. This is the reason that the |cross marks| style uses different
3927 crosses:
3928 %
3929 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
3930 \tikz \datavisualization [
3931 visualize as line/.list={a,b},
3932 visualize as smooth line=c,
3933 style sheet=cross marks,
3934 a={label in legend={text=good example a}},
3935 b={label in legend={text=good example b}},
3936 c={gap line, label in legend={text=good example c}}];
3937 \end{codeexample}
3938 %
3939 \end{key}
3940
3941 \begin{key}{/tikz/data visualization/legend entry options/circular label in legend line}
3942 This style is especially tailored to represent lines that are closed. It is
3943 automatically selected for instance by the |polygon| or the |smooth cycle|
3944 styles.
3945 %
3946 \begin{codeexample}[
3947 width=7cm,
3948 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3949 ]
3950 \tikz \datavisualization [
3951 scientific axes={clean}, all axes={length=3cm},
3952 visualize as line/.list={a,b,c},
3953 a={polygon}, b={smooth cycle},
3954 style sheet=cross marks,
3955 a={label in legend={text=polygon}},
3956 b={label in legend={text=circle}},
3957 c={label in legend={text=line}}]
3958 data [format=function, set=a] {
3959 var t : {0,72,...,359};
3960 func x = cos(\value t);
3961 func y = sin(\value t);
3962 }
3963 data [format=function, set=b] {
3964 var t : [0:2*pi];
3965 func x = .8*cos(\value t r);
3966 func y = .8*sin(\value t r);
3967 }
3968 data point [x=-1, y=0.5, set=c]
3969 data point [x=1, y=0.25, set=c];
3970 \end{codeexample}
3971 %
3972 \end{key}
3973
3974 \begin{key}{/tikz/data visualization/legend entry options/gap circular label in legend line}
3975 This style is especially tailored to for the |gap cycle| style and
3976 automatically selected by it:
3977 %
3978 \begin{codeexample}[
3979 width=7cm,
3980 preamble={\usetikzlibrary{datavisualization.formats.functions}},
3981 ]
3982 \tikz \datavisualization [
3983 scientific axes={clean}, all axes={length=3cm},
3984 visualize as line/.list={a,b,c},
3985 a={gap cycle}, b={smooth cycle}, c={gap line},
3986 a={style={mark=*, mark size=0.5pt},
3987 label in legend={text=polygon}},
3988 b={label in legend={text=circle}},
3989 c={style={mark=*, mark size=0.5pt, mark options=red},
3990 label in legend={text=line}}]
3991 data [format=function, set=a] {
3992 var t : {0,72,...,359};
3993 func x = cos(\value t);
3994 func y = sin(\value t);
3995 }
3996 data [format=function, set=b] {
3997 var t : [0:352];
3998 func x = .8*cos(\value t);
3999 func y = .8*sin(\value t);
4000 }
4001 data point [x=-1, y=0.5, set=c]
4002 data point [x=1, y=0.25, set=c];
4003 \end{codeexample}
4004 %
4005 \end{key}
4006
4007 \begin{key}{/tikz/data visualization/legend entry options/label in legend one mark}
4008 To be used with scatter plots, since no line is drawn. Just displays a
4009 single mark (this is the default with a scatter plot or when the |no line|
4010 is selected.
4011 %
4012 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
4013 \tikz \datavisualization [visualize as scatter/.list={a,b,c},
4014 style sheet=cross marks,
4015 a={label in legend={text=example a}},
4016 b={label in legend={text=example b}},
4017 c={label in legend={text=example c}}];
4018 \end{codeexample}
4019 %
4020 \end{key}
4021
4022 \begin{key}{/tikz/data visualization/legend entry options/label in legend three marks}
4023 An alternative to the previous style, where several marks are shown.
4024 %
4025 \begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
4026 \tikz \datavisualization [visualize as scatter/.list={a,b,c},
4027 style sheet=cross marks,
4028 a={label in legend={text=example a, label in legend three marks}},
4029 b={label in legend={text=example b, label in legend three marks}},
4030 c={label in legend={text=example c, label in legend three marks}}];
4031 \end{codeexample}
4032 %
4033 \end{key}