% Copyright 2010 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} To be written... \subsection{Concepts} \subsubsection{Axes} \subsubsection{Mayor, Minor, and Subminor Ticks} \subsubsection{Tick Placement Strategies} \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, see Section~\ref{section-dv-tick-placement-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}[] \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} \subsubsection{Grids} \subsection{Usage} \subsection{Reference: Standard Axis Systems} In this section the axis system commonly used in data visualizations are described. \subsubsection{Scientific Axis Systems} \begin{key}{/tikz/data visualization/scientific axes} This key installs a two-dimensional coordinate system based on the attributes |/data point/x| and |/data point/y|. \begin{codeexample}[] \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. Note, however, that this axis system will always distort the relative magnitudes of the units on the two axis. If you wish the units on both axes to be equal, consider directly specifying the unit length ``by hand'': \begin{codeexample}[] \begin{tikzpicture} \datavisualization [visualize as smooth line, 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. \item Ticks are drawn `` on the outside'' of the frame so that they interfere as little as possible with the data. \item Tick labels and axis labels (if present) are drawn left and below. \end{itemize} \end{key} \begin{key}{/tikz/data visualization/scientific inner axes} This axis system works like |scientific axes|, only the ticks are on the ``inside'' of the frame. \begin{codeexample}[] \begin{tikzpicture} \datavisualization [scientific inner axes, 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}[] \begin{tikzpicture} \datavisualization [scientific inner axes, scientific axes/width=3.2cm, visualize as scatter/.list={a,b}] data [a] { x, y 0, 0 1, 1 0.5, 0.5 2, 1 } data [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 clean axes} This axis system is another version of |scientific axes|. However, 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}[] \begin{tikzpicture} \datavisualization [scientific clean axes, visualize as smooth line] data [format=function] { var x : interval [-12:12]; func y = \value x*\value x*\value x; }; \end{tikzpicture} \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}[] \begin{tikzpicture} \datavisualization [scientific clean axes, visualize as smooth line, scientific axes standard labels, 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{tikzpicture} \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}[] \begin{tikzpicture} \datavisualization [scientific clean axes, visualize as smooth line, scientific axes upright labels, x axis={label=degree $d$, ticks={tick unit=${}^\circ$}}, y axis={label=$\cos d$, ticks={style={/pgf/number format/.cd,precision=4,fixed zerofill}}}] data [format=function] { var x : interval [-10:10] samples 10; func y = cos(\value x); }; \end{tikzpicture} \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}[] \begin{tikzpicture} \datavisualization [scientific clean axes, visualize as smooth line, scientific axes end labels, x axis={label=degree $d$, ticks={tick unit=${}^\circ$}}, y axis={label=$\tan d$}] data [format=function] { var x : interval [-10:10] samples 10; func y = tan(\value x); }; \end{tikzpicture} \end{codeexample} \end{key} \subsubsection{School Book Axis Systems} \begin{key}{/tikz/data visualization/school book axes} This axis system is intended to ``look like'' the coordinate systems often used in school books: The axes are drawn in such a way that they intersect to origin. Furthermore, no automatic scaling is done to ensure that the lengths of units are the same in all directions. This axis system must be used with care -- it is nearly always necessary to specify the desired unit length by hand using the option |unit length|. If the magnitudes of the units on the two axes differ, different unit lengths typically need to be specified for the different axes. Finally, if the data is ``far removed'' from the origin, this axis system will also ``look bad.'' \begin{codeexample}[] \begin{tikzpicture} \datavisualization [school book axes, visualize as smooth line] 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. \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}[] \begin{tikzpicture} \datavisualization [school book axes, visualize as smooth line, school book axes standard labels, 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} \subsubsection{Advanced: 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}[] \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{Reference: Tick Placement Strategies} \label{section-dv-tick-placement-strategies} As described in \ref{section-dv-concept-tick-placement-strategies}, it is not a trivial task for the data visualization engine to correctly automatically determine good positions for the placement of ticks on axes. When the values on an axis range between, say, $17.4$ and $34.5$, it is somewhat unclear where ticks should be placed. \subsubsection{Predefined Strategies} The following strategies are always available: \begin{key}{/tikz/data visualization/axis options/linear steps} This strategy placed ticks at positions that are evenly spaced by the current value of |step|. In detail, the following happens: Let $a$ be the minimum value of the data values along the axis and let $b$ be the maximum. Let the current \emph{stepping} be $s$ (the stepping is set using the |step| option, see below) and let the current \emph{phasing} be $p$ (set using the |phase|) option. Then ticks are placed all positions $i\cdot s + p$ that lie in the interval $[a,b]$, where $i$ ranges over all integers. The tick positions computed in the way described above are \emph{mayor} step positions. In addition to these, if the key |minor steps between steps| is set to some number $n$, then $n$ many minor ticks are introduced between each two mayor ticks (and also before and after the last mayor tick, provided the values still lie in the interval $[a,b]$). Note that is $n$ is $1$, then one minor tick will be added in the middle between any two mayor ticks. Use a value of $9$ (not $10$) to partition the interval between two mayor ticks into ten equally sized minor intervals. \begin{codeexample}[] \begin{tikzpicture} \datavisualization [scientific inner axes, scientific axes/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} \begin{key}{/tikz/data visualization/axis options/exponential steps} This strategy produces ticks at positions that are appropriate for logarithmic plots. It is automatically selected when you use the |logarithmic| option with an axis. In detail, the following happens: As for |linear steps| let numbers $a$, $b$, $s$, and $p$ be given. Then, mayor ticks are placed at all positions $10^{i\cdot s+p}$ that lie in the interval $[a,b]$ for $i \in \mathbb Z$. The minor steps are added in the same way as for |linear steps|. In particular, they interpolate \emph{linearly} between mayor steps. \begin{codeexample}[] \begin{tikzpicture} \datavisualization [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{Choosing a Stepping Explicitly} 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 described above, see the explanations there. \end{key} \begin{key}{/tikz/data visualization/minor steps between steps=\meta{number} (default 9)} As for |step|, see the explanation of |linear steps|. \end{key} \begin{key}{/tikz/data visualization/phase=\meta{value} (initially 0)} As for |step|, see the explanation of |linear steps|. \end{key} \subsubsection{Choosing a Stepping Automatically} The |step| option gives you ``total control'' over the stepping of ticks on an axis, but you often do not know the correct stepping in advance. In this case, you may prefer to have a good value for |step| being computed for you automatically. Like the |step| key, these options are passed to the |ticks| option. So, for instance, you would write |x axis={ticks={about=4}}| to request about four ticks to be placed on the $x$-axis. \begin{key}{/tikz/data visualization/about=\meta{number}} This key asks the data visualization to place \emph{about} \meta{number} many ticks on an axis. It is not guaranteed that \emph{exactly} \meta{number} many ticks will be used, rather the actual number will be the closest number of ticks to \meta{number} so that their stepping is still ``good''. For instance, when you say |about=10|, it may happen that exactly |10|, but perhaps even |13| ticks are actually selected, provided that these numbers of ticks lead to good stepping values like |5| or |2.5| rather than numbers like |3.4| or |7|. The method that is used to determine which steppings a deemed to be ``good'' depends on the current tick placement strategy. \medskip \textbf{Linear steps.} Let us start with |linear steps|: First, the difference between the maximum value $v_{\max}$ and the minimum value $v_{\min}$ on the axis is computed; let us call it $r$ for ``range.'' Then, $r$ is divided by \meta{number}, yielding a target stepping~$s$. If $s$ is a number like $1$ or $5$ or $10$, then this number could be used directly as the new value of |step|. However, $s$ will typically something strange like $0.02345$ or $345223.76$, so $s$ must be replaced by a better value like $0.02$ in the first case and perhaps $250000$ in the second case. In order to determine which number is to be used, $s$ is rewritten in the form $m \cdot 10^k$ with $1 \le m < 10$ and $k \in \mathbb Z$. For instance, $0.02345$ would be rewritten as $2.345 \cdot 10^{-2}$ and $345223.76$ as $3.4522376 \cdot 10^5$. The next step is to replace the still not-so-good number $m$ like $2.345$ or $3.452237$ by a ``good'' value $m'$. For this, the current value of the |about strategy| is used: \begin{key}{/tikz/data visualization/about strategy=\meta{list}} The \meta{list} is a comma-separated sequence of pairs \meta{threshold}/\meta{value} like for instance |1.5/1.0| or |2.3/2.0|. When a good value $m'$ is sought for a given $m$, we iterate over the list and find the first pair \meta{threshold}/\meta{value} where \meta{threshold} exceeds~$m$. Then $m'$ is set to \meta{value}. For instance, if \meta{list} is |1.5/1.0,2.3/2.0,4/2.5,7/5,11/10|, which is the default, then for $m=3.141$ we would get $m'=2.5$ since $4 > 3.141$, but $2.3 \le 3.141$. For $m=6.3$ we would get $m'=5$. \end{key} Once $m'$ has been determined, the stepping is set to $s' = m' \cdot 10^k$. % Define an axis type \tikzdatavisualizationset{ one dimensional axis/.style={ new Cartesian axis=axis, axis={ attribute=main, unit vector={(0pt,1pt)}, visualize axis={style=->}, visualize ticks={major={tick text at low},direction axis=perpendicular}, length=3cm }, new Cartesian axis=perpendicular, perpendicular={ attribute=perp, unit vector={(1pt,0pt)}, include values=0, include values=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 values=0, include values=\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 values=1, include values=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/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{Advanced: Defining New Placing 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}[] \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 Axes} \subsection{Advanced: Creating New Axis Systems}