diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex | 3920 |
1 files changed, 1970 insertions, 1950 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex index f44b1b4ad4a..a0e46cbaf9b 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex @@ -7,176 +7,178 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. + \section{Axes} \label{section-dv-axes} - \subsection{Overview} -When a data point is visualized, the most obvious way of creating a -visual representation of its many attributes is to -vary \emph{where} the data point is shown. The data visualization -system uses \emph{axes} to turn data point attributes into positions -on a page. The simplest -- and most common -- use of axes is to vary -the horizontal position of data points according to one attribute and -to vary the vertical position according to another attribute. In -contrast, in a polar plot one attribute dictates the distance of the -data point from the origin and another attribute describes the -angle. From the data visualization engine's point of view, in both -cases two \emph{axes} are involved. - -In addition to specifying how the value of a certain attribute is -converted into a displacement on the page, an axis is also typically -(but not always) visualized (``drawn'') somewhere on the page. In this case, it is -also customary to add a visual representation on this axis of which -attribute values correspond to which positions on the page -- -something commonly known as \emph{ticks}. Similar to ticks, \emph{grid - lines} also indicate positions where a certain attribute has a -certain value, but instead of just indicating a single position on an -axis, a grid line goes through all points that share an attribute -value. - -In the following, in Section~\ref{section-dv-axes-main} we first have -a look at how axes can be defined and configured. As you will see, a -lot of powerful configurations are available, but you will rarely -define and configure an axis from scratch. Rather, it is more common -to use a preconfigured axis -instead. Section~\ref{section-dv-axis-systems} introduces \emph{axis - systems}, which are predefined bundles of axes. You can define your -own axis systems, but, again, in most cases it will suffice to just -use one of the many preconfigured axis systems and use a few options -to configure it so that it fits your -need. Section~\ref{section-dv-ticks-and-grids} explains how ticks and -grid lines can be configured. Again, several layers of -options allow you to configure the way ticks look and where they are -placed in great detail. - -This section documents the standard axis systems that are always -available. For polar axis systems, a special library needs to be -loaded, which is documented in Section~\ref{section-dv-polar}. - +When a data point is visualized, the most obvious way of creating a visual +representation of its many attributes is to vary \emph{where} the data point is +shown. The data visualization system uses \emph{axes} to turn data point +attributes into positions on a page. The simplest -- and most common -- use of +axes is to vary the horizontal position of data points according to one +attribute and to vary the vertical position according to another attribute. In +contrast, in a polar plot one attribute dictates the distance of the data point +from the origin and another attribute describes the angle. From the data +visualization engine's point of view, in both cases two \emph{axes} are +involved. + +In addition to specifying how the value of a certain attribute is converted +into a displacement on the page, an axis is also typically (but not always) +visualized (``drawn'') somewhere on the page. In this case, it is also +customary to add a visual representation on this axis of which attribute values +correspond to which positions on the page -- something commonly known as +\emph{ticks}. Similar to ticks, \emph{grid lines} also indicate positions where +a certain attribute has a certain value, but instead of just indicating a +single position on an axis, a grid line goes through all points that share an +attribute value. + +In the following, in Section~\ref{section-dv-axes-main} we first have a look at +how axes can be defined and configured. As you will see, a lot of powerful +configurations are available, but you will rarely define and configure an axis +from scratch. Rather, it is more common to use a preconfigured axis instead. +Section~\ref{section-dv-axis-systems} introduces \emph{axis systems}, which are +predefined bundles of axes. You can define your own axis systems, but, again, +in most cases it will suffice to just use one of the many preconfigured axis +systems and use a few options to configure it so that it fits your need. +Section~\ref{section-dv-ticks-and-grids} explains how ticks and grid lines can +be configured. Again, several layers of options allow you to configure the way +ticks look and where they are placed in great detail. + +This section documents the standard axis systems that are always available. For +polar axis systems, a special library needs to be loaded, which is documented +in Section~\ref{section-dv-polar}. \subsection{Basic Configuration of Axes} \label{section-dv-axes-main} -Inside the data visualization system, an \emph{axis} is roughly a -``systematic, named way of mapping an attribute to a -position on a page''. For instance, the classical ``$x$-axis'' is the -``systematic way of mapping the value of the |x| attribute of data -points to a horizontal position on the page''. An axis is \emph{not} -its visual representation (such as the horizontal line with the ticks -drawn to represent the $x$-axis), but a visual representation can be +Inside the data visualization system, an \emph{axis} is roughly a ``systematic, +named way of mapping an attribute to a position on a page''. For instance, the +classical ``$x$-axis'' is the ``systematic way of mapping the value of the |x| +attribute of data points to a horizontal position on the page''. An axis is +\emph{not} its visual representation (such as the horizontal line with the +ticks drawn to represent the $x$-axis), but a visual representation can be created once an axis has been defined. -The transformation of an attribute value (such as the value |1000000000| -for the |x| attribute) to a specific displacement of the corresponding -data point on the page involves two steps: +The transformation of an attribute value (such as the value |1000000000| for +the |x| attribute) to a specific displacement of the corresponding data point +on the page involves two steps: +% \begin{enumerate} -\item First, the range of possible values such as $[-5.6\cdot - 10^{12},7.8\cdot 10^{12}]$ must be mapped to a ``reasonable'' - interval such as $[0\mathrm{cm},5\mathrm{cm}]$ or - $[0^\circ,180^\circ]$. \tikzname's drawing routines will only be - able to cope with values from such a ``reasonable'' interval. -\item Second, the values from the reasonable interval must be mapped - to a transformation. + \item First, the range of possible values such as $[-5.6\cdot + 10^{12},7.8\cdot 10^{12}]$ must be mapped to a ``reasonable'' interval + such as $[0\mathrm{cm},5\mathrm{cm}]$ or $[0^\circ,180^\circ]$. + \tikzname's drawing routines will only be able to cope with values from + such a ``reasonable'' interval. + \item Second, the values from the reasonable interval must be mapped to a + transformation. \end{enumerate} -The first step is always the same for all axes, while the second -requires different strategies. For this reason, the command -|new axis base| is used to create a ``basic'' axis that has a -``scaling mapper'', whose job it is to map the range of values of a -specific attribute to a reasonable interval, but such a basic axis -does not define an actual transformation object. For this second step, -additional objects such as a |linear transformer| need to be created -separately. +% +The first step is always the same for all axes, while the second requires +different strategies. For this reason, the command |new axis base| is used to +create a ``basic'' axis that has a ``scaling mapper'', whose job it is to map +the range of values of a specific attribute to a reasonable interval, but such +a basic axis does not define an actual transformation object. For this second +step, additional objects such as a |linear transformer| need to be created +separately. \subsubsection{Usage} -To create an axis, the key |new axis base| is used first. Since this key -does not create a transformation object, users typically do not use -this key directly. Rather, it is used internally by other keys -that create ``real'' axes. These keys are listed in -Section~\ref{section-dv-reference-axis-types}. +To create an axis, the key |new axis base| is used first. Since this key does +not create a transformation object, users typically do not use this key +directly. Rather, it is used internally by other keys that create ``real'' +axes. These keys are listed in Section~\ref{section-dv-reference-axis-types}. \begin{key}{/tikz/data visualization/new axis base=\meta{axis name}} - This key defines a new axis for the current data visualization - called \meta{name}. This has two effects: - \begin{enumerate} - \item A so called \emph{scaling mapper} is created that will monitor - a certain attribute, rescale it, and map it to another - attribute. (This will be explained in detail in a moment.) - \item The \meta{axis name} is made available as a key that can be - used to configure the axis: - \begin{key}{/tikz/data visualization/\meta{axis name}=\meta{options}} - This key becomes available once |new axis base=|meta{axis name} has - been called. It will execute the \meta{options} with the path - prefix |/tikz/data visualization/axis options|. + This key defines a new axis for the current data visualization called + \meta{name}. This has two effects: + % + \begin{enumerate} + \item A so called \emph{scaling mapper} is created that will monitor a + certain attribute, rescale it, and map it to another attribute. + (This will be explained in detail in a moment.) + \item The \meta{axis name} is made available as a key that can be used + to configure the axis: + % + \begin{key}{/tikz/data visualization/\meta{axis name}=\meta{options}} + This key becomes available once |new axis base=|meta{axis name} + has been called. It will execute the \meta{options} with the + path prefix |/tikz/data visualization/axis options|. + % \begin{codeexample}[code only] [new axis base=my axis, my axis={attribute=some attribute}] \end{codeexample} - \end{key} - \item The \meta{axis name} becomes part of the current set of - axes. This set can be accessed through the following key: - \begin{key}{/tikz/data visualization/all axes=\meta{options}} - This key passes the \meta{options} to all axes inside the - current scope, just as if you had written \meta{some axis - name}|=|\meta{options} for each \meta{some axis name} in the - current scope, including the just-created name \meta{axis name}. - \end{key} - \end{enumerate} - There are many \meta{options} that can be passed to a newly created - axis. They are explained in the rest of this section. + \end{key} + \item The \meta{axis name} becomes part of the current set of axes. + This set can be accessed through the following key: + % + \begin{key}{/tikz/data visualization/all axes=\meta{options}} + This key passes the \meta{options} to all axes inside the + current scope, just as if you had written \meta{some axis + name}|=|\meta{options} for each \meta{some axis name} in the + current scope, including the just-created name \meta{axis + name}. + \end{key} + \end{enumerate} + % + There are many \meta{options} that can be passed to a newly created axis. + They are explained in the rest of this section. \end{key} Note the |new axis base| does \emph{not} cause attributes to be mapped to -positions on a page. Rather, special keys like |new Cartesian axis| -first use |new axis base| to create an axis and then create an internal -object that performs a linear mapping of the attribute to -positions along a vectors. +positions on a page. Rather, special keys like |new Cartesian axis| first use +|new axis base| to create an axis and then create an internal object that +performs a linear mapping of the attribute to positions along a vectors. \subsubsection{The Axis Attribute} \label{section-dv-axis-attribute} -The first main job of an axis is to map the different values of some -attribute to a reasonable interval. To achieve this, the following -options are important (recall that these options are passed to the key -whose name is the name of the axis): +The first main job of an axis is to map the different values of some attribute +to a reasonable interval. To achieve this, the following options are important +(recall that these options are passed to the key whose name is the name of the +axis): \begin{key}{/tikz/data visualization/axis options/attribute=\meta{attribute}} - Specifies that the axis is used to transform the data points - according the different values of the key - |/data point/|\meta{attribute}. For instance, when we create a - classical two-dimensional Cartesian coordinate system, then there - are two axes called |x axis| and |y axis| that monitor the values of - the attributes |/data point/x| and |/data point/y|, respectively: + Specifies that the axis is used to transform the data points according the + different values of the key |/data point/|\meta{attribute}. For instance, + when we create a classical two-dimensional Cartesian coordinate system, + then there are two axes called |x axis| and |y axis| that monitor the + values of the attributes |/data point/x| and |/data point/y|, respectively: + % \begin{codeexample}[code only] [new axis base=x axis, new axis base=y axis, x axis={attribute=x}, y axis={attribute=y}] \end{codeexample} - In another example, we also create an |x axis| and a - |y axis|. However, this time, we want to plot the values of the - |/data point/time| attribute on the $x$-axis and, say, the value of - the |height| attribute on the $y$-axis: + % + In another example, we also create an |x axis| and a |y axis|. However, + this time, we want to plot the values of the |/data point/time| attribute + on the $x$-axis and, say, the value of the |height| attribute on the + $y$-axis: + % \begin{codeexample}[code only] [new axis base=x axis, new axis base=y axis, x axis={attribute=time}, y axis={attribute=height}] \end{codeexample} - During the data visualization, the \meta{attribute} will be - ``monitored'' during the survey phase. This means that for each data - point, the current value of |/data point/|\meta{attribute} is - examined and the minimum value of all of these values as well as the - maximum value is recorded internally. Note that this works even when - very large numbers like |100000000000| are involved. - - Here is a real-life example. The |scientific axes| create two axes, - called |x axis| and |y axis|, respectively. + % + During the data visualization, the \meta{attribute} will be ``monitored'' + during the survey phase. This means that for each data point, the current + value of |/data point/|\meta{attribute} is examined and the minimum value + of all of these values as well as the maximum value is recorded internally. + Note that this works even when very large numbers like |100000000000| are + involved. + + Here is a real-life example. The |scientific axes| create two axes, called + |x axis| and |y axis|, respectively. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, x axis={attribute=people, length=2.5cm, ticks=few}, @@ -191,39 +193,41 @@ whose name is the name of the axis): 2000, 150 }; \end{codeexample} + % \end{key} \subsubsection{The Axis Attribute Range Interval} -Once an attribute has been specified for an axis, the data -visualization engine will start monitoring this value. This means that -before anything actual visualization is done, a ``survey phase'' is -used to determine the range of values encountered for the attribute -for all data points. This range of values results in what is called -the \emph{attribute range interval}. Its minimum is the smallest value -encountered in the data and its maximum is the largest value. - -Even though the attribute range interval is computed automatically and -even though you typically do not need to worry about it, there are -some situations where you may wish to set or enlarge the attribute -range interval: +Once an attribute has been specified for an axis, the data visualization engine +will start monitoring this value. This means that before anything actual +visualization is done, a ``survey phase'' is used to determine the range of +values encountered for the attribute for all data points. This range of values +results in what is called the \emph{attribute range interval}. Its minimum is +the smallest value encountered in the data and its maximum is the largest +value. + +Even though the attribute range interval is computed automatically and even +though you typically do not need to worry about it, there are some situations +where you may wish to set or enlarge the attribute range interval: +% \begin{itemize} -\item You may wish to start the interval with $0$, even though the - range of values contains only positive values. -\item You may wish to slightly enlarge the interval so that, say, the - maximum is some ``nice'' value like |100| or |60|. + \item You may wish to start the interval with $0$, even though the range of + values contains only positive values. + \item You may wish to slightly enlarge the interval so that, say, the + maximum is some ``nice'' value like |100| or |60|. \end{itemize} -The following keys can be used to influence the size of the attribute -range interval: -\begin{key}{/tikz/data visualization/axis options/include - value=\meta{list of value}} - This key ``fakes'' data points for which the attribute's values are - in the comma-separated \meta{list of values}. For instance, when you - write |include value=0|, then the attribute range interval is - guaranteed to contain |0| -- even if the actual data points are all - positive or all negative. +The following keys can be used to influence the size of the attribute range +interval: +% +\begin{key}{/tikz/data visualization/axis options/include value=\meta{list of value}} + This key ``fakes'' data points for which the attribute's values are in the + comma-separated \meta{list of values}. For instance, when you write + |include value=0|, then the attribute range interval is guaranteed to + contain |0| -- even if the actual data points are all positive or all + negative. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=3cm}, visualize as line] @@ -231,7 +235,8 @@ range interval: var x : interval [5:10]; func y = \value x * \value x; }; -\end{codeexample} +\end{codeexample} + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=3cm}, visualize as line, @@ -241,44 +246,48 @@ range interval: var x : interval [5:10]; func y = \value x * \value x; }; -\end{codeexample} +\end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/axis options/min value=\meta{value}} - This key allows you to simply set the minimum value, regardless of - which values are present in the actual data. This key should be used - with care: If there are data points for which the attribute's value - is less than \meta{value}, they will still be depicted, but - typically outside the normal visualization area. Usually, saying - |include value=|\meta{value} will achieve the same as saying - |min value=|\meta{value}, but with less danger of creating - ill-formed visualizations. + This key allows you to simply set the minimum value, regardless of which + values are present in the actual data. This key should be used with care: + If there are data points for which the attribute's value is less than + \meta{value}, they will still be depicted, but typically outside the normal + visualization area. Usually, saying |include value=|\meta{value} will + achieve the same as saying |min value=|\meta{value}, but with less danger + of creating ill-formed visualizations. \end{key} \begin{key}{/tikz/data visualization/axis options/max value=\meta{value}} - Works like |min value|. + Works like |min value|. \end{key} \subsubsection{Scaling: The General Mechanism} -The above key allows us specify which attribute should be -``monitored''. The next key is used to specify what should happen with -the observed values. +The above key allows us specify which attribute should be ``monitored''. The +next key is used to specify what should happen with the observed values. \begin{key}{/tikz/data visualization/axis options/scaling=\meta{scaling spec}} - The \meta{scaling spec} must have the following form: - \begin{quote} - \meta{$s_1$}| at |\meta{$t_1$}| and |\meta{$s_2$}| at |\meta{$t_2$} - \end{quote} - This means that monitored values in the interval $[s_1,s_2]$ should - be mapped to values the ``reasonable'' interval $[t_1,t_2]$, - instead. For instance, we might write + The \meta{scaling spec} must have the following form: + % + \begin{quote} + \meta{$s_1$}| at |\meta{$t_1$}| and |\meta{$s_2$}| at |\meta{$t_2$} + \end{quote} + % + This means that monitored values in the interval $[s_1,s_2]$ should be + mapped to values the ``reasonable'' interval $[t_1,t_2]$, instead. For + instance, we might write + % \begin{codeexample}[code only] [y axis = {scaling = 1900 at 0cm and 2000 at 5cm}] \end{codeexample} - in order to map dates between 1900 and 2000 to the dimension - interval $[0\mathrm{cm},5\mathrm{cm}]$. + % + in order to map dates between 1900 and 2000 to the dimension interval + $[0\mathrm{cm},5\mathrm{cm}]$. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -294,115 +303,120 @@ the observed values. 2000, 150 }; \end{codeexample} - So much for the basic idea. Let us now have a detailed look at what - happens. - - \medskip - \textbf{Number format and the min and max keywords.} - The source values $s_1$ and $s_2$ are typically just numbers like - |3.14| or |10000000000|. However, as described in - Section~\ref{section-dv-expressions}, you can also specify - expressions like |(pi/2)|, provided that (currently) you put them in - parentheses. - - Instead of a number, you may alternatively also use the two key - words |min| and |max| for $s_1$ and/or $s_2$. In this case, |min| - evaluates to the smallest value observed for the attribute in the - data, symmetrically |max| evaluates to the largest values. For - instance, in the above example with the |year| attribute ranging - from |1900| to |2000|, the keyword |min| would stand for |1900| and - |max| for |2000|. Similarly, for the |people| attribute |min| stands - for |100| and |max| for |250|. Note that |min| and |max| can only be - used for $s_1$ and $s_2$, not for $t_1$ and $t_2$. - - A typical use of the |min| and |max| keywords is to say + % + So much for the basic idea. Let us now have a detailed look at what + happens. + + + \medskip + \textbf{Number format and the min and max keywords.} + The source values $s_1$ and $s_2$ are typically just numbers like |3.14| or + |10000000000|. However, as described in + Section~\ref{section-dv-expressions}, you can also specify expressions like + |(pi/2)|, provided that (currently) you put them in parentheses. + + Instead of a number, you may alternatively also use the two key words |min| + and |max| for $s_1$ and/or $s_2$. In this case, |min| evaluates to the + smallest value observed for the attribute in the data, symmetrically |max| + evaluates to the largest values. For instance, in the above example with + the |year| attribute ranging from |1900| to |2000|, the keyword |min| would + stand for |1900| and |max| for |2000|. Similarly, for the |people| + attribute |min| stands for |100| and |max| for |250|. Note that |min| and + |max| can only be used for $s_1$ and $s_2$, not for $t_1$ and $t_2$. + + A typical use of the |min| and |max| keywords is to say + % \begin{codeexample}[code only] -scaling = min at 0cm and max at 5cm -\end{codeexample} - to map the complete range of values into an interval of length of - 5cm. - - The interval $[s_1,s_2]$ need not contain all values that the - \meta{attribute} may attain. It is permissible that values are less - than $s_1$ or more than $s_2$. - - \medskip - \textbf{Linear transformation of the attribute.} - As indicated earlier, the main job of an axis is to map values from - a ``large'' interval $[s_1,s_2]$ to a more reasonable interval - $[t_1,t_2]$. Suppose - that for the current data point the value of the key - |/data point/|\meta{attribute} is the number $v$. In the simplest - case, the following happens: A new value $v'$ is computed so that - $v' = t_1$ when $v=s_1$ and $v'=t_2$ when $v=s_2$ and $v'$ is some - value in between $t_1$ and $t_2$ then $v$ is some value in between - $s_1$ and $s_2$. (Formally, in this basic case $v' = t_1 + - (v-s_1)\frac{t_2-t_1}{s_2-s_1}$.) - - Once $v'$ has been computed, it is stored in the key - |/data point/|\meta{attribute}|/scaled|. Thus, the ``reasonable'' - value $v'$ does not replace the value of the attribute, but it is - placed in a different key. This means that both the original value - and the more ``scaled'' values are available when the data point is - visualized. - - As an example, suppose you have written +scaling = min at 0cm and max at 5cm +\end{codeexample} + % + to map the complete range of values into an interval of length of 5cm. + + The interval $[s_1,s_2]$ need not contain all values that the + \meta{attribute} may attain. It is permissible that values are less than + $s_1$ or more than $s_2$. + + + \medskip + \textbf{Linear transformation of the attribute.} + As indicated earlier, the main job of an axis is to map values from a + ``large'' interval $[s_1,s_2]$ to a more reasonable interval $[t_1,t_2]$. + Suppose that for the current data point the value of the key + |/data point/|\meta{attribute} is the number $v$. In the simplest case, the + following happens: A new value $v'$ is computed so that $v' = t_1$ when + $v=s_1$ and $v'=t_2$ when $v=s_2$ and $v'$ is some value in between $t_1$ + and $t_2$ then $v$ is some value in between $s_1$ and $s_2$. (Formally, in + this basic case $v' = t_1 + (v-s_1)\frac{t_2-t_1}{s_2-s_1}$.) + + Once $v'$ has been computed, it is stored in the key + |/data point/|\meta{attribute}|/scaled|. Thus, the ``reasonable'' value + $v'$ does not replace the value of the attribute, but it is placed in a + different key. This means that both the original value and the more + ``scaled'' values are available when the data point is visualized. + + As an example, suppose you have written + % \begin{codeexample}[code only] [x axis = {attribute = x, scaling=1000 at 20 and 2000 at 30}] \end{codeexample} - Now suppose that |/data point/x| equals |1200| for a data - point. Then the key |/data point/x/scaled| will be set to |22| when - the data point is being visualized. - - \medskip - \textbf{Nonlinear transformations of the attribute.} - By default, the transformation of $[s_1,s_2]$ to $[t_1,t_2]$ is the - linear transformation described above. However, in some case you may - be interested in a different kind of transformation: For example, in - a logarithmic plot, values of an attribute may range between, say, - |1| and |1000| and we want an axis of length |3cm|. So, we would - write - \begin{codeexample}[code only] + % + Now suppose that |/data point/x| equals |1200| for a data point. Then the + key |/data point/x/scaled| will be set to |22| when the data point is being + visualized. + + + \medskip + \textbf{Nonlinear transformations of the attribute.} + By default, the transformation of $[s_1,s_2]$ to $[t_1,t_2]$ is the linear + transformation described above. However, in some case you may be interested + in a different kind of transformation: For example, in a logarithmic plot, + values of an attribute may range between, say, |1| and |1000| and we want + an axis of length |3cm|. So, we would write + % +\begin{codeexample}[code only] [x axis = {attribute = x, scaling=1 at 0cm and 1000 at 3cm}] - \end{codeexample} - Indeed, |1| will now be mapped to position |0cm| and |1000| will be - mapped to position |3cm|. Now, the value |10| will be mapped to - approximately |0.03cm| because it is (almost) at one percent between - |1| and |1000|. However, in a logarithmic plot we actually want |10| - to be mapped to the position |1cm| rather than |0.03cm| and we want - |100| to be mapped to the position |2cm|. Such a mapping a - \emph{nonlinear} mapping between the intervals. - - In order to achieve such a nonlinear mapping, the |function| key can - be used, whose syntax is described in a moment. The effect of this key is - to specify a function $f \colon \mathbb R \to \mathbb R$ like, say, - the logarithm function. When such a function is specified, the - mapping of $v$ to $v'$ is computed as follows: - \begin{align*} - v' = t_1 + (f(s_2) - f(v))\frac{t_2 - t_1}{f(s_2)-f(s_1)}. - \end{align*} - - The syntax of the |function| key is described next, but you - typically will not call this key directly. Rather, you will use a - key like |logarithmic| that installs appropriate code for the - |function| key for you. - \begin{key}{/tikz/data visualization/axis options/function=\meta{code}} - The \meta{code} should specify a function $f$ that is applied - during the transformation of the interval $[s_1,s_2]$ to the - interval $[t_1,t_2]$ in the following way: When the \meta{code} is - called, the macro |\pgfvalue| will have been set to an internal - representation of the to-be-transformed value~$v$. You can then - call the commands of the math-micro-kernel of the data - visualization system, see Section~\ref{section-dv-math-kernel}, to - compute a new value. This new value must once more be stored in - |\pgfvalue|. - - The most common use of this key is to say +\end{codeexample} + % + Indeed, |1| will now be mapped to position |0cm| and |1000| will be mapped + to position |3cm|. Now, the value |10| will be mapped to approximately + |0.03cm| because it is (almost) at one percent between |1| and |1000|. + However, in a logarithmic plot we actually want |10| to be mapped to the + position |1cm| rather than |0.03cm| and we want |100| to be mapped to the + position |2cm|. Such a mapping a \emph{nonlinear} mapping between the + intervals. + + In order to achieve such a nonlinear mapping, the |function| key can be + used, whose syntax is described in a moment. The effect of this key is to + specify a function $f \colon \mathbb{R} \to \mathbb{R}$ like, say, the + logarithm function. When such a function is specified, the mapping of $v$ + to $v'$ is computed as follows: + % + \begin{align*} + v' = t_1 + (f(s_2) - f(v))\frac{t_2 - t_1}{f(s_2)-f(s_1)}. + \end{align*} + + The syntax of the |function| key is described next, but you typically will + not call this key directly. Rather, you will use a key like |logarithmic| + that installs appropriate code for the |function| key for you. + % + \begin{key}{/tikz/data visualization/axis options/function=\meta{code}} + The \meta{code} should specify a function $f$ that is applied during + the transformation of the interval $[s_1,s_2]$ to the interval + $[t_1,t_2]$ in the following way: When the \meta{code} is called, the + macro |\pgfvalue| will have been set to an internal representation of + the to-be-transformed value~$v$. You can then call the commands of the + math-micro-kernel of the data visualization system, see + Section~\ref{section-dv-math-kernel}, to compute a new value. This new + value must once more be stored in |\pgfvalue|. + + The most common use of this key is to say + % \begin{codeexample}[code only] -some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}} +some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}} \end{codeexample} - This specifies that the function $f$ is the logarithm - function. + % + This specifies that the function $f$ is the logarithm function. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -414,7 +428,9 @@ some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}} x={1,100,...,1000}, y={1,2,3} }; \end{codeexample} - Another possibility might be to use the square-root function, instead: + % + Another possibility might be to use the square-root function, instead: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -426,49 +442,52 @@ some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}} x={0,100,...,1000}, y={1,2,3} }; \end{codeexample} - \end{key} - - \medskip - \textbf{Default scaling.} - When no scaling is specified, it may seem natural to use $[0,1]$ - both as the source and the target interval. However, this would not - work when the logarithm function is used as transformations: In this - case the logarithm of zero would be computed, leading to an - error. Indeed, for a logarithmic axis it is far more natural to use - $[1,10]$ as the source interval and $[0,1]$ as the target interval. - - For these reasons, the default value for the |scaling| that is used - when no value is specified explicitly can be set using a special - key: - \begin{key}{/tikz/data visualization/axis options/scaling/default=\meta{text}} - The \meta{text} is used as |scaling| whenever no other scaling is - specified. This key is mainly used when a transformation function - is set using |function|; normally, you will not use this key - directly. - \end{key} -\end{key} - -Most of the time, you will not use neither the |scaling| nor the -|function| key directly, but rather you will use one of the following -predefined styles documented in the following. + \end{key} + + + \medskip + \textbf{Default scaling.} + When no scaling is specified, it may seem natural to use $[0,1]$ both as + the source and the target interval. However, this would not work when the + logarithm function is used as transformations: In this case the logarithm + of zero would be computed, leading to an error. Indeed, for a logarithmic + axis it is far more natural to use $[1,10]$ as the source interval and + $[0,1]$ as the target interval. + + For these reasons, the default value for the |scaling| that is used when no + value is specified explicitly can be set using a special key: + % + \begin{key}{/tikz/data visualization/axis options/scaling/default=\meta{text}} + The \meta{text} is used as |scaling| whenever no other scaling is + specified. This key is mainly used when a transformation function is + set using |function|; normally, you will not use this key directly. + \end{key} +\end{key} + +Most of the time, you will not use neither the |scaling| nor the |function| key +directly, but rather you will use one of the following predefined styles +documented in the following. \subsubsection{Scaling: Logarithmic Axes} \begin{key}{/tikz/data visualization/axis options/logarithmic} - When this key is used with an axis, three things happen: - \begin{enumerate} - \item The transformation |function| of the axis is setup to the - logarithm. - \item The strategy for automatically generating ticks and grid lines - is set to the |exponential strategy|, see - Section~\ref{section-dv-exponential-strategy} for details. - \item The default scaling is setup sensibly. - \end{enumerate} - All told, to turn an axis into a logarithmic axis, you just need to - add this option to the axis. + When this key is used with an axis, three things happen: + % + \begin{enumerate} + \item The transformation |function| of the axis is setup to the + logarithm. + \item The strategy for automatically generating ticks and grid lines is + set to the |exponential strategy|, see + Section~\ref{section-dv-exponential-strategy} for details. + \item The default scaling is setup sensibly. + \end{enumerate} + % + All told, to turn an axis into a logarithmic axis, you just need to add + this option to the axis. + % \begin{codeexample}[width=8cm] -\tikz \datavisualization [scientific axes, +\tikz \datavisualization [scientific axes, x axis={logarithmic}, y axis={logarithmic}, visualize as line] @@ -477,39 +496,42 @@ predefined styles documented in the following. func y = \value x * \value x; }; \end{codeexample} - Note that this will work with any axis, - including, say, the degrees on a polar axis: + % + Note that this will work with any axis, including, say, the degrees on a + polar axis: + % \begin{codeexample}[] \tikz \datavisualization - [new polar axes, + [new polar axes, angle axis={logarithmic, scaling=1 at 0 and 90 at 90}, radius axis={scaling=0 at 0cm and 100 at 3cm}, visualize as scatter] data [format=named] { angle={1,10,...,90}, radius={1,10,...,100} }; -\end{codeexample} +\end{codeexample} + % \begin{codeexample}[] \tikz \datavisualization - [new polar axes, + [new polar axes, angle axis={degrees}, radius axis={logarithmic, scaling=1 at 0cm and 100 at 3cm}, visualize as scatter] data [format=named] { angle={1,10,...,90}, radius={1,10,...,100} }; -\end{codeexample} +\end{codeexample} + % \end{key} - \subsubsection{Scaling: Setting the Length or Unit Length} \begin{key}{/tikz/data visualization/axis options/length=\meta{dimension}} - Sets |scaling| to |min at 0cm and max at |\meta{dimension}. The - effect is that the range of all values of the axis's attribute will - be mapped to an interval of exact length \meta{dimension}. - + Sets |scaling| to |min at 0cm and max at |\meta{dimension}. The effect is + that the range of all values of the axis's attribute will be mapped to an + interval of exact length \meta{dimension}. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, x axis={length=3cm}, @@ -524,6 +546,7 @@ predefined styles documented in the following. 13, 20 }; \end{codeexample} + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, x axis={length=3cm}, @@ -538,15 +561,15 @@ predefined styles documented in the following. 13, 20 }; \end{codeexample} - + % \end{key} -\begin{key}{/tikz/data visualization/axis - options/unit length=\meta{dimension}\opt{| per |\meta{number}| units|}} - Sets |scaling| to |0 at 0cm and 1 at |\meta{dimension}. In other - words, this key allows you to specify how long a single unit should - be. This key is particularly useful when you wish to ensure that the - same scaling is used across multiple axes or pictures. +\begin{key}{/tikz/data visualization/axis options/unit length=\meta{dimension}\opt{| per |\meta{number}| units|}} + Sets |scaling| to |0 at 0cm and 1 at |\meta{dimension}. In other words, + this key allows you to specify how long a single unit should be. This key + is particularly useful when you wish to ensure that the same scaling is + used across multiple axes or pictures. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={ticks=few, unit length=1mm}, @@ -559,12 +582,13 @@ predefined styles documented in the following. 13, 20 }; \end{codeexample} - The optional |per |\meta{number}| units| allows you to apply more - drastic scaling. Suppose that you want to plot a graph where one - billion corresponds to one centimeter. Then the unit length would be - need to be set to a hundredth of a nanometer -- much too small for - \TeX\ to handle as a dimension. In this case, you can write - |unit length=1cm per 1000000000 units|: + The optional |per |\meta{number}| units| allows you to apply more drastic + scaling. Suppose that you want to plot a graph where one billion + corresponds to one centimeter. Then the unit length would be need to be set + to a hundredth of a nanometer -- much too small for \TeX\ to handle as a + dimension. In this case, you can write + |unit length=1cm per 1000000000 units|: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -578,18 +602,19 @@ predefined styles documented in the following. 13000000000, 20 }; \end{codeexample} + % \end{key} -\begin{key}{/tikz/data visualization/axis - options/power unit length=\meta{dimension}} - This key is used in conjunction with the |logarithmic| setting. It - cases the |scaling| to be set to - |1 at 0cm and 10 at |\meta{dimension}. This causes a ``power unit,'' - that is, one power of ten in a logarithmic plot, to get a length of - \meta{dimension}. Again, this key is useful for ensuring that the - same scaling is used across multiple axes or pictures. +% +\begin{key}{/tikz/data visualization/axis options/power unit length=\meta{dimension}} + This key is used in conjunction with the |logarithmic| setting. It cases + the |scaling| to be set to |1 at 0cm and 10 at |\meta{dimension}. This + causes a ``power unit'', that is, one power of ten in a logarithmic plot, + to get a length of \meta{dimension}. Again, this key is useful for ensuring + that the same scaling is used across multiple axes or pictures. + % \begin{codeexample}[width=8cm] \tikz \datavisualization - [scientific axes, + [scientific axes, y axis={logarithmic, power unit length=1mm, grid}, visualize as line] data { @@ -603,25 +628,26 @@ predefined styles documented in the following. 6, 5000000000000000000 }; \end{codeexample} + % \end{key} - \subsubsection{Axis Label} -An axis can have a \emph{label}, which is a textual representation of -the attribute according to which the axis varies the position of the -page. You can set the attribute using the following key: - -\begin{key}{/tikz/data visualization/axis - options/label=\opt{|\char`\{[|\meta{options}|]|}\meta{text}\opt{|\char`\}|} - (default \normalfont axis's label in math mode)} - This key sets the label of an axis to \meta{text}. This text will - typically be placed inside a |node| and the \meta{options} can be - used to further configure the way this node is rendered. The - \meta{options} will be executed with the path prefix - |/tikz/data visualization/|, so you need to say |node style| to - configure the styling of a node, see Section~\ref{section-dv-style}. +An axis can have a \emph{label}, which is a textual representation of the +attribute according to which the axis varies the position of the page. You can +set the attribute using the following key: + +\begin{key}{/tikz/data visualization/axis options/label=\opt{|\char`\{[|\meta{options}|]|}\meta{text}\opt{|\char`\}|} + (default \normalfont axis's label in math mode)% +} + This key sets the label of an axis to \meta{text}. This text will typically + be placed inside a |node| and the \meta{options} can be used to further + configure the way this node is rendered. The \meta{options} will be + executed with the path prefix |/tikz/data visualization/|, so you need to + say |node style| to configure the styling of a node, see + Section~\ref{section-dv-style}. + % \begin{codeexample}[] \tikz \datavisualization [ scientific axes, @@ -632,55 +658,52 @@ page. You can set the attribute using the following key: var x : interval [-3:5]; func y = \value x * \value x; }; -\end{codeexample} +\end{codeexample} + % \end{key} -Note that using the |label| key does not actually cause a node to be -created, because it is somewhat unclear where the label should be -placed. Instead, the |visualize label| key is used (typically -internally by an axis system) to show the label at some sensible -position. This key is documented in -Section~\ref{section-dv-visualize-label}. - +Note that using the |label| key does not actually cause a node to be created, +because it is somewhat unclear where the label should be placed. Instead, the +|visualize label| key is used (typically internally by an axis system) to show +the label at some sensible position. This key is documented in +Section~\ref{section-dv-visualize-label}. \subsubsection{Reference: Axis Types} - \label{section-dv-reference-axis-types} -As explained earlier, when you use |new axis base| to create a new axis, -a powerful scaling and attribute mapping mechanism is installed, but -no mapping of values to positions on the page is performed. For this, -a \emph{transformation object} must be installed. The following keys -take care of this for you. Note, however, that even these keys do not -cause a visual representation of the axis to be added to the -visualization -- this is the job of an axis system, see -Section~\ref{section-dv-axis-systems}. +As explained earlier, when you use |new axis base| to create a new axis, a +powerful scaling and attribute mapping mechanism is installed, but no mapping +of values to positions on the page is performed. For this, a +\emph{transformation object} must be installed. The following keys take care of +this for you. Note, however, that even these keys do not cause a visual +representation of the axis to be added to the visualization -- this is the job +of an axis system, see Section~\ref{section-dv-axis-systems}. \begin{key}{/tikz/data visualization/new Cartesian axis=\meta{name}} - This key creates a new ``Cartesian'' axis, named \meta{name}. For - such an axis, the (scaled) values of the axis's attribute are - transformed into a displacement on the page along a straight - line. The following key is used to configure in which ``direction'' - the axis points: - \begin{key}{/tikz/data visualization/axis options/unit - vector=\meta{coordinate} (initially {(1pt,0pt)})} - Recall that an axis takes the values of an attribute and rescales - them so that they fit into a ``reasonable'' interval - $[t_1,t_2]$. Suppose that $v'$ is the rescaled dimension in (\TeX) - points. Then when the data point is visualized, the coordinate - system will be shifted by $v'$ times the \meta{coordinate}. - - As an example, suppose that you have said - |scaling=0 and 10pt and 50 and 20pt|. Then when the underlying - attribute has the value |25|, it will be mapped to a $v'$ of $15$ - (because |25| lies in the middle of |0| and |50| and |15pt| lies - in the middle of |10pt| and |20pt|). This, in turn, causes the - data point to be displaced by $15$ times the \meta{coordinate}. - - The bottom line is that the \meta{coordinate} should usually - denote a point that is at distance |1pt| from the origin and that - points into the direction of the axis. + This key creates a new ``Cartesian'' axis, named \meta{name}. For such an + axis, the (scaled) values of the axis's attribute are transformed into a + displacement on the page along a straight line. The following key is used + to configure in which ``direction'' the axis points: + % + \begin{key}{/tikz/data visualization/axis options/unit vector=\meta{coordinate} (initially {(1pt,0pt)})} + Recall that an axis takes the values of an attribute and rescales them + so that they fit into a ``reasonable'' interval $[t_1,t_2]$. Suppose + that $v'$ is the rescaled dimension in (\TeX) points. Then when the + data point is visualized, the coordinate system will be shifted by $v'$ + times the \meta{coordinate}. + + As an example, suppose that you have said + |scaling=0 and 10pt and 50 and 20pt|. Then when the underlying + attribute has the value |25|, it will be mapped to a $v'$ of $15$ + (because |25| lies in the middle of |0| and |50| and |15pt| lies in the + middle of |10pt| and |20pt|). This, in turn, causes the data point to + be displaced by $15$ times the \meta{coordinate}. + + The bottom line is that the \meta{coordinate} should usually denote a + point that is at distance |1pt| from the origin and that points into + the direction of the axis. + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); @@ -703,71 +726,72 @@ Section~\ref{section-dv-axis-systems}. }; \end{tikzpicture} \end{codeexample} -\end{key} + \end{key} \end{key} - \subsection{Axis Systems} \label{section-dv-axis-systems} +An \emph{axis system} is, as the name suggests, a whole family of axes that act +in concert. For example, in the ``standard'' axis system there is a horizontal +axis called the $x$-axis that monitors the |x| attribute (by default, you can +change this easily) and a vertical axis called the $y$-axis. Furthermore, a +certain number of ticks are added and labels are placed at sensible positions. -An \emph{axis system} is, as the name suggests, a whole family of axes -that act in concert. For example, in the ``standard'' axis system there -is a horizontal axis called the $x$-axis that monitors the |x| -attribute (by default, you can change this easily) and a vertical axis -called the $y$-axis. Furthermore, a certain number of ticks are added -and labels are placed at sensible positions. \subsubsection{Usage} -Using an axis system is usually pretty easy: You just specify a key -like |scientific axes| and the necessary axes get initialized with -sensible default values. You can then start to modify these default -values, if necessary. +Using an axis system is usually pretty easy: You just specify a key like +|scientific axes| and the necessary axes get initialized with sensible default +values. You can then start to modify these default values, if necessary. -First, you can (and should) set the attributes to which the difference -axes refer. For instance, if the |time| attribute is plotted along the -$x$-axis, you would write +First, you can (and should) set the attributes to which the difference axes +refer. For instance, if the |time| attribute is plotted along the $x$-axis, you +would write +% \begin{codeexample}[code only] x axis = {attribute = time} \end{codeexample} -Second, you may wish to modify the lengths of the axes. For this, you -can use keys like |length| or further keys as described in the -references later on. +Second, you may wish to modify the lengths of the axes. For this, you can use +keys like |length| or further keys as described in the references later on. -Third, you may often wish to modify how many ticks and grid lines are -shown. By default, no grid lines are shown, but you can say the -following in order to cause grid lines to be shown: +Third, you may often wish to modify how many ticks and grid lines are shown. By +default, no grid lines are shown, but you can say the following in order to +cause grid lines to be shown: +% \begin{codeexample}[code only] all axes={grid} \end{codeexample} -Naturally, instead of |all axes| you can also specify a single axis, -causing only grid lines to be shown for this axis. -In order to change the number of ticks that are shown, you can say +% +Naturally, instead of |all axes| you can also specify a single axis, causing +only grid lines to be shown for this axis. In order to change the number of +ticks that are shown, you can say +% \begin{codeexample}[code only] -all axes={ticks=few} +all axes={ticks=few} \end{codeexample} -or also |many| instead of |few| or even |none|. Far more fine-grained -control over the tick placement and rendering is possible, -see Section~\ref{section-dv-ticks-and-grids} for details. +% +or also |many| instead of |few| or even |none|. Far more fine-grained control +over the tick placement and rendering is possible, see +Section~\ref{section-dv-ticks-and-grids} for details. Fourth, consider adding units (like ``cm'' for centimeters or -``$\mathrm m/\mathrm s^2$'' for acceleration) to your ticks: +``$\mathrm{m}/\mathrm{s}^2$'' for acceleration) to your ticks: +% \begin{codeexample}[code only] -x axis={ticks={tick unit=cm}}, y axis={ticks={tick unit=m/s^2}} +x axis={ticks={tick unit=cm}}, y axis={ticks={tick unit=m/s^2}} \end{codeexample} - -Finally, consider adding labels to your axes. For this, use the label -option: +Finally, consider adding labels to your axes. For this, use the label option: +% \begin{codeexample}[code only] -x axes={time $t$ (ms)}, y axis={distance $d$ (mm)} +x axes={time $t$ (ms)}, y axis={distance $d$ (mm)} \end{codeexample} Here is an example that employs most of the above features: - +% \begin{codeexample}[width=8.5cm] \tikz \datavisualization [ scientific axes=clean, @@ -790,13 +814,12 @@ data { \end{codeexample} - \subsubsection{Reference: Scientific Axis Systems} \begin{key}{/tikz/data visualization/scientific axes=\opt{\meta{options}}} - This key installs a two-dimensional coordinate system based on the - attributes |/data point/x| and |/data point/y|. - + This key installs a two-dimensional coordinate system based on the + attributes |/data point/x| and |/data point/y|. + % \begin{codeexample}[width=7cm] \begin{tikzpicture} \datavisualization [scientific axes, @@ -808,24 +831,25 @@ data { \end{tikzpicture} \end{codeexample} - This axis system is usually a good choice to depict ``arbitrary two - dimensional data.'' Because the axes are automatically scaled, you - do not need to worry about how large or small the values will - be. The name |scientific axes| is intended to indicate that this - axis system is often used in scientific publications. + This axis system is usually a good choice to depict ``arbitrary two + dimensional data''. Because the axes are automatically scaled, you do not + need to worry about how large or small the values will be. The name + |scientific axes| is intended to indicate that this axis system is often + used in scientific publications. - You can use the \meta{options} to fine tune the axis system. The - \meta{options} will be executed with the following path prefix: + You can use the \meta{options} to fine tune the axis system. The + \meta{options} will be executed with the following path prefix: + % \begin{codeexample}[code only] -/tikz/data visualization/scientific axes +/tikz/data visualization/scientific axes \end{codeexample} - All keys with this prefix can thus be passed as \meta{options}. - - This axis system will always distort the - relative magnitudes of the units on the two axis. If you wish the - units on both axes to be equal, consider directly specifying the - unit length ``by hand'': + % + All keys with this prefix can thus be passed as \meta{options}. + This axis system will always distort the relative magnitudes of the units + on the two axis. If you wish the units on both axes to be equal, consider + directly specifying the unit length ``by hand'': + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization [visualize as smooth line, @@ -838,44 +862,46 @@ data { \end{tikzpicture} \end{codeexample} - The |scientific axes| have the following properties: - \begin{itemize} - \item The |x|-values are surveyed and the $x$-axis is then scaled - and shifted so that it has the length specified by the following key. - \begin{key}{/tikz/data visualization/scientific - axes/width=\meta{dimension} (initially 5cm)} - \end{key} - The minimum value is at the left end of the axis and at the canvas - origin. The maximum value is at the right end of the axis. - \item The |y|-values are surveyed and the $y$-axis is then scaled so - that is has the length specified by the following key. - \begin{key}{/tikz/data visualization/scientific - axes/height=\meta{dimension}} - By default, the |height| is the golden ratio times the |width|. - \end{key} - The minimum value is at the bottom of the axis and at the canvas - origin. The maximum value is at the top of the axis. - \item Lines (forming a frame) are depicted at the minimum and - maximum values of the axes in 50\% black. - \end{itemize} + The |scientific axes| have the following properties: + % + \begin{itemize} + \item The |x|-values are surveyed and the $x$-axis is then scaled and + shifted so that it has the length specified by the following key. + % + \begin{key}{/tikz/data visualization/scientific axes/width=\meta{dimension} (initially 5cm)} + \end{key} + % + The minimum value is at the left end of the axis and at the canvas + origin. The maximum value is at the right end of the axis. \item + The |y|-values are surveyed and the $y$-axis is then scaled so that + is has the length specified by the following key. + % + \begin{key}{/tikz/data visualization/scientific axes/height=\meta{dimension}} + By default, the |height| is the golden ratio times the |width|. + \end{key} + % + The minimum value is at the bottom of the axis and at the canvas + origin. The maximum value is at the top of the axis. + \item Lines (forming a frame) are depicted at the minimum and maximum + values of the axes in 50\% black. + \end{itemize} - The following keys are executed by default as options: |outer ticks| - and |standard labels|. + The following keys are executed by default as options: |outer ticks| and + |standard labels|. - You can use the following style to overrule the defaults: + You can use the following style to overrule the defaults: - \begin{stylekey}{/tikz/data visualization/every scientific axes} - \end{stylekey} + \begin{stylekey}{/tikz/data visualization/every scientific axes} + \end{stylekey} \end{key} -The keys described in the following can be used to fine-tune the way -the scientific axis system is rendered. +The keys described in the following can be used to fine-tune the way the +scientific axis system is rendered. \begin{key}{/tikz/data visualization/scientific axes/outer ticks} - This causes the ticks to be drawn `` on the outside'' of the frame - so that they interfere as little as possible with the data. It is - the default. - + This causes the ticks to be drawn `` on the outside'' of the frame so that + they interfere as little as possible with the data. It is the default. + % \begin{codeexample}[width=7cm] \begin{tikzpicture} \datavisualization [scientific axes=outer ticks, @@ -886,12 +912,13 @@ the scientific axis system is rendered. }; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/scientific axes/inner ticks} - This axis system works like |scientific axes|, only the ticks are on - the ``inside'' of the frame. - + This axis system works like |scientific axes|, only the ticks are on the + ``inside'' of the frame. + % \begin{codeexample}[width=7cm] \begin{tikzpicture} \datavisualization [scientific axes=inner ticks, @@ -903,9 +930,10 @@ the scientific axis system is rendered. \end{tikzpicture} \end{codeexample} - This axis system is also common in publications, but the ticks tend - to interfere with marks if they are near to the border as can be - seen in the following example: + This axis system is also common in publications, but the ticks tend to + interfere with marks if they are near to the border as can be seen in the + following example: + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization [scientific axes={inner ticks, width=3.2cm}, @@ -927,14 +955,14 @@ the scientific axis system is rendered. }; \end{tikzpicture} \end{codeexample} - + % \end{key} \begin{key}{/tikz/data visualization/scientific axes/clean} - The axes and the ticks are completely removed from the actual data, - making this axis system especially useful for scatter plots, but - also for most other scientific plots. - + The axes and the ticks are completely removed from the actual data, making + this axis system especially useful for scatter plots, but also for most + other scientific plots. + % \begin{codeexample}[width=7.5cm] \tikz \datavisualization [ scientific axes=clean, @@ -945,19 +973,19 @@ data [format=function] { }; \end{codeexample} - The distance of the axes from the actual plot is given by the - padding of the axes. + The distance of the axes from the actual plot is given by the padding of + the axes. \end{key} - -For all scientific axis systems, different label placement strategies -can be specified. They are discussed in the following. +For all scientific axis systems, different label placement strategies can be +specified. They are discussed in the following. \begin{key}{/tikz/data visualization/scientific axes/standard labels} - As the name suggests, this is the standard placement strategy. The - label of the $x$-axis is placed below the center of the $x$-axis, - the label of the $y$-axis is rotated by $90^\circ$ and placed left - of the center of the $y$-axis. + As the name suggests, this is the standard placement strategy. The label of + the $x$-axis is placed below the center of the $x$-axis, the label of the + $y$-axis is rotated by $90^\circ$ and placed left of the center of the + $y$-axis. + % \begin{codeexample}[width=8cm] \tikz \datavisualization [scientific axes={clean, standard labels}, @@ -970,11 +998,13 @@ data [format=function] { func y = sin(\value x); }; \end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/scientific axes/upright labels} - Works like |scientific axes standard labels|, only the label of the - $y$-axis is not rotated. + Works like |scientific axes standard labels|, only the label of the + $y$-axis is not rotated. + % \begin{codeexample}[width=8cm] \tikz \datavisualization [ scientific axes={clean, upright labels}, @@ -990,12 +1020,13 @@ data [format=function] { func y = cos(\value x); }; \end{codeexample} + % \end{key} - \begin{key}{/tikz/data visualization/scientific axes/end labels} - Places the labels at the end of the $x$- and the $y$-axis, similar - to the axis labels of a school book axis system. + Places the labels at the end of the $x$- and the $y$-axis, similar to the + axis labels of a school book axis system. + % \begin{codeexample}[width=8cm] \tikz \datavisualization [ scientific axes={clean, end labels}, @@ -1008,28 +1039,26 @@ data [format=function] { func y = tan(\value x); }; \end{codeexample} + % \end{key} - \subsubsection{Reference: School Book Axis Systems} \begin{key}{/tikz/data visualization/school book axes=\meta{options}} - This axis system is intended to ``look like'' the coordinate systems - often used in school books: The axes are drawn in such a way that - they intersect to origin. Furthermore, no automatic - scaling is done to ensure that the lengths of units are the same in - all directions. - - This axis system must be used with care -- it is nearly always - necessary to specify the desired unit length by hand using the - option |unit length|. If the magnitudes of the units on the two axes - differ, different unit lengths typically need to be specified for - the different axes. - - Finally, if the data is ``far removed'' from the origin, this - axis system will also ``look bad.'' - + This axis system is intended to ``look like'' the coordinate systems often + used in school books: The axes are drawn in such a way that they intersect + to origin. Furthermore, no automatic scaling is done to ensure that the + lengths of units are the same in all directions. + + This axis system must be used with care -- it is nearly always necessary to + specify the desired unit length by hand using the option |unit length|. If + the magnitudes of the units on the two axes differ, different unit lengths + typically need to be specified for the different axes. + + Finally, if the data is ``far removed'' from the origin, this axis system + will also ``look bad''. + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization [school book axes, visualize as smooth line] @@ -1040,15 +1069,17 @@ data [format=function] { \end{tikzpicture} \end{codeexample} - The stepping of the ticks is one unit by default. Using keys like - |ticks=some| may help to give better steppings. - - The \meta{options} are executed with the key itself as path - prefix. Thus, the following subkeys are permissible options: - \begin{key}{/tikz/data visualization/school book axes/unit=\meta{value}} - Sets the scaling so that 1\,cm corresponds to \meta{value} - units. At the same time, the stepping of the ticks will also be - set to \meta{value}. + The stepping of the ticks is one unit by default. Using keys like + |ticks=some| may help to give better steppings. + + The \meta{options} are executed with the key itself as path prefix. Thus, + the following subkeys are permissible options: + % + \begin{key}{/tikz/data visualization/school book axes/unit=\meta{value}} + Sets the scaling so that 1\,cm corresponds to \meta{value} units. At + the same time, the stepping of the ticks will also be set to + \meta{value}. + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization [school book axes={unit=10}, @@ -1062,15 +1093,16 @@ data [format=function] { }; \end{tikzpicture} \end{codeexample} - \end{key} + \end{key} - \begin{key}{/tikz/data visualization/school book axes/standard labels} - This key makes the label of the $x$-axis appear at the right end of - this axis and it makes the label of the $y$-axis appear at the top - of the $y$-axis. + \begin{key}{/tikz/data visualization/school book axes/standard labels} + This key makes the label of the $x$-axis appear at the right end of + this axis and it makes the label of the $y$-axis appear at the top of + the $y$-axis. - Currently, this is the only supported placement strategy for the - school book axis system. + Currently, this is the only supported placement strategy for the school + book axis system. + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization [school book axes={standard labels}, @@ -1084,29 +1116,25 @@ data [format=function] { }; \end{tikzpicture} \end{codeexample} - \end{key} + \end{key} \end{key} - \subsubsection{Advanced Reference: Underlying Cartesian Axis Systems} -The axis systems described in the following are typically not used -directly by the user. The systems setup \emph{directions} for several -axes in some sensible way, but they do not actually draw anything on -these axes. For instance, the |xy Cartesian| creates two axes called -|x axis| and |y axis| and makes the $x$-axis point right and the -$y$-axis point up. In contrast, an axis system like |scientific axes| -uses the axis system |xy Cartesian| internally and then proceeds to -setup a lot of keys so that the axis lines are drawn, -ticks and grid lines are drawn, and labels are placed at the correct -positions. +The axis systems described in the following are typically not used directly by +the user. The systems setup \emph{directions} for several axes in some sensible +way, but they do not actually draw anything on these axes. For instance, the +|xy Cartesian| creates two axes called |x axis| and |y axis| and makes the +$x$-axis point right and the $y$-axis point up. In contrast, an axis system +like |scientific axes| uses the axis system |xy Cartesian| internally and then +proceeds to setup a lot of keys so that the axis lines are drawn, ticks and +grid lines are drawn, and labels are placed at the correct positions. \begin{key}{/tikz/data visualization/xy Cartesian} - This axis system creates two axes called |x axis| and |y axis| that - point right and up, respectively. By default, one unit is mapped to - one cm. - + This axis system creates two axes called |x axis| and |y axis| that point + right and up, respectively. By default, one unit is mapped to one cm. + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization [xy Cartesian, visualize as smooth line] @@ -1117,122 +1145,112 @@ positions. \end{tikzpicture} \end{codeexample} - - \begin{key}{/tikz/data visualization/xy axes=\meta{options}} - This key applies the \meta{options} both to the |x axis| and the - |y axis|. - \end{key} - + \begin{key}{/tikz/data visualization/xy axes=\meta{options}} + This key applies the \meta{options} both to the |x axis| and the + |y axis|. + \end{key} \end{key} - \begin{key}{/tikz/data visualization/xyz Cartesian cabinet} - This axis system works like |xy Cartesian|, only it - \emph{additionally} creates an axis called |z axis| that points left - and down. For this axis, one unit corresponds to $\frac{1}{2}\sin - 45^\circ\mathrm{cm}$. This is also known as a cabinet projection. - - \begin{key}{/tikz/data visualization/xyz axes=\meta{options}} - This key applies the \meta{options} both to the |x axis| and the - |y axis|. - \end{key} - + This axis system works like |xy Cartesian|, only it \emph{additionally} + creates an axis called |z axis| that points left and down. For this axis, + one unit corresponds to $\frac{1}{2}\sin 45^\circ\mathrm{cm}$. This is also + known as a cabinet projection. + + \begin{key}{/tikz/data visualization/xyz axes=\meta{options}} + This key applies the \meta{options} both to the |x axis| and the + |y axis|. + \end{key} \end{key} - \begin{key}{/tikz/data visualization/uv Cartesian} - This axis system works like |xy Cartesian|, but it introduces two - axes called |u axis| and |v axis| rather than the |x axis| and the - |y axis|. The idea is that in addition to a ``major'' - $xy$-coordinate system this is also a ``smaller'' or ``minor'' - coordinate system in use for depicting, say, small vectors with - respect to this second coordinate system. - - \begin{key}{/tikz/data visualization/uv axes=\meta{options}} - Applies the \meta{options} to both the |u axis| and the |y axis|. - \end{key} - + This axis system works like |xy Cartesian|, but it introduces two axes + called |u axis| and |v axis| rather than the |x axis| and the |y axis|. The + idea is that in addition to a ``major'' $xy$-coordinate system this is also + a ``smaller'' or ``minor'' coordinate system in use for depicting, say, + small vectors with respect to this second coordinate system. + + \begin{key}{/tikz/data visualization/uv axes=\meta{options}} + Applies the \meta{options} to both the |u axis| and the |y axis|. + \end{key} \end{key} \begin{key}{/tikz/data visualization/uvw Cartesian cabinet} - Like |xyz Cartesian cabinet|, but for the $uvw$-system. + Like |xyz Cartesian cabinet|, but for the $uvw$-system. - \begin{key}{/tikz/data visualization/uvw axes=\meta{options}} - Like |xyz axes|. - \end{key} + \begin{key}{/tikz/data visualization/uvw axes=\meta{options}} + Like |xyz axes|. + \end{key} \end{key} - \subsection{Ticks and Grids} \label{section-dv-ticks-and-grids} - \subsubsection{Concepts} -A \emph{tick} is a small visual indication on an axis of the value of -the axis's attribute at the position where the tick is shown. A tick -may be accompanied additionally by a textual representation, but it -need not. A \emph{grid line} is similar to a tick, but it is not an -indication on the axis, but rather a whole line that indicates all -positions where the attribute has a certain value. Unlike ticks, -grid lines (currently) are not accompanied by a textual -representation. - -Just as for axes, the data visualization system decouples the -specification of which ticks are present \emph{in principle} from -where they are visualized. In the following, I describe how you -specify which ticks and grid lines you would like to be drawn and how -they should look like (their styling). The axis system of your choice -will then visualize the ticks at a sensible position for the chosen -system. For details on how to change where whole axis is shown along -with its ticks, see Section~\ref{section-dv-visualize-ticks}. - -Specifying which ticks you are interested in is done as follows: -First, you use |ticks| key (or, for specifying which grid lines should -be present, the |grid| key). This key takes several possible options, -described in detail in the following, which have different effects: +A \emph{tick} is a small visual indication on an axis of the value of the +axis's attribute at the position where the tick is shown. A tick may be +accompanied additionally by a textual representation, but it need not. A +\emph{grid line} is similar to a tick, but it is not an indication on the axis, +but rather a whole line that indicates all positions where the attribute has a +certain value. Unlike ticks, grid lines (currently) are not accompanied by a +textual representation. + +Just as for axes, the data visualization system decouples the specification of +which ticks are present \emph{in principle} from where they are visualized. In +the following, I describe how you specify which ticks and grid lines you would +like to be drawn and how they should look like (their styling). The axis system +of your choice will then visualize the ticks at a sensible position for the +chosen system. For details on how to change where whole axis is shown along +with its ticks, see Section~\ref{section-dv-visualize-ticks}. + +Specifying which ticks you are interested in is done as follows: First, you use +|ticks| key (or, for specifying which grid lines should be present, the |grid| +key). This key takes several possible options, described in detail in the +following, which have different effects: +% \begin{enumerate} -\item Keys like |step=10| or |minor steps between steps| cause a - ``semi-automatic'' computation of possible steps. Here, you - explicitly specify the stepping of steps, but the first stepping and - their number are computed automatically according to the range of - possible values for the attribute. -\item Keys like |few|, |some|, or |many| can be passed to |ticks| in - order to have \tikzname\ compute good tick positions - automatically. This is usually what you want to happen, which is why - most axis system will implicitly say |ticks={some}|. -\item Keys like |at| or |also at| provide ``absolute control'' over - which ticks or grid lines are shown. For these keys, you can not only - specify at what value a tick should be shown, but also its styling - and also whether it is a major, minor, or subminor tick or grid line. + \item Keys like |step=10| or |minor steps between steps| cause a + ``semi-automatic'' computation of possible steps. Here, you explicitly + specify the stepping of steps, but the first stepping and their number + are computed automatically according to the range of possible values + for the attribute. + \item Keys like |few|, |some|, or |many| can be passed to |ticks| in order + to have \tikzname\ compute good tick positions automatically. This is + usually what you want to happen, which is why most axis system will + implicitly say |ticks={some}|. + \item Keys like |at| or |also at| provide ``absolute control'' over which + ticks or grid lines are shown. For these keys, you can not only specify + at what value a tick should be shown, but also its styling and also + whether it is a major, minor, or subminor tick or grid line. \end{enumerate} -In the following, the main keys |ticks| and |grids| are documented -first. Then the different kinds of ways of specifying where ticks or -grid lines should be shown are explained. +In the following, the main keys |ticks| and |grids| are documented first. Then +the different kinds of ways of specifying where ticks or grid lines should be +shown are explained. \subsubsection{The Main Options: Tick and Grid} -\begin{key}{/tikz/data visualization/axis options/ticks=\meta{options} - (default some)} - This key can be passed to an axis in order to configure which ticks - are present for the axis. The possible \meta{options} include, for - instance, keys like |step|, which is used to specify a stepping for - the ticks, but also keys like |major| or |minor| for specifying the - positions of major and minor ticks in detail. The list of possible - options is described in the rest of this section. - - Note that the |ticks| option will only configure which ticks should - be shown in principle. The actual rendering is done only when the - |visualize ticks| key is used, documented in - Section~\ref{section-dv-visualize-ticks}, which is typically done - only internally by an axis system. - - The \meta{options} will be executed with the path prefix - |/tikz/data visualization/|. When the |ticks| key is used multiple - times for an axis, the \meta{options} accumulate. +\begin{key}{/tikz/data visualization/axis options/ticks=\meta{options} (default some)} + This key can be passed to an axis in order to configure which ticks are + present for the axis. The possible \meta{options} include, for instance, + keys like |step|, which is used to specify a stepping for the ticks, but + also keys like |major| or |minor| for specifying the positions of major and + minor ticks in detail. The list of possible options is described in the + rest of this section. + + Note that the |ticks| option will only configure which ticks should be + shown in principle. The actual rendering is done only when the + |visualize ticks| key is used, documented in + Section~\ref{section-dv-visualize-ticks}, which is typically done only + internally by an axis system. + + The \meta{options} will be executed with the path prefix + |/tikz/data visualization/|. When the |ticks| key is used multiple times + for an axis, the \meta{options} accumulate. + % \begin{codeexample}[width=6cm] \tikz \datavisualization [ scientific axes, visualize as line, @@ -1251,29 +1269,29 @@ grid lines should be shown are explained. 80, 0.47 }; \end{codeexample} + % \end{key} -\begin{key}{/tikz/data visualization/axis options/grid=\meta{options} - (default at default ticks)} - This key is similar to |ticks|, only it is used to configure where - grid lines should be shown rather than ticks. In particular, the - options that can be passed to the |ticks| key can also be passed to - the |grid| key. Just like |ticks|, the \meta{options} only specify - which grid lines should be drawn in principle; it is the job of the - |visualize grid| key to actually cause any grid lines to be shown. +\begin{key}{/tikz/data visualization/axis options/grid=\meta{options} (default at default ticks)} + This key is similar to |ticks|, only it is used to configure where grid + lines should be shown rather than ticks. In particular, the options that + can be passed to the |ticks| key can also be passed to the |grid| key. Just + like |ticks|, the \meta{options} only specify which grid lines should be + drawn in principle; it is the job of the |visualize grid| key to actually + cause any grid lines to be shown. - If you do not specify any \meta{options}, the default text - |at default ticks| is used. This option causes grid lines to be - drawn at all positions where ticks are shown by default. Since this - usually exactly what you would like to happen, most of the time you - just need to |all axes=grid| to cause a grid to be shown. + If you do not specify any \meta{options}, the default text + |at default ticks| is used. This option causes grid lines to be drawn at + all positions where ticks are shown by default. Since this usually exactly + what you would like to happen, most of the time you just need to + |all axes=grid| to cause a grid to be shown. \end{key} \begin{key}{/tikz/data visualization/axis options/ticks and grid=\meta{options}} - This key passes the \meta{options} to both the |ticks| key and also - to the |grid| key. This is useful when you want to specify some - special points explicitly where you wish a tick to be shown and also - a grid line. + This key passes the \meta{options} to both the |ticks| key and also to the + |grid| key. This is useful when you want to specify some special points + explicitly where you wish a tick to be shown and also a grid line. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -1286,44 +1304,42 @@ grid lines should be shown are explained. func y = sin(\value x r); }; \end{codeexample} + % \end{key} \subsubsection{Semi-Automatic Computation of Tick and Grid Line Positions} \label{section-dv-concept-tick-placement-strategies} -Consider the following problem: The data visualization engine -determines that in a plot the $x$-values vary between $17.4$ and -$34.5$. In this case, we -certainly do not want, say, ten ticks at exactly ten evenly spaced -positions starting with $17.4$ and ending with $34.5$, because this -would yield ticks at positions like $32.6$. Ticks should be placed at -``nice'' positions like $20$, $25$, and $30$. - -Determining which positions are ``nice'' is somewhat difficult. In the -above example, the positions $20$, $25$, and $30$ are certainly nice, -but only three ticks may be a bit few of them. Better might be the -tick positions $17.5$, $20$, $22.5$, through to $32.5$. However, users -might prefer even numbers over fractions like $2.5$ as the stepping. - -A \emph{tick placement strategy} is a method of automatically deciding -which positions are \emph{good} for placing ticks. The data -visualization engine comes with a number of predefined strategies, but -you can also define new ones yourself. When the data visualization is -requested to automatically determine -``good'' positions for the placement of ticks on an axis, it uses one -of several possible \emph{basic strategies}. These strategies differ -dramatically in which tick positions they will choose: For a range of -values between $5$ and $1000$, a |linear steps| strategy might place -ticks at positions $100$, $200$, through to $1000$, while an -|exponential steps| strategy would prefer the tick positions $10$, -$100$ and $1000$. The exact number and values of the tick positions -chosen by either strategy can be fine-tuned using additional options +Consider the following problem: The data visualization engine determines that +in a plot the $x$-values vary between $17.4$ and $34.5$. In this case, we +certainly do not want, say, ten ticks at exactly ten evenly spaced positions +starting with $17.4$ and ending with $34.5$, because this would yield ticks at +positions like $32.6$. Ticks should be placed at ``nice'' positions like $20$, +$25$, and $30$. + +Determining which positions are ``nice'' is somewhat difficult. In the above +example, the positions $20$, $25$, and $30$ are certainly nice, but only three +ticks may be a bit few of them. Better might be the tick positions $17.5$, +$20$, $22.5$, through to $32.5$. However, users might prefer even numbers over +fractions like $2.5$ as the stepping. + +A \emph{tick placement strategy} is a method of automatically deciding which +positions are \emph{good} for placing ticks. The data visualization engine +comes with a number of predefined strategies, but you can also define new ones +yourself. When the data visualization is requested to automatically determine +``good'' positions for the placement of ticks on an axis, it uses one of +several possible \emph{basic strategies}. These strategies differ dramatically +in which tick positions they will choose: For a range of values between $5$ and +$1000$, a |linear steps| strategy might place ticks at positions $100$, $200$, +through to $1000$, while an |exponential steps| strategy would prefer the tick +positions $10$, $100$ and $1000$. The exact number and values of the tick +positions chosen by either strategy can be fine-tuned using additional options like |step| or |about|. -Here is an example of the different stepping chosen when one varies -the tick placement strategy: - +Here is an example of the different stepping chosen when one varies the tick +placement strategy: +% \begin{codeexample}[] \begin{tikzpicture} \datavisualization [scientific axes, visualize as smooth line] @@ -1346,25 +1362,24 @@ the tick placement strategy: \end{codeexample} Two strategies are always available: |linear steps|, which yields -(semi)automatic ticks are evenly spaced positions, and -|exponential steps|, which yields (semi)automatic steps at positions -at exponentially increasing positions -- which is exactly what is -needed for logarithmic plots. These strategies are details in -Section~\ref{section-dv-strategies}. - -The following options are used to configure tick placement strategies -like |linear steps|. Unlike the basic choice of a placement strategy, -which is an axis option, the following should be passed to the option -|ticks| or |grid| only. So, you would write -things like |x axis={ticks={step=2}}|, but |x axis={linear steps}|. +(semi)automatic ticks are evenly spaced positions, and |exponential steps|, +which yields (semi)automatic steps at positions at exponentially increasing +positions -- which is exactly what is needed for logarithmic plots. These +strategies are details in Section~\ref{section-dv-strategies}. + +The following options are used to configure tick placement strategies like +|linear steps|. Unlike the basic choice of a placement strategy, which is an +axis option, the following should be passed to the option |ticks| or |grid| +only. So, you would write things like |x axis={ticks={step=2}}|, but +|x axis={linear steps}|. \begin{key}{/tikz/data visualization/step=\meta{value} (initially 1)} - The value of this key is used to determine the spacing of the major - ticks. The key is used by the |linear steps| and |exponential steps| - strategies, see the explanations in - Section~\ref{section-dv-strategies} for details. Basically, all - ticks are placed at all multiples of \meta{value} that lie in the - attribute range interval. + The value of this key is used to determine the spacing of the major ticks. + The key is used by the |linear steps| and |exponential steps| strategies, + see the explanations in Section~\ref{section-dv-strategies} for details. + Basically, all ticks are placed at all multiples of \meta{value} that lie + in the attribute range interval. + % \begin{codeexample}[] \tikz \datavisualization [ school book axes, visualize as smooth line, @@ -1375,16 +1390,16 @@ things like |x axis={ticks={step=2}}|, but |x axis={linear steps}|. func y = \value x*\value x/2; }; \end{codeexample} + % \end{key} -\begin{key}{/tikz/data visualization/minor steps between - steps=\meta{number} (default 9)} - Specifies that between any two major steps (whose positions are - specified by the |step| key), there should be \meta{number} many - minor steps. Note that the default of |9| is exactly the right - number so that each interval between two minor steps is exactly a - tenth of the size of a major step. See also - Section~\ref{section-dv-strategies} for further details. +\begin{key}{/tikz/data visualization/minor steps between steps=\meta{number} (default 9)} + Specifies that between any two major steps (whose positions are specified + by the |step| key), there should be \meta{number} many minor steps. Note + that the default of |9| is exactly the right number so that each interval + between two minor steps is exactly a tenth of the size of a major step. See + also Section~\ref{section-dv-strategies} for further details. + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization [school book axes, visualize as smooth line, @@ -1397,270 +1412,260 @@ things like |x axis={ticks={step=2}}|, but |x axis={linear steps}|. }; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/phase=\meta{value} (initially 0)} - See Section~\ref{section-dv-strategies} for details on how the phase - of steps influences the tick placement. + See Section~\ref{section-dv-strategies} for details on how the phase of + steps influences the tick placement. \end{key} - \subsubsection{Automatic Computation of Tick and Grid Line Positions} -The |step| option gives you ``total control'' over the stepping of -ticks on an axis, but you often do not know the correct stepping in -advance. In this case, you may prefer to have a good value for |step| -being computed for you automatically. - -Like the |step| key, these options are passed to the |ticks| -option. So, for instance, you would write |x axis={ticks={about=4}}| -to request about four ticks to be placed on the $x$-axis. +The |step| option gives you ``total control'' over the stepping of ticks on an +axis, but you often do not know the correct stepping in advance. In this case, +you may prefer to have a good value for |step| being computed for you +automatically. +Like the |step| key, these options are passed to the |ticks| option. So, for +instance, you would write |x axis={ticks={about=4}}| to request about four +ticks to be placed on the $x$-axis. \begin{key}{/tikz/data visualization/about=\meta{number}} - This key asks the data visualization to place \emph{about} - \meta{number} many ticks on an axis. It is not guaranteed that - \emph{exactly} \meta{number} many ticks will be used, rather the - actual number will be the closest number of ticks to \meta{number} - so that their stepping is still ``good''. For instance, when you say - |about=10|, it may happen that exactly |10|, but perhaps even |13| ticks are - actually selected, provided that these numbers of ticks lead to good - stepping values like |5| or |2.5| rather than numbers like |3.4| or - |7|. The method that is used to determine which steppings a deemed to - be ``good'' depends on the current tick placement strategy. - - \medskip - \textbf{Linear steps.} - Let us start with |linear steps|: First, the difference between the - maximum value $v_{\max}$ and the minimum value $v_{\min}$ on the - axis is computed; let us call it $r$ for ``range.'' Then, $r$ is - divided by \meta{number}, - yielding a target stepping~$s$. If $s$ is a number like $1$ or $5$ - or $10$, then this number could be used directly as the new value of - |step|. However, $s$ will typically something strange like $0.02345$ - or $345223.76$, so $s$ must be replaced by a better value like $0.02$ - in the first case and perhaps $250000$ in the second case. - - In order to determine which number is to be used, $s$ is rewritten - in the form $m \cdot 10^k$ with $1 \le m < 10$ and $k \in \mathbb - Z$. For instance, $0.02345$ would be rewritten as $2.345 \cdot - 10^{-2}$ and $345223.76$ as $3.4522376 \cdot 10^5$. The next step - is to replace the still not-so-good number $m$ like $2.345$ or - $3.452237$ by a ``good'' value $m'$. For this, the current value of - the |about strategy| is used: - \begin{key}{/tikz/data visualization/about strategy=\meta{list}} - The \meta{list} is a comma-separated sequence of pairs - \meta{threshold}/\meta{value} like for instance |1.5/1.0| or - |2.3/2.0|. When a good value $m'$ is sought for a given $m$, we - iterate over the list and find the first pair - \meta{threshold}/\meta{value} where \meta{threshold} - exceeds~$m$. Then $m'$ is set to \meta{value}. For instance, if - \meta{list} is |1.5/1.0,2.3/2.0,4/2.5,7/5,11/10|, which is the - default, then for $m=3.141$ we would get $m'=2.5$ since $4 > - 3.141$, but $2.3 \le 3.141$. For $m=6.3$ we would get $m'=5$. - \end{key} - Once $m'$ has been determined, the stepping is set to $s' = m' - \cdot 10^k$. - - % Define an axis type - \tikzdatavisualizationset{ - one dimensional axis/.style={ - new Cartesian axis=axis, - axis={ - attribute=main, - unit vector={(0pt,1pt)}, - visualize axis={style=->}, - visualize ticks={major={tick text at low},direction axis=perpendicular}, - length=3cm - }, - new Cartesian axis=perpendicular, - perpendicular={ - attribute=perp, - unit vector={(1pt,0pt)}, - include value=0, - include value=1 - } - } - } + This key asks the data visualization to place \emph{about} \meta{number} + many ticks on an axis. It is not guaranteed that \emph{exactly} + \meta{number} many ticks will be used, rather the actual number will be the + closest number of ticks to \meta{number} so that their stepping is still + ``good''. For instance, when you say |about=10|, it may happen that exactly + |10|, but perhaps even |13| ticks are actually selected, provided that + these numbers of ticks lead to good stepping values like |5| or |2.5| + rather than numbers like |3.4| or |7|. The method that is used to determine + which steppings a deemed to be ``good'' depends on the current tick + placement strategy. - \def\showstrategy#1{ - % Show the effect for the different strategies \medskip - \begin{tikzpicture} - \foreach \max/\about [count=\c] in {10/5,20/5,30/5,40/5,50/5,60/5,70/5,80/5,90/5,100/5,100/3,100/10} - { - \begin{scope}[xshift=\c pt*30] - \datavisualization [#1, - one dimensional axis, - axis={ - ticks={about=\about}, - include value=0, - include value=\max + \textbf{Linear steps.} + Let us start with |linear steps|: First, the difference between the maximum + value $v_{\max}$ and the minimum value $v_{\min}$ on the axis is computed; + let us call it $r$ for ``range''. Then, $r$ is divided by \meta{number}, + yielding a target stepping~$s$. If $s$ is a number like $1$ or $5$ or $10$, + then this number could be used directly as the new value of |step|. + However, $s$ will typically something strange like $0.023\,45$ or + $345\,223.76$, so $s$ must be replaced by a better value like $0.02$ in the + first case and perhaps $250\,000$ in the second case. + + In order to determine which number is to be used, $s$ is rewritten in the + form $m \cdot 10^k$ with $1 \le m < 10$ and $k \in \mathbb Z$. For + instance, $0.023\,45$ would be rewritten as $2.345 \cdot 10^{-2}$ and + $345\,223.76$ as $3.452\,2376 \cdot 10^5$. The next step is to replace the + still not-so-good number $m$ like $2.345$ or $3.452\,237$ by a ``good'' + value $m'$. For this, the current value of the |about strategy| is used: + % + \begin{key}{/tikz/data visualization/about strategy=\meta{list}} + The \meta{list} is a comma-separated sequence of pairs + \meta{threshold}/\meta{value} like for instance |1.5/1.0| or |2.3/2.0|. + When a good value $m'$ is sought for a given $m$, we iterate over the + list and find the first pair \meta{threshold}/\meta{value} where + \meta{threshold} exceeds~$m$. Then $m'$ is set to \meta{value}. For + instance, if \meta{list} is |1.5/1.0,2.3/2.0,4/2.5,7/5,11/10|, which is + the default, then for $m=3.141$ we would get $m'=2.5$ since $4 > + 3.141$, but $2.3 \le 3.141$. For $m=6.3$ we would get $m'=5$. + \end{key} + % + Once $m'$ has been determined, the stepping is set to $s' = m' \cdot 10^k$. + + % Define an axis type + \tikzdatavisualizationset{ + one dimensional axis/.style={ + new Cartesian axis=axis, + axis={ + attribute=main, + unit vector={(0pt,1pt)}, + visualize axis={style=->}, + visualize ticks={major={tick text at low},direction axis=perpendicular}, + length=3cm + }, + new Cartesian axis=perpendicular, + perpendicular={ + attribute=perp, + unit vector={(1pt,0pt)}, + include value=0, + include value=1 + } + } + } + + \def\showstrategy#1{ + % Show the effect for the different strategies + \medskip + \begin{tikzpicture} + \foreach \max/\about [count=\c] in {10/5,20/5,30/5,40/5,50/5,60/5,70/5,80/5,90/5,100/5,100/3,100/10} + { + \begin{scope}[xshift=\c pt*30] + \datavisualization [#1, + one dimensional axis, + axis={ + ticks={about=\about}, + include value=0, + include value=\max + } + ]; + + \node at (0,-5mm) [anchor=mid] {\texttt{\about}}; + \end{scope} } - ]; - \node at (0,-5mm) [anchor=mid] {\texttt{\about}}; - \end{scope} - } + \node at (30pt,-5mm) [anchor=mid east] {\texttt{about=\ \ }}; + \end{tikzpicture} + } - \node at (30pt,-5mm) [anchor=mid east] {\texttt{about=\ \ }}; - \end{tikzpicture} -} + The net effect of all this is that for the default strategy the only valid + stepping are the values $1$, $2$, $2.5$ and $5$ and every value obtainable + by multiplying one of these values by a power of ten. The following example + shows the effects of, first, setting |about=5| (corresponding to the |some| + option) and then having axes where the minimum value is always |0| and + where the maximum value ranges from |10| to |100| and, second, setting + |about| to the values from |3| (corresponding to the |few| option) and to + |10| (corresponding to the |many| option) while having the minimum at |0| + and the maximum at |100|: - The net effect of all this is that for the default strategy the - only valid stepping are the values $1$, $2$, $2.5$ and $5$ and every - value obtainable by multiplying one of these values by a power of - ten. The following example shows the effects of, first, setting - |about=5| (corresponding to the |some| option) and then having axes - where the minimum value is always |0| and where the maximum value - ranges from |10| to |100| and, second, setting |about| to the values - from |3| (corresponding to the |few| option) and to |10| - (corresponding to the |many| option) while having the - minimum at |0| and the maximum at |100|: - - \showstrategy{standard about strategy} - - \medskip - \textbf{Exponential steps.} - For |exponential steps| the strategy for determining a good stepping - value is similar to |linear steps|, but with the following - differences: - \begin{itemize} - \item Naturally, since the stepping value refers to the exponent, - the whole computation of a good stepping value needs to be done - ``in the exponent.'' Mathematically spoken, instead of considering - the difference $r = v_{\max} - v_{\min}$, we consider the difference $r = - \log v_{\max} - \log v_{\min}$. With this difference, we still - compute $s = r / \meta{number}$ and let $s = m \cdot 10^k$ with $1 - \le m < 10$. - \item It makes no longer sense to use values like $2.5$ for $m'$ - since this would yield a fractional exponent. Indeed, the only - sensible values for $m'$ seem to be $1$, $3$, $6$, and - $10$. Because of this, the |about strategy| is ignored and one of - these values or a multiple of one of them by a power of ten is - used. - \end{itemize} - - The following example shows the chosen steppings for a maximum - varying from $10^1$ to $10^5$ and from $10^{10}$ to $10^{50}$ as - well as for $10^{100}$ for |about=3|: - - \medskip - \begin{tikzpicture} - \foreach \max [count=\c] in {1,...,5,10,20,...,50,100} - { - \begin{scope}[xshift=\c pt*40] - \datavisualization [ - one dimensional axis, - axis={ - logarithmic, - ticks={about=3}, - include value=1, - include value=1e\max - } - ]; - \end{scope} - } - \end{tikzpicture} + \showstrategy{standard about strategy} + + \medskip + \textbf{Exponential steps.} + For |exponential steps| the strategy for determining a good stepping value + is similar to |linear steps|, but with the following differences: + % + \begin{itemize} + \item Naturally, since the stepping value refers to the exponent, the + whole computation of a good stepping value needs to be done ``in + the exponent''. Mathematically spoken, instead of considering the + difference $r = v_{\max} - v_{\min}$, we consider the difference $r + = \log v_{\max} - \log v_{\min}$. With this difference, we still + compute $s = r / \meta{number}$ and let $s = m \cdot 10^k$ with $1 + \le m < 10$. + \item It makes no longer sense to use values like $2.5$ for $m'$ since + this would yield a fractional exponent. Indeed, the only sensible + values for $m'$ seem to be $1$, $3$, $6$, and $10$. Because of + this, the |about strategy| is ignored and one of these values or a + multiple of one of them by a power of ten is used. + \end{itemize} + + The following example shows the chosen steppings for a maximum varying from + $10^1$ to $10^5$ and from $10^{10}$ to $10^{50}$ as well as for $10^{100}$ + for |about=3|: + + \medskip + \begin{tikzpicture} + \foreach \max [count=\c] in {1,...,5,10,20,...,50,100} + { + \begin{scope}[xshift=\c pt*40] + \datavisualization [ + one dimensional axis, + axis={ + logarithmic, + ticks={about=3}, + include value=1, + include value=1e\max + } + ]; + \end{scope} + } + \end{tikzpicture} - \medskip - \textbf{Alternative strategies.} + \medskip + \textbf{Alternative strategies.} - In addition to the standard |about strategy|, there are some - additional strategies that you might wish to use instead: + In addition to the standard |about strategy|, there are some additional + strategies that you might wish to use instead: - \begin{key}{/tikz/data visualization/standard about - strategy} - Permissible values for $m'$ are: $1$, $2$, $2.5$, and~$5$. This - strategy is the default strategy. - \end{key} + \begin{key}{/tikz/data visualization/standard about strategy} + Permissible values for $m'$ are: $1$, $2$, $2.5$, and~$5$. This + strategy is the default strategy. + \end{key} - \begin{key}{/tikz/data visualization/euro about strategy} - Permissible values for $m'$ are: $1$, $2$, and~$5$. These are the - same values as for the Euro coins, hence the - name. + \begin{key}{/tikz/data visualization/euro about strategy} + Permissible values for $m'$ are: $1$, $2$, and~$5$. These are the same + values as for the Euro coins, hence the name. - \showstrategy{euro about strategy} - \end{key} + \showstrategy{euro about strategy} + \end{key} - \begin{key}{/tikz/data visualization/half about strategy} - Permissible values for $m'$: $1$ and $5$. Use this - strategy if only powers of $10$ or halves thereof seem logical. + \begin{key}{/tikz/data visualization/half about strategy} + Permissible values for $m'$: $1$ and $5$. Use this strategy if only + powers of $10$ or halves thereof seem logical. - \showstrategy{half about strategy} - \end{key} + \showstrategy{half about strategy} + \end{key} - \begin{key}{/tikz/data visualization/decimal about strategy} - The only permissible value for $m'$ is $1$. This is an even more - radical version of the previous strategy. + \begin{key}{/tikz/data visualization/decimal about strategy} + The only permissible value for $m'$ is $1$. This is an even more + radical version of the previous strategy. - \showstrategy{decimal about strategy} - \end{key} + \showstrategy{decimal about strategy} + \end{key} - \begin{key}{/tikz/data visualization/quarter about strategy} - Permissible values for $m'$ are: $1$, $2.5$, and $5$. + \begin{key}{/tikz/data visualization/quarter about strategy} + Permissible values for $m'$ are: $1$, $2.5$, and $5$. - \showstrategy{quarter about strategy} - \end{key} + \showstrategy{quarter about strategy} + \end{key} - \begin{key}{/tikz/data visualization/int about strategy} - Permissible values for $m'$ are: $1$, $2$, $3$, $4$, and $5$. + \begin{key}{/tikz/data visualization/int about strategy} + Permissible values for $m'$ are: $1$, $2$, $3$, $4$, and $5$. - \showstrategy{int about strategy} - \end{key} + \showstrategy{int about strategy} + \end{key} \end{key} \begin{key}{/tikz/data visualization/many} - This is an abbreviation for |about=10|. + This is an abbreviation for |about=10|. \end{key} \begin{key}{/tikz/data visualization/some} - This is an abbreviation for |about=5|. + This is an abbreviation for |about=5|. \end{key} \begin{key}{/tikz/data visualization/few} - This is an abbreviation for |about=3|. + This is an abbreviation for |about=3|. \end{key} \begin{key}{/tikz/data visualization/none} - Switches off the automatic step computation. Unless you use |step=| - explicitly to set a stepping, no ticks will be (automatically) - added. + Switches off the automatic step computation. Unless you use |step=| + explicitly to set a stepping, no ticks will be (automatically) added. \end{key} - \subsubsection{Manual Specification of Tick and Grid Line Positions} -The automatic computation of ticks and grid lines will usually do a -good job, but not always. For instance, you might wish to have ticks -exactly at, say, prime numbers or at Fibonacci numbers or you might -wish to have an additional tick at $\pi$. In these cases you need more -direct control over the specification of tick positions. - -First, it is important to understand that the data visualization -system differentiates between three kinds of -ticks and grid lines: major, minor, and subminor. The major ticks are -the most prominent ticks where, typically, a textual representation of -the tick is shown; and the major grid lines are the thickest. The -minor ticks are smaller, more numerous, and lie between major -ticks. They are used, for instance, to indicate positions in the -middle between major ticks or at all integer positions between major -ticks. Finally, subminor ticks are even smaller than minor ticks and -they lie between minor ticks. +The automatic computation of ticks and grid lines will usually do a good job, +but not always. For instance, you might wish to have ticks exactly at, say, +prime numbers or at Fibonacci numbers or you might wish to have an additional +tick at $\pi$. In these cases you need more direct control over the +specification of tick positions. + +First, it is important to understand that the data visualization system +differentiates between three kinds of ticks and grid lines: major, minor, and +subminor. The major ticks are the most prominent ticks where, typically, a +textual representation of the tick is shown; and the major grid lines are the +thickest. The minor ticks are smaller, more numerous, and lie between major +ticks. They are used, for instance, to indicate positions in the middle between +major ticks or at all integer positions between major ticks. Finally, subminor +ticks are even smaller than minor ticks and they lie between minor ticks. Four keys are used to configure the different kinds: \begin{key}{/tikz/data visualization/major=\meta{options}} - The key can be passed as an option to the |ticks| key and also to - the |grid| key, which in turn is passed as an option to an axis. The - \meta{options} passed to |major| specify at which positions - major ticks/grid lines should be shown (using the |at| option and - |also at| option) and also any special styling. The different - possible options are described later in this section. + The key can be passed as an option to the |ticks| key and also to the + |grid| key, which in turn is passed as an option to an axis. The + \meta{options} passed to |major| specify at which positions major + ticks/grid lines should be shown (using the |at| option and |also at| + option) and also any special styling. The different possible options are + described later in this section. + % \begin{codeexample}[] \tikz \datavisualization [ school book axes, visualize as smooth line, @@ -1670,10 +1675,12 @@ Four keys are used to configure the different kinds: func y = \value x * \value x / 2; }; \end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/minor=\meta{options}} - Like |major|, only for minor ticks/grid lines. + Like |major|, only for minor ticks/grid lines. + % \begin{codeexample}[] \tikz \datavisualization [ school book axes, visualize as smooth line, @@ -1683,19 +1690,20 @@ Four keys are used to configure the different kinds: func y = \value x * \value x / 2; }; \end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/subminor=\meta{options}} - Like |major|, only for subminor ticks/grid lines. + Like |major|, only for subminor ticks/grid lines. \end{key} - \begin{key}{/tikz/data visualization/common=\meta{options}} - This key allows you to specify \meta{options} that apply to |major|, - |minor| and |subminor| alike. It does not make sense to use |common| - to specify positions (since you typically do not want both a major - and a minor tick at the same position), but it can be useful to - configure, say, the size of all kinds of ticks: + This key allows you to specify \meta{options} that apply to |major|, + |minor| and |subminor| alike. It does not make sense to use |common| to + specify positions (since you typically do not want both a major and a minor + tick at the same position), but it can be useful to configure, say, the + size of all kinds of ticks: + % \begin{codeexample}[] \tikz \datavisualization [ school book axes, visualize as smooth line, @@ -1705,20 +1713,21 @@ Four keys are used to configure the different kinds: func y = \value x * \value x / 2; }; \end{codeexample} + % \end{key} - -The following keys can now be passed to the |major|, |minor|, and -|subminor| keys to specify where ticks or grid lines should be shown: +The following keys can now be passed to the |major|, |minor|, and |subminor| +keys to specify where ticks or grid lines should be shown: \begin{key}{/tikz/data visualization/at=\meta{list}} - Basically, the \meta{list} must be a list of values that is - processed with the |\foreach| macro (thus, it can contain ellipses - to specify ranges of value). Empty values are skipped. - - The effect of passing |at| to a |major|, |minor|, or |subminor| key - is that ticks or grid lines on the axis will be placed exactly at - the values in \meta{list}. Here is an example: + Basically, the \meta{list} must be a list of values that is processed with + the |\foreach| macro (thus, it can contain ellipses to specify ranges of + value). Empty values are skipped. + + The effect of passing |at| to a |major|, |minor|, or |subminor| key is that + ticks or grid lines on the axis will be placed exactly at the values in + \meta{list}. Here is an example: + % \begin{codeexample}[] \tikz \datavisualization [ school book axes, visualize as smooth line, @@ -1727,44 +1736,48 @@ The following keys can now be passed to the |major|, |minor|, and var x : interval [-1.25:2]; func y = \value x * \value x / 2; }; -\end{codeexample} - When this option is used, any previously specified tick positions - are overwritten by the values in \meta{list}. Automatically computed - ticks are also overwritten. Thus, this option gives you complete - control over where ticks should be placed. - - Normally, the individual values inside the \meta{list} are just - numbers that are specified in the same way as an attribute - value. However, such a value may also contain the keyword |as|, - which allows you so specify the styling of the tick in - detail. Section~\ref{section-dv-ticks-styling} details how this - works. - - It is often a bit cumbersome that one has to write things like -\begin{codeexample}[code only] -some axis = {ticks = {major = {at = {...}}}} \end{codeexample} - A slight simplification is given by the following keys, which can be - passed directly to |ticks| and |grid|: - \begin{key}{/tikz/data visualization/major at=\meta{list}} - A shorthand for |major={at={|\meta{list}|}}|. - \end{key} - \begin{key}{/tikz/data visualization/minor at=\meta{list}} - A shorthand for |major={at={|\meta{list}|}}|. - \end{key} - \begin{key}{/tikz/data visualization/subminor at=\meta{list}} - A shorthand for |major={at={|\meta{list}|}}|. - \end{key} + When this option is used, any previously specified tick positions are + overwritten by the values in \meta{list}. Automatically computed ticks are + also overwritten. Thus, this option gives you complete control over where + ticks should be placed. + + Normally, the individual values inside the \meta{list} are just numbers + that are specified in the same way as an attribute value. However, such a + value may also contain the keyword |as|, which allows you so specify the + styling of the tick in detail. Section~\ref{section-dv-ticks-styling} + details how this works. + + It is often a bit cumbersome that one has to write things like + % +\begin{codeexample}[code only] +some axis = {ticks = {major = {at = {...}}}} +\end{codeexample} + % + A slight simplification is given by the following keys, which can be passed + directly to |ticks| and |grid|: + % + \begin{key}{/tikz/data visualization/major at=\meta{list}} + A shorthand for |major={at={|\meta{list}|}}|. + \end{key} + % + \begin{key}{/tikz/data visualization/minor at=\meta{list}} + A shorthand for |major={at={|\meta{list}|}}|. + \end{key} + % + \begin{key}{/tikz/data visualization/subminor at=\meta{list}} + A shorthand for |major={at={|\meta{list}|}}|. + \end{key} \end{key} \begin{key}{/tikz/data visualization/also at=\meta{list}} - This key is similar to |at|, but it causes ticks or grid lines to be - placed at the positions in the \meta{list} \emph{in addition} to the - ticks that have already been specified either directly using |at| or - indirectly using keys like |step| or |some|. The effect of multiple - calls of this key accumulate. However, when |at| is used after an - |also at| key, the |at| key completely resets the positions where - ticks or grid lines are shown. + This key is similar to |at|, but it causes ticks or grid lines to be placed + at the positions in the \meta{list} \emph{in addition} to the ticks that + have already been specified either directly using |at| or indirectly using + keys like |step| or |some|. The effect of multiple calls of this key + accumulate. However, when |at| is used after an |also at| key, the |at| key + completely resets the positions where ticks or grid lines are shown. + % \begin{codeexample}[] \tikz \datavisualization [ school book axes, visualize as smooth line, @@ -1773,101 +1786,102 @@ some axis = {ticks = {major = {at = {...}}}} var x : interval [-1.25:2]; func y = \value x * \value x / 2; }; -\end{codeexample} - As for |at|, there are some shorthands available: - \begin{key}{/tikz/data visualization/major also at=\meta{list}} - A shorthand for |major={also at={|\meta{list}|}}|. - \end{key} - \begin{key}{/tikz/data visualization/minor also at=\meta{list}} - A shorthand for |major={also at={|\meta{list}|}}|. - \end{key} - \begin{key}{/tikz/data visualization/subminor also at=\meta{list}} - A shorthand for |major={also at={|\meta{list}|}}|. - \end{key} +\end{codeexample} + % + As for |at|, there are some shorthands available: + % + \begin{key}{/tikz/data visualization/major also at=\meta{list}} + A shorthand for |major={also at={|\meta{list}|}}|. + \end{key} + % + \begin{key}{/tikz/data visualization/minor also at=\meta{list}} + A shorthand for |major={also at={|\meta{list}|}}|. + \end{key} + % + \begin{key}{/tikz/data visualization/subminor also at=\meta{list}} + A shorthand for |major={also at={|\meta{list}|}}|. + \end{key} \end{key} \subsubsection{Styling Ticks and Grid Lines: Introduction} - \label{section-dv-ticks-styling} -When a tick, a tick label, or a grid line is visualized on the page, a -whole regiment of styles influences the appearance. The reason for -this large number of interdependent styles is the fact that we often -wish to influence only a very certain part of how a tick is rendered -while leaving the other aspects untouched: Sometimes we need to modify -just the font of the tick label; sometimes we wish to change the -length of the tick label and the tick label position at the same time; -sometimes we wish to change the color of grid line, tick, and tick -label; and sometimes we wish to generally change the thickness of all -ticks. - -Let us go over the different kinds of things that can be styled (grid -lines, ticks, and tick labels) one by one and let us have a look at -which styles are involved. We will start with the grid lines, since they -turn out to be the most simple, but first let us have a look at the -general |style| and |styling| mechanism that is used in many placed in -the following: +When a tick, a tick label, or a grid line is visualized on the page, a whole +regiment of styles influences the appearance. The reason for this large number +of interdependent styles is the fact that we often wish to influence only a +very certain part of how a tick is rendered while leaving the other aspects +untouched: Sometimes we need to modify just the font of the tick label; +sometimes we wish to change the length of the tick label and the tick label +position at the same time; sometimes we wish to change the color of grid line, +tick, and tick label; and sometimes we wish to generally change the thickness +of all ticks. + +Let us go over the different kinds of things that can be styled (grid lines, +ticks, and tick labels) one by one and let us have a look at which styles are +involved. We will start with the grid lines, since they turn out to be the most +simple, but first let us have a look at the general |style| and |styling| +mechanism that is used in many placed in the following: -\subsubsection{Styling Ticks and Grid Lines: The Style and Node Style Keys} +\subsubsection{Styling Ticks and Grid Lines: The Style and Node Style Keys} \label{section-dv-style} All keys of the data visualization system have the path prefix -|/tikz/data visualization|. This is not only true for the main keys -like |scientific axes| or |visualize as line|, but also for keys that -govern how ticks are visualized. In particular, a style like -|every major grid| has the path prefix |/tikz/data visualization| and -all keys stored in this style are also executed with this path -prefix. - -Normally, this does not cause any trouble since most of the keys and -even styles used in a data visualization are intended to configure -what is shown in the visualization. However, at some point, we may -also with to specify options that no longer configure the -visualization in general, but specify the appearance of a line or a -node on the \tikzname\ layer. +|/tikz/data visualization|. This is not only true for the main keys like +|scientific axes| or |visualize as line|, but also for keys that govern how +ticks are visualized. In particular, a style like |every major grid| has the +path prefix |/tikz/data visualization| and all keys stored in this style are +also executed with this path prefix. + +Normally, this does not cause any trouble since most of the keys and even +styles used in a data visualization are intended to configure what is shown in +the visualization. However, at some point, we may also with to specify options +that no longer configure the visualization in general, but specify the +appearance of a line or a node on the \tikzname\ layer. Two keys are used to ``communicate'' with the \tikzname\ layer: \begin{key}{/tikz/data visualization/style=\meta{\tikzname\ options}} - This key takes options whose path prefix is |/tikz|, not - |/tikz/data visualization|. These options will be \emph{appended} to - a current list of such options (thus, multiple calls of this key - accumulate). The resulting list of keys is not executed - immediately, but it will be executed whenever the data visualization - engine calls the \tikzname\ layer to draw something (this placed - will be indicated in the following). + This key takes options whose path prefix is |/tikz|, not + |/tikz/data visualization|. These options will be \emph{appended} to a + current list of such options (thus, multiple calls of this key accumulate). + The resulting list of keys is not executed immediately, but it will be + executed whenever the data visualization engine calls the \tikzname\ layer + to draw something (this placed will be indicated in the following). + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={ticks={style=blue}, length=3cm}, - y axis={grid, grid={minor steps between steps, major={style=red}}}, + y axis={grid, grid={minor steps between steps, major={style=red}}}, visualize as line] data [format=function] { var x : interval [5:10]; func y = \value x * \value x; }; \end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/styling} - Executing this key will cause all ``accumulated'' \tikzname\ options - from previous calls to the key |/tikz/data visualization/style| to be - executed. Thus, you use |style| to set \tikzname\ options, but you - use |styling| to actually apply these options. Usually, you do not - call this option directly since this application is only done deep - inside the data visualization engine. + Executing this key will cause all ``accumulated'' \tikzname\ options from + previous calls to the key |/tikz/data visualization/style| to be executed. + Thus, you use |style| to set \tikzname\ options, but you use |styling| to + actually apply these options. Usually, you do not call this option directly + since this application is only done deep inside the data visualization + engine. \end{key} -Similar to |style| (and |styling|) there also exist the -|node style| (and |node styling|) key that takes \tikzname\ options that -apply to nodes only -- in addition to the usual |style|. +Similar to |style| (and |styling|) there also exist the |node style| (and +|node styling|) key that takes \tikzname\ options that apply to nodes only -- +in addition to the usual |style|. \begin{key}{/tikz/data visualization/node style=\meta{\tikzname\ options}} - This key works like |style|, only it has an effect only on nodes - that are created during a data visualization. This includes tick - labels and axis labels: + This key works like |style|, only it has an effect only on nodes that are + created during a data visualization. This includes tick labels and axis + labels: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -1878,13 +1892,14 @@ apply to nodes only -- in addition to the usual |style|. func y = \value x * \value x; }; \end{codeexample} - Note that in the example the ticks themselves (the little thicker - lines) are not red. + % + Note that in the example the ticks themselves (the little thicker lines) + are not red. \end{key} \begin{key}{/tikz/data visualization/node styling} - Executing this key will cause all ``accumulated'' node stylings to - be executed. + Executing this key will cause all ``accumulated'' node stylings to be + executed. \end{key} @@ -1892,40 +1907,35 @@ apply to nodes only -- in addition to the usual |style|. \label{section-dv-styling-grid-lines} When a grid line is visualized, see -Section~\ref{section-dv-visualize-gridlines} for details on when this -happens, the following styles are executed in the specified order. - +Section~\ref{section-dv-visualize-gridlines} for details on when this happens, +the following styles are executed in the specified order. +% \begin{enumerate} -\item - |grid layer|. -\item - |every grid|. -\item |every major grid| or |every minor grid| or - |every subminor grid|, depending on the kind of grid line. -\item - locally specified options for the individual grid line, see - Section~\ref{section-dv-local-styles}. -\item - |styling|, see Section~\ref{section-dv-style}. + \item |grid layer|. + \item |every grid|. + \item |every major grid| or |every minor grid| or |every subminor grid|, + depending on the kind of grid line. + \item locally specified options for the individual grid line, see + Section~\ref{section-dv-local-styles}. + \item |styling|, see Section~\ref{section-dv-style}. \end{enumerate} -All of these keys have the path prefix -|/tikz/data visualization|. However, the options stored in the first -style (|grid layer|) and also in the last (|styling|) are executed -with the path prefix |/tikz| (see Section~\ref{section-dv-style}). +All of these keys have the path prefix |/tikz/data visualization|. However, the +options stored in the first style (|grid layer|) and also in the last +(|styling|) are executed with the path prefix |/tikz| (see +Section~\ref{section-dv-style}). Let us now have a look at these keys in detail: \begin{stylekey}{/tikz/data visualization/grid layer (initially on background layer)} - \label{section-dv-grid-layer}% - This key is used to specified the \emph{layer} on which grid lines - should be drawn (layers are explained in - Section~\ref{section-tikz-backgrounds}). By default, all grid lines - are placed on the |background| layer and thus behind the data - visualization. This is a sensible strategy since it avoids obscuring - the more important data with the far less important grid - lines. However, you can change this style to ``get the grid lines to - the front'': +\label{section-dv-grid-layer}% + This key is used to specified the \emph{layer} on which grid lines should + be drawn (layers are explained in Section~\ref{section-tikz-backgrounds}). + By default, all grid lines are placed on the |background| layer and thus + behind the data visualization. This is a sensible strategy since it avoids + obscuring the more important data with the far less important grid lines. + However, you can change this style to ``get the grid lines to the front'': + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -1940,26 +1950,29 @@ Let us now have a look at these keys in detail: var x : interval [5:10]; func y = \value x * \value x; }; -\end{codeexample} - When this style is executed, the keys stored in the style will be - executed with the prefix |/tikz|. Normally, you should only set this - style to be empty or to |on background layer|. +\end{codeexample} + % + When this style is executed, the keys stored in the style will be executed + with the prefix |/tikz|. Normally, you should only set this style to be + empty or to |on background layer|. \end{stylekey} \begin{stylekey}{/tikz/data visualization/every grid} - This style provides overall configuration options for grid lines. By - default, it is set to the following: + This style provides overall configuration options for grid lines. By + default, it is set to the following: + % \begin{codeexample}[code only] low=min, high=max \end{codeexample} - This causes grid lines to span all possible values when they are - visualized, which is usually the desired behaviour (the |low| and - |high| keys are explained in - Section~\ref{section-dv-visualize-ticks}. You can append - the |style| key to this style to configure the overall appearance of - grid lines. In the following example we cause all grid lines to be - dashed (which is not a good idea in general since it creates a - distracting background pattern). + % + This causes grid lines to span all possible values when they are + visualized, which is usually the desired behaviour (the |low| and |high| + keys are explained in Section~\ref{section-dv-visualize-ticks}. You can + append the |style| key to this style to configure the overall appearance of + grid lines. In the following example we cause all grid lines to be dashed + (which is not a good idea in general since it creates a distracting + background pattern). + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -1970,18 +1983,21 @@ low=min, high=max var x : interval [5:10]; func y = \value x * \value x; }; -\end{codeexample} +\end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/data visualization/every major grid} - This style configures the appearance of major grid lines. It does so - by calling the |style| key to setup appropriate \tikzname\ options - for visualizing major grid lines. The default definition of this - style is: + This style configures the appearance of major grid lines. It does so by + calling the |style| key to setup appropriate \tikzname\ options for + visualizing major grid lines. The default definition of this style is: + % \begin{codeexample}[code only] style = {help lines, thin, black!25} \end{codeexample} - In the following example, we use thin major blue grid lines: + % + In the following example, we use thin major blue grid lines: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, @@ -1996,148 +2012,144 @@ style = {help lines, thin, black!25} var x : interval [5:10]; func y = \value x * \value x; }; -\end{codeexample} - As can be seen, this is not exactly visually pleasing. The default - settings for the grid lines should work in most situations; you may - wish to increase the blackness level, however, when you experience - trouble during printing or projecting graphics. +\end{codeexample} + % + As can be seen, this is not exactly visually pleasing. The default settings + for the grid lines should work in most situations; you may wish to increase + the blackness level, however, when you experience trouble during printing + or projecting graphics. \end{stylekey} \begin{stylekey}{/tikz/data visualization/every minor grid} - Works like |every major grid|. The default is + Works like |every major grid|. The default is + % \begin{codeexample}[code only] style = {help lines, black!25} \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/data visualization/every subminor grid} - Works like |every major grid|. The default is + Works like |every major grid|. The default is + % \begin{codeexample}[code only] style = {help lines, black!10} \end{codeexample} + % \end{stylekey} - \subsubsection{Styling Ticks and Grid Lines: Styling Ticks and Tick Labels} - \label{section-dv-styling-ticks} -Styling ticks and tick labels is somewhat similar to styling grid -lines. Let us start with the tick \emph{mark}, that is, the small line -that represents the tick. When this mark is drawn, the following styles are applied: - +Styling ticks and tick labels is somewhat similar to styling grid lines. Let us +start with the tick \emph{mark}, that is, the small line that represents the +tick. When this mark is drawn, the following styles are applied: +% \begin{enumerate} -\item - |every ticks|. -\item |every major ticks| or |every minor ticks| or - |every subminor ticks|, depending on the kind of ticks to be - visualized. -\item - locally specified options for the individual tick, see - Section~\ref{section-dv-local-styles}. -\item - |tick layer| -\item - |every odd tick| or |every even tick|, see Section~\ref{section-dv-stacking}. -\item - |draw| -\item - |styling|, see Section~\ref{section-dv-style}. + \item |every ticks|. + \item |every major ticks| or |every minor ticks| or |every subminor ticks|, + depending on the kind of ticks to be visualized. + \item locally specified options for the individual tick, see + Section~\ref{section-dv-local-styles}. + \item |tick layer| + \item |every odd tick| or |every even tick|, see + Section~\ref{section-dv-stacking}. + \item |draw| + \item |styling|, see Section~\ref{section-dv-style}. \end{enumerate} -For the tick label node (the node containing the textual -representation of the attribute's value at the tick position), the -following styles are applied: - +For the tick label node (the node containing the textual representation of the +attribute's value at the tick position), the following styles are applied: +% \begin{enumerate} -\item - |every ticks|. -\item |every major ticks| or |every minor ticks| or - |every subminor ticks|, depending on the kind of ticks to be - visualized. -\item - locally specified options for the individual tick, see - Section~\ref{section-dv-local-styles}. -\item - |tick node layer| -\item - |every odd tick| or |every even tick|, see Section~\ref{section-dv-stacking}. -\item - |styling|, see Section~\ref{section-dv-style}. -\item - |node styling|, see Section~\ref{section-dv-style}. + \item |every ticks|. + \item |every major ticks| or |every minor ticks| or |every subminor ticks|, + depending on the kind of ticks to be visualized. + \item locally specified options for the individual tick, see + Section~\ref{section-dv-local-styles}. + \item |tick node layer| + \item |every odd tick| or |every even tick|, see + Section~\ref{section-dv-stacking}. + \item |styling|, see Section~\ref{section-dv-style}. + \item |node styling|, see Section~\ref{section-dv-style}. \end{enumerate} \begin{stylekey}{/tikz/data visualization/every ticks} - This style allows you to configure the appearance of ticks using the - |style| and |node style| key. Here is (roughly) the default - definition of this style: + This style allows you to configure the appearance of ticks using the + |style| and |node style| key. Here is (roughly) the default definition of + this style: + % \begin{codeexample}[code only] node style={ font=\footnotesize, inner sep=1pt, outer sep=.1666em, rounded corners=1.5pt -} +} \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/data visualization/every major ticks} - The default is + The default is + % \begin{codeexample}[code only] style={line cap=round}, tick length=2pt \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/data visualization/every minor ticks} - The default is + The default is + % \begin{codeexample}[code only] style={help lines,thin, line cap=round}, tick length=1.4pt \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/data visualization/every subminor ticks} - The default is + The default is + % \begin{codeexample}[code only] style={help lines, line cap=round}, tick length=0.8pt \end{codeexample} + % \end{stylekey} - \begin{stylekey}{/tikz/data visualization/tick layer (initially on background layer)} - Like |grid layer|, this key specifies on which layer the ticks - should be placed. + Like |grid layer|, this key specifies on which layer the ticks should be + placed. \end{stylekey} -\begin{stylekey}{/tikz/data visualization/tick node layer (initially - \normalfont empty)} - Like |tick layer|, but now for the nodes. By default, tick nodes are - placed on the main layer and thus on top of the data in case that - the tick nodes are inside the data. +\begin{stylekey}{/tikz/data visualization/tick node layer (initially \normalfont empty)} + Like |tick layer|, but now for the nodes. By default, tick nodes are placed + on the main layer and thus on top of the data in case that the tick nodes + are inside the data. \end{stylekey} \subsubsection{Styling Ticks and Grid Lines: Exceptional Ticks} -You may sometimes wish to style a few ticks differently from the other -ticks. For instance, in the axis system |school book axes| there -should be a tick label at the |0| position only on one axis and then -this label should be offset a bit. In many cases this is easy to -achieve: When you add a tick ``by hand'' using the |at| or |also at| -option, you can add any special options in square brackets. +You may sometimes wish to style a few ticks differently from the other ticks. +For instance, in the axis system |school book axes| there should be a tick +label at the |0| position only on one axis and then this label should be offset +a bit. In many cases this is easy to achieve: When you add a tick ``by hand'' +using the |at| or |also at| option, you can add any special options in square +brackets. -However, in some situations the special tick position has been -computed automatically for you, for instance by the |step| key or by -saying |tick=some|. In this case, adding a tick mark with the desired -options using |also at| would cause the tick mark with the correct -options to be shown in addition to the tick mark with the wrong -options. In cases like this one, the following option may be helpful: +However, in some situations the special tick position has been computed +automatically for you, for instance by the |step| key or by saying |tick=some|. +In this case, adding a tick mark with the desired options using |also at| would +cause the tick mark with the correct options to be shown in addition to the +tick mark with the wrong options. In cases like this one, the following option +may be helpful: \begin{key}{/tikz/data visualization/options at=\meta{value} |as [|\meta{options}|]|} - This key causes the \meta{options} to be executed for any tick - mark(s) at \meta{value} in addition to any options given already for - this position: + This key causes the \meta{options} to be executed for any tick mark(s) at + \meta{value} in addition to any options given already for this position: + % \begin{codeexample}[width=7cm] \tikz \datavisualization [ scientific axes, @@ -2151,53 +2163,45 @@ data [format=function] { func y = sin(\value x r); }; \end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/no tick text at=\meta{value}} - Shorthand for |options at=|\meta{value}| as [no tick text]|. + Shorthand for |options at=|\meta{value}| as [no tick text]|. \end{key} - \subsubsection{Styling Ticks and Grid Lines: Styling and Typesetting a Value} - \label{section-dv-local-styles} \label{section-dv-tick-labels} - -The |at| and |also at| key allow you to provide a comma-separated -\meta{list} of \meta{value}s where ticks or grid lines should be -placed. In the simplest case, the \meta{value} is simply a -number. However, the general syntax allows three different kinds of -\meta{value}s: - +The \todosp{why 2 labels?} |at| and |also at| key allow you to provide a +comma-separated \meta{list} of \meta{value}s where ticks or grid lines should +be placed. In the simplest case, the \meta{value} is simply a number. However, +the general syntax allows three different kinds of \meta{value}s: +% \begin{enumerate} -\item - \meta{value} -\item - \meta{value} |as| |[|\meta{local options}|]| -\item - \meta{value} |as| \opt{|[|\meta{local options}|]|} \meta{text} + \item \meta{value} + \item \meta{value} |as| |[|\meta{local options}|]| + \item \meta{value} |as| \opt{|[|\meta{local options}|]|} \meta{text} \end{enumerate} -In the first case, the \meta{value} is just a number that is -interpreted like any other attribute value. - -In the second case, where the keyword |as| is present, followed by -some option in square brackets, but nothing following the closing -square bracket, when the tick or grid line at position \meta{value} is -shown, the \meta{local options} are executed first. These can use the -|style| key or the |node style| key to configure the appearance of -this single tick or grid line. You can also use keys like |low| or -|high| to influence how large the grid lines or the ticks are or keys -like |tick text at low| to explicitly hide or show a tick label. - -In the third case, which is only important for |ticks| and not for -|grid|, the same happens as in the second case, but the -text that is shown as tick label is \meta{text} rather than the -automatically generated tick label. This automatic generation of tick -labels is explained in the following. - +In the first case, the \meta{value} is just a number that is interpreted like +any other attribute value. + +In the second case, where the keyword |as| is present, followed by some option +in square brackets, but nothing following the closing square bracket, when the +tick or grid line at position \meta{value} is shown, the \meta{local options} +are executed first. These can use the |style| key or the |node style| key to +configure the appearance of this single tick or grid line. You can also use +keys like |low| or |high| to influence how large the grid lines or the ticks +are or keys like |tick text at low| to explicitly hide or show a tick label. + +In the third case, which is only important for |ticks| and not for |grid|, the +same happens as in the second case, but the text that is shown as tick label is +\meta{text} rather than the automatically generated tick label. This automatic +generation of tick labels is explained in the following. +% \begin{codeexample}[] \tikz \datavisualization [scientific axes=clean, @@ -2215,36 +2219,33 @@ labels is explained in the following. }; \end{codeexample} - -A value like ``2'' or ``17'' could just be used as \meta{text} to be -displayed in the node of a tick label. However, things are more -difficult when the to-be-shown value is $0.0000000015$, because we -then would typically (but not always) prefer something like $1.5 \cdot -10^{-9}$ to be shown. Also, we might wish a unit to be added like -$23\mathrm{m}/\mathrm{s}$. Finally, we might wish a number like -$3.141$ to be replaced by $\pi$. For these reasons, the data -visualization system does not simply put the to-be-shown value in a -node as plain text. Instead, the number is passed to a -\emph{typesetter} whose job it is to typeset this number nicely using -\TeX's typesetting capabilities. The only exception is, as indicated -above, the third syntax version of the |at| and |also at| keys, where -\meta{text} is placed in the tick label's node, regardless of what the -typesetting would usually do. +A value like ``2'' or ``17'' could just be used as \meta{text} to be displayed +in the node of a tick label. However, things are more difficult when the +to-be-shown value is $0.0000000015$, because we then would typically (but not +always) prefer something like $1.5 \cdot 10^{-9}$ to be shown. Also, we might +wish a unit to be added like $23\mathrm{m}/\mathrm{s}$. Finally, we might wish +a number like $3.141$ to be replaced by $\pi$. For these reasons, the data +visualization system does not simply put the to-be-shown value in a node as +plain text. Instead, the number is passed to a \emph{typesetter} whose job it +is to typeset this number nicely using \TeX's typesetting capabilities. The +only exception is, as indicated above, the third syntax version of the |at| and +|also at| keys, where \meta{text} is placed in the tick label's node, +regardless of what the typesetting would usually do. The text produced by the automatic typesetting is computed as follows: +% \begin{enumerate} -\item The current contents of the key |tick prefix| is put into the node. -\item This is followed by a call of the key |tick typesetting| which - gets the \meta{value} of the tick as its argument in scientific - notation. -\item This is followed by the contents of the key |tick suffix|. + \item The current contents of the key |tick prefix| is put into the node. + \item This is followed by a call of the key |tick typesetting| which gets + the \meta{value} of the tick as its argument in scientific notation. + \item This is followed by the contents of the key |tick suffix|. \end{enumerate} Let us have a look at these keys in detail: -\begin{key}{/tikz/data visualization/tick prefix=\meta{text} - (initially \normalfont empty)} - The \meta{text} will be put in front of every typeset tick: +\begin{key}{/tikz/data visualization/tick prefix=\meta{text} (initially \normalfont empty)} + The \meta{text} will be put in front of every typeset tick: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={ticks=few, length=2.5cm}, @@ -2255,15 +2256,17 @@ Let us have a look at these keys in detail: func y = \value x * \value x; }; \end{codeexample} + % \end{key} -\begin{key}{/tikz/data visualization/tick suffix=\meta{text} - (initially \normalfont empty)} - Works like |tick prefix|. This key is especially useful for adding - units like ``cm'' or ``$\mathrm m/\mathrm s$'' to every tick - label. For this reason, there is a (near) alias that is easier to memorize: - \begin{key}{/tikz/data visualization/tick unit=\meta{roman math text}} - A shorthand for |tick suffix={$\,\rm|\meta{roman math text}|$}|: +\begin{key}{/tikz/data visualization/tick suffix=\meta{text} (initially \normalfont empty)} + Works like |tick prefix|. This key is especially useful for adding units + like ``cm'' or ``$\mathrm m/\mathrm s$'' to every tick label. For this + reason, there is a (near) alias that is easier to memorize: + % + \begin{key}{/tikz/data visualization/tick unit=\meta{roman math text}} + A shorthand for |tick suffix={$\,\rm|\meta{roman math text}|$}|: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=3cm}, @@ -2275,21 +2278,20 @@ Let us have a look at these keys in detail: func y = \value x * \value x; }; \end{codeexample} - \end{key} + \end{key} \end{key} \begin{key}{/tikz/data visualization/tick typesetting=\meta{value}} - The key gets called for each number that should be typeset. The - argument \meta{value} will be in scientific notation (like |1.0e1| - for $10$). By default, this key applies |\pgfmathprintnumber| to its - argument. This command is a powerful number printer whose - configuration is documented in - Section~\ref{pgfmath-numberprinting}. - - You are invited to code underlying this key so that a different - typesetting mechanism is used. Here is a (not quite finished) - example that shows how, say, numbers could be printed in terms of - multiples of $\pi$: + The key gets called for each number that should be typeset. The argument + \meta{value} will be in scientific notation (like |1.0e1| for $10$). By + default, this key applies |\pgfmathprintnumber| to its argument. This + command is a powerful number printer whose configuration is documented in + Section~\ref{pgfmath-numberprinting}. + + You are invited to code underlying this key so that a different typesetting + mechanism is used. Here is a (not quite finished) example that shows how, + say, numbers could be printed in terms of multiples of $\pi$: + % \begin{codeexample}[] \def\mytypesetter#1{% \pgfmathparse{#1/pi}% @@ -2305,19 +2307,16 @@ Let us have a look at these keys in detail: func y = sin(\value x r); }; \end{codeexample} + % \end{key} - - \subsubsection{Stacked Ticks} - \label{section-dv-stacking} - - -Sometimes, the text of tick labels are so long or so numerous that the -text of adjacent tick labels overlap (or have too little padding): +Sometimes, the text of tick labels are so long or so numerous that the text of +adjacent tick labels overlap (or have too little padding): +% \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=2.5cm}, @@ -2327,9 +2326,12 @@ text of adjacent tick labels overlap (or have too little padding): func x = \value y*\value y; }; \end{codeexample} +% There are two ways to address this problem: +% \begin{itemize} -\item One can rotate the labels on horizontal axes: + \item One can rotate the labels on horizontal axes: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=2.5cm}, @@ -2340,10 +2342,12 @@ There are two ways to address this problem: func x = \value y*\value y; }; \end{codeexample} - This is often a good solution, but may be hard to read. Also - consider rotating labels only by $45^\circ$ or $30^\circ$. -\item One can specify different shifts of the nodes for the different - ticks, whereby the ticks text no longer overlap. + % + This is often a good solution, but may be hard to read. Also consider + rotating labels only by $45^\circ$ or $30^\circ$. + \item One can specify different shifts of the nodes for the different + ticks, whereby the ticks text no longer overlap. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=2.5cm}, @@ -2357,10 +2361,12 @@ There are two ways to address this problem: func x = \value y*\value y; }; \end{codeexample} - However, specifying shifts ``by hand'' in the above way is not - always an option, especially when the tick positions should be - computed automatically. Instead, the |stack| option can be used, - which is much easier to use and gives better results: + % + However, specifying shifts ``by hand'' in the above way is not always + an option, especially when the tick positions should be computed + automatically. Instead, the |stack| option can be used, which is much + easier to use and gives better results: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=2.5cm}, x axis={ticks=stack}, @@ -2370,44 +2376,44 @@ There are two ways to address this problem: func x = \value y*\value y; }; \end{codeexample} + % \end{itemize} - -The |stack| option is actually just a style that gives you access to -the general even/odd mechanism for ticks with labels. Whenever a tick -mark is created where a tick label is also to be drawn, two special -things happen: - +The |stack| option is actually just a style that gives you access to the +general even/odd mechanism for ticks with labels. Whenever a tick mark is +created where a tick label is also to be drawn, two special things happen: +% \begin{enumerate} -\item For every odd tick mark, the |every odd tick| style is executed, - for every even tick mark the |every even tick|. Here, ``odd'' and - ``even'' are with respect to the order in which the ticks have been - added to the list of |at| positions for each major, minor, or - subminor tick list, not with respect to the order in which they will - appear on the axis. Thus, when you write + \item For every odd tick mark, the |every odd tick| style is executed, for + every even tick mark the |every even tick|. Here, ``odd'' and ``even'' + are with respect to the order in which the ticks have been added to the + list of |at| positions for each major, minor, or subminor tick list, + not with respect to the order in which they will appear on the axis. + Thus, when you write + % \begin{codeexample}[code only] ticks={major at={1,2,3,4}, major at={0,-1,-2}, minor at={9,8,7}} \end{codeexample} - then for |1|, |3|, |0|, and |-2| as well as |9| and |7| the key - |every odd tick| will be executed, while |every even tick| will be - executed for positions |2|, |4|, |-1|, and also |8|. -\item When a tick node label is shown at the |low| position of the - tick mark, the dimension stored in the key - |tick text low even padding| is added to the |low| value. Provided - that this padding is not zero (which is the default), the length of - the even tick marks will be increased and the tick label node will - be placed at a greater distance from the axis. - - Similar keys exist for padding ticks with labels at high positions - and also at even positions. + % + then for |1|, |3|, |0|, and |-2| as well as |9| and |7| the key + |every odd tick| will be executed, while |every even tick| will be + executed for positions |2|, |4|, |-1|, and also |8|. + \item When a tick node label is shown at the |low| position of the tick + mark, the dimension stored in the key |tick text low even padding| is + added to the |low| value. Provided that this padding is not zero (which + is the default), the length of the even tick marks will be increased + and the tick label node will be placed at a greater distance from the + axis. + + Similar keys exist for padding ticks with labels at high positions and + also at even positions. \end{enumerate} - -\begin{key}{/tikz/data visualization/tick text low even - padding=\meta{dimension} (initially 0pt)} - When a tick label is shown at the low position of an even tick, the - \meta{distance} is added to the |low| value, see also - Section~\ref{section-dv-visualize-ticks}. +\begin{key}{/tikz/data visualization/tick text low even padding=\meta{dimension} (initially 0pt)} + When a tick label is shown at the low position of an even tick, the + \meta{distance} is added to the |low| value, see also + Section~\ref{section-dv-visualize-ticks}. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=2.5cm}, @@ -2418,36 +2424,38 @@ ticks={major at={1,2,3,4}, major at={0,-1,-2}, minor at={9,8,7}} func x = \value y*\value y; }; \end{codeexample} - Note that \meta{dimension} should usually be non-positive. + % + Note that \meta{dimension} should usually be non-positive. \end{key} The following keys work similarly: +% \begin{key}{/tikz/data visualization/tick text low odd padding=\meta{dimension} (initially 0pt)} \end{key} +% \begin{key}{/tikz/data visualization/tick text high even padding=\meta{dimension} (initially 0pt)} \end{key} +% \begin{key}{/tikz/data visualization/tick text high odd padding=\meta{dimension} (initially 0pt)} \end{key} -\begin{key}{/tikz/data visualization/tick text odd - padding=\meta{dimension}} - A shorthand for setting |tick text odd low padding| and - |tick text odd high padding| at the same time. +\begin{key}{/tikz/data visualization/tick text odd padding=\meta{dimension}} + A shorthand for setting |tick text odd low padding| and + |tick text odd high padding| at the same time. \end{key} -\begin{key}{/tikz/data visualization/tick text even - padding=\meta{dimension}} - A shorthand for setting |tick text even low padding| and - |tick text even high padding| at the same time. +\begin{key}{/tikz/data visualization/tick text even padding=\meta{dimension}} + A shorthand for setting |tick text even low padding| and + |tick text even high padding| at the same time. \end{key} -\begin{key}{/tikz/data visualization/tick text - padding=\meta{dimension}} - Sets all text paddings to \meta{dimension}. +\begin{key}{/tikz/data visualization/tick text padding=\meta{dimension}} + Sets all text paddings to \meta{dimension}. \end{key} \begin{key}{/tikz/data visualization/stack=\meta{dimension} (default 1em)} - Shorthand for |tick text even padding=|\meta{dimension}. + Shorthand for |tick text even padding=|\meta{dimension}. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=2.5cm}, @@ -2458,13 +2466,13 @@ The following keys work similarly: func x = \value y*\value y; }; \end{codeexample} + % \end{key} \begin{key}{/tikz/data visualization/stack'=\meta{dimension}} - Shorthand for |tick text odd padding=|\meta{dimension}. The - difference to |stack| is that the set of value that are - ``lowered'' is exactly exchanged with the set of value ``lowered'' - by |stack|. + Shorthand for |tick text odd padding=|\meta{dimension}. The difference to + |stack| is that the set of value that are ``lowered'' is exactly exchanged + with the set of value ``lowered'' by |stack|. \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=2.5cm}, @@ -2475,13 +2483,13 @@ The following keys work similarly: func x = \value y*\value y; }; \end{codeexample} + % \end{key} -Note that the above keys have an effect on all tick labels of an axis, -also on special ticks that you may have added using the |also at| -key. When using the |stack| key, you should specify a |tick text padding| -explicitly for such keys: - +Note that the above keys have an effect on all tick labels of an axis, also on +special ticks that you may have added using the |also at| key. When using the +|stack| key, you should specify a |tick text padding| explicitly for such keys: +% \begin{codeexample}[width=7cm] \tikz \datavisualization [scientific axes, @@ -2496,31 +2504,29 @@ explicitly for such keys: \subsubsection{Reference: Basic Strategies} - \label{section-dv-strategies} \begin{key}{/tikz/data visualization/axis options/linear steps} - This strategy places ticks at positions that are evenly spaced by - the current value of |step|. - - In detail, the following happens: Let $a$ be the minimum value of the - data values along the axis and let $b$ be the maximum. Let the - current \emph{stepping} be $s$ (the stepping is set using the |step| - option, see below) and let the current \emph{phasing} be $p$ (set - using the |phase|) option. Then ticks are placed all positions - $i\cdot s + p$ that lie in the interval $[a,b]$, where $i$ ranges - over all integers. - - The tick positions computed in the way described above are - \emph{mayor} step positions. In addition to these, if the key - |minor steps between steps| is set to some number $n$, then $n$ many - minor ticks are introduced between each two mayor ticks (and also - before and after the last mayor tick, provided the values still lie - in the interval $[a,b]$). Note that is $n$ is $1$, then one minor tick - will be added in the middle between any two mayor ticks. Use a value - of $9$ (not $10$) to partition the interval between two mayor ticks - into ten equally sized minor intervals. - + This strategy places ticks at positions that are evenly spaced by the + current value of |step|. + + In detail, the following happens: Let $a$ be the minimum value of the data + values along the axis and let $b$ be the maximum. Let the current + \emph{stepping} be $s$ (the stepping is set using the |step| option, see + below) and let the current \emph{phasing} be $p$ (set using the |phase|) + option. Then ticks are placed all positions $i\cdot s + p$ that lie in the + interval $[a,b]$, where $i$ ranges over all integers. + + The tick positions computed in the way described above are \emph{mayor} + step positions. In addition to these, if the key + |minor steps between steps| is set to some number $n$, then $n$ many minor + ticks are introduced between each two mayor ticks (and also before and + after the last mayor tick, provided the values still lie in the interval + $[a,b]$). Note that is $n$ is $1$, then one minor tick will be added in the + middle between any two mayor ticks. Use a value of $9$ (not $10$) to + partition the interval between two mayor ticks into ten equally sized minor + intervals. + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization @@ -2535,23 +2541,23 @@ explicitly for such keys: }; \end{tikzpicture} \end{codeexample} + % \end{key} \label{section-dv-exponential-strategy} \begin{key}{/tikz/data visualization/axis options/exponential steps} - This strategy produces ticks at positions that are appropriate for - logarithmic plots. It is automatically selected when you use the - |logarithmic| option with an axis. - - In detail, the following happens: As for |linear steps| let numbers - $a$, $b$, $s$, and $p$ be given. Then, mayor ticks are placed at all - positions $10^{i\cdot s+p}$ that lie in the interval $[a,b]$ for $i - \in \mathbb Z$. + This strategy produces ticks at positions that are appropriate for + logarithmic plots. It is automatically selected when you use the + |logarithmic| option with an axis. - The minor steps are added in the same way as for |linear steps|. In - particular, they interpolate \emph{linearly} between mayor steps. + In detail, the following happens: As for |linear steps| let numbers $a$, + $b$, $s$, and $p$ be given. Then, mayor ticks are placed at all positions + $10^{i\cdot s+p}$ that lie in the interval $[a,b]$ for $i \in \mathbb{Z}$. + The minor steps are added in the same way as for |linear steps|. In + particular, they interpolate \emph{linearly} between mayor steps. + % \begin{codeexample}[] \begin{tikzpicture} \datavisualization @@ -2566,40 +2572,41 @@ explicitly for such keys: }; \end{tikzpicture} \end{codeexample} + % \end{key} - \subsubsection{Advanced: Defining New Placement Strategies} -\begin{key}{/tikz/data visualization/axis options/tick placement - strategy=\meta{macro}} - This key can be used to install a so-called \emph{tick placement - strategy}. Whenever |visualize ticks| is used to request some - ticks to be visualized, it is checked whether some automatic ticks - should be created. This is the case when the following key is set: - \begin{key}{/tikz/data visualization/compute step=\meta{code}} - The \meta{code} should compute a suitable value for the stepping - to be used by the \meta{macro} in the tick placement strategy. - - For instance, the |step| key sets |compute step| to - |\def\tikz@lib@dv@step{#1}|. Thus, when you say |step=5|, then the - desired stepping of |5| is communicated to the \meta{macro} via the - macro |\tikz@lib@dv@step|. - \end{key} - - Provided |compute step| is set to some nonempty value, upon - visualization of ticks the \meta{macro} is executed. Typically, - \meta{macro} will first call the \meta{code} stored in the key - |compute step|. Then, it should implement some strategy then uses - the value of the computed or desired stepping to create appropriate - |at| commands. To be precise, it should set the keys |major|, - |minor|, and/or |subminor| with some appropriate |at| values. - - Inside the call of \meta{macro}, the macro |\tikzdvaxis| will have - been set to the name of the axis for which default ticks need to be - computed. This allows you to access the minimum and the maximum - value stored in the |scaling mapper| of that axis. +\begin{key}{/tikz/data visualization/axis options/tick placement strategy=\meta{macro}} + This key can be used to install a so-called \emph{tick placement strategy}. + Whenever |visualize ticks| is used to request some ticks to be visualized, + it is checked whether some automatic ticks should be created. This is the + case when the following key is set: + % + \begin{key}{/tikz/data visualization/compute step=\meta{code}} + The \meta{code} should compute a suitable value for the stepping to be + used by the \meta{macro} in the tick placement strategy. + + For instance, the |step| key sets |compute step| to + |\def\tikz@lib@dv@step{#1}|. Thus, when you say |step=5|, then the + desired stepping of |5| is communicated to the \meta{macro} via the + macro |\tikz@lib@dv@step|. + \end{key} + + Provided |compute step| is set to some nonempty value, upon visualization + of ticks the \meta{macro} is executed. Typically, \meta{macro} will first + call the \meta{code} stored in the key |compute step|. Then, it should + implement some strategy then uses the value of the computed or desired + stepping to create appropriate |at| commands. To be precise, it should set + the keys |major|, |minor|, and/or |subminor| with some appropriate |at| + values. + + Inside the call of \meta{macro}, the macro |\tikzdvaxis| will have been set + to the name of the axis for which default ticks need to be computed. This + allows you to access the minimum and the maximum value stored in the + |scaling mapper| of that axis. + % \begin{codeexample}[width=7cm] \def\silly{ \tikzdatavisualizationset{major={at={ @@ -2617,46 +2624,44 @@ explicitly for such keys: }; \end{tikzpicture} \end{codeexample} + % \end{key} - - - \subsection{Advanced: Creating New Axis Systems} -The data visualization library comes with a number of predefined axis -systems, like |scientific axes=clean|, but it is also possible and -to define new axis systems. Doing so involves the following steps: - +The data visualization library comes with a number of predefined axis systems, +like |scientific axes=clean|, but it is also possible and to define new axis +systems. Doing so involves the following steps: +% \begin{enumerate} -\item Creating a number of axes. -\item Configuring attributes of these axes like their length or - default scaling. -\item Creating visual representations of the axes. -\item Creating visual representations of the ticks and grid lines. + \item Creating a number of axes. + \item Configuring attributes of these axes like their length or default + scaling. + \item Creating visual representations of the axes. + \item Creating visual representations of the ticks and grid lines. \end{enumerate} -The first step uses |new ... axis| keys to create new axes, the -last steps use |visualize ...| keys to create the visual -representations of the axes. +The first step uses |new ... axis| keys to create new axes, the last steps use +|visualize ...| keys to create the visual representations of the axes. -Note that the axis system has no control over the actual attribute -value ranges and neither over which ticks need to be drawn. The axis -system can only provide good defaults and then specify \emph{how} the -ticks or labels should be drawn and \emph{where} on the page -- but -not at which values. +Note that the axis system has no control over the actual attribute value ranges +and neither over which ticks need to be drawn. The axis system can only provide +good defaults and then specify \emph{how} the ticks or labels should be drawn +and \emph{where} on the page -- but not at which values. In the following, as a running example let us develop an axis system -|our system| that does the following: For the $x$-axis is looks like a -normal scientific axis system, but there are actually two $y$-axes: -One at the left and one at the right, each using a different -attribute, but both coexisting in the same picture. +|our system| that does the following: For the $x$-axis is looks like a normal +scientific axis system, but there are actually two $y$-axes: One at the left +and one at the right, each using a different attribute, but both coexisting in +the same picture. + \subsubsection{Creating the Axes} A new axis system is created as a style key with the prefix |/tikz/data visualization|. Thus, we would write: +% \begin{codeexample}[code only] \tikzset{ data visualization/our system/.style={ @@ -2665,9 +2670,9 @@ A new axis system is created as a style key with the prefix } \end{codeexample} -In our system we need three axis: The $x$-axis, the left axis and the -right axis. Since all of these axes are Cartesian axes, we write the -following: +In our system we need three axis: The $x$-axis, the left axis and the right +axis. Since all of these axes are Cartesian axes, we write the following: +% \begin{codeexample}[code only] \tikzset{ data visualization/our system/.style={ @@ -2680,28 +2685,30 @@ following: } } \end{codeexample} -As can be seen, we also configure things so that the $x$-axis will use -the |x| attribute by default (users can later change this by saying -|x axis={attribute=|\meta{some other attribute}|}|), but we do not -configure the attributes of the |left axis| nor the |right axis|. We -also make the left and right axis point upward (the |x axis| needs no -configuration here since a Cartesian axis points right by default). The -reason is the |left| would not be a particularly good attribute name -and this way we ensure that users have to pick names themselves -(hopefully good ones). - -The next step is to define a standard scaling for the axes. Here, we -can use the same as for |scientific axes|, so we would add the -following keys to the definition of |our system|: +% +As can be seen, we also configure things so that the $x$-axis will use the |x| +attribute by default (users can later change this by saying +|x axis={attribute=|\meta{some other attribute}|}|), but we do not configure +the attributes of the |left axis| nor the |right axis|. We also make the left +and right axis point upward (the |x axis| needs no configuration here since a +Cartesian axis points right by default). The reason is the |left| would not be +a particularly good attribute name and this way we ensure that users have to +pick names themselves (hopefully good ones). + +The next step is to define a standard scaling for the axes. Here, we can use +the same as for |scientific axes|, so we would add the following keys to the +definition of |our system|: +% \begin{codeexample}[code only] x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} \end{codeexample} -We now already have enough to try our system, although we will not yet -see any axes or ticks, but we will see the correct scaling of the -attributes. Let us first define a data group: +We now already have enough to try our system, although we will not yet see any +axes or ticks, but we will see the correct scaling of the attributes. Let us +first define a data group: +% \begin{codeexample}[] \tikz \datavisualization data group {people and money} = { data [set=people 1] { @@ -2731,7 +2738,7 @@ attributes. Let us first define a data group: 1960, 3 1970, 4 1990, 3.5 - } + } }; \end{codeexample} @@ -2759,66 +2766,65 @@ attributes. Let us first define a data group: people 2={style={visualizer color=blue!50}}, money 1={style={visualizer color=red}}, money 2={style={visualizer color=red!50}}] - data group {people and money}; + data group {people and money}; \end{codeexample} - \subsubsection{Visualizing the Axes} - \label{section-dv-visualize-axis} -We must now show the axes themselves. For this we can use the -|visualize axis| key: +We must now show the axes themselves. For this we can use the |visualize axis| +key: \begin{key}{/tikz/data visualization/axis options/visualize axis=\meta{options}} - This key is passed to an axis as an option. It causes a visual - representation of the axis to be created during the data visualization. The - \meta{options} are used to determine where the axis should be drawn - and how long it should be. We can specify, for instance, that an - axis should be drawn at the minimum value of another axis or where - another axis has the value |0|. - - \medskip - \textbf{The goto, high, and low Keys.} - In our example, the |left axis| should be shown at the left hand - side. This is the position where the |x axis| has its minimum - value. To specify this, we would use the following code: + This key is passed to an axis as an option. It causes a visual + representation of the axis to be created during the data visualization. The + \meta{options} are used to determine where the axis should be drawn and how + long it should be. We can specify, for instance, that an axis should be + drawn at the minimum value of another axis or where another axis has the + value |0|. + + + \medskip + \textbf{The goto, high, and low Keys.} + In our example, the |left axis| should be shown at the left hand side. This + is the position where the |x axis| has its minimum value. To specify this, + we would use the following code: + % \begin{codeexample}[code only] left axis={ visualize axis={ x axis={ goto=min } } \end{codeexample} - As can be seen, we can pass another axis as an \meta{option} to - |visualize axis|, where we pass the following key to the axis in - turn: - \begin{key}{/tikz/data visualization/axis options/goto=\meta{value}} - The key can be passed to an axis. It will set the attribute - monitored by the axis to the given \meta{value}, which is usually - some number. However, \meta{value} may also be one of the - following, which causes a special behaviour: - \begin{itemize} - \item - |min|: The attribute is set to the minimal value that the - attribute has attained along this axis. - \item - |max|: Like |min|. - \item - |padded min|: This will also set the \meta{attribute} monitored - by the axis to the same value as |min|. Additionally, however, - the subkey |/data point/|\meta{attribute}|/offset| is set to the - current padding for the minimum, see the description of - |padding min| later on. The effect of this is that the actual - point ``meant'' by the attribute is offset by this padding along - the attribute's axis. - \item - |padded max|: Like |padded min|. - \end{itemize} - \end{key} + % + As can be seen, we can pass another axis as an \meta{option} to + |visualize axis|, where we pass the following key to the axis in turn: + % + \begin{key}{/tikz/data visualization/axis options/goto=\meta{value}} + The key can be passed to an axis. It will set the attribute monitored + by the axis to the given \meta{value}, which is usually some number. + However, \meta{value} may also be one of the following, which causes a + special behaviour: + % + \begin{itemize} + \item |min|: The attribute is set to the minimal value that the + attribute has attained along this axis. + \item |max|: Like |min|. + \item |padded min|: This will also set the \meta{attribute} + monitored by the axis to the same value as |min|. + Additionally, however, the subkey + |/data point/|\meta{attribute}|/offset| is set to the current + padding for the minimum, see the description of |padding min| + later on. The effect of this is that the actual point ``meant'' + by the attribute is offset by this padding along the + attribute's axis. + \item |padded max|: Like |padded min|. + \end{itemize} + \end{key} - The |right axis| would be visualized the same way, only at - |goto=max|. The $x$-axis actually need to be visualized - \emph{twice}: Once at the bottom and once at the top. Thus, we need - to call |visualize axis| twice for this axis: - + The |right axis| would be visualized the same way, only at |goto=max|. The + $x$-axis actually need to be visualized \emph{twice}: Once at the bottom + and once at the top. Thus, we need to call |visualize axis| twice for this + axis: +% \tikzdatavisualizationset{ our system/.style={ new Cartesian axis=x axis, @@ -2847,30 +2853,31 @@ left axis={ visualize axis={ x axis={ goto=min } } left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={people 1, people 2, money 1, money 2}] - data group {people and money}; -\end{codeexample} - - There is another key that is similar to |goto|, but has a slightly - different semantics: - \begin{key}{/tikz/data visualization/axis options/goto pos=\meta{fraction}} - The key works like |goto|, only the \meta{fraction} is not - interpreted as a value but as a fraction of the way between the - minimum and the maximum value for this axis. - - Suppose that for an axis the attribute range interval is - $[500,1000]$ and the reasonable interval is $[1,3]$. Then for a - \meta{fraction} of |0|, the mapping process would choose value - $1$ from the reasonable interval, for a \meta{fraction} of |1| the - position $3$ from the reasonable interval, and for a - \meta{fraction} or |0.25| the position $1.5$ since it is one - quarter at the distance from $1$ to $3$. - - Note that neither the attribute range interval nor the - transformation function for the attribute are important for the - |goto pos| option -- the \meta{fraction} is computed with respect - to the reasonable interval. Also note that the values of the - actual attribute corresponding to the fractional positions in the - reasonable interval are not computed. + data group {people and money}; +\end{codeexample} + + There is another key that is similar to |goto|, but has a slightly + different semantics: + % + \begin{key}{/tikz/data visualization/axis options/goto pos=\meta{fraction}} + The key works like |goto|, only the \meta{fraction} is not interpreted + as a value but as a fraction of the way between the minimum and the + maximum value for this axis. + + Suppose that for an axis the attribute range interval is $[500,1000]$ + and the reasonable interval is $[1,3]$. Then for a \meta{fraction} of + |0|, the mapping process would choose value $1$ from the reasonable + interval, for a \meta{fraction} of |1| the position $3$ from the + reasonable interval, and for a \meta{fraction} or |0.25| the position + $1.5$ since it is one quarter at the distance from $1$ to $3$. + + Note that neither the attribute range interval nor the transformation + function for the attribute are important for the |goto pos| option -- + the \meta{fraction} is computed with respect to the reasonable + interval. Also note that the values of the actual attribute + corresponding to the fractional positions in the reasonable interval + are not computed. + % \begin{codeexample}[] \tikzset{ data visualization/our system/.append style={ @@ -2884,73 +2891,78 @@ left axis={ visualize axis={ x axis={ goto=min } } left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={people 1, people 2, money 1, money 2}] - data group {people and money}; -\end{codeexample} - \end{key} - - By default, when an axis is visualized, it spans the set of all - possible values for the monitored attribute, that is, from |min| to - |max|. However, there are actually two keys that allow you to adjust - this: - \begin{key}{/tikz/data visualization/low=\meta{value}} - This is the attribute value where the axis visualization - starts. The same special values as for |goto| are permissible - (like |min| or |padded min|, but also |0| or |1|). - \end{key} - \begin{key}{/tikz/data visualization/high=\meta{value}} - Like |low|, only for where the axis ends. - \end{key} - - By default, |low=min| and |high=max| are set for an axis - visualization. Another sensible setting is |low=padded min| and - |high=padded max|. The following key provides a shorthand for this: - \begin{key}{/tikz/data visualization/padded} - Shorthand for |low=padded min, high=padded max|. - \end{key} - As an example, consider the |scientific axes=clean|. Here, each axis - is actually drawn three times: Once at the minimum, once at the - maximum and then once more at the padded minimum. - - - \medskip - \textbf{The axis line.} - When an axis is drawn, \tikzname\ does not simply draw a straight - line from the |low| position to the |high| position. In reality, the - data visualization system uses the two commands |\pgfpathdvmoveto| - and |\pgfpathdvlineto| internally. These will replace the straight - line by a curve in certain situations. For instance, in a polar - coordinate system, if an axis should be drawn along an angle axis - for a fixed radius, an arc will be used instead of a straight line. - - \medskip - \textbf{Styling the axis.} - As can be seen, we now get the axis we want (but without the ticks, - visualizing them will be explained later). The axis is, however, - simply a black line. We can \emph{style} the axis in a manner - similar to styling ticks and grid lines, see - Section~\ref{section-dv-style}. In detail, the following styles get - executed: - \begin{enumerate} - \item |axis layer| - \item |every axis| - \item |styling| - \end{enumerate} - Additionally, even before |every axis| is executed, |low=min| and - |high=max| are executed. - - \begin{stylekey}{/tikz/data visualization/axis layer (initially on - background layer)} - The layer on which the axis is drawn. See the description of - |grid layer| on page~\ref{section-dv-grid-layer} for details. - \end{stylekey} - - \begin{stylekey}{/tikz/data visualization/every axis} - Put styling of the axis here. It is usually a good idea to set - this style to |style={black!50}|. - \end{stylekey} - - Recall that the |styling| key is set using the |style| key, see - Section~\ref{section-dv-style}. + data group {people and money}; +\end{codeexample} + \end{key} + + By default, when an axis is visualized, it spans the set of all possible + values for the monitored attribute, that is, from |min| to |max|. However, + there are actually two keys that allow you to adjust this: + % + \begin{key}{/tikz/data visualization/low=\meta{value}} + This is the attribute value where the axis visualization starts. The + same special values as for |goto| are permissible (like |min| or + |padded min|, but also |0| or |1|). + \end{key} + % + \begin{key}{/tikz/data visualization/high=\meta{value}} + Like |low|, only for where the axis ends. + \end{key} + + By default, |low=min| and |high=max| are set for an axis visualization. + Another sensible setting is |low=padded min| and |high=padded max|. The + following key provides a shorthand for this: + % + \begin{key}{/tikz/data visualization/padded} + Shorthand for |low=padded min, high=padded max|. + \end{key} + % + As an example, consider the |scientific axes=clean|. Here, each axis is + actually drawn three times: Once at the minimum, once at the maximum and + then once more at the padded minimum. + + + \medskip + \textbf{The axis line.} + When an axis is drawn, \tikzname\ does not simply draw a straight line from + the |low| position to the |high| position. In reality, the data + visualization system uses the two commands |\pgfpathdvmoveto| and + |\pgfpathdvlineto| internally. These will replace the straight line by a + curve in certain situations. For instance, in a polar coordinate system, if + an axis should be drawn along an angle axis for a fixed radius, an arc will + be used instead of a straight line. + + + \medskip + \textbf{Styling the axis.} + As can be seen, we now get the axis we want (but without the ticks, + visualizing them will be explained later). The axis is, however, simply a + black line. We can \emph{style} the axis in a manner similar to styling + ticks and grid lines, see Section~\ref{section-dv-style}. In detail, the + following styles get executed: + % + \begin{enumerate} + \item |axis layer| + \item |every axis| + \item |styling| + \end{enumerate} + % + Additionally, even before |every axis| is executed, |low=min| and + |high=max| are executed. + + \begin{stylekey}{/tikz/data visualization/axis layer (initially on background layer)} + The layer on which the axis is drawn. See the description of + |grid layer| on page~\ref{section-dv-grid-layer} for details. + \end{stylekey} + + \begin{stylekey}{/tikz/data visualization/every axis} + Put styling of the axis here. It is usually a good idea to set this + style to |style={black!50}|. + \end{stylekey} + + Recall that the |styling| key is set using the |style| key, see + Section~\ref{section-dv-style}. + % \tikzset{ } \begin{codeexample}[] @@ -2969,7 +2981,7 @@ left axis={ visualize axis={ x axis={ goto=min } } left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={people 1, people 2, money 1, money 2}] - data group {people and money}; + data group {people and money}; \end{codeexample} \tikzset{ data visualization/our system/.append style={ @@ -2980,27 +2992,27 @@ left axis={ visualize axis={ x axis={ goto=min } } visualize axis={left axis={goto=max}}}, } } - - \medskip - \textbf{Padding the Axis.} - When an axis is visualized, it is often a good idea to make it ``a - little bit longer'' or to ``remove it a bit from the border,'' because - the visualization of an axis should not interfere with the actual - data. For this reason, a \emph{padding} can be specified for axes: - - \begin{key}{/tikz/data visualization/axis options/padding min=\meta{dimension}} - This is the dimension that is used whenever |goto=padded min| is - used. The \meta{dimension} is then put into the |offset| subkey of - the attribute monitored by the axis. When a data point is - transformed by a linear transformer and when this subkey is - nonzero, this offset is added. (For an angle axis of a polar - transformer, the \meta{dimension} is interpreted as an additional - angle rather than as an additional distance). Note that - \meta{dimension} should typically be negative since - ``adding the \meta{dimension}'' will then make the axis longer - (because it starts at a smaller value). The standard - axis systems set the padding to some default and take its value - into account: + + + \medskip + \textbf{Padding the Axis.} + When an axis is visualized, it is often a good idea to make it ``a little + bit longer'' or to ``remove it a bit from the border'', because the + visualization of an axis should not interfere with the actual data. For + this reason, a \emph{padding} can be specified for axes: + + \begin{key}{/tikz/data visualization/axis options/padding min=\meta{dimension}} + This is the dimension that is used whenever |goto=padded min| is used. + The \meta{dimension} is then put into the |offset| subkey of the + attribute monitored by the axis. When a data point is transformed by a + linear transformer and when this subkey is nonzero, this offset is + added. (For an angle axis of a polar transformer, the \meta{dimension} + is interpreted as an additional angle rather than as an additional + distance). Note that \meta{dimension} should typically be negative + since ``adding the \meta{dimension}'' will then make the axis longer + (because it starts at a smaller value). The standard axis systems set + the padding to some default and take its value into account: + % \begin{codeexample}[width=8cm] \begin{tikzpicture} \datavisualization [scientific axes=clean, @@ -3013,8 +3025,9 @@ left axis={ visualize axis={ x axis={ goto=min } } \end{tikzpicture} \end{codeexample} - Using padded and using the |padded| key, we can visualize our axis - ``a little removed from the actual data'': + Using padded and using the |padded| key, we can visualize our axis ``a + little removed from the actual data'': + % \begin{codeexample}[] \tikzset{ data visualization/our system/.append style={ @@ -3031,88 +3044,90 @@ left axis={ visualize axis={ x axis={ goto=min } } left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={people 1, people 2, money 1, money 2}] - data group {people and money}; -\end{codeexample} - \end{key} + data group {people and money}; +\end{codeexample} + \end{key} - \begin{key}{/tikz/data visualization/axis options/padding max=\meta{dimension}} - Works like |padding min|, but \meta{dimension} should typically be positive. - \end{key} - - \begin{key}{/tikz/data visualization/axis options/padding=\meta{dimension}} - Sets both |padding min| to the negated value of \meta{dimension} and - |padding max| to \meta{dimension}. - \end{key} -\end{key} + \begin{key}{/tikz/data visualization/axis options/padding max=\meta{dimension}} + Works like |padding min|, but \meta{dimension} should typically be + positive. + \end{key} + \begin{key}{/tikz/data visualization/axis options/padding=\meta{dimension}} + Sets both |padding min| to the negated value of \meta{dimension} and + |padding max| to \meta{dimension}. + \end{key} +\end{key} \subsubsection{Visualizing Grid Lines} - \label{section-dv-visualize-gridlines} -As explained earlier, the |grid| key is used to specify at which -positions grid lines should be drawn in principle. However, this key -does not actually cause any grid lines to be drawn. Instead, the -|visualize grid| key is used by the axis system to specify how grid -lines are drawn. +As explained earlier, the |grid| key is used to specify at which positions grid +lines should be drawn in principle. However, this key does not actually cause +any grid lines to be drawn. Instead, the |visualize grid| key is used by the +axis system to specify how grid lines are drawn. \begin{key}{/tikz/data visualization/axis options/visualize grid=\meta{options}} - This key is passed to an axis. It causes grid lines to be drawn at - the positions specified by the |grid| key for this axis. The - \meta{options} govern where and how the grid lines will be drawn. - - \medskip - \textbf{The direction axis.} - At first sight, one might expect that the grid lines for an axis - should simply be drawn perpendicular to the axis between the minimum - and maximum value of the axis. However, things are somewhat more - difficult in reality: - \begin{enumerate} - \item A grid line is supposed to indicate all positions where a - certain attribute attains a fixed value. But, then, a grid line - does not really need to be a grid \emph{line}. Consider for - instance a three dimensional axis system. A ``grid line'' for the - $x$-coordinate |3| would actually be a ``grid plane.'' - \item For a polar coordinate system and a fixed radius, this set of - positions at a certain radius is not a straight line, but an - arc. For more complicated coordinate systems such as the one - arising from three-dimensional spherical projections, a grid line - may well be a fairly involved curve. - \end{enumerate} - The |visualize grid| command addresses these complications as - follows: - \begin{enumerate} - \item A grid line is always a line, not a plane or a volume. This - means that in the example of a three dimensional axis system and - the $x$-attribute being |3|, one would have to choose whether the - grid line should go ``along'' the $y$-axis or ``along'' the - $z$-axis for this position. One can, however, call the - |visualize grid| command twice, once for each direction, to cause - grid lines to be shown for both directions. - \item A grid line is created by moving to a start position and then - doing a lineto to the target position. However, the ``moveto'' - and ``lineto'' are done by calling special commands of the data - visualization system. These special commands allow coordinate - system to ``notice'' that the line is along an axis and will allow - them to replace the straight line by an appropriate curve. The - polar axes systems employ this strategy, for instance. - \end{enumerate} - - By the above discussion, in order to create a grid line for - attribute $a$ having value $v$, we need to specify an axis ``along'' - which the line should be drawn. When there are only two axes, this - is usually ``the other axis''. This ``other axis'' is specified using the following key: - \begin{key}{/tikz/data visualization/direction axis=\meta{axis name}} - You must pass this key as an \meta{option} each time you use - |visualize axis|. When the grid line is drawn, the attribute $a$ - is set to $v$ and the axis \meta{axis name}'s attribute is set - once to the current value of |low| and once to |high|. Then a line - is drawn between these two positions using |\pgfpathdvlineto|. - \end{key} - The |low| and |high| keys are the same as the ones used in the - |visualize axis| key. - + This key is passed to an axis. It causes grid lines to be drawn at the + positions specified by the |grid| key for this axis. The \meta{options} + govern where and how the grid lines will be drawn. + + + \medskip + \textbf{The direction axis.} + At first sight, one might expect that the grid lines for an axis should + simply be drawn perpendicular to the axis between the minimum and maximum + value of the axis. However, things are somewhat more difficult in reality: + % + \begin{enumerate} + \item A grid line is supposed to indicate all positions where a certain + attribute attains a fixed value. But, then, a grid line does not + really need to be a grid \emph{line}. Consider for instance a three + dimensional axis system. A ``grid line'' for the $x$-coordinate |3| + would actually be a ``grid plane''. + \item For a polar coordinate system and a fixed radius, this set of + positions at a certain radius is not a straight line, but an arc. + For more complicated coordinate systems such as the one arising + from three-dimensional spherical projections, a grid line may well + be a fairly involved curve. + \end{enumerate} + % + The |visualize grid| command addresses these complications as follows: + % + \begin{enumerate} + \item A grid line is always a line, not a plane or a volume. This means + that in the example of a three dimensional axis system and the + $x$-attribute being |3|, one would have to choose whether the grid + line should go ``along'' the $y$-axis or ``along'' the $z$-axis for + this position. One can, however, call the |visualize grid| command + twice, once for each direction, to cause grid lines to be shown for + both directions. + \item A grid line is created by moving to a start position and then + doing a lineto to the target position. However, the ``moveto'' and + ``lineto'' are done by calling special commands of the data + visualization system. These special commands allow coordinate + system to ``notice'' that the line is along an axis and will allow + them to replace the straight line by an appropriate curve. The + polar axes systems employ this strategy, for instance. + \end{enumerate} + + By the above discussion, in order to create a grid line for attribute $a$ + having value $v$, we need to specify an axis ``along'' which the line + should be drawn. When there are only two axes, this is usually ``the other + axis''. This ``other axis'' is specified using the following key: + % + \begin{key}{/tikz/data visualization/direction axis=\meta{axis name}} + You must pass this key as an \meta{option} each time you use + |visualize axis|. When the grid line is drawn, the attribute $a$ is set + to $v$ and the axis \meta{axis name}'s attribute is set once to the + current value of |low| and once to |high|. Then a line is drawn between + these two positions using |\pgfpathdvlineto|. + \end{key} + % + The |low| and |high| keys are the same as the ones used in the + |visualize axis| key. + % \begin{codeexample}[] \tikz \datavisualization [ xyz Cartesian cabinet, @@ -3124,48 +3139,50 @@ lines are drawn. 0, 0, 1 0, 1, 0 2, 2, 2 - }; -\end{codeexample} + }; +\end{codeexample} + % \begin{codeexample}[] \tikz \datavisualization [ xyz Cartesian cabinet, all axes={visualize axis={low=0, style=->}, grid=many}, - x axis={visualize grid={direction axis=z axis}}, + x axis={visualize grid={direction axis=z axis}}, z axis={visualize grid={direction axis=x axis}, - visualize grid={direction axis=y axis},}, + visualize grid={direction axis=y axis},}, visualize as scatter] data { x, y, z 0, 0, 1 0, 1, 0 2, 2, 2 - }; -\end{codeexample} - - \medskip - \textbf{Styling the grid lines.} - When a grid line is draw, styles are applied as described in - Section~\ref{section-dv-styling-grid-lines}. - - \medskip - \textbf{The major, minor, and subminor grid lines.} - The |grid| option allows you to specify for each kind of grid line - (major, minor, or subminor) a set of different values for which - these grid lines should be drawn. Correspondingly, it is also - possible to configure for each kind of grid line how it should be - drawn. For this, the |major|, |minor|, |subminor|, and also the - |common| keys can be used inside the \meta{options} of - |visualize grid|. While as option to |grid| these keys are used to - specify |at| values, as options of |visualize grid| they are used to - configure the different kinds of grid lines. - - Most of the time, no special configuration is necessary since all - styling is best done by configuring keys like - |every major grid|. You need to use a key like |major| only if you - wish to configure for instance the |low| or |high| values of a - |major| grid line differently from those of |minor| grid lines -- - are rather unlikely setting -- or when the styling should deviate - from the usual settings. + }; +\end{codeexample} + + + \medskip + \textbf{Styling the grid lines.} + When a grid line is draw, styles are applied as described in + Section~\ref{section-dv-styling-grid-lines}. + + + \medskip + \textbf{The major, minor, and subminor grid lines.} + The |grid| option allows you to specify for each kind of grid line (major, + minor, or subminor) a set of different values for which these grid lines + should be drawn. Correspondingly, it is also possible to configure for each + kind of grid line how it should be drawn. For this, the |major|, |minor|, + |subminor|, and also the |common| keys can be used inside the + \meta{options} of |visualize grid|. While as option to |grid| these keys + are used to specify |at| values, as options of |visualize grid| they are + used to configure the different kinds of grid lines. + + Most of the time, no special configuration is necessary since all styling + is best done by configuring keys like |every major grid|. You need to use a + key like |major| only if you wish to configure for instance the |low| or + |high| values of a |major| grid line differently from those of |minor| grid + lines -- are rather unlikely setting -- or when the styling should deviate + from the usual settings. + % \begin{codeexample}[] \tikz \datavisualization [ xy Cartesian, @@ -3179,17 +3196,17 @@ lines are drawn. x, y 0, 0 3, 3 - }; -\end{codeexample} + }; +\end{codeexample} + % \end{key} -Returning to the example of |our system| with the two axis systems, it -is straight-forward to configure the grid lines of the $x$-axis: The -direction axis is either of the other two axis (they point in the same -direction and they have the same range). For the other two axes, we -visualize one grid independently of the other, using different colors. - - +Returning to the example of |our system| with the two axis systems, it is +straight-forward to configure the grid lines of the $x$-axis: The direction +axis is either of the other two axis (they point in the same direction and they +have the same range). For the other two axes, we visualize one grid +independently of the other, using different colors. +% \begin{codeexample}[] \tikzset{ data visualization/our system/.append style={ @@ -3206,27 +3223,25 @@ visualize one grid independently of the other, using different colors. left axis ={attribute=money, grid=some}, right axis={attribute=people, grid=few}, visualize as line/.list={people 1, people 2, money 1, money 2}] - data group {people and money}; + data group {people and money}; \end{codeexample} - \subsubsection{Visualizing the Ticks and Tick Labels} - \label{section-dv-visualize-ticks} \begin{key}{/tikz/data visualization/axis options/visualize ticks=\meta{options}} - Visualizing a tick involves (possibly) drawing a tick mark and - adding (possibly) the tick node. The process is similar to - |visualize grid|: Users use the |ticks| key to configure how many - ticks they would like for an axis and at which positions. The axis - system uses the |visualize ticks| key to specify where these ticks - should actually be shown. - - Unlike grid lines, which are typically only visualized once for each - combination of an axis and a direction axis, tick marks might be - visualized at different places for the same axis. Consider for - instance the |scientific axes|: + Visualizing a tick involves (possibly) drawing a tick mark and adding + (possibly) the tick node. The process is similar to |visualize grid|: Users + use the |ticks| key to configure how many ticks they would like for an axis + and at which positions. The axis system uses the |visualize ticks| key to + specify where these ticks should actually be shown. + + Unlike grid lines, which are typically only visualized once for each + combination of an axis and a direction axis, tick marks might be visualized + at different places for the same axis. Consider for instance the + |scientific axes|: + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=3cm}, x axis={ticks={stack}}, @@ -3236,36 +3251,37 @@ visualize one grid independently of the other, using different colors. func y = \value x*\value x; }; \end{codeexample} - Have a look at the ticks on the $y$-axis: There are ticks at values |0|, - |1|, |2|, |3|, and~|4|. These are visualized both at the left - side (where the tick nodes are also shown) and additionally also at - the right side, but only as small marks. Similarly, the ticks on the - $x$-axis appear at the bottom, but also (in much simpler versions) - at the top. Both for the $x$-axis and for the $y$-axis the - |visualize ticks| key was called twice. - - \medskip - \textbf{The tick marks.} - Drawing a tick mark is quite similar to visualizing a grid line; - indeed a tick mark can be thought of as a ``mini grid line'': Just - like a grid line it ``points a long an axis.'' However, a tick will - always be a short straight line -- even when the coordinate system - is actually twisted (experimentation has shown that ticks that - follow the curvature of the coordinate system like grid lines are - hard to recognize). For this reason, the |low| and |high| keys have - a different meaning from the one used with the |visualize grid| - key. In detail to configure the size and position of a tick mark for - the value $v$ of attribute $a$, proceed as follows: - \begin{itemize} - \item The |visualize ticks| key will have setup attribute $a$ to be - equal to $v$. - \item You should now use the |goto| or |goto pos| key together with all - \emph{other} axes to configure at which position with respect to - these other options the tick mark should be shown. For instance, - suppose we want tick marks in |our system| for the $x$-axis at the - bottom and at the top. This corresponds to once setting the - |left axis| to its minimal value and once to its maximal value: + % + Have a look at the ticks on the $y$-axis: There are ticks at values |0|, + |1|, |2|, |3|, and~|4|. These are visualized both at the left side (where + the tick nodes are also shown) and additionally also at the right side, but + only as small marks. Similarly, the ticks on the $x$-axis appear at the + bottom, but also (in much simpler versions) at the top. Both for the + $x$-axis and for the $y$-axis the |visualize ticks| key was called twice. + + \medskip + \textbf{The tick marks.} + Drawing a tick mark is quite similar to visualizing a grid line; indeed a + tick mark can be thought of as a ``mini grid line'': Just like a grid line + it ``points a long an axis''. However, a tick will always be a short + straight line -- even when the coordinate system is actually twisted + (experimentation has shown that ticks that follow the curvature of the + coordinate system like grid lines are hard to recognize). For this reason, + the |low| and |high| keys have a different meaning from the one used with + the |visualize grid| key. In detail to configure the size and position of a + tick mark for the value $v$ of attribute $a$, proceed as follows: + % + \begin{itemize} + \item The |visualize ticks| key will have setup attribute $a$ to be + equal to $v$. + \item You should now use the |goto| or |goto pos| key together with all + \emph{other} axes to configure at which position with respect to + these other options the tick mark should be shown. For instance, + suppose we want tick marks in |our system| for the $x$-axis at the + bottom and at the top. This corresponds to once setting the + |left axis| to its minimal value and once to its maximal value: + % \begin{codeexample}[] \tikzset{ data visualization/our system/.append style={ @@ -3280,39 +3296,45 @@ visualize one grid independently of the other, using different colors. left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={people 1, people 2, money 1, money 2}] - data group {people and money}; -\end{codeexample} - \item In the above example, we may wish to shorten the ticks a bit - at the bottom and at the top. For this, we use the |low| and - |high| key: - \begin{key}{/tikz/data visualization/low=\meta{dimension}} - When used with the |visualize ticks| option, the |low| key - contains a dimension that specifies the extend of the tick going - ``toward the minimum'' of the direction axis. More precisely, when a tick - mark is visualized, a unit tangent vector at the current data point - in the direction of the |direction axis| is computed and this - vector is multiplied by \meta{dimension} to compute the start - position of the tick line. The end position is given by this - vector times the |high| value. - - Note that the \meta{dimension} should usually be negative for - the |low| key and positive for the |high| key. - - For tick marks where a tick label node is shown, the - \meta{dimension} is increased by the current values of keys like - |tick text even low padding|, see - Section~\ref{section-dv-stacking} for details. - \end{key} - \begin{key}{/tikz/data visualization/high=\meta{dimension}} - Like |low|. - \end{key} - \begin{key}{/tikz/data visualization/tick length=\meta{dimension}} - Shorthand for |low=-|\meta{dimension}|, high=|\meta{dimension}. - \end{key} - - What we want to happen is that in the upper visualization of the - ticks the |low| value is |0pt|, while in the lower one the |high| - value is |0pt|: + data group {people and money}; +\end{codeexample} + % + \item In the above example, we may wish to shorten the ticks a bit at + the bottom and at the top. For this, we use the |low| and |high| + key: + % + \begin{key}{/tikz/data visualization/low=\meta{dimension}} + When used with the |visualize ticks| option, the |low| key + contains a dimension that specifies the extend of the tick + going ``toward the minimum'' of the direction axis. More + precisely, when a tick mark is visualized, a unit tangent + vector at the current data point in the direction of the + |direction axis| is computed and this vector is multiplied by + \meta{dimension} to compute the start position of the tick + line. The end position is given by this vector times the |high| + value. + + Note that the \meta{dimension} should usually be negative for + the |low| key and positive for the |high| key. + + For tick marks where a tick label node is shown, the + \meta{dimension} is increased by the current values of keys + like |tick text even low padding|, see + Section~\ref{section-dv-stacking} for details. + \end{key} + % + \begin{key}{/tikz/data visualization/high=\meta{dimension}} + Like |low|. + \end{key} + % + \begin{key}{/tikz/data visualization/tick length=\meta{dimension}} + Shorthand for |low=-|\meta{dimension}|, high=|\meta{dimension}. + \end{key} + + What we want to happen is that in the upper visualization of the + ticks the |low| value is |0pt|, while in the lower one the |high| + value is |0pt|: + % \begin{codeexample}[] \tikzset{ data visualization/our system/.append style={ @@ -3328,28 +3350,31 @@ visualize one grid independently of the other, using different colors. left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={people 1, people 2, money 1, money 2}] - data group {people and money}; + data group {people and money}; \end{codeexample} -\end{itemize} - In order to style the tick mark, use the styling mechanism that is - detailed in Section~\ref{section-dv-styling-ticks}. - - \medskip - \textbf{The tick label node.} - At certain tick positions, we may wish to add a node indicating the - value of the attribute at the given position. The |visualize ticks| - command has no influence over which text should be shown at a node - -- the text is specified and typeset as explained in - Section~\ref{section-dv-tick-labels}. - - Each time |visualize ticks|, for each tick position up to two tick - label nodes will be created: One at the |low| position and one at - the |high| position. The following keys are used to configure which - of these cases happen: - \begin{key}{/tikz/data visualization/tick text at - low=\opt{\meta{true or false}} (default true)} - Pass this option to |visualize ticks| when you want tick label - nodes to be placed at the |low| position of each tick mark. + % + \end{itemize} + % + In order to style the tick mark, use the styling mechanism that is detailed + in Section~\ref{section-dv-styling-ticks}. + + + \medskip + \textbf{The tick label node.} + At certain tick positions, we may wish to add a node indicating the value + of the attribute at the given position. The |visualize ticks| command has + no influence over which text should be shown at a node -- the text is + specified and typeset as explained in Section~\ref{section-dv-tick-labels}. + + Each time |visualize ticks|, for each tick position up to two tick label + nodes will be created: One at the |low| position and one at the |high| + position. The following keys are used to configure which of these cases + happen: + % + \begin{key}{/tikz/data visualization/tick text at low=\opt{\meta{true or false}} (default true)} + Pass this option to |visualize ticks| when you want tick label nodes to + be placed at the |low| position of each tick mark. + % \begin{codeexample}[] \tikzset{ data visualization/our system/.append style={ @@ -3367,16 +3392,17 @@ visualize one grid independently of the other, using different colors. left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={people 1, people 2, money 1, money 2}] - data group {people and money}; -\end{codeexample} - \end{key} - \begin{key}{/tikz/data visualization/tick text at - high=\opt{\meta{true or false}} (default true)} - Like |tick text at low|. - \end{key} - - \begin{key}{/tikz/data visualization/no tick text} - Shorthand for |tick text at low=false, tick text at high=false|. + data group {people and money}; +\end{codeexample} + \end{key} + % + \begin{key}{/tikz/data visualization/tick text at high=\opt{\meta{true or false}} (default true)} + Like |tick text at low|. + \end{key} + + \begin{key}{/tikz/data visualization/no tick text} + Shorthand for |tick text at low=false, tick text at high=false|. + % \begin{codeexample}[] \tikz \datavisualization [scientific axes, all axes={length=3cm}, x axis={ticks={ @@ -3386,55 +3412,51 @@ visualize one grid independently of the other, using different colors. var x : interval [5:10]; func y = \value x * \value x; }; -\end{codeexample} - \end{key} - - When a tick label node is to be placed at the low or the high - position, the next step is to determine the exact position and the - correct anchor of the node. This is done as follows: - \begin{itemize} - \item In order to compute an appropriate |anchor|, the tick mark is - considered: This is a short line pointing in a certain - direction. For a tick label node at the |low| position, the - |anchor| attribute is setup in such a way that the node label will - be below the |low| position when the tick mark direction points - up, it will be to the right when the direction points left, above - when it points down, and so on also for diagonal - directions. Similarly, for the |high| position, when the direction - points up, the node will be placed above the tick mark and so on. - - This computation is done automatically. - \item The tick label node is styled. The styles that are applied are - described in Section~\ref{section-dv-styling-ticks}. - \item A tick label node for the |low| position is usually anchored - at this |low| position, but an additional padding will be - added as described in Section~\ref{section-dv-stacking}. - \end{itemize} -\end{key} - +\end{codeexample} + \end{key} + When a tick label node is to be placed at the low or the high position, the + next step is to determine the exact position and the correct anchor of the + node. This is done as follows: + % + \begin{itemize} + \item In order to compute an appropriate |anchor|, the tick mark is + considered: This is a short line pointing in a certain direction. + For a tick label node at the |low| position, the |anchor| attribute + is setup in such a way that the node label will be below the |low| + position when the tick mark direction points up, it will be to the + right when the direction points left, above when it points down, + and so on also for diagonal directions. Similarly, for the |high| + position, when the direction points up, the node will be placed + above the tick mark and so on. + + This computation is done automatically. + \item The tick label node is styled. The styles that are applied are + described in Section~\ref{section-dv-styling-ticks}. + \item A tick label node for the |low| position is usually anchored at + this |low| position, but an additional padding will be added as + described in Section~\ref{section-dv-stacking}. + \end{itemize} +\end{key} \subsubsection{Visualizing the Axis Labels} - \label{section-dv-visualize-label} -The |label| option can be used with an axis to specify a text should -be shown next to the axis to indicates which attribute this axis -refers to. Like |ticks| or |grid|, the |label| option does not -actually draw the label, this is the job of the |visualize label| key, -which is configured by the axis system. +The |label| option can be used with an axis to specify a text should be shown +next to the axis to indicates which attribute this axis refers to. Like |ticks| +or |grid|, the |label| option does not actually draw the label, this is the job +of the |visualize label| key, which is configured by the axis system. \begin{key}{/tikz/data visualization/axis options/visualize label=\meta{options}} - The \meta{options} should be used to configure a ``good place'' for - the axis label. Usually, you will use the |goto| or the |goto pos| - key. - - For the example of |our system|, we would like the label of the - |x axis| to be placed below at the middle of the axis, so we use - |goto pos=.5| to determine this position. Concerning the other axes, - we want it to be placed at the minimum position of the |left axis| - with a lot of padding. + The \meta{options} should be used to configure a ``good place'' for the + axis label. Usually, you will use the |goto| or the |goto pos| key. + + For the example of |our system|, we would like the label of the |x axis| to + be placed below at the middle of the axis, so we use |goto pos=.5| to + determine this position. Concerning the other axes, we want it to be placed + at the minimum position of the |left axis| with a lot of padding. + % \begin{codeexample}[width=7cm] \tikzdatavisualizationset{ our system/.append style={ @@ -3444,27 +3466,27 @@ which is configured by the axis system. } } \tikz \datavisualization [ - our system, + our system, x axis={attribute=time, ticks=some, label}, left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={ people 1, people 2, money 1, money 2}] - data group {people and money}; -\end{codeexample} - - In the above example, the |padding| of |1.5em| was rather arbitrary - and ``suboptimal''. It would be outright wrong if the labels on the |x axis| were larger or - if they were missing. It would be better if the vertical position of - the |x axis| label were always ``below'' all other options. For such - cases a slightly strange approach is useful: You position the node - using |node style={at=...}| where |at| - is now the normal \tikzname\ option that is used to specify the - position of a node. Inside the |...|, you specify that the - horizontal position should be the bottom of up-to-now-constructed - data visualization and the vertical position should be at the - ``origin,'' which is, however, the position computed by the |goto| - keys for the axes: + data group {people and money}; +\end{codeexample} + + In the above example, the |padding| of |1.5em| was rather arbitrary and + ``suboptimal''. It would be outright wrong if the labels on the |x axis| + were larger or if they were missing. It would be better if the vertical + position of the |x axis| label were always ``below'' all other options. For + such cases a slightly strange approach is useful: You position the node + using |node style={at=...}| where |at| is now the normal \tikzname\ option + that is used to specify the position of a node. Inside the |...|, you + specify that the horizontal position should be the bottom of + up-to-now-constructed data visualization and the vertical position should + be at the ``origin'', which is, however, the position computed by the + |goto| keys for the axes: + % \begin{codeexample}[width=7cm] \tikzdatavisualizationset{ our system/.append style={ @@ -3475,36 +3497,38 @@ which is configured by the axis system. below } } } } } \tikz \datavisualization [ - our system, + our system, x axis={attribute=time, ticks=some, label=Year}, left axis ={attribute=money}, right axis={attribute=people}, visualize as line/.list={ people 1, people 2, money 1, money 2}] - data group {people and money}; -\end{codeexample} - - Two additional keys are useful for positioning axis labels: - \begin{key}{/tikz/data visualization/axis option/anchor at min} - When passed to an axis, this key sets the |anchor| so that a node - positioned at either the |min| or the |padded min| value of the - axis will be placed ``nicely'' with respect to the axis. For - instance, if the axis points upwards from the |min| value to the - |max| value, the |anchor| would be set to |north| since this gives - a label below the axis's start. Similarly, if the axis points - right, the anchor would be set to |east|, and so on. - \end{key} - \begin{key}{/tikz/data visualization/axis option/anchor at max} - Like |anchor at min|. - \end{key} + data group {people and money}; +\end{codeexample} + + Two additional keys are useful for positioning axis labels: + % + \begin{key}{/tikz/data visualization/axis option/anchor at min} + When passed to an axis, this key sets the |anchor| so that a node + positioned at either the |min| or the |padded min| value of the axis + will be placed ``nicely'' with respect to the axis. For instance, if + the axis points upwards from the |min| value to the |max| value, the + |anchor| would be set to |north| since this gives a label below the + axis's start. Similarly, if the axis points right, the anchor would be + set to |east|, and so on. + \end{key} + % + \begin{key}{/tikz/data visualization/axis option/anchor at max} + Like |anchor at min|. + \end{key} \end{key} \subsubsection{The Complete Axis System} -Here is the code for the complete axis system developed above and an -example of how it is used: - +Here is the code for the complete axis system developed above and an example of +how it is used: +% \begin{codeexample}[code only] \tikzdatavisualizationset{ our system/.style={ % The axes @@ -3529,7 +3553,7 @@ example of how it is used: left axis= {visualize grid={direction axis=x axis, common={style=red!50}}}, right axis={visualize grid={direction axis=x axis, common={style=blue!50}}}, % Visualizing the ticks, when requested - left axis={visualize ticks={style={red!50!black}, direction axis=x axis, + left axis={visualize ticks={style={red!50!black}, direction axis=x axis, x axis={goto=padded min}, high=0pt, tick text at low}}, right axis={visualize ticks={style={blue!80!black}, direction axis=x axis, x axis={goto=padded max}, low=0pt, tick text at high}}, @@ -3548,7 +3572,6 @@ example of how it is used: }} \end{codeexample} - \tikzdatavisualizationset{ our system/.style={ % The axes @@ -3601,7 +3624,7 @@ example of how it is used: \begin{codeexample}[] \tikz \datavisualization [ - our system, + our system, x axis={attribute=time, label=Year, ticks={tick text padding=2pt, style={/pgf/number format/set thousands separator=}}}, left axis={attribute=money, label=Spending, @@ -3618,80 +3641,77 @@ example of how it is used: people 2={style={visualizer color=blue!50}}, money 1={style={visualizer color=red}}, money 2={style={visualizer color=red!50}} ] -data group {people and money}; +data group {people and money}; \end{codeexample} - \subsubsection{Using the New Axis System Key} -The axis system |our system| that we developed in the course of the -previous section is not yet ``configurable.'' The only configuration -that was possible was to ``misuse'' the |width| and |height| keys of -the |scientific axes|. +The axis system |our system| that we developed in the course of the previous +section is not yet ``configurable''. The only configuration that was possible +was to ``misuse'' the |width| and |height| keys of the |scientific axes|. In order to make |our system| configurable so that we can say -|our system=|\meta{options}, where \meta{options} are executed with -the path prefix +|our system=|\meta{options}, where \meta{options} are executed with the path +prefix +% \begin{codeexample}[code only] -/tikz/data visualization/our system +/tikz/data visualization/our system \end{codeexample} +% we can use the following key: \begin{key}{/tikz/data visualization/new axis system=\marg{axis system name}\marg{axis setup}\marg{default options}\\ \marg{application - options}} - The |new axis system| key takes four parameters. The first one, - \meta{system name}, is the name of the to-be-created axis system, - |our system| in our case. The |new axis system| will create the - following new key: - \begin{key}{/tikz/data visualization/\meta{axis system - name}=\opt{\meta{options}}} - When the key \meta{axis system name} is used, the following keys - will be executed in the following order: - \begin{enumerate} - \item - The \meta{axis setup} with the path prefix |/tikz/data visualization/|. - \item - The \meta{default options} with the same path prefix. - \item - The following style: - \begin{stylekey}{/tikz/data visualization/every \meta{axis system name}} - Even though this style has the path prefix - |/tikz/data visualization| itself, the keys stored in this - style will be executed with the path prefix - |/tikz/data visualization/|\meta{axis system name}. - \end{stylekey} - \item - The \meta{options} with the path prefix - |/tikz/data visualization/|\meta{axis system name}. - \item - The \meta{application options} with the path prefix |/tikz/data visualization/| - \end{enumerate} - \end{key} - - Let us now have a look at what all of this means. First, the - \meta{axis setup} will contain all options that setup the axis - system in all ways that need not be configured. For instance, the - \meta{axis setup} for the |scientific axes| will create an |x axis| - and also a |y axis| (because these are always present), but will not - setup the label visualization (because this can be configured in - different ways). For |our system|, which cannot be configured at - all, we would place all of our configuration in the \meta{axis - setup}. - - The \meta{default options} can be used to pick default values that - would usually be passed to the \meta{options} of the newly created - axis system. For instance, for |scientific axis|, the - \meta{default options} are set to |outer ticks,standard labels|, - because these are the defaults. - - Finally, the \meta{application options} can be used to actually - apply the configuration that has been chosen by the - \meta{options}. The idea is that \meta{default options}, - \meta{options}, and also |every| \meta{axis system name} all have a - chance of changing, re-changing and re-setting all sorts of styles - and keys. Then, with the last change ``winning,'' the resulting - setting of a style can be executed, which may then cause a label - visualization to be installed. + options}% +} + The |new axis system| key takes four parameters. The first one, + \meta{system name}, is the name of the to-be-created axis system, + |our system| in our case. The |new axis system| will create the following + new key: + % + \begin{key}{/tikz/data visualization/\meta{axis system name}=\opt{\meta{options}}} + When the key \meta{axis system name} is used, the following keys will be + executed in the following order: + % + \begin{enumerate} + \item The \meta{axis setup} with the path prefix + |/tikz/data visualization/|. + \item The \meta{default options} with the same path prefix. + \item The following style: + % + \begin{stylekey}{/tikz/data visualization/every \meta{axis system name}} + Even though this style has the path prefix + |/tikz/data visualization| itself, the keys stored in this + style will be executed with the path prefix + |/tikz/data visualization/|\meta{axis system name}. + \end{stylekey} + \item The \meta{options} with the path prefix + |/tikz/data visualization/|\meta{axis system name}. + \item The \meta{application options} with the path prefix + |/tikz/data visualization/| + \end{enumerate} + \end{key} + + Let us now have a look at what all of this means. First, the \meta{axis + setup} will contain all options that setup the axis system in all ways that + need not be configured. For instance, the \meta{axis setup} for the + |scientific axes| will create an |x axis| and also a |y axis| (because + these are always present), but will not setup the label visualization + (because this can be configured in different ways). For |our system|, which + cannot be configured at all, we would place all of our configuration in the + \meta{axis setup}. + + The \meta{default options} can be used to pick default values that would + usually be passed to the \meta{options} of the newly created axis system. + For instance, for |scientific axis|, the \meta{default options} are set to + |outer ticks,standard labels|, because these are the defaults. + + Finally, the \meta{application options} can be used to actually apply the + configuration that has been chosen by the \meta{options}. The idea is that + \meta{default options}, \meta{options}, and also |every| \meta{axis system + name} all have a chance of changing, re-changing and re-setting all sorts + of styles and keys. Then, with the last change ``winning'', the resulting + setting of a style can be executed, which may then cause a label + visualization to be installed. \end{key} |