summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-dv-axes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-dv-axes.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-dv-axes.tex3822
1 files changed, 3822 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-dv-axes.tex b/graphics/pgf/base/doc/pgfmanual-en-dv-axes.tex
new file mode 100644
index 0000000000..373402b5cd
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-dv-axes.tex
@@ -0,0 +1,3822 @@
+% Copyright 2019 by Till Tantau
+%
+% This file may be distributed and/or modified
+%
+% 1. under the LaTeX Project Public License and/or
+% 2. under the GNU Free Documentation License.
+%
+% 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}.
+
+
+\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
+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:
+%
+\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.
+\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.
+
+
+\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}.
+
+\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|.
+ %
+\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}
+
+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.
+
+
+\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):
+
+\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:
+ %
+\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:
+ %
+\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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [scientific axes,
+ x axis={attribute=people, length=2.5cm, ticks=few},
+ y axis={attribute=year},
+ visualize as scatter]
+ data {
+ year, people
+ 1900, 100
+ 1910, 200
+ 1950, 200
+ 1960, 250
+ 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:
+%
+\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|.
+\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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes, all axes={length=3cm},
+ visualize as line]
+ data [format=function] {
+ var x : interval [5:10];
+ func y = \value x * \value x;
+ };
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes, all axes={length=3cm},
+ visualize as line,
+ x axis={include value=20},
+ y axis={include value=0}]
+ data [format=function] {
+ var x : interval [5:10];
+ func y = \value x * \value x;
+ };
+\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.
+\end{key}
+
+\begin{key}{/tikz/data visualization/axis options/max value=\meta{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.
+
+\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
+ %
+\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}]$.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization
+ [scientific axes,
+ x axis={attribute=people, length=2.5cm, ticks=few},
+ y axis={attribute=year, scaling=1900 at 0cm and 2000 at 5cm},
+ visualize as scatter]
+ data {
+ year, people
+ 1900, 100
+ 1910, 200
+ 1950, 200
+ 1960, 250
+ 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
+ %
+\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
+ %
+\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]
+[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
+ %
+\begin{codeexample}[code only]
+some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}}
+\end{codeexample}
+ %
+ This specifies that the function $f$ is the logarithm function.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization
+ [scientific axes,
+ x axis={ticks={major={at={1,10,100,1000}}},
+ scaling=1 at 0cm and 1000 at 3cm,
+ function=\pgfdvmathln{\pgfvalue}{\pgfvalue}},
+ visualize as scatter]
+ data [format=named] {
+ x={1,100,...,1000}, y={1,2,3}
+ };
+\end{codeexample}
+ %
+ Another possibility might be to use the square-root function, instead:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization
+ [scientific axes,
+ x axis={ticks=few,
+ scaling=1 at 0cm and 1000 at 3cm,
+ function=\pgfdvmathunaryop{\pgfvalue}{sqrt}{\pgfvalue}},
+ visualize as scatter]
+ data [format=named] {
+ 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.
+
+
+\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.
+ %
+\begin{codeexample}[
+ width=8cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization [scientific axes,
+ x axis={logarithmic},
+ y axis={logarithmic},
+ visualize as line]
+ data [format=function] {
+ var x : interval [0.01:100];
+ func y = \value x * \value x;
+ };
+\end{codeexample}
+ %
+ Note that this will work with any axis, including, say, the degrees on a
+ polar axis:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
+\tikz \datavisualization
+ [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}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
+\tikz \datavisualization
+ [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{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}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [scientific axes,
+ x axis={length=3cm},
+ y axis={length=2cm},
+ all axes={ticks=few},
+ visualize as line]
+ data {
+ x, y
+ 10, 10
+ 20, 20
+ 15, 30
+ 13, 20
+ };
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [scientific axes,
+ x axis={length=3cm},
+ y axis={length=4cm},
+ all axes={ticks=few},
+ visualize as line]
+ data {
+ x, y
+ 10, 10
+ 20, 20
+ 15, 30
+ 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{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [scientific axes,
+ all axes={ticks=few, unit length=1mm},
+ visualize as line]
+ data {
+ x, y
+ 10, 10
+ 40, 20
+ 15, 30
+ 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|:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization
+ [scientific axes,
+ x axis={unit length=1mm per 1000000000 units, ticks=few},
+ visualize as line]
+ data {
+ x, y
+ 10000000000, 10
+ 40000000000, 20
+ 15000000000, 30
+ 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{codeexample}[width=8cm,preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization
+ [scientific axes,
+ y axis={logarithmic, power unit length=1mm, grid},
+ visualize as line]
+ data {
+ x, y
+ 0, 0.0000000001
+ 1, 1
+ 2, 100000
+ 3, 100000000000
+ 4, 10000000000000000000000000000000
+ 5, 500000000
+ 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}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [
+ scientific axes,
+ x axis = {label, length=2.5cm},
+ y axis = {label={[node style={fill=blue!20}]{$x^2$}}},
+ visualize as smooth line]
+ data [format=function] {
+ var x : interval [-3:5];
+ func y = \value x * \value x;
+ };
+\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}.
+
+
+\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}.
+
+\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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\begin{tikzpicture}
+ \draw [help lines] (0,0) grid (3,2);
+
+ \datavisualization
+ [new Cartesian axis=x axis, x axis={attribute=x},
+ new Cartesian axis=y axis, y axis={attribute=y},
+ x axis={unit vector=(0:1pt)},
+ y axis={unit vector=(60:1pt)},
+ visualize as scatter]
+ data {
+ x, y
+ 0, 0
+ 1, 0
+ 2, 0
+ 1, 1
+ 2, 1
+ 1, 1.5
+ 2, 1.5
+ };
+\end{tikzpicture}
+\end{codeexample}
+ \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.
+
+
+\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.
+
+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.
+
+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
+%
+\begin{codeexample}[code only]
+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.
+
+Fourth, consider adding units (like ``cm'' for centimeters or
+``$\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}}
+\end{codeexample}
+
+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)}
+\end{codeexample}
+
+Here is an example that employs most of the above features:
+%
+\begin{codeexample}[width=8.5cm,preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [
+ scientific axes=clean,
+ x axis={attribute=time, ticks={tick unit=ms},
+ label={elapsed time}},
+ y axis={attribute=v, ticks={tick unit=m/s},
+ label={speed of disc}},
+ all axes=grid,
+ visualize as line]
+data {
+ time, v
+ 0, 0
+ 1, 0.001
+ 2, 0.002
+ 3, 0.004
+ 4, 0.0035
+ 5, 0.0085
+ 6, 0.0135
+};
+\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|.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\begin{tikzpicture}
+ \datavisualization [scientific axes,
+ visualize as smooth line]
+ data [format=function] {
+ var x : interval [0:100];
+ func y = sqrt(\value x);
+ };
+\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.
+
+ 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
+\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'':
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\begin{tikzpicture}
+ \datavisualization [visualize as smooth line,
+ scientific axes,
+ all axes={unit length=1cm per 10 units, ticks={few}}]
+ data [format=function] {
+ var x : interval [0:100];
+ func y = sqrt(\value x);
+ };
+\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 following keys are executed by default as options: |outer ticks| and
+ |standard labels|.
+
+ You can use the following style to overrule the defaults:
+
+ \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.
+
+\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.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\begin{tikzpicture}
+ \datavisualization [scientific axes=outer ticks,
+ visualize as smooth line]
+ data [format=function] {
+ var x : interval [-12:12];
+ func y = \value x*\value x*\value x;
+ };
+\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.
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\begin{tikzpicture}
+ \datavisualization [scientific axes=inner ticks,
+ visualize as smooth line]
+ data [format=function] {
+ var x : interval [-12:12];
+ func y = \value x*\value x*\value x;
+ };
+\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:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\begin{tikzpicture}
+ \datavisualization [scientific axes={inner ticks, width=3.2cm},
+ style sheet=cross marks,
+ visualize as scatter/.list={a,b}]
+ data [set=a] {
+ x, y
+ 0, 0
+ 1, 1
+ 0.5, 0.5
+ 2, 1
+ }
+ data [set=b] {
+ x, y
+ 0.05, 0
+ 1.5, 1
+ 0.5, 0.75
+ 2, 0.5
+ };
+\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.
+ %
+\begin{codeexample}[
+ width=7.5cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization [
+ scientific axes=clean,
+ visualize as smooth line]
+data [format=function] {
+ var x : interval [-12:12];
+ func y = \value x*\value x*\value x;
+};
+\end{codeexample}
+
+ 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.
+
+\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.
+ %
+\begin{codeexample}[
+ width=8cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes={clean, standard labels},
+ visualize as smooth line,
+ x axis={label=degree $d$,
+ ticks={tick unit={}^\circ}},
+ y axis={label=$\sin d$}]
+data [format=function] {
+ var x : interval [-10:10] samples 10;
+ 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.
+ %
+\begin{codeexample}[
+ width=8cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization [
+ scientific axes={clean, upright labels},
+ visualize as smooth line,
+ x axis={label=degree $d$,
+ ticks={tick unit={}^\circ}},
+ y axis={label=$\cos d$, include value=1,
+ ticks={style={
+ /pgf/number format/precision=4,
+ /pgf/number format/fixed zerofill}}}]
+data [format=function] {
+ var x : interval [-10:10] samples 10;
+ 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.
+ %
+\begin{codeexample}[
+ width=8cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization [
+ scientific axes={clean, end labels},
+ visualize as smooth line,
+ x axis={label=degree $d$,
+ ticks={tick unit={}^\circ}},
+ y axis={label=$\tan d$}]
+data [format=function] {
+ var x : interval [-80:80];
+ 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''.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\begin{tikzpicture}
+ \datavisualization [school book axes, visualize as smooth line]
+ data [format=function] {
+ var x : interval [-1.3:1.3];
+ func y = \value x*\value x*\value x;
+ };
+\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}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\begin{tikzpicture}
+ \datavisualization [school book axes={unit=10},
+ visualize as smooth line,
+ clean ticks,
+ x axis={label=$x$},
+ y axis={label=$f(x)$}]
+ data [format=function] {
+ var x : interval [-20:20];
+ func y = \value x*\value x/10;
+ };
+\end{tikzpicture}
+\end{codeexample}
+ \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.
+
+ Currently, this is the only supported placement strategy for the school
+ book axis system.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\begin{tikzpicture}
+ \datavisualization [school book axes={standard labels},
+ visualize as smooth line,
+ clean ticks,
+ x axis={label=$x$},
+ y axis={label=$f(x)$}]
+ data [format=function] {
+ var x : interval [-1:1];
+ func y = \value x*\value x + 1;
+ };
+\end{tikzpicture}
+\end{codeexample}
+ \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.
+
+\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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\begin{tikzpicture}
+ \datavisualization [xy Cartesian, visualize as smooth line]
+ data [format=function] {
+ var x : interval [-1.25:1.25];
+ func y = \value x*\value x*\value x;
+ };
+\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}
+\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}
+\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}
+\end{key}
+
+\begin{key}{/tikz/data visualization/uvw Cartesian cabinet}
+ Like |xyz Cartesian cabinet|, but for the $uvw$-system.
+
+ \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:
+%
+\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.
+\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.
+
+
+\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{codeexample}[width=6cm,preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [
+ scientific axes, visualize as line,
+ x axis={ticks={step=24, minor steps between steps=3},
+ label=hours}]
+ data {
+ x, y
+ 0, 0
+ 10, 0
+ 20, 0.5
+ 30, 0.75
+ 40, 0.7
+ 50, 0.6
+ 60, 0.5
+ 70, 0.45
+ 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.
+
+ 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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes,
+ visualize as smooth line,
+ all axes= {grid, unit length=1.25cm},
+ y axis={ ticks=few },
+ x axis={ ticks=many, ticks and grid={ major also at={(pi/2) as $\frac{\pi}{2}$}}}]
+ data [format=function] {
+ var x : interval [-pi/2:3*pi] samples 50;
+ 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
+like |step| or |about|.
+
+Here is an example of the different stepping chosen when one varies the tick
+placement strategy:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\begin{tikzpicture}
+ \datavisualization [scientific axes, visualize as smooth line]
+ data [format=function] {
+ var x : interval [1:11];
+ func y = \value x*\value x;
+ };
+\end{tikzpicture}
+\qquad
+\begin{tikzpicture}
+ \datavisualization [scientific axes, visualize as smooth line,
+ y axis={exponential steps},
+ x axis={ticks={quarter about strategy}},
+ ]
+ data [format=function] {
+ var x : interval [1:11];
+ func y = \value x*\value x;
+ };
+\end{tikzpicture}
+\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}|.
+
+\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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [
+ school book axes, visualize as smooth line,
+ y axis={ticks={step=1.25}},
+ ]
+ data [format=function] {
+ var x : interval [0:3];
+ 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{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\begin{tikzpicture}
+ \datavisualization [school book axes, visualize as smooth line,
+ x axis={ticks={minor steps between steps=3}},
+ y axis={ticks={minor steps between steps}},
+ ]
+ data [format=function] {
+ var x : interval [-1.5:1.5];
+ func y = \value x*\value x;
+ };
+\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.
+\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.
+
+\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.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 (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|:
+
+ \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.}
+
+ 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/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}
+
+ \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}
+
+ \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}
+
+ \begin{key}{/tikz/data visualization/quarter about strategy}
+ Permissible values for $m'$ are: $1$, $2.5$, and $5$.
+
+ \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$.
+
+ \showstrategy{int about strategy}
+ \end{key}
+\end{key}
+
+\begin{key}{/tikz/data visualization/many}
+ This is an abbreviation for |about=10|.
+\end{key}
+
+\begin{key}{/tikz/data visualization/some}
+ This is an abbreviation for |about=5|.
+\end{key}
+
+\begin{key}{/tikz/data visualization/few}
+ 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.
+\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.
+
+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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [ school book axes, visualize as smooth line,
+ x axis={ticks={major={at={1, 1.5, 2}}}}]
+ data [format=function] {
+ var x : interval [-1.25:2];
+ 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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [ school book axes, visualize as smooth line,
+ x axis={grid={minor={at={1, 1.5, 2}}}}]
+ data [format=function] {
+ var x : interval [-1.25:2];
+ 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.
+\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:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [ school book axes, visualize as smooth line,
+ x axis={ticks={minor steps between steps, common={low=0}}} ]
+ data [format=function] {
+ var x : interval [-1.25:2];
+ 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:
+
+\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:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [ school book axes, visualize as smooth line,
+ x axis={ticks={major={at={-1,0.5,(pi/2)}}}}]
+ data [format=function] {
+ 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}
+\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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [ school book axes, visualize as smooth line,
+ x axis={grid, ticks and grid={major={also at={0.5}}}}]
+ data [format=function] {
+ 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{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:
+
+
+\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.
+
+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).
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes,
+ all axes={ticks={style=blue}, length=3cm},
+ 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.
+\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|.
+
+\begin{key}{/tikz/data visualization/node style=\meta{\tikzname\ options}}
+ This key works like |style|, but it has an effect only on nodes that are
+ created during a data visualization. This includes tick labels and axis
+ labels:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes,
+ all axes={ticks={node style=red}, length=3cm},
+ visualize as line]
+ data [format=function] {
+ var x : interval [5:10];
+ func y = \value x * \value x;
+ };
+\end{codeexample}
+ %
+ 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.
+\end{key}
+
+
+\subsubsection{Styling Ticks and Grid Lines: Styling Grid Lines}
+\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.
+%
+\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}.
+\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}).
+
+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'':
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes,
+ all axes={
+ length=3cm,
+ grid,
+ grid={minor steps between steps}
+ },
+ grid layer/.style=, % none, so on top of data (bad idea)
+ visualize as line]
+ data [format=function] {
+ 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{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:
+ %
+\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 behavior (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. It should be noted that settings to |style| inside |every grid|
+ will take precedence over ones in |every major grid| and |every minor grid|.
+ 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}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes,
+ all axes={length=3cm, grid},
+ every grid/.append style={style=densely dashed},
+ visualize as line]
+ data [format=function] {
+ var x : interval [5:10];
+ func y = \value x * \value x;
+ };
+\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:
+ %
+\begin{codeexample}[code only]
+style = {help lines, thin, black!25}
+\end{codeexample}
+ %
+ In the following example, we use thin major blue grid lines:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes,
+ all axes={
+ length=3cm,
+ grid,
+ grid={minor steps between steps}
+ },
+ every major grid/.style = {style={blue, thin}},
+ visualize as line]
+ data [format=function] {
+ 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{stylekey}
+
+\begin{stylekey}{/tikz/data visualization/every minor grid}
+ 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
+ %
+\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:
+%
+\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}.
+\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:
+%
+\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}.
+\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:
+ %
+\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
+ %
+\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
+ %
+\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
+ %
+\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.
+\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.
+\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.
+
+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:
+ %
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization [
+ scientific axes,
+ visualize as smooth line,
+ x axis={ticks={major={
+ options at = 3 as [no tick text],
+ also at = (pi) as
+ [{tick text padding=1ex}] $\pi$}}}]
+data [format=function] {
+ var x : interval[0:2*pi];
+ 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]|.
+\end{key}
+
+
+\subsubsection{Styling Ticks and Grid Lines: Styling and Typesetting a Value}
+\label{section-dv-local-styles}
+\label{section-dv-tick-labels}
+
+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}
+\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.
+%
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes=clean,
+ x axis={length=2.5cm, ticks={major at={
+ 5,
+ 6 as [style=red],
+ 7 as [{style=blue, low=-1em}],
+ 8 as [style=green] $2^3$,
+ 10 as ten
+ }}},
+ visualize as line]
+ data [format=function] {
+ var x : interval [5:10];
+ func y = \value x * \value x;
+ };
+\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.
+
+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 typesetter| 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{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes, all axes={ticks=few, length=2.5cm},
+ x axis={ticks={tick prefix=$\langle$, tick suffix=$]$}},
+ 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/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}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization
+ [scientific axes, all axes={length=3cm},
+ x axis={ticks={tick unit=s}},
+ y axis={ticks={tick unit=m/s^2}},
+ visualize as line]
+ data [format=function] {
+ var x : interval [5:10];
+ func y = \value x * \value x;
+ };
+\end{codeexample}
+ \end{key}
+\end{key}
+
+\begin{key}{/tikz/data visualization/tick typesetter=\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$:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\def\mytypesetter#1{%
+ \pgfmathparse{#1/pi}%
+ \pgfmathprintnumber{\pgfmathresult}$\pi$%
+}
+\tikz \datavisualization
+ [school book axes, all axes={unit length=1.25cm},
+ x axis={ticks={step=(0.5*pi), tick typesetter/.code=\mytypesetter{##1}}},
+ y axis={include value={-1,1}},
+ visualize as smooth line]
+ data [format=function] {
+ var x : interval [0.5:7];
+ 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):
+%
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes,
+ all axes={length=2.5cm},
+ visualize as smooth line]
+ data [format=function] {
+ var y : interval[-100:100];
+ 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:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes,
+ all axes={length=2.5cm},
+ x axis={ticks={node style={rotate=90, anchor=east}}},
+ visualize as smooth line]
+ data [format=function] {
+ var y : interval[-100:100];
+ 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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes,
+ all axes={length=2.5cm},
+ x axis={ticks={major at={0,4000,8000,
+ 2000 as [node style={yshift=-1em}],
+ 6000 as [node style={yshift=-1em}],
+ 10000 as [node style={yshift=-1em}]}}},
+ visualize as smooth line]
+ data [format=function] {
+ var y : interval[-100:100];
+ 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:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes,
+ all axes={length=2.5cm}, x axis={ticks=stack},
+ visualize as smooth line]
+ data [format=function] {
+ var y : interval[-100:100];
+ 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:
+%
+\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
+ %
+\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.
+\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{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes,
+ all axes={length=2.5cm},
+ x axis={ticks={tick text low even padding=-1em}},
+ visualize as smooth line]
+ data [format=function] {
+ var y : interval[-100:100];
+ func x = \value y*\value y;
+ };
+\end{codeexample}
+ %
+ 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.
+\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.
+\end{key}
+
+\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}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes,
+ all axes={length=2.5cm},
+ x axis={ticks={stack=1.5em}},
+ visualize as smooth line]
+ data [format=function] {
+ var y : interval[-100:100];
+ 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|.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes,
+ all axes={length=2.5cm},
+ x axis={ticks=stack'},
+ visualize as smooth line]
+ data [format=function] {
+ var y : interval[-100:100];
+ 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:
+%
+\begin{codeexample}[
+ width=7cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\tikz \datavisualization
+ [scientific axes,
+ x axis={ticks={stack, many, major also at=
+ {(pi) as [{tick text padding=2.5em}] $\pi$}}},
+ visualize as smooth line]
+ data [format=function] {
+ var x : interval[0:(2*pi)];
+ func y = sin(\value x r);
+ };
+\end{codeexample}
+
+
+\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{major}
+ 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 major ticks (and also before and
+ after the last major 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 major ticks. Use a value of $9$ (not $10$) to
+ partition the interval between two major ticks into ten equally sized minor
+ intervals.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\begin{tikzpicture}
+ \datavisualization
+ [scientific axes={inner ticks, width=3cm},
+ x axis={ticks={step=3, minor steps between steps=2}},
+ y axis={ticks={step=.36}},
+ visualize as scatter]
+ data {
+ x, y
+ 17, 30
+ 34, 32
+ };
+\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, major 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 major steps.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\begin{tikzpicture}
+ \datavisualization
+ [scientific axes,
+ x axis={logarithmic, length=2cm, ticks={step=1.5}},
+ y axis={logarithmic, ticks={step=1, minor steps between steps=9}},
+ visualize as scatter]
+ data {
+ x, y
+ 1, 10
+ 1000, 1000000
+ };
+\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{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
+\def\silly{
+ \tikzdatavisualizationset{major={at={
+ 2,3,5,7,11,13}}}
+}
+\begin{tikzpicture}
+ \datavisualization [
+ scientific axes, visualize as scatter,
+ x axis={tick placement strategy=\silly}
+ ]
+ data {
+ x, y
+ 0, 0
+ 15, 15
+ };
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+
+\subsection{Advanced: Creating New Axis Systems}
+
+The |datavisualization| 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.
+\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.
+
+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.
+
+
+\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={
+ ...
+ }
+}
+\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:
+%
+\begin{codeexample}[code only]
+\tikzset{
+ data visualization/our system/.style={
+ new Cartesian axis=x axis,
+ new Cartesian axis=left axis,
+ new Cartesian axis=right axis,
+ x axis={attribute=x},
+ left axis={unit vector={(0cm,1pt)}},
+ right axis={unit vector={(0cm,1pt)}},
+ }
+}
+\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|:
+%
+\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:
+%
+\begin{codeexample}[setup code]
+\tikz \datavisualization data group {people and money} = {
+ data [set=people 1] {
+ time, people
+ 1900, 1000000000
+ 1920, 1500000000
+ 1930, 2000000000
+ 1980, 3000000000
+ }
+ data [set=people 2] {
+ time, people
+ 1900, 2000000000
+ 1920, 2500000000
+ 1940, 4000000000
+ 2000, 5700000000
+ }
+ data [set=money 1] {
+ time, money
+ 1910, 1.1
+ 1920, 2
+ 1930, 5
+ 1980, 2
+ }
+ data [set=money 2] {
+ time, money
+ 1950, 3
+ 1960, 3
+ 1970, 4
+ 1990, 3.5
+ }
+ };
+\end{codeexample}
+
+\begin{codeexample}[setup code,hidden]
+\tikzdatavisualizationset{
+ our system/.style={
+ new Cartesian axis=x axis,
+ new Cartesian axis=left axis,
+ new Cartesian axis=right axis,
+ x axis={attribute=x},
+ left axis={unit vector={(0cm,1pt)}},
+ right axis={unit vector={(0cm,1pt)}},
+ 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}
+%
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=4cm},
+ left axis ={attribute=money},
+ right axis={attribute=people},
+ visualize as line/.list={people 1, people 2, money 1, money 2},
+ people 1={style={visualizer color=blue}},
+ 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};
+\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:
+
+\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:
+ %
+\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 behavior:
+ %
+ \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 needs 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,
+ new Cartesian axis=left axis,
+ new Cartesian axis=right axis,
+ x axis={attribute=x},
+ left axis={unit vector={(0cm,1pt)}},
+ right axis={unit vector={(0cm,1pt)}},
+ 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}}
+ }
+}
+\begin{codeexample}[
+ preamble={\usetikzlibrary{datavisualization}},
+ pre={\tikzdatavisualizationset{
+ our system/.style={
+ new Cartesian axis=x axis,
+ new Cartesian axis=left axis,
+ new Cartesian axis=right axis,
+ x axis={attribute=x},
+ left axis={unit vector={(0cm,1pt)}},
+ right axis={unit vector={(0cm,1pt)}},
+ 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}}
+ }
+}}]
+\tikzset{
+ data visualization/our system/.append style={
+ left axis= {visualize axis={x axis= {goto=min}}},
+ right axis={visualize axis={x axis= {goto=max}}},
+ x axis= {visualize axis={left axis={goto=min}},
+ visualize axis={left axis={goto=max}}},
+ }
+}
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=4cm},
+ 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.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{datavisualization}},
+ pre={\tikzdatavisualizationset{
+ our system/.style={
+ new Cartesian axis=x axis,
+ new Cartesian axis=left axis,
+ new Cartesian axis=right axis,
+ x axis={attribute=x},
+ left axis={unit vector={(0cm,1pt)}},
+ right axis={unit vector={(0cm,1pt)}},
+ 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}}
+ }
+}}]
+\tikzset{
+ data visualization/our system/.append style={
+ x axis= {visualize axis={left axis={goto pos=0.25}},
+ visualize axis={left axis={goto pos=0.5}}},
+ }
+}
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=4cm},
+ 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~\pageref{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}.
+ %
+% TODOsp: codeexamples: What is this empty `\tikzset` good for?
+\tikzset{
+}
+\begin{codeexample}[
+ preamble={\usetikzlibrary{datavisualization}},
+ pre={\tikzdatavisualizationset{
+ our system/.style={
+ new Cartesian axis=x axis,
+ new Cartesian axis=left axis,
+ new Cartesian axis=right axis,
+ x axis={attribute=x},
+ left axis={unit vector={(0cm,1pt)}},
+ right axis={unit vector={(0cm,1pt)}},
+ 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}}
+ }
+}}]
+\tikzset{
+ data visualization/our system/.append style={
+ every axis/.style={style=black!50}, % make this the default
+ left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
+ right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
+ x axis= {visualize axis={left axis={goto=min}},
+ visualize axis={left axis={goto=max}}},
+ }
+}
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=4cm},
+ 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}
+\tikzset{
+ data visualization/our system/.append style={
+ every axis/.style={style=black!50}, % make this the default
+ left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
+ right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
+ x axis= {visualize axis={left 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:
+ %
+\begin{codeexample}[
+ width=8cm,
+ preamble={\usetikzlibrary{datavisualization.formats.functions}},
+]
+\begin{tikzpicture}
+ \datavisualization [scientific axes=clean,
+ x axis={padding min=-1cm},
+ visualize as smooth line]
+ data [format=function] {
+ var x : interval [-3:5];
+ func y = \value x * \value x;
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+ Using padded and using the |padded| key, we can visualize our axis ``a
+ little removed from the actual data'':
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{datavisualization}},
+ pre={\tikzdatavisualizationset{
+ our system/.style={
+ new Cartesian axis=x axis,
+ new Cartesian axis=left axis,
+ new Cartesian axis=right axis,
+ x axis={attribute=x},
+ left axis={unit vector={(0cm,1pt)}},
+ right axis={unit vector={(0cm,1pt)}},
+ 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}}
+ }
+}%
+\tikzset{
+ data visualization/our system/.append style={
+ every axis/.style={style=black!50}, % make this the default
+ left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
+ right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
+ x axis= {visualize axis={left axis={goto=min}},
+ visualize axis={left axis={goto=max}}},
+ }
+}}]
+\tikzset{
+ data visualization/our system/.append style={
+ all axes= {padding=.5em},
+ left axis= {visualize axis={x axis= {goto=padded min}, padded}},
+ right axis={visualize axis={x axis= {goto=padded max}, padded}},
+ x axis= {visualize axis={left axis={goto=padded min}, padded},
+ visualize axis={left axis={goto=padded max}, padded}},
+ }
+}
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=3cm},
+ 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/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.
+
+\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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [
+ xyz Cartesian cabinet,
+ all axes={visualize axis={low=0, style=->}},
+ x axis={visualize grid={direction axis=y axis}, grid=many},
+ visualize as scatter]
+ data {
+ x, y, z
+ 0, 0, 1
+ 0, 1, 0
+ 2, 2, 2
+ };
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [
+ xyz Cartesian cabinet,
+ all axes={visualize axis={low=0, style=->}, grid=many},
+ x axis={visualize grid={direction axis=z axis}},
+ z axis={visualize grid={direction axis=x 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.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikz \datavisualization [
+ xy Cartesian,
+ all axes={visualize axis={low=0, style=->},
+ grid={some, minor steps between steps}},
+ x axis= {visualize grid={
+ direction axis=y axis,
+ minor={low=0.25, high=1.75, style=red!50}}},
+ visualize as scatter]
+ data {
+ x, y
+ 0, 0
+ 3, 3
+ };
+\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.
+%
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikzset{
+ data visualization/our system/.append style={
+ x axis= {visualize grid={direction axis=left axis}},
+ left axis= {visualize grid={direction axis=x axis,
+ common={style=red!50}}},
+ right axis={visualize grid={direction axis=x axis,
+ common={style=blue!50}}},
+ }
+}
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=3cm, grid=many},
+ 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};
+\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|:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes, all axes={length=3cm},
+ x axis={ticks={stack}},
+ visualize as smooth line]
+ data [format=function] {
+ var x : interval [0:2];
+ 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:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikzset{
+ data visualization/our system/.append style={
+ x axis={visualize ticks={direction axis=left axis, left axis={goto=min}},
+ visualize ticks={direction axis=left axis, left axis={goto=max}},
+ }
+ }
+}
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=3cm, ticks=many},
+ 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|:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
+\tikzset{
+ data visualization/our system/.append style={
+ x axis={
+ visualize ticks={direction axis=left axis,high=0pt,left axis={goto=min}},
+ visualize ticks={direction axis=left axis,low=0pt,left axis={goto=max}},
+ }
+ }
+}
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=3cm, ticks=many},
+ 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{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}[preamble={\usetikzlibrary{datavisualization}}]
+\tikzset{
+ data visualization/our system/.append style={
+ x axis={
+ visualize ticks={direction axis=left axis, left axis={goto=min},
+ high=0pt, tick text at low, stack},
+ visualize ticks={direction axis=left axis, left axis={goto=max},
+ low=0pt, tick text at high, stack}
+ }
+ }
+}
+\tikz \datavisualization [
+ our system,
+ x axis={attribute=time, length=3cm, ticks=some},
+ 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|.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
+\tikz \datavisualization [scientific axes, all axes={length=3cm},
+ x axis={ticks={
+ major also at={6.5 as [no tick text]}}},
+ visualize as smooth line]
+ data [format=function] {
+ 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}
+
+
+\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.
+
+\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.
+ %
+\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
+\tikzdatavisualizationset{
+ our system/.append style={
+ x axis={visualize label={
+ x axis={goto pos=.5},
+ left axis={padding=1.5em, goto=padded min}}}
+ }
+}
+\tikz \datavisualization [
+ 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:
+ %
+\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
+\tikzdatavisualizationset{
+ our system/.append style={
+ x axis={visualize label={
+ x axis={goto pos=.5},
+ node style={
+ at={(0,0 |- data visualization bounding box.south)},
+ below
+} } } } }
+\tikz \datavisualization [
+ 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}
+\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:
+%
+\begin{codeexample}[code only]
+\tikzdatavisualizationset{ our system/.style={
+ % The axes
+ new Cartesian axis=x axis, new Cartesian axis=left axis, new Cartesian axis=right axis,
+ % The directions of the axes
+ all axes={padding=.5em}, left axis={unit vector={(0cm,1pt)}}, right axis={unit vector={(0cm,1pt)}},
+ % The default attributes, other attributes must be configured
+ x axis={attribute=x},
+ % The lengths of the axes
+ 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}},
+ % The styling of the axes
+ every axis/.style={style=black!50}, % make this the default
+ % Visualizing the axes themselves
+ left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}},
+ right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}},
+ x axis= {visualize axis={left axis={goto=padded min}, padded},
+ visualize axis={left axis={goto=padded max}, padded}},
+ % Visualizing the grid, when requested
+ x axis= {visualize grid={direction axis=left axis}},
+ 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,
+ 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}},
+ x axis={visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt,
+ tick text at low},
+ visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt}},
+ % By default, there are ticks on all axes
+ all axes={ticks},
+ % Visualizing the axis labels, when requested
+ x axis={visualize label={x axis={goto pos=.5}, node style={
+ at={(0,0 |- data visualization bounding box.south)}, below}}},
+ left axis={visualize label={left axis={goto pos=.5}, node style={
+ at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}},
+ right axis={visualize label={right axis={goto pos=.5}, node style={
+ at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}},
+}}
+\end{codeexample}
+
+\begin{codeexample}[
+ preamble={\usetikzlibrary{datavisualization}},
+ pre={\tikzdatavisualizationset{
+ our system/.style={
+ % The axes
+ new Cartesian axis=x axis,
+ new Cartesian axis=left axis,
+ new Cartesian axis=right axis,
+ % The default attributes, other attributes must be configured
+ x axis={attribute=x},
+ % The directions of the axes
+ all axes={padding=.5em},
+ left axis={unit vector={(0cm,1pt)}},
+ right axis={unit vector={(0cm,1pt)}},
+ % The lengths of the axes
+ 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}},
+ % The styling of the axes
+ every axis/.style={style=black!50}, % make this the default
+ % Visualizing the axes themselves
+ left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}},
+ right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}},
+ x axis= {visualize axis={left axis={goto=padded min}, padded},
+ visualize axis={left axis={goto=padded max}, padded}},
+ % Visualizing the grid, when requested
+ x axis= {visualize grid={direction axis=left axis, padded}},
+ left axis= {visualize grid={direction axis=x axis, padded, common={style=red!50}}},
+ right axis={visualize grid={direction axis=x axis, padded, common={style=blue!50}}},
+ % Visualizing the ticks, when requested
+ 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}},
+ x axis={
+ visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt, tick text at low},
+ visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt}
+ },
+ % By default, there are ticks on all axes
+ all axes={ticks},
+ % Visualizing the axis labels, when requested
+ x axis={visualize label={
+ x axis={goto pos=.5}, node style={at={(0,0 |- data visualization bounding box.south)}, below}}},
+ left axis={visualize label={
+ left axis={goto pos=.5}, node style={
+ at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}},
+ right axis={visualize label={
+ right axis={goto pos=.5}, node style={
+ at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}},
+ }
+}}]
+\tikz \datavisualization [
+ 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,
+ padding min=0, include value=0, grid,
+ ticks={tick prefix=\$, style={/pgf/number format/fixed,
+ /pgf/number format/fixed zerofill, /pgf/number format/precision=2}}},
+ right axis={attribute=people,
+ label=Population,
+ padding min=0, include value=0,
+ ticks={style=/pgf/number format/fixed}},
+ visualize as line/.list={
+ people 1, people 2, money 1, money 2},
+ people 1={style={visualizer color=blue}},
+ 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};
+\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|.
+
+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
+%
+\begin{codeexample}[code only]
+/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.
+\end{key}