diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex | 2419 |
1 files changed, 2416 insertions, 3 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex index 44c866cd04b..43682ca38e3 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex @@ -13,17 +13,2430 @@ \subsection{Overview} -To be written... +In many data visualizations, different sets of data need to be +visualized in a single visualization. For instance, in a plot there +might be a line for the sine of~$x$ and another line for the cosine +of~$x$; in another visualization there might be a set of points +representing data from a first experiment and another set of points +representing data from a second experiment; and so on. In order to +indicate to which data set a data point belongs, one might plot the +curve of the sine in, say, black, and the curve of the cosine in red; +we might plot the data from the fist experiment using stars and the +data from the second experiment using circles; and so on. Finally, at +some place in the visualization -- either inside the data or in a +legend next to it -- the meaning of the colors or symbols need to be +explained. + +Just as you would like \tikzname\ to map the data points automatically +onto the axes, you will also typically wish \tikzname\ to choose for +instance the coloring of the lines automatically for you. This is done +using \emph{style sheets}. There are at least two good reasons why you +should prefer style sheets over configuring the styling of each +visualizer ``by hand'' using the |style| key: +\begin{enumerate} +\item It is far more convenient to just say + |style sheet=strong colors| than having to individually + picking the different colors. +\item The style sheets were chosen and constructed rather + carefully. + + For instance, the |strong colors| style sheet does not + pick colors like pure green or pure yellow, which have very low + contrast with respect to a white background and which often lead to + unintelligible graphics. Instead, opposing primary colors with + maximum contrast on a white background were picked that are visually + quite pleasing. + + Similarly, the different dashing style sheets are + constructed in such a way that there are only few and small gaps in + the dashing so that no data points get lost because the dashes are + spaced too far apart. Also dashing patterns were chosen that have a + maximum optical difference. + + As a final example, style sheets for + plot marks are constructed in such a way that even when two plot + marks lie directly on top of each other, they are still easily + distinguishable. +\end{enumerate} +The bottom line is that whenever possible, you should use one of the +predefined style sheets rather than picking colors or dashings at +random. \subsection{Concepts: Style Sheets} +A \emph{style sheet} is a predefined list of styles such as a list of +colors, a list of dashing pattern, a list of plot marks, or a +combinations thereof. A style sheet can be \emph{attached} to a data +point attribute. Then, the value of this attribute is used with data +points to choose which style in the list should be chosen to visualize +the data point. + +In most cases, there is just one attribute to which style sheets get +attached: the |/data point/visualizer| attribute. The effect of +attaching a style sheet to this attribute is that each visualizer is +styled differently. + +For the following examples, let us first define a simple data set: +\begin{codeexample}[] +\tikz \datavisualization data group {function classes} = { + data [set=log, format=function] { + var x : interval [0.2:2.5]; + func y = ln(\value x); + } + data [set=lin, format=function] { + var x : interval [-2:2.5]; + func y = 0.5*\value x; + } + data [set=squared, format=function] { + var x : interval [-1.5:1.5]; + func y = \value x*\value x; + } + data [set=exp, format=function] { + var x : interval [-2.5:1]; + func y = exp(\value x); + } +}; +\end{codeexample} + +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, all axes={unit length=7.5mm}, + visualize as smooth line/.list={log, lin, squared, exp}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, all axes={unit length=7.5mm}, + visualize as smooth line/.list={log, lin, squared, exp}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + + + \subsection{Concepts: Legends} +\label{section-dv-labels-in} + +A \emph{legend} is a box that is next to a data visualization (or +inside it at some otherwise empty position) that contains a textual +explanation of the different colors or styles used in a data +visualization. + +Just as it is difficult to get colors and dashing patterns right ``by +hand,'' it is also difficult to get a legend right. For instance, when +a small line is shown in the legend that represents the actual line in +the data visualization, if the line is too short and the dashing is +too large, it may be impossible to discern which dashing is actually +meant. Similarly, when plot marks are shown on such a short line, +using a simple straight line may make it hard to read the plot marks +correctly. + +The data visualization engine makes some effort to make it easy to +create high-quality legends. Additionally, it also offers ways of +easily adding labels for visualizers directly inside the data +visualization, which is even better than adding a legend, in general. + +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + school book axes, all axes={unit length=7.5mm}, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + + +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + every data set label/.append style={text colored}, + log= {pin in data={text'=$\log x$, when=y is -1}}, + lin= {pin in data={text=$x/2$, when=x is 2, + pin length=1ex}}, + squared={pin in data={text=$x^2$, when=x is 1.1, + pin angle=230}}, + exp= {label in data={text=$e^x$, when=x is -2}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + + +\subsection{Usage: Style Sheets} + +\subsubsection{Picking a Style Sheet} + +To use a style sheet, you need to \emph{attach} it to an +attribute. You can attach multiple style sheets to an attribute and +in this case all of these style sheets can influence the appearance of +the data points. + +Most of the time, you will attach a style sheet to the |set| +attribute. This has the effect that each different data set inside the +same visualization is rendered in a different way. Since this use of +style sheets is the most common, there is a special, easy-to-remember +option for this: + +\begin{key}{/tikz/data visualization/style sheet=\meta{style sheet}} + Adds the \meta{style sheet} to the list of style sheets attached to + the |set| attribute. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, all axes={unit length=7.5mm}, + visualize as smooth line/.list={log, lin, squared, exp}, + style sheet=vary thickness and dashing, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} +\end{key} + +While the |style sheet| key will attach a style sheet only to the +|set| attribute, the following key handler can be used to attach a +style sheet to an arbitrary attribute: + + +\begin{handler}{{.style sheet}=\meta{style sheet}} + Inside a data visualization you can use this key handler together + with an attribute, that is, with a key having the path prefix + |/data point|. For instance, in order to attach the \meta{style + sheet} |strong colors| to the attribute |set|, you could write +\begin{codeexample}[code only] +/data point/set/.style sheet=strong colors +\end{codeexample} + Indeed, the |style sheet| key is just a shorthand for the above. + + The effect of attaching a style sheet is the following: + \begin{itemize} + \item A new object is created that will monitor the attribute. + \item Each time a special \emph{styling key} is emitted by the data + visualization engine, this object will inspect the current value + of the attribute to which it is attached. + \item Depending on this value, one of the styles stored in the style + sheet is chosen (how this works, exactly, will be explained in a + moment). + \item The chosen style is then locally applied. + \end{itemize} + + In reality, things are a bit more complicated: If the attribute of + the data point happens to have a subkey named in the same way as the + value, then the value of is this subkey is used instead of the value + itself. This allows you to ``rename'' a value. + + In a sense, a style sheet behaves much like a visualizer (see + Section~\ref{section-dv-visualizers}): In accordance with the value + of a certain attribute, the appearance of data points + change. However, there are a few differences: First, the styling of + a data point needs to be triggered explicitly and this triggering is + not necessarily done for each data point individually, but only for + a whole visualizer. Second, styles can be computed even when no data + point is present. This is useful for instance in a legend since, + here, a visual representation of a visualizer needs to be created + independently of the actual data points. +\end{handler} + +\subsubsection{Creating a New Style Sheet} + +Creating a style sheet works as follows: For each +possible value that an attribute can attain we must specify a +style. This is done by creating a style key for each such possible +value with a special path prefix and setting this style key to the +desired value. The special path prefix is +|/pgf/data visualization/style sheets| followed by the name of the +style sheet. + +As an example, suppose we wish to create a style sheet |test| that makes +styled data points |red| when the attribute has value |foo| and +|green| when the attribute has value |bar| and |dashed, blue| when the +attribute is |foobar|. We could then write +\begin{codeexample}[code only] +/pgf/data visualization/style sheets/test/foo/.style={red}, +/pgf/data visualization/style sheets/test/bar/.style={green}, +/pgf/data visualization/style sheets/test/foobar/.style={dashed, blue}, +\end{codeexample} + +We could then attach this style sheet to the attribute |code| as +follows: +\begin{codeexample}[code only] +/data point/code/.style sheet=test +\end{codeexample} + +Then, when |/data point/code=foobar| holds when the styling signal is +raised, the style |dashed, blue| will get executed. + +A natural question arises concerning the situation that the value of +the attribute is not defined as a subkey of the style sheet. In this +case, a special key gets executed: + +\begin{stylekey}{/pgf/data visualization/style sheets/\meta{style + sheet}/default style=\meta{value}} + This key gets during styling whenever + |/pgf/data visualization/style sheet/|\meta{style + sheet}|/|\meta{value} is not defined. +\end{stylekey} + +Let us put all of this together in a real-life example. Suppose we +wish to create a style sheet that makes the first data set |green|, the +second |yellow| and the third one |red|. Further data sets should be, +say, |black|. The attribute that we intend to style is the |set| +attribute. For the moment, we assume that the data sets will be named +|1|, |2|, |3|, and so on (instead of, say, |experiment 1| or |sin| or +something more readable -- we will get rid of this restriction in a +minute). + +We would now write: + +\begin{codeexample}[] +\pgfkeys{ + /pgf/data visualization/style sheets/traffic light/.cd, + % All these styles have the above prefix. + 1/.style={green!50!black}, + 2/.style={yellow!90!black}, + 3/.style={red!80!black}, + default style/.style={black} +} +\tikz \datavisualization [ + school book axes, + visualize as line=1, + visualize as line=2, + visualize as line=3, + style sheet=traffic light] +data point [x=0, y=0, set=1] +data point [x=2, y=2, set=1] +data point [x=0, y=1, set=2] +data point [x=2, y=1, set=2] +data point [x=0.5, y=1.5, set=3] +data point [x=2.25, y=1.75, set=3]; +\end{codeexample} + +In the above example, we have to name the visualizers |1|, |2|, |3| +and so one since the value of the |set| attribute is used both assign +data points to visualizers and also pick a style sheet. However, it +would be much nicer if we could name any way we want. To achieve this, +we use the special rule for style sheets that says that if there is a +subkey of an attribute whose name is the same name as the value, then +the value of this key is used instead. This slightly intimidating +definition is much easier to understand when we have a look at an +example: + +\pgfkeys{ + /pgf/data visualization/style sheets/traffic light/.cd, + % All these styles have the above prefix. + 1/.style={green!50!black}, + 2/.style={yellow!90!black}, + 3/.style={red!80!black}, + default style/.style={black} +} + +\begin{codeexample}[] +% Definition of traffic light keys as above +\begin{tikzpicture} + \datavisualization data group {lines} = { + data point [x=0, y=0, set=normal] + data point [x=2, y=2, set=normal] + data point [x=0, y=1, set=heated] + data point [x=2, y=1, set=heated] + data point [x=0.5, y=1.5, set=critical] + data point [x=2.25, y=1.75, set=critical] + }; + \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + /data point/set/normal/.initial=1, + /data point/set/heated/.initial=2, + /data point/set/critical/.initial=3, + style sheet=traffic light] + data group {lines}; +\end{tikzpicture} +\end{codeexample} + +Now, it is a bit bothersome that we have to set all these +|/data point/set/...| keys by hand. It turns out that this is not +necessary: Each time a visualizer is created, a subkey of +|/data point/set| with the name of the visualizer is created +automatically and a number is stored that is increased for each new +visualizer in a data visualization. This means that the three lines +starting with |/data point| are inserted automatically for you, so +they can be left out. However, you would need them for instance when +you would like several different data sets to use the same styling: + + +\begin{codeexample}[] +% Definition of traffic light keys as above +\tikz \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + /data point/set/critical/.initial=1, % same styling as first set + style sheet=traffic light] +data group {lines}; +\end{codeexample} + +We can a command that slightly simplifies the definition of style +sheets: + +\begin{command}{\pgfdvdeclarestylesheet\marg{name}\marg{keys}} + This command executes the \meta{keys} with the path prefix + |/pgf/data visualization/style sheets/|\penalty0\meta{name}. The above + definition of the traffic light style sheet could be rewritten as + follows: +\begin{codeexample}[code only] +\pgfdvdeclarestylesheet{traffic light}{ + 1/.style={green!50!black}, + 2/.style={yellow!90!black}, + 3/.style={red!80!black}, + default style/.style={black} +} +\end{codeexample} +\end{command} + +As a final example, let us create a style sheet that changes the +dashing pattern according to the value of the attribute. We do not +need to define an large number of styles in this case, but can use the +|default style| key to ``calculate'' the correct dashing. + +\begin{codeexample}[] +\pgfdvdeclarestylesheet{my dashings}{ + default style/.style={dash pattern={on #1pt off 1pt}} +} +\tikz \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + style sheet=my dashings] +data group {lines}; +\end{codeexample} + +\subsubsection{Creating a New Color Style Sheet} + +Creating a style sheet that varies colors according to an attribute +works the same way as creating a normal style sheet: Subkeys lies |1|, +|2|, and so on use the |style| attribute to setup a color. However, +instead of using the |color| attribute to set the color, you should +use the |visualizer color| key to set the color: + +\begin{key}{/tikz/visualizer color=\meta{color}} + This key is used to set the color |visualizer color| to + \meta{color}. This color is used by visualizers to color the data + they visualize, rather than the current ``standard color.'' The + reason for not using the normal current color is simply that it + makes many internals of the data visualization engine a bit + simpler. +\begin{codeexample}[] +\pgfdvdeclarestylesheet{my colors} +{ + default style/.style={visualizer color=black}, + 1/.style={visualizer color=black}, + 2/.style={visualizer color=red!80!black}, + 3/.style={visualizer color=blue!80!black}, +} +\tikz \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + style sheet=my colors] +data group {lines}; +\end{codeexample} +\end{key} + +There is an additional command that makes it easy to define a style +sheet based on a \emph{color series}. Color series are a concept from +the |xcolor| package: The idea is that we start with a certain color +for the first data set and then add a certain ``color offset'' for +each next data point. Please consult the documentation of the |xcolor| +package for details. + +\begin{command}{\tikzdvdeclarestylesheetcolorseries\marg{name}\marg{color + model}\marg{initial color}\marg{step}} + This command creates a new style sheet using + |\pgfdvdeclarestylesheet|. This style sheet will only have a default + style setup that maps numbers to the color in the color series + starting with \meta{initial color} and having a stepping of + \meta{step}. Note that when the value of the attribute is |1|, which + it is the first data set, the \emph{second} color in the color + series is used (since counting starts at |0| for color + series). Thus, in general, you need to start the \meta{initial + color} ``one early.'' +\begin{codeexample}[] +\tikzdvdeclarestylesheetcolorseries{greens}{hsb}{0.3,1.3,0.8}{0,-.4,-.1} +\tikz \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + style sheet=greens] +data group {lines}; +\end{codeexample} + +\end{command} + -\subsection{Usage: Selecting Style Sheets} -\subsection{Usage: Labeling Visualizations} \subsection{Reference: Style Sheets for Lines} +The following style sheets can be applied to visualizations that use +the |visualize as line| and related keys. For the examples, the +following style and data set are used: + +\begin{codeexample}[code only] +\tikzdatavisualizationset { + example visualization/.style={ + scientific axes=clean, + y axis={ticks={style={ + /pgf/number format/fixed, + /pgf/number format/fixed zerofill, + /pgf/number format/precision=2}}}, + x axis={ticks={tick suffix=${}^\circ$}}, + 1={label in legend={text=$\frac{1}{6}\sin 11x$}}, + 2={label in legend={text=$\frac{1}{7}\sin 12x$}}, + 3={label in legend={text=$\frac{1}{8}\sin 13x$}}, + 4={label in legend={text=$\frac{1}{9}\sin 14x$}}, + 5={label in legend={text=$\frac{1}{10}\sin 15x$}}, + 6={label in legend={text=$\frac{1}{11}\sin 16x$}}, + 7={label in legend={text=$\frac{1}{12}\sin 17x$}}, + 8={label in legend={text=$\frac{1}{13}\sin 18x$}} + } +} +\end{codeexample} +\tikzdatavisualizationset { + example visualization/.style={ + scientific axes=clean, + y axis={ticks={style={ + /pgf/number format/fixed, + /pgf/number format/fixed zerofill, + /pgf/number format/precision=2}}}, + x axis={ticks={tick suffix=${}^\circ$}}, + 1={label in legend={text=$\frac{1}{6}\sin 11x$}}, + 2={label in legend={text=$\frac{1}{7}\sin 12x$}}, + 3={label in legend={text=$\frac{1}{8}\sin 13x$}}, + 4={label in legend={text=$\frac{1}{9}\sin 14x$}}, + 5={label in legend={text=$\frac{1}{10}\sin 15x$}}, + 6={label in legend={text=$\frac{1}{11}\sin 16x$}}, + 7={label in legend={text=$\frac{1}{12}\sin 17x$}}, + 8={label in legend={text=$\frac{1}{13}\sin 18x$}} + } +} + +\begin{codeexample}[code only] +\tikz \datavisualization data group {sin functions} = { + data [format=function] { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } +}; +\end{codeexample} +\tikz \datavisualization data group {sin functions} = { + data [format=function] { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } +}; + +\begin{stylesheet}{vary thickness} + This style varies the thickness of lines. It should be used only + when there are only two or three lines, and even then it is not + particularly pleasing visually. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary thickness] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\begin{stylesheet}{vary dashing} + This style varies the dashing of lines. Although it is not + particularly pleasing visually and although visualizations using + this style sheet tend to look ``excited'' (but not necessarily + ``exciting''), this style sheet is often the best choice when the + visualization is to be printed in black and white. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary dashing] +data group {sin functions}; +\end{codeexample} + As can be seen, there are only seven distinct dashing patterns. The + eighth and further lines will use a solid line once more. You will + then have to specify the dashing ``by hand'' using the |style| + option together with the visualizer. +\end{stylesheet} + +\begin{stylesheet}{vary dashing and thickness} + This style alternates between varying the thickness and the dashing + of lines. The + difference to just using both the |vary thickness| and + |vary dashing| is that too thick lines are avoided. Instead, this + style creates clearly distinguishable line styles for many lines (up + to 14) with a minimum of visual clutter. This style is the most + useful for visualizations when many different lines (ten or more) + should be printed in black and white. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary thickness + and dashing] +data group {sin functions}; +\end{codeexample} + For comparison, here is the must-less-than-satisfactory result of + combining the two independent style sheets: +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary thickness, + style sheet=vary dashing] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\subsection{Reference: Style Sheets for Scatter Plots} + +The following style sheets can be used both for scatter plots and also +with lines. In the latter case, the marks are added to the lines. + +\begin{stylesheet}{cross marks} + This style uses different crosses to distinguish between the data + points of different data sets. The crosses were chosen in such a way + that when two different cross marks lie at the same coordinate, + their overall shape allows one to still uniquely determine which + marks are on top of each other. + + This style supports only up to six different data sets. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as scatter/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=cross marks] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=cross marks] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + \subsection{Reference: Color Style Sheets} +Color style sheets are very useful for creating visually pleasing data +visualizations that contain multiple data sets. However, there are two +things to keep in mind: + +\begin{itemize} +\item At some point, every data visualization is printed or photo + copied in black and white by someone. In this case, data sets can + often no longer be distinguished. +\item A few people are color blind. They will not be able to + distinguish between red and green lines (and some people are not + even able to distinguish colors at all). +\end{itemize} + +For these reasons, if there is any chance that the data visualization +will be printed in black and white at some point, consider combining +color style sheets with style sheets like |vary dashing| to make data +sets distinguishable in all situations. + + +\begin{stylesheet}{strong colors} + This style sheets uses pure primary colors that can very easily be + distinguished. Although not as visually pleasing as the |vary hue| + style sheet, the visualizations are easier to read when this style + sheet is used. Up to six different data sets are supported. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=strong colors] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=strong colors, + style sheet=vary dashing] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +Unlike |strong colors|, the following style sheets support, in +principle, an unlimited number of data set. In practice, as always, +more than four or five data sets lead to nearly indistinguishable data +sets. + +\begin{stylesheet}{vary hue} + This style uses a different hue for each data set. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary hue] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + +\begin{stylesheet}{shades of blue} + As the name suggests, different shades of blue are used for different + data sets. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=shades of blue] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\begin{stylesheet}{shades of red} +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=shades of red] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\begin{stylesheet}{gray scale} + For once, this style sheet can also be used when the visualization + is printed in black and white. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=gray scale] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\subsection{Usage: Labeling Data Sets Inside the Visualization} + +In a visualization that contains multiple data sets, it is often +necessary to clearly point out which line or mark type corresponds to +which data set. This can be done in the main text via a sentence like +``the normal data (black) lies clearly below the critical values +(red),'' but it often a good idea to indicate data sets ideally +directly inside the data visualization or directly next to it in a +so-called legend. + +The data visualization engine has direct support both for indicating +data sets directly inside the visualization and also for indicating +them in a legend. + +The ``best'' way of indicating where a data set lies or which color is +used for it is to put a label directly inside the data +visualization. The reason this is the ``best'' way is that people do +not have to match the legend entries against the data, let alone +having to look up the meaning of line styles somewhere in the +text. However, adding a label directly inside the visualization is +also the most tricky way of indicating data sets since it is hard to +compute good positions for the labels automatically and since there +needs to be some empty space where the label can be put. + +\subsubsection{Placing a Label Next to a Data Set} + +The following key is used to create a label inside the data +visualization for a data set: + +\begin{key}{/tikz/data visualization/visualizer options/label in data=\meta{options}} + This key is passed to a visualizer that has previously been created + using keys starting |visualize as ...|. It will create a label + inside the data visualization ``next'' to the visualizer (the + details are explained in a moment). You can use this key multiple + times with a visualizer to create multiple labels at different + points with different texts. + + The \meta{options} determine which text is shown and where it is + shown. They are executed with the following path prefix: +\begin{codeexample}[code only] +/tikz/data visualization/visualizer label options +\end{codeexample} + + In order to configure which text is shown and where, use the + following keys inside the \meta{options}: + + \begin{key}{/tikz/data visualization/visualizer label options/text=\meta{text}} + This is the text that will be displayed next to the data. It will + be to the ``left'' of the data, see the description below. + \end{key} + \begin{key}{/tikz/data visualization/visualizer label options/text'=\meta{text}} + Like |text|, only the text will be to the ``right'' of the data. + \end{key} + + The following keys are used to configure where the label will be + shown. They use different strategies to specify one data point where + the label will be anchored. The coordinate of this data point will + be stored in |(label| |visualizer| |coordinate)|. Independently of + the strategy, once the data point has been chosen, the coordinate of + the next data point is stored in |(label| |visualizer| + |coordinate')|. Then, a (conceptual) line is created from the first + coordinate to the second and a node is placed at the beginning of + this line to its ``left'' or, for the |text'| option, on its + ``right.'' More precisely, an automatic anchor is computed for a + node placed implicitly on this line using the |auto| option or, for + the |text'| option, using |auto,swap|. + + The node placed at the position computed in this way will have the + \meta{text} set by the |text| or |text'| option and its styling is + determined by the current |node style|. + + Let us now have a look at the different ways of determining the data + point at which the label in anchored: + \begin{key}{/tikz/data visualization/visualizer label + options/when=\meta{attribute}| is|\meta{number}} + This key causes the value of the \meta{attribute} to be monitored + in the stream of data points. The chosen is data point is the + first data point where the \meta{attribute} is at least + \meta{number} (if this never happens, the last data point is used). +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + log= {label in data={text'=$\log x$, when=y is -1, + text colored}}, + lin= {label in data={text=$x/2$, when=x is 2}}, + squared={label in data={text=$x^2$, when=x is 1.1}}, + exp= {label in data={text=$e^x$, when=x is -2, + text colored}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/data visualization/visualizer label + options/index=\meta{number}} + This key chooses the \meta{number}th data point belonging to the + visualizer's data set. +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={exp}, + exp= {label in data={text=$5$, index=5}, + label in data={text=$10$, index=10}, + label in data={text=$20$, index=20}, + style={mark=x}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/data visualization/visualizer label options/pos=\meta{fraction}} + This key chooses the first data point belonging to the data set + whose index is at least \meta{fraction} times the number of all + data points in the data set. +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line=exp, + exp= {label in data={text=$.2$, pos=0.2}, + label in data={text=$.5$, pos=0.5}, + label in data={text=$.95$, pos=0.95}, + style={mark=x}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/data visualization/visualizer label options/auto} + This key is executed automatically by default. It works like the + |pos| option, where the \meta{fraction} is set to $(\meta{data set's + index}-1/2)/\meta{number of data sets}$. For instance, when + there are $10$ data sets, the fraction for the first one will be + $5\%$, the fraction for the second will be $15\%$, for the third + it will be $25\%$, ending with $95\%$ for the last one. + + The net effect of all this is that when there are several lines, + labels will be placed at different positions along the lines with + hopefully only little overlap. +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + scientific axes=clean, + visualize as smooth line/.list={linear, squared, cubed}, + linear ={label in data={text=$2x$}}, + squared={label in data={text=$x^2$}}, + cubed ={label in data={text=$x^3$}}] +data [set=linear, format=function] { + var x : interval [0:1.5]; + func y = 2*\value x; +} +data [set=squared, format=function] { + var x : interval [0:1.5]; + func y = \value x * \value x; +} +data [set=cubed, format=function] { + var x : interval [0:1.5]; + func y = \value x * \value x * \value x; +}; +\end{codeexample} + As can be seen in the example, the result is not always + satisfactory. In this case, the |pin in data| option might be + preferable, see below. + \end{key} + + The following keys allow you to style labels. + + \begin{key}{/tikz/data visualization/visualizer label + options/node style=\meta{options}} + Just passes the options to |/tikz/data visualization/node style|. + \end{key} + \begin{key}{/tikz/data visualization/visualizer label + options/text colored} + Causes the |node style| to set the text color to + |visualizer color|. The effect of this is that the label's text + will have the same color as the data set to which it is attached. + \end{key} + + \begin{stylekey}{/tikz/data visualization/every data set label} + This style is executed with every label that represents a + data set. Inside this style, use |node style| to change the + appearance of nodes. This style has a default definition, usually + you should just append things to this style. + +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + every data set label/.append style={text colored}, + log= {label in data={text'=$\log x$, when=y is -1}}, + lin= {label in data={text=$x/2$, + node style=sloped, when=x is 2}}, + squared={label in data={text=$x^2$, when=x is 1.1}}, + exp= {label in data={text=$e^x$, + node style=sloped, when=x is -2}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + \end{stylekey} + + \begin{stylekey}{/tikz/data visualization/every label in data} + Like |every data set label|, this key is also executed with + labels. However, this key is executed after the style sheets have + been executed, giving you a chance to overrule their styling. + \end{stylekey} +\end{key} + +\subsubsection{Connecting a Label to a Data Set via a Pin} + +\begin{key}{/tikz/data visualization/visualizer options/pin in data=\meta{options}} + This key is a variant of the |label in data| key and takes the same + options, plus two additional ones. The difference to |label in data| + is that the label node is shown a bit removed from the data set, but + connected to it via a small line (this is like the difference + between the |label| and |pin| options). +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + scientific axes=clean, + visualize as smooth line/.list={linear, squared, cubed}, + linear ={pin in data={text=$2x$}}, + squared={pin in data={text=$x^2$}}, + cubed ={pin in data={text=$x^3$}}] +data [set=linear, format=function] { + var x : interval [0:1.5]; + func y = \value x; +} +data [set=squared, format=function] { + var x : interval [0:1.5]; + func y = \value x * \value x; +} +data [set=cubed, format=function] { + var x : interval [0:1.5]; + func y = \value x * \value x * \value x; +}; +\end{codeexample} + The following keys can be used additionally: + \begin{key}{/tikz/data visualization/visualizer label options/pin angle=\meta{angle}} + The position of the label of a |pin in data| is mainly computed in + the same way as for a |label in data|. However, once the position + has been computed, the label is shifted as follows: + \begin{itemize} + \item When an \meta{angle} is specified using the present key, the + shift is by the current value of |pin length| in the direction + of \meta{angle}. + \item When \meta{angle} is empty (which is the default), then the + shift is also by the current value of |pin length|, but now in + the direction that is orthogonal and to the left of the line + between the coordinate of the data point and the coordinate of + the next data point. When |text'| is used, the direction is to + the right instead of the left. + \end{itemize} + \end{key} + + \begin{key}{/tikz/data visualization/visualizer label options/pin length=\meta{dimension}} + See the description of |pin angle|. + \end{key} + +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + every data set label/.append style={text colored}, + log= {pin in data={text'=$\log x$, when=y is -1}}, + lin= {pin in data={text=$x/2$, when=x is 2, + pin length=1ex}}, + squared={pin in data={text=$x^2$, when=x is 1.1, + pin angle=230}}, + exp= {label in data={text=$e^x$, when=x is -2}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} +\end{key} + + + +\subsection{Usage: Labeling Data Sets Inside a Legend} + +The ``classical'' way of indicating the style used for the different +data sets inside a visualization is a \emph{legend}. It is a +description next to or even inside the visualization that contains one +line for each data set and displays an iconographic version of the +data set next to some text labeling the data set. Note, however, that +even though legend are quite common, also +consider using a |label in data| or a |pin in data| instead. + +Creating a high-quality legend is by no means simple. A legend should +not distract the reader, so aggressive borders should definitively be +avoided. A legend should make it easy to match the actual +styling of a data set (like, say, using a red, dashed line) to +the ``iconographic'' representation of this styling. An example of +what can go wrong here is using short lines to represent lines dashed +in different way where the lines are so short that the differences in +the dashing cannot be discerned. Another example is showing straight +lines with plot marks on them where the plot marks are obscured by the +horizontal line itself, while the plot marks are clearly visible in +the actual visualization since no horizontal lines occur. + +The data visualization engine comes with a large set of options for +creating and placing high-quality legends next or inside data +visualizations. + +\subsubsection{Creating Legends and Legend Entries} + +A data visualization can be accompanied by one or more legends. In +order to create a legend, the following key can be used (although, in +practice, you will usually use the |legend| key instead, see below): + +\begin{key}{/tikz/data visualization/new legend=\meta{legend name} + (default main legend)} + This key is used to create a new legend named \meta{legend name}. The + legend is empty by default and further options are needed to add + entries to it. When the key is called a second time for the same + \meta{legend name} nothing happens. + + When a legend is created, a new key is created that can + subsequently be used to configure the legend: + \begin{key}{/tikz/data visualization/\meta{legend name}=\meta{options}} + When this key is used, the \meta{options} are executed with the + path prefix +\begin{codeexample}[code only] +/tikz/data visualization/legend options +\end{codeexample} + The different keys with this path prefix allow you to change the + position where the legend is shown and how it is organised (for + instance, whether legend entries are shown in a row or in a column + or in a square). + + The different possible keys will be explained in the course of + this section. + \end{key} + + In the end, the legend is just a \tikzname\ node, a |matrix| node, + to be precise. The following key is used to style this node: + + + \begin{key}{/tikz/data visualization/legend options/matrix node style=\meta{options}} + Adds the \meta{options} to the list of options that will be + executed when the legend's node is created. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={matrix node style={fill=black!25}}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + \end{key} + + + The following style allows you to configure the default appearance + of every newly created legend: + \begin{stylekey}{/tikz/data visualization/legend options/every new legend} + This key defaults to |east outside, label style=text right|. This means + that by default a legend is placed to the right of the data + visualization and that in the individual legend entries the text + is to the right of the data set visualization. + \end{stylekey} + +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + scientific axes, x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + new legend={upper legend}, + new legend={lower legend}, + upper legend=above, + lower legend=below, + log= {label in legend={text=$\log x$, legend=upper legend}}, + lin= {label in legend={text=$x/2$, legend=upper legend}}, + squared={label in legend={text=$x^2$, legend=lower legend}}, + exp= {label in legend={text=$e^x$, legend=lower legend}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend=\meta{options}} + This is a shorthand for |new legend=main legend, main legend=|\meta{options}. + In other words, this key creates a new |main legend| and immediately + passes the configuration \meta{options} to this legend. + +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes, x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + legend=below, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} +\end{key} + +As pointed out above, a legend is empty by default. In particular, +the different data sets are not automatically inserted into the +legend. Instead, the key |label in legend| must be used together +with a data set: + +\begin{key}{/tikz/data visualization/visualizer options/label in legend=\meta{options}} + This key is passed to a data set, similar to options like + |pin in data| or |smooth line|. The \meta{options} are used to + configure the following: + \begin{itemize} + \item The legend in which the data set should be visualized. + \item The text that is to be shown in the legend for the data set. + \item The appearance of the legend entries. + \end{itemize} + In detail, the \meta{options} are executed with the path prefix +\begin{codeexample}[code only] +/tikz/data visualization/legend entry options +\end{codeexample} + To configure in which legend the label should appear, use the + following key: + \begin{key}{/tikz/data visualization/legend entry + options/legend=\meta{name} (initially main legend)} + Set this key to the name of a legend that has previously been + created using |new legend|. The label will then be shown in this + legend. + + In most cases, there is only one legend (namely |main legend|) and + there is no need to set this key since it defaults to the main + legend. + + Also note that the legend \meta{name} is automatically created if + it nodes not yet exist. + \end{key} + + \begin{key}{/tikz/data visualization/legend entry options/text=\meta{text}} + Use this key to setup the \meta{text} that is shown as the label + of the data set. + +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, x axis={label=$x$}, + visualize as smooth line/.list= + {log, lin, squared, exp}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={pin in data ={text=$x^2$, pos=0.1}}, + exp= {label in data ={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + \end{key} + + In addition to the two keys described above, there are further + keys that are described in + Section~\ref{section-dv-label-legend-entry-options}. +\end{key} + + +\subsubsection{Rows and Columns of Legend Entries} + +In a legend, the different legend entries are arranged in a matrix, +which typically has only one row or one column. For the impatient +reader: Say |rows=1| to get everything in a row, say |columns=1| to +get everything in a single column, and skip the rest of this section. + +The more patient reader will appreciate that when there are very many +different data sets in a single visualization, it may be +necessary to use more than one row or column inside the legend. +\tikzname\ comes with a rather powerful mechanism for distributing the +multiple legend entries over the matrix. + +The first thing to decide is in which ``direction'' the entries should +be inserted into the matrix. Suppose we have a $3 \times 3$ matrix and +our entries are $a$, $b$, $c$, and so on. Then, one might place the +$a$ in the upper left corner of the matrix, $b$ in the upper middle +position, $c$ in the upper right position, and $d$ in the middle left +position. This is a ``first right, then down'' strategy. A different +strategy might be to place the $a$ in the upper left corner, but $b$ +in the middle left position, $c$ in the lower left position, and $d$ +then in the upper middle position. This is a ``first down, then +right'' strategy. In certain situations it might even make sense to +place $a$ in the lower right corner and then go ``first up, then +left''. + +All of these strategies are supported by the |legend| command. You can +configure which strategy is used using the following keys: + +\tikzdatavisualizationset { + legend example/.style={ + scientific axes, all axes={length=1cm, ticks=none}, + 1={label in legend={text=1}}, + 2={label in legend={text=2}}, + 3={label in legend={text=3}}, + 4={label in legend={text=4}}, + 5={label in legend={text=5}}, + 6={label in legend={text=6}}, + 7={label in legend={text=7}}, + 8={label in legend={text=8}} + } +} + + +\begin{key}{/tikz/data visualization/legend options/down then right} + Causes the legend entries to fill the legend matrix first downward + and, once a column is full, the next column is begun to the right of + the previous one. This is the default. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={down then right, columns=3}] +data group {sin functions}; +\end{codeexample} + In the example, the |legend example| is the following style: +\begin{codeexample}[code only] +\tikzdatavisualizationset { + legend example/.style={ + scientific axes, all axes={length=1cm, ticks=none}, + 1={label in legend={text=1}}, + 2={label in legend={text=2}}, + 3={label in legend={text=3}}, + 4={label in legend={text=4}}, + 5={label in legend={text=5}}, + 6={label in legend={text=6}}, + 7={label in legend={text=7}}, + 8={label in legend={text=8}} + } +} +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/down then left} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={down then left, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/up then right} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={up then right, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/up then left} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={up then left, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend options/left then up} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={left then up, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/left then down} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={left then down, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/right then up} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then up, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/right then down} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then down, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + + +Having configured the directions in which the matrix is being filled, +you must next setup the number of rows or columns that are to be +shown. There are actually two different ways of doing so. The first +way is to specify a maximum number of rows or columns. For instance, +you might specify that there should be at most ten rows to a column +and when there are more, a new column should be begun. This is +achieved using the following keys: + +\begin{key}{/tikz/data visualization/legend options/max rows=\meta{number}} + As the legend matrix is being filled, whenever the number of rows in + the current column would exceed \meta{number}, a new column is + started. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max rows=3}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max rows=4}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max rows=5}] +data group {sin functions}; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend options/max columns=\meta{number}} + This key works like |max rows|, only now the number of columns is + monitored. Note that this strategy only really makes sense when the + when you use this key with a strategy that first goes left or right + and then up or down. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then down, max columns=2}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then down,max columns=3}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then down,max columns=4}] +data group {sin functions}; +\end{codeexample} +\end{key} + + +The second way of specifying the number of entries in a row or column +is to specify an ``ideal number of rows or columns.'' The idea is as +follows: Suppose that we use the standard strategy and would like to +have everything in two columns. Then if there are eight entries, the +first four should go to the first column, while the next four should +go to the second column. If we have 20 entries, the first ten should +go the first column and the next ten to the second, and so on. So, in +general, the objective is to distribute the entries evenly so the this +``ideal number of columns'' is reached. Only when there are too few +entries to achieve this or when the number of entries per column would +exceed the |max rows| value, will the number of columns deviate from +this ideal value. + + + +\begin{key}{/tikz/data visualization/legend options/ideal number of columns=\meta{number}} + Specifies, that the entries should be split into \meta{number} + different columns, whenever possible. However, when there would be + more than the |max rows| value of rows per column, more columns than + the ideal number are created. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={ideal number of columns=2}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={ideal number of columns=4}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max rows=3,ideal number of columns=2}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend + options/rows=\meta{number}} + Shorthand for |ideal number of rows=|\meta{number}. +\end{key} + + +\begin{key}{/tikz/data visualization/legend options/ideal number of rows=\meta{number}} + Works like |ideal number of columns|. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={ideal number of rows=2}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={ideal number of rows=4}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max columns=3,ideal number of rows=2}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend + options/columns=\meta{number}} + Shorthand for |ideal number of columns=|\meta{number}. +\end{key} + + +\subsubsection{Legend Placement: The General Mechanism} + +A legend can either be placed next to the data visualization or inside +the data visualization at some place where there are no data +entries. Both approached have advantages: Placing the legend next to +the visualization minimises the ``cluttering'' by keeping all the +extra information apart from the actual data, while placing the legend +inside the visualization minimises the distance between the data sets +and their explanations, making it easier for the eye to connect them. + +For both approaches there are options that make the placement easier, +see Sections \ref{section-dv-legend-outside} +and~\ref{section-dv-legend-inside}, but these options internally just +map to the following two options: + +\begin{key}{/tikz/data visualization/legend + options/anchor=\meta{anchor}} + The whole legend is a \tikzname-matrix internally. Thus, + in particular, it is stored in a node, which has anchors. Like for + any other node, when the node is shown, the node is shifted in such + a way that the \meta{anchor} of the node lies at the current |at| + position. +\end{key} + +\begin{key}{/tikz/data visualization/legend + options/at=\meta{coordinate}} + Configures the \meta{coordinate} at which the \meta{anchor} of the + legend's node should lie. + + It may seem hard to predict a good \meta{coordinate} for a legend + since, depending of the size of the axis, different positions need + to the chosen for the legend. However, it turns out that one + can often use the coordinates of the special nodes + |data bounding box| and |data visualization bounding box|, + documented in Section~\ref{section-dv-bounding-box}. + + As an example, let us put a legend to the right of the + visualization, but so that the first entry starts at the top of the + visualization: +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, x axis={label=$x$}, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={anchor=north west, at= + (data visualization bounding box.north east)}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + As can be seen, a bit of an additional shift might have been in + order, but the result is otherwise quite satisfactory. +\end{key} + + +\subsubsection{Legend Placement: Outside to the Data Visualization} +\label{section-dv-legend-outside} + +The following keys make it easy to place a legend outside the data +visualization. + +\begin{key}{/tikz/data visualization/legend options/east outside} + Placing the legend to the right of the data visualization is the default: +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + + \begin{key}{/tikz/data visualization/legend options/right} + This is an easier-to-remember alias. + \end{key} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/north east outside} + A variant, where the legend is to the right, but aligned with the + northern end of the data visualization: +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/south east outside} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=south east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/west outside} + The legend is placed left. Note that the text also swaps its + position. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=west outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + \begin{key}{/tikz/data visualization/legend options/left} + This is an easier-to-remember alias. + \end{key} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/north west outside} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north west outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/south west outside} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=south west outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend options/north outside} + The legend is placed above the data. Note that the legend entries + now for a row rather than a column. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + \begin{key}{/tikz/data visualization/legend options/above} + This is an easier-to-remember alias. + \end{key} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/south outside} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=south outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + \begin{key}{/tikz/data visualization/legend options/below} + This is an easier-to-remember alias. + \end{key} +\end{key} + + + +\subsubsection{Legend Placement: Inside to the Data Visualization} +\label{section-dv-legend-inside} + +There are two sets of options for placing a legend directly inside a +data visualization: First, there are options for placing it inside, +but next to some part of the border. Second, there are options for +positioning it relative to a coordinate given by a certain data point. + + + +\begin{key}{/tikz/data visualization/legend options/south east inside} + Puts the legend in the upper right corner of the data. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin}, + legend=south east inside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + + Note that the text is now a little smaller since there tends to be + much less space inside the data visualization than next to it. Also, + the legend's node is filled in white by default to ensures that the + legend is clearly legible even in the presence of, say, a grid or + data points behind it. This behaviour is triggered by the following + style key: + + \begin{stylekey}{/tikz/data visualization/legend options/every legend inside} + Executed the keys |opaque| by default and sets the text size to + the size of footnotes. + \end{stylekey} +\end{key} + +In order to further configure the default appearance of an inner +legend, the following keys might be useful: + +\begin{key}{/tikz/data visualization/legend + options/opaque=\meta{color} (default white)} + When this key is used, the legend's node will be filled with the + \meta{color} and its corners will be rounded. Additionally, the + inner and outer separations will be set to sensible values. +\end{key} +\begin{key}{/tikz/data visualization/legend + options/transparent} + Sets the filling of the legend node to |none|. +\end{key} + +The following keys work much the same way as |south east inside|: + +\begin{key}{/tikz/data visualization/legend options/east inside} +\end{key} +\begin{key}{/tikz/data visualization/legend options/north east inside} +\end{key} +\begin{key}{/tikz/data visualization/legend options/south west inside} +\end{key} +\begin{key}{/tikz/data visualization/legend options/west inside} +\end{key} +\begin{key}{/tikz/data visualization/legend options/north west inside} +\end{key} + +The keys |south inside| and |north inside| are a bit different: They use a row +rather than a column for the legend entries: + +\begin{key}{/tikz/data visualization/legend options/south inside} + Puts the legend in the upper right corner of the data. Note that the + text is now a little smaller since there tends to be much less space + inside the data visualization than next to it. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list={log, lin}, + legend=south inside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/north inside} + As above. +\end{key} + +The above keys do not always give you as fine a control as you may +need over the placement of the legend. In such cases, the following +keys may help (or you can revert to directly setting the |at| and the +|anchor| keys): + +\begin{key}{/tikz/data visualization/legend options/at + values=\meta{data point}} + This key allows you to specify the desired center of the legend in + terms of a data point. The \meta{data point} should be a list of + comma-separated key--value pairs that specify a data point. The + legend will then be centered at this data point. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list={log, lin}, + legend={at values={x=-1, y=2}}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/right + of=\meta{data point}} + Works like |at values|, but the anchor is set to |west|: +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list={log, lin}, + legend={right of={x=-1, y=2}}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +The following keys work similarly: +\begin{key}{/tikz/data visualization/legend options/above right of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/above of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/above left of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/left of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/below left of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/below of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/below right of=\meta{data point}} +\end{key} + + + + +\subsubsection{Legend Entries: General Styling} + +\label{section-dv-label-legend-entry-options} + +The entries in a legend can be styled in several ways: + +\begin{itemize} +\item + You can configure the styling of the text node. +\item + You can configure the relative placement of the text node and the + little picture depicting the data set's styling. +\item + You can configure how the data set's styling is depicted. +\end{itemize} + +Before we have look at how each of these are configured, in detail, +let us first have a look at the keys that allow us to save a set of +such styles: + +\begin{stylekey}{/tikz/data visualization/every label in legend} + This key is executed with every label in a legend. However, the + options stored in this style are executed with the path prefix + |/tikz/data visualization/legend entry options|. Thus, this key can + use keys like |node style| to configure the styling of all text + nodes: +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + every label in legend/.style={node style= + {fill=red!30}}, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$, + node style={circle, draw=red}}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{stylekey} + +\begin{key}{/tikz/data visualization/legend options/label style=\meta{options}} + This key can be used with a legend. It will simply add the + \meta{options} to the |every label in legend| style for the given + legend. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={label style={node style=draw}}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$, + node style={circle, draw=red}}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + + +\subsubsection{Legend Entries: Styling the Text Node} + +The appearance of the text nodes is easy to configure. + +\begin{key}{/tikz/data visualization/legend entry options/node style=\meta{options}} + This key adds \meta{options} to the styling of the text nodes of the + label. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$, + node style={circle, draw=red}}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend entry options/text colored} + Causes the |node style| to set the text color to + |visualizer color|. The effect of this is that the label's text + will have the same color as the data set to which it is attached. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={label style=text colored}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + + +\subsubsection{Legend Entries: Text Placement} + +Three keys govern where the text will be placed relative to the data +set style visualization. + +\begin{key}{/tikz/data visualization/legend entry options/text right} + Placed the text node to the right of the data set style + visualization. This is the default for most, but not all, legends. +\end{key} +\begin{key}{/tikz/data visualization/legend entry options/text left} + Placed the text node to the left of the data set style + visualization. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={label style=text left}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/data visualization/legend entry options/text only} + Shows only the text nodes and no data set style visualization at + all. This options only makes sense in conjunction with the + |text colored| options, which is why this options is also selected + implicitly. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={south east inside, rows=2, + label style=text only}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + + + + + +\subsubsection{Advanced: Labels in Legends and Their Visualizers} + +\label{section-dv-legend-entries} + +The following explanations are important only for you if you intend to +create a new visualizer and an accompanying label in legend +visualizer; otherwise you can safely proceed with the next section. + +A legend entry consists not only of some explaining text, but, even +more importantly, of a visual representation of the style used for the +data points, created by a \emph{label in legend visualizer}. For +instance, when data points are visualized as lines in +different colors, the legend entry for the first line might consist of +the text ``first experiment'' and a short line in black and the second +entry might consist of ``failed experiment'' and a short line in red +-- assuming, of course, that the style sheet makes the first line +black and the second line blue. As another example, when data sets are +visualized as clouds of plot marks, the texts in the legend would be +accompanied by the plot marks used to visualize the data sets. + +For every visualizer, the \emph{label in legend visualizer} creates an +appropriate visualization of the data set's styling. There may be more +than one possible such label in legend visualizer that is appropriate, +in which case options are used to choose between them. + +Let us start with the key for creating a new legend entry. This key +gets called for instance by |label in legend|: + +\begin{key}{/tikz/data visualization/new legend entry=\meta{options}} + This key will add a new entry to the legend that is identified by + the \meta{options}. For this, the \meta{options} are executed once + with the path prefix |/tikz/data visualization/legend entry options| + and the resulting setting of the |legend| key is used to pick which + legend the new entry should belong to. Then, the \meta{options} are + stored away for the time being. + + Later, when the legend is created, the \meta{options} get executed + once more. This time, however, the |legend| key is no longer + important. Instead, the \meta{options} that setup keys like + |text| or |visualizer in legend| now play a role. + + In detail, the following happens: + \begin{itemize} + \item For the legend entry, a little cell picture is created in the + matrix of the legend (see Section~\ref{section-tikz-cell-pictures} + for details on cell pictures). + \item Inside this picture, a node is created whose text is taken + from the key +\begin{codeexample}[code only] +/tikz/data visualization/legend entry options/text +\end{codeexample} + \item Also inside the picture, the code stored in the following key + gets executed: + \begin{key}{/tikz/data visualization/legend entry options/visualizer in legend} + Set this key to some code that paints something in the cell + picture. Typically, this will be a visual representation of the + data set styling, but it could also be something different. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + style sheet=vary dashing, + a={label in legend={text=a}}, + new legend entry={ + text=spacer, + visualizer in legend={\draw[solid] (0,0) circle[radius=2pt];} + }, + b={label in legend={text=b}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} + \end{key} + \end{itemize} + The following styles are applied in the following order before the + cell picture is filled: + \begin{enumerate} + \item |/tikz/data visualization/every data set label| with path + |/tikz/data visualization| + \item |/tikz/data visualization/every label in legend| with path\\ + |/tikz/data visualization/legend entry options|. + \item The \meta{options}. + \item The code in the following key: + \begin{key}{/tikz/data visualization/legend entry options/setup} + Some code to be executed at this point. Mostly, it is used to + setup attributes for style sheets. + \end{key} + \item A styling signal is emitted. + \item Only for the node: The current value of |node style|. + \item Only for the visualizer in legend: The styling that has been + accumulated by calls to the following key: + \begin{stylekey}{/tikz/data visualization/legend entry + options/visualizer in legend style=\\\marg{options}} + Calls to this key accumulate \meta{options} that will be + executed with the path prefix |/tikz| at this point. + \end{stylekey} + \end{enumerate} +\end{key} + +As indicated earlier, the |new legend entry| key is called by the +|label in legend=|\meta{options} key internally. In this case, the +following extra \meta{extra options} are passed to |new legend entry| +key: +\begin{itemize} +\item The styling of the visualizer. +\item The |/tikz/data visualization/every label in legend| style. +\item The |/tikz/every label| style with path |/tikz|. +\item Setting |setup| to |/data point/set=|\meta{name of the visualizer}. +\item The value of the |label legend options| that are stored in the + visualizer. These options can be changed using the following key: + \begin{key}{/tikz/data visualization/visualizer options/label in + legend options=\meta{options}} + Use this key with a visualizer to configure the label in legend + options. Typically, this key is used only internally by a + visualizer upon its creating to set the \meta{options} to setup + the |visualizer in legend| key. + \end{key} +\end{itemize} + + +\subsubsection{Reference: Label in Legend Visualizers for Lines and Scatter Plots} + +Visualizers like |visualize as line| or |visualize as smooth line| +use a label in legend visualizer that draws a short line to represent +the data set inside the legend. However, this line needs not be a +simple straight line, but can be a little curve or a small circle -- +indeed, even the default line is not a simple straight line but rather +a small zig-zag curve. To configure this line, the two keys +are used, although you will only rarely use them directly, but +rather use one of the predefined styles mentioned later on. + +Before we go into the glorious details of all of these keys, let us +first have a look at the keys you are most likely to use in practice: +The keys for globally reconfiguring the default label in legend +visualizers: +\begin{stylekey}{/tikz/data visualization/legend entry options/default + label in legend path} + This style is set, by default, to |zig zag label in legend line|. It + is installed by the styles |straight line|, |smooth line|, and + |gap line|, so changing this style will change the appearance of lines in + legends. The main other sensible option for this key is + |straight label in legend line|. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + style sheet=vary dashing, + a={label in legend={text=a}}, b={label in legend={text=b}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + legend entry options/default label in legend path/.style= + straight label in legend line, + style sheet=vary dashing, + a={label in legend={text=a}}, b={label in legend={text=b}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} +\end{stylekey} +\begin{stylekey}{/tikz/data visualization/legend entry options/default + label in legend closed path} + This style is executed by |smooth cycle| and |straight cycle|. There + are (currently) no other predefined sets of coordinates that can be + used instead of the default value |circular label in legend line|. +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/legend entry options/default + label in legend mark} + This style is executed by |no lines| and, implicitly, by scatter + plots. The default is to use + |label in legend line one mark|. Another possible value is + |label in legend line three marks|. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + visualize as scatter/.list={a,b,c}, + style sheet=cross marks, + legend entry options/default label in legend mark/.style= + label in legend three marks, + a={label in legend={text=example a}}, + b={label in legend={text=example b}}, + c={label in legend={text=example c}}]; +\end{codeexample} +\end{stylekey} + +\begin{key}{/tikz/data visualization/legend entry options/label in + legend line coordinates=\\\marg{list of coordinates}} + This key takes a \meta{list of coordinates}, which are + \tikzname-coordinates separated by commas like |(0,0),|\penalty0|(1,1)|. The + effect of setting the key is the following: The label in legend + visualizer used by, for instance, |visualize as line| will draw a + path going through these points. When the line is drawn, the exact + same style will be used as was used for the data set. For instance, + if the |smooth line| key was used and also the |style=red| key, the + line through the \meta{list of coordinates} will also be red and + smooth. When the |straight cycle| key was used, the coordinates will + also be connected by a cycle, and so on. + + When the line connecting the \meta{list of coordinates} is drawn, + the coordinate system will have been shifted and transformed in such + a way that |(0,0)| lies to the left of the text and at half the + height of the character ``x''. This means that the right-most-point + in the list should usually be |(0,0)| and all other $x$-coordinates + should usually be negative. When the |text left| options is used, + the coordinate system will have been flipped, so the \meta{list of + coordinates} is independent of whether the text is to the right or + to the left of the line. + + Let us now have a look at a first, simple example. We create a + legend entry that is just a straight line, so it should start + somewhere to the left of the origin at height $0$ and go to the + origin: +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + style sheet=vary dashing, + a={label in legend={text=a, + label in legend line coordinates={(-1em,0), (0,0)}}}, + b={label in legend={text=b, + label in legend line coordinates={(-2em,0), (0,0)}}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} + + Now let us make this a bit more fancy and useful by using shifted lines: +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + legend={up then right}, style sheet=vary dashing, + a={label in legend={text=a, + label in legend line coordinates={(-2em,-.25ex), (0,0)}}}, + b={label in legend={text=b, + label in legend line coordinates={(-2em,.25ex), (0,0)}}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} + + In the final example, we use a little ``hat'' to represent lines: +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + legend={up then right}, style sheet=vary dashing, + a={label in legend={text=a, + label in legend line coordinates={ + (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}}}, + b={label in legend={text=b, + label in legend line coordinates={ + (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend entry options/label in + legend mark coordinates=\\\marg{list of coordinates}} + This key is similar to |label in legend line coordinates|, but now + the \meta{list of coordinates} is used as the positions where plot + marks are shown. Naturally, plot marks are only shown there if they + are also shown by the visualizer in the actual data -- just like the + line through the coordinates of the previous key is only shown when + there is a line. + + The \meta{list of coordinates} may be the same as the one used for + lines, but usually it is not. In general, it is better to have marks + for instance not at the ends of the line. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + legend={up then right}, + style sheet=vary dashing, + style sheet=cross marks, + a={label in legend={text=a, + label in legend line coordinates={ + (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}, + label in legend mark coordinates={ + (-1em,.2ex)}}}, + b={label in legend={text=b, + label in legend line coordinates={ + (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}, + label in legend mark coordinates={ + (-2em,-.2ex), (0,-.2ex)}}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} +\end{key} + + + +Naturally, you typically will not give coordinates explicitly for each +label, but use one of the following styles: + +\begin{key}{/tikz/data visualization/legend entry options/straight label in legend line} + Just gives a straight line and two plot marks. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [visualize as line, + line={style={mark=x}, label in legend={text=example, + straight label in legend line}}]; +\end{codeexample} + This style might seem like a good idea to use in general, but it + does have a huge drawback: Some commonly used plot marks will be impossible to + distinguish -- even though there is no problem distinguishing them + in a graph. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [visualize as line/.list={a,b,c}, + legend entry options/default label in legend path/.style= + straight label in legend line, + a={style={mark=+}, label in legend={text=bad example a}}, + b={style={mark=-}, label in legend={text=bad example b}}, + c={style={mark=|}, label in legend={text=bad example c}}]; +\end{codeexample} + For this reason, this option is not the default, but rather the next one. +\end{key} + +\begin{key}{/tikz/data visualization/legend entry options/zig zag label in legend line} + Uses a small up-down-up line as the label in legend visualizer. The + two plot marks are at the extremal points of the line. It works + pretty well in almost all situations and is the default. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + visualize as line=a, + visualize as smooth line/.list={b,c}, + a={style={mark=+}, label in legend={text=better example a}}, + b={style={mark=-}, label in legend={text=better example b}}, + c={style={mark=|}, label in legend={text=better example c}}]; +\end{codeexample} + Even though the above example shows that the marks are easier to + distinguish than with a straight line, the chosen marks are still + not optimal. This is the reason that the |cross marks| style uses + different crosses: +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + visualize as line/.list={a,b}, + visualize as smooth line=c, + style sheet=cross marks, + a={label in legend={text=good example a}}, + b={label in legend={text=good example b}}, + c={gap line, label in legend={text=good example c}}]; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend entry options/circular label in legend line} + This style is especially tailored to represent lines that are + closed. It is automatically selected for instance by the |polygon| + or the |smooth cycle| styles. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes={clean}, all axes={length=3cm}, + visualize as line/.list={a,b,c}, + a={polygon}, b={smooth cycle}, + style sheet=cross marks, + a={label in legend={text=polygon}}, + b={label in legend={text=circle}}, + c={label in legend={text=line}}] +data [format=function, set=a] { + var t : {0,72,...,359}; + func x = cos(\value t); + func y = sin(\value t); +} +data [format=function, set=b] { + var t : [0:2*pi]; + func x = .8*cos(\value t r); + func y = .8*sin(\value t r); +} +data point [x=-1, y=0.5, set=c] +data point [x=1, y=0.25, set=c]; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend entry options/gap circular label in legend line} + This style is especially tailored to for the |gap cycle| style and + automatically selected by it: +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes={clean}, all axes={length=3cm}, + visualize as line/.list={a,b,c}, + a={gap cycle}, b={smooth cycle}, c={gap line}, + a={style={mark=*, mark size=0.5pt}, + label in legend={text=polygon}}, + b={label in legend={text=circle}}, + c={style={mark=*, mark size=0.5pt, mark options=red}, + label in legend={text=line}}] +data [format=function, set=a] { + var t : {0,72,...,359}; + func x = cos(\value t); + func y = sin(\value t); +} +data [format=function, set=b] { + var t : [0:352]; + func x = .8*cos(\value t); + func y = .8*sin(\value t); +} +data point [x=-1, y=0.5, set=c] +data point [x=1, y=0.25, set=c]; +\end{codeexample} +\end{key} + + + +\begin{key}{/tikz/data visualization/legend entry options/label in legend one mark} + To be used with scatter plots, since no line is drawn. Just displays + a single mark (this is the default with a scatter plot or when the + |no line| is selected. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [visualize as scatter/.list={a,b,c}, + style sheet=cross marks, + a={label in legend={text=example a}}, + b={label in legend={text=example b}}, + c={label in legend={text=example c}}]; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend entry options/label in legend three marks} + An alternative to the previous style, where several marks are + shown. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [visualize as scatter/.list={a,b,c}, + style sheet=cross marks, + a={label in legend={text=example a, label in legend three marks}}, + b={label in legend={text=example b, label in legend three marks}}, + c={label in legend={text=example c, label in legend three marks}}]; +\end{codeexample} +\end{key} + + + |