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.tex2082
1 files changed, 1059 insertions, 1023 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 43682ca38e3..0e162cc1c32 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,70 +13,64 @@
\subsection{Overview}
-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:
+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.
+ \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.
+%
+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.
+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.
+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] {
@@ -115,29 +109,26 @@ 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.
-
+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},
@@ -151,7 +142,6 @@ visualization, which is even better than adding a legend, in general.
data group {function classes};
\end{codeexample}
-
\begin{codeexample}[width=6.3cm]
\tikz \datavisualization [
school book axes,
@@ -173,20 +163,19 @@ data group {function classes};
\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.
+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:
+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.
+ 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},
@@ -195,103 +184,103 @@ option for this:
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:
-
+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
+ 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.
+/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
+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},
+/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:
+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.
+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:
+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.
+\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).
+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,
@@ -315,16 +304,15 @@ 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:
-
+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.
@@ -333,11 +321,10 @@ example:
3/.style={red!80!black},
default style/.style={black}
}
-
\begin{codeexample}[]
-% Definition of traffic light keys as above
+% Definition of traffic light keys as above
\begin{tikzpicture}
- \datavisualization data group {lines} = {
+ \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]
@@ -358,19 +345,17 @@ example:
\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:
-
-
+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
+% Definition of traffic light keys as above
\tikz \datavisualization [
school book axes,
visualize as line=normal,
@@ -381,14 +366,13 @@ you would like several different data sets to use the same styling:
data group {lines};
\end{codeexample}
-We can a command that slightly simplifies the definition of style
-sheets:
+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:
+ 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},
@@ -397,12 +381,13 @@ sheets:
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.
+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}{
@@ -417,21 +402,22 @@ need to define an large number of styles in this case, but can use the
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:
+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.
+ 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}
{
@@ -448,26 +434,24 @@ use the |visualizer color| key to set the color:
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.''
+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 [
@@ -478,18 +462,16 @@ package for details.
style sheet=greens]
data group {lines};
\end{codeexample}
-
+ %
\end{command}
-
-
\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:
-
+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={
@@ -508,7 +490,7 @@ following style and data set are used:
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={
@@ -527,7 +509,7 @@ following style and data set are used:
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} = {
@@ -536,7 +518,7 @@ following style and data set are used:
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] {
@@ -544,12 +526,13 @@ following style and data set are used:
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.
+ 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=
@@ -558,15 +541,16 @@ following style and data set are used:
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.
+ 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=
@@ -575,21 +559,22 @@ data group {sin functions};
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.
+ %
+ 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.
+ 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=
@@ -599,8 +584,10 @@ data group {sin functions};
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:
+ %
+ 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=
@@ -610,22 +597,25 @@ data group {sin functions};
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.
+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.
+ 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 and requires the
+ |plotmarks| library.
+ %
\begin{codeexample}[width=10cm]
\tikz \datavisualization [
visualize as scatter/.list=
@@ -634,6 +624,7 @@ with lines. In the latter case, the marks are added to the lines.
style sheet=cross marks]
data group {sin functions};
\end{codeexample}
+ %
\begin{codeexample}[width=10cm]
\tikz \datavisualization [
visualize as smooth line/.list=
@@ -642,35 +633,36 @@ data group {sin functions};
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:
-
+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).
+ \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.
-
+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.
+ 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=
@@ -679,6 +671,7 @@ sets distinguishable in all situations.
style sheet=strong colors]
data group {sin functions};
\end{codeexample}
+ %
\begin{codeexample}[width=10cm]
\tikz \datavisualization [
visualize as smooth line/.list=
@@ -688,16 +681,17 @@ data group {sin functions};
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.
+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.
+ This style uses a different hue for each data set.
+ %
\begin{codeexample}[width=10cm]
\tikz \datavisualization [
visualize as smooth line/.list=
@@ -706,11 +700,12 @@ sets.
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.
+ 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=
@@ -719,9 +714,9 @@ data group {sin functions};
style sheet=shades of blue]
data group {sin functions};
\end{codeexample}
+ %
\end{stylesheet}
-
\begin{stylesheet}{shades of red}
\begin{codeexample}[width=10cm]
\tikz \datavisualization [
@@ -733,10 +728,10 @@ 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.
+ 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=
@@ -745,88 +740,88 @@ data group {sin functions};
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.
+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:
+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:
+ 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).
+ 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,
@@ -841,11 +836,12 @@ visualization for a data set:
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.
+ \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,
@@ -858,11 +854,13 @@ data group {function classes};
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.
+ \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,
@@ -875,18 +873,20 @@ data group {function classes};
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.
+ \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,
@@ -907,30 +907,29 @@ data [set=cubed, format=function] {
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.
+ %
+ 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,
@@ -946,23 +945,25 @@ data [set=cubed, format=function] {
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{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}
+
+\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).
+ 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,
@@ -983,28 +984,31 @@ data [set=cubed, format=function] {
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}
+ %
+ 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,
@@ -1020,73 +1024,72 @@ data [set=cubed, format=function] {
style sheet=vary hue]
data group {function classes};
\end{codeexample}
-\end{key}
-
+ \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.
+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
+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.
+ %
+ 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,
@@ -1099,19 +1102,19 @@ practice, you will usually use the |legend| key instead, see below):
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}
+\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$},
@@ -1126,14 +1129,16 @@ data group {function classes};
exp= {label in legend={text=$e^x$, legend=lower legend}},
style sheet=vary dashing]
data group {function classes};
-\end{codeexample}
+\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.
-
+ 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$},
@@ -1146,91 +1151,88 @@ data group {function classes};
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:
+
+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
+ 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.
+ %
+ 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.
+ 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.
+ 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, 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{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''.
+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:
@@ -1247,13 +1249,13 @@ configure which strategy is used using the following keys:
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.
+ 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},
@@ -1261,7 +1263,9 @@ configure which strategy is used using the following keys:
main legend={down then right, columns=3}]
data group {sin functions};
\end{codeexample}
- In the example, the |legend example| is the following style:
+ %
+ In the example, the |legend example| is the following style:
+ %
\begin{codeexample}[code only]
\tikzdatavisualizationset {
legend example/.style={
@@ -1275,8 +1279,9 @@ data group {sin functions};
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}
@@ -1309,7 +1314,6 @@ data group {sin functions};
\end{codeexample}
\end{key}
-
\begin{key}{/tikz/data visualization/legend options/left then up}
\begin{codeexample}[width=6cm]
\tikz \datavisualization [
@@ -1350,191 +1354,192 @@ 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:
+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.
+ 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}
+\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}
+\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{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.
+ 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}
+\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}
+\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{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.
-
-
+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.
+ 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}
+\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}
+\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{codeexample}
+ %
\end{key}
-\begin{key}{/tikz/data visualization/legend
- options/rows=\meta{number}}
- Shorthand for |ideal number of rows=|\meta{number}.
+\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|.
+ 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}
+\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}
+\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{codeexample}
+ %
\end{key}
-\begin{key}{/tikz/data visualization/legend
- options/columns=\meta{number}}
- Shorthand for |ideal number of columns=|\meta{number}.
+\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:
+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$},
@@ -1549,8 +1554,9 @@ map to the following two options:
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.
+ %
+ As can be seen, a bit of an additional shift might have been in order, but
+ the result is otherwise quite satisfactory.
\end{key}
@@ -1558,13 +1564,14 @@ data group {function classes};
\label{section-dv-legend-outside}
The following keys make it easy to place a legend outside the data
-visualization.
+visualization.
\begin{key}{/tikz/data visualization/legend options/east outside}
- Placing the legend to the right of the data visualization is the default:
+ Placing the legend to the right of the data visualization is the default:
+ %
\begin{codeexample}[width=8cm]
\tikz \datavisualization [
- scientific axes,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=east outside,
@@ -1574,19 +1581,20 @@ visualization.
exp= {label in legend={text=$e^x$}},
style sheet=strong colors]
data group {function classes};
-\end{codeexample}
+\end{codeexample}
- \begin{key}{/tikz/data visualization/legend options/right}
- This is an easier-to-remember alias.
- \end{key}
+ \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:
+ 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,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=north east outside,
@@ -1596,13 +1604,14 @@ data group {function classes};
exp= {label in legend={text=$e^x$}},
style sheet=strong colors]
data group {function classes};
-\end{codeexample}
+\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/data visualization/legend options/south east outside}
\begin{codeexample}[width=8cm]
\tikz \datavisualization [
- scientific axes,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=south east outside,
@@ -1612,15 +1621,15 @@ data group {function classes};
exp= {label in legend={text=$e^x$}},
style sheet=strong colors]
data group {function classes};
-\end{codeexample}
+\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.
+ The legend is placed left. Note that the text also swaps its position.
+ %
\begin{codeexample}[width=8cm]
\tikz \datavisualization [
- scientific axes,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=west outside,
@@ -1630,16 +1639,17 @@ data group {function classes};
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{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,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=north west outside,
@@ -1649,13 +1659,13 @@ data group {function classes};
exp= {label in legend={text=$e^x$}},
style sheet=strong colors]
data group {function classes};
-\end{codeexample}
+\end{codeexample}
\end{key}
\begin{key}{/tikz/data visualization/legend options/south west outside}
\begin{codeexample}[width=8cm]
\tikz \datavisualization [
- scientific axes,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=south west outside,
@@ -1665,16 +1675,17 @@ data group {function classes};
exp= {label in legend={text=$e^x$}},
style sheet=strong colors]
data group {function classes};
-\end{codeexample}
+\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.
+ 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,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=north outside,
@@ -1684,16 +1695,17 @@ data group {function classes};
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{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,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=south outside,
@@ -1703,29 +1715,28 @@ data group {function classes};
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{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.
-
-
+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.
+ Puts the legend in the upper right corner of the data.
+ %
\begin{codeexample}[width=8cm]
\tikz \datavisualization [
- scientific axes,
+ scientific axes,
visualize as smooth line/.list=
{log, lin},
legend=south east inside,
@@ -1733,45 +1744,47 @@ positioning it relative to a coordinate given by a certain data point.
lin= {label in legend={text=$x/2$}},
style sheet=strong colors]
data group {function classes};
-\end{codeexample}
+\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:
+ 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}
+ \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:
+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.
+\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|.
+%
+\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}
@@ -1779,108 +1792,111 @@ 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.
+ 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,
+ 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{codeexample}
+ %
\end{key}
\begin{key}{/tikz/data visualization/legend options/north inside}
- As above.
+ 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):
+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{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,
+ 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{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{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,
+ 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{codeexample}
+ %
\end{key}
The following keys work similarly:
-\begin{key}{/tikz/data visualization/legend options/above right of=\meta{data point}}
+%
+\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}}
+%
+\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}}
+%
+\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}}
+%
+\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}}
+%
+\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}}
+%
+\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}}
+%
+\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.
+ \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:
+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:
+ 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,
@@ -1897,12 +1913,13 @@ such styles:
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.
+ 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,
@@ -1917,19 +1934,20 @@ data group {function classes};
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.
+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.
+ This key adds \meta{options} to the styling of the text nodes of the label.
+ %
\begin{codeexample}[width=8cm]
\tikz \datavisualization [
- scientific axes,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend=north east outside,
@@ -1941,15 +1959,17 @@ The appearance of the text nodes is easy to configure.
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.
+ 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,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend={label style=text colored},
@@ -1960,24 +1980,26 @@ data group {function classes};
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.
+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.
+ 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.
+ Placed the text node to the left of the data set style visualization.
+ %
\begin{codeexample}[width=8cm]
\tikz \datavisualization [
- scientific axes,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend={label style=text left},
@@ -1988,15 +2010,17 @@ set style visualization.
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.
+ 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,
+ scientific axes,
visualize as smooth line/.list=
{log, lin, squared, exp},
legend={south east inside, rows=2,
@@ -2008,69 +2032,70 @@ data group {function classes};
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.
+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.
+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|:
+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
+ 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.
+/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},
@@ -2084,76 +2109,77 @@ gets called for instance by |label in legend|:
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}
+ \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:
+|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}
+ \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
+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|.
+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},
@@ -2162,6 +2188,7 @@ visualizers:
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},
@@ -2172,23 +2199,23 @@ data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=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|.
+%
+\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{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},
+ 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,
@@ -2196,35 +2223,34 @@ data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
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{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},
@@ -2237,7 +2263,8 @@ 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:
+ 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},
@@ -2250,7 +2277,8 @@ 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:
+ 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},
@@ -2264,20 +2292,20 @@ data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=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}
-\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.
+\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.
+ 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},
@@ -2297,72 +2325,80 @@ data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=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}
-
-Naturally, you typically will not give coordinates explicitly for each
-label, but use one of the following styles:
+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.
+ 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,
+\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.
+ %
+ 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},
+\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.
+ %
+ 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.
+ 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},
+ 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:
+ %
+ 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,
+ 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.
+ 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},
+ a={polygon}, b={smooth cycle},
style sheet=cross marks,
a={label in legend={text=polygon}},
b={label in legend={text=circle}},
@@ -2380,17 +2416,18 @@ data [format=function, set=b] {
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:
+ 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={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}},
@@ -2409,14 +2446,14 @@ data [format=function, set=b] {
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.
+ 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,
@@ -2424,11 +2461,12 @@ data point [x=1, y=0.25, set=c];
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.
+ 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,
@@ -2436,7 +2474,5 @@ data point [x=1, y=0.25, set=c];
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}
-
-
-