summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex
diff options
context:
space:
mode:
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.tex2419
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}
+
+
+