| 1 |
% Copyright 2019 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Axes} |
| 12 |
\label{section-dv-axes} |
| 13 |
|
| 14 |
\subsection{Overview} |
| 15 |
|
| 16 |
When a data point is visualized, the most obvious way of creating a visual |
| 17 |
representation of its many attributes is to vary \emph{where} the data point is |
| 18 |
shown. The data visualization system uses \emph{axes} to turn data point |
| 19 |
attributes into positions on a page. The simplest -- and most common -- use of |
| 20 |
axes is to vary the horizontal position of data points according to one |
| 21 |
attribute and to vary the vertical position according to another attribute. In |
| 22 |
contrast, in a polar plot one attribute dictates the distance of the data point |
| 23 |
from the origin and another attribute describes the angle. From the data |
| 24 |
visualization engine's point of view, in both cases two \emph{axes} are |
| 25 |
involved. |
| 26 |
|
| 27 |
In addition to specifying how the value of a certain attribute is converted |
| 28 |
into a displacement on the page, an axis is also typically (but not always) |
| 29 |
visualized (``drawn'') somewhere on the page. In this case, it is also |
| 30 |
customary to add a visual representation on this axis of which attribute values |
| 31 |
correspond to which positions on the page -- something commonly known as |
| 32 |
\emph{ticks}. Similar to ticks, \emph{grid lines} also indicate positions where |
| 33 |
a certain attribute has a certain value, but instead of just indicating a |
| 34 |
single position on an axis, a grid line goes through all points that share an |
| 35 |
attribute value. |
| 36 |
|
| 37 |
In the following, in Section~\ref{section-dv-axes-main} we first have a look at |
| 38 |
how axes can be defined and configured. As you will see, a lot of powerful |
| 39 |
configurations are available, but you will rarely define and configure an axis |
| 40 |
from scratch. Rather, it is more common to use a preconfigured axis instead. |
| 41 |
Section~\ref{section-dv-axis-systems} introduces \emph{axis systems}, which are |
| 42 |
predefined bundles of axes. You can define your own axis systems, but, again, |
| 43 |
in most cases it will suffice to just use one of the many preconfigured axis |
| 44 |
systems and use a few options to configure it so that it fits your need. |
| 45 |
Section~\ref{section-dv-ticks-and-grids} explains how ticks and grid lines can |
| 46 |
be configured. Again, several layers of options allow you to configure the way |
| 47 |
ticks look and where they are placed in great detail. |
| 48 |
|
| 49 |
This section documents the standard axis systems that are always available. For |
| 50 |
polar axis systems, a special library needs to be loaded, which is documented |
| 51 |
in Section~\ref{section-dv-polar}. |
| 52 |
|
| 53 |
|
| 54 |
\subsection{Basic Configuration of Axes} |
| 55 |
\label{section-dv-axes-main} |
| 56 |
|
| 57 |
Inside the data visualization system, an \emph{axis} is roughly a ``systematic, |
| 58 |
named way of mapping an attribute to a position on a page''. For instance, the |
| 59 |
classical ``$x$-axis'' is the ``systematic way of mapping the value of the |x| |
| 60 |
attribute of data points to a horizontal position on the page''. An axis is |
| 61 |
\emph{not} its visual representation (such as the horizontal line with the |
| 62 |
ticks drawn to represent the $x$-axis), but a visual representation can be |
| 63 |
created once an axis has been defined. |
| 64 |
|
| 65 |
The transformation of an attribute value (such as the value |1000000000| for |
| 66 |
the |x| attribute) to a specific displacement of the corresponding data point |
| 67 |
on the page involves two steps: |
| 68 |
% |
| 69 |
\begin{enumerate} |
| 70 |
\item First, the range of possible values such as $[-5.6\cdot |
| 71 |
10^{12},7.8\cdot 10^{12}]$ must be mapped to a ``reasonable'' interval |
| 72 |
such as $[0\mathrm{cm},5\mathrm{cm}]$ or $[0^\circ,180^\circ]$. |
| 73 |
\tikzname's drawing routines will only be able to cope with values from |
| 74 |
such a ``reasonable'' interval. |
| 75 |
\item Second, the values from the reasonable interval must be mapped to a |
| 76 |
transformation. |
| 77 |
\end{enumerate} |
| 78 |
% |
| 79 |
The first step is always the same for all axes, while the second requires |
| 80 |
different strategies. For this reason, the command |new axis base| is used to |
| 81 |
create a ``basic'' axis that has a ``scaling mapper'', whose job it is to map |
| 82 |
the range of values of a specific attribute to a reasonable interval, but such |
| 83 |
a basic axis does not define an actual transformation object. For this second |
| 84 |
step, additional objects such as a |linear transformer| need to be created |
| 85 |
separately. |
| 86 |
|
| 87 |
|
| 88 |
\subsubsection{Usage} |
| 89 |
|
| 90 |
To create an axis, the key |new axis base| is used first. Since this key does |
| 91 |
not create a transformation object, users typically do not use this key |
| 92 |
directly. Rather, it is used internally by other keys that create ``real'' |
| 93 |
axes. These keys are listed in Section~\ref{section-dv-reference-axis-types}. |
| 94 |
|
| 95 |
\begin{key}{/tikz/data visualization/new axis base=\meta{axis name}} |
| 96 |
This key defines a new axis for the current data visualization called |
| 97 |
\meta{name}. This has two effects: |
| 98 |
% |
| 99 |
\begin{enumerate} |
| 100 |
\item A so called \emph{scaling mapper} is created that will monitor a |
| 101 |
certain attribute, rescale it, and map it to another attribute. |
| 102 |
(This will be explained in detail in a moment.) |
| 103 |
\item The \meta{axis name} is made available as a key that can be used |
| 104 |
to configure the axis: |
| 105 |
% |
| 106 |
\begin{key}{/tikz/data visualization/\meta{axis name}=\meta{options}} |
| 107 |
This key becomes available once |new axis base=|meta{axis name} |
| 108 |
has been called. It will execute the \meta{options} with the |
| 109 |
path prefix |/tikz/data visualization/axis options|. |
| 110 |
% |
| 111 |
\begin{codeexample}[code only] |
| 112 |
[new axis base=my axis, |
| 113 |
my axis={attribute=some attribute}] |
| 114 |
\end{codeexample} |
| 115 |
\end{key} |
| 116 |
\item The \meta{axis name} becomes part of the current set of axes. |
| 117 |
This set can be accessed through the following key: |
| 118 |
% |
| 119 |
\begin{key}{/tikz/data visualization/all axes=\meta{options}} |
| 120 |
This key passes the \meta{options} to all axes inside the |
| 121 |
current scope, just as if you had written \meta{some axis |
| 122 |
name}|=|\meta{options} for each \meta{some axis name} in the |
| 123 |
current scope, including the just-created name \meta{axis |
| 124 |
name}. |
| 125 |
\end{key} |
| 126 |
\end{enumerate} |
| 127 |
% |
| 128 |
There are many \meta{options} that can be passed to a newly created axis. |
| 129 |
They are explained in the rest of this section. |
| 130 |
\end{key} |
| 131 |
|
| 132 |
Note the |new axis base| does \emph{not} cause attributes to be mapped to |
| 133 |
positions on a page. Rather, special keys like |new Cartesian axis| first use |
| 134 |
|new axis base| to create an axis and then create an internal object that |
| 135 |
performs a linear mapping of the attribute to positions along a vectors. |
| 136 |
|
| 137 |
|
| 138 |
\subsubsection{The Axis Attribute} |
| 139 |
\label{section-dv-axis-attribute} |
| 140 |
|
| 141 |
The first main job of an axis is to map the different values of some attribute |
| 142 |
to a reasonable interval. To achieve this, the following options are important |
| 143 |
(recall that these options are passed to the key whose name is the name of the |
| 144 |
axis): |
| 145 |
|
| 146 |
\begin{key}{/tikz/data visualization/axis options/attribute=\meta{attribute}} |
| 147 |
Specifies that the axis is used to transform the data points according the |
| 148 |
different values of the key |/data point/|\meta{attribute}. For instance, |
| 149 |
when we create a classical two-dimensional Cartesian coordinate system, |
| 150 |
then there are two axes called |x axis| and |y axis| that monitor the |
| 151 |
values of the attributes |/data point/x| and |/data point/y|, respectively: |
| 152 |
% |
| 153 |
\begin{codeexample}[code only] |
| 154 |
[new axis base=x axis, |
| 155 |
new axis base=y axis, |
| 156 |
x axis={attribute=x}, |
| 157 |
y axis={attribute=y}] |
| 158 |
\end{codeexample} |
| 159 |
% |
| 160 |
In another example, we also create an |x axis| and a |y axis|. However, |
| 161 |
this time, we want to plot the values of the |/data point/time| attribute |
| 162 |
on the $x$-axis and, say, the value of the |height| attribute on the |
| 163 |
$y$-axis: |
| 164 |
% |
| 165 |
\begin{codeexample}[code only] |
| 166 |
[new axis base=x axis, |
| 167 |
new axis base=y axis, |
| 168 |
x axis={attribute=time}, |
| 169 |
y axis={attribute=height}] |
| 170 |
\end{codeexample} |
| 171 |
% |
| 172 |
During the data visualization, the \meta{attribute} will be ``monitored'' |
| 173 |
during the survey phase. This means that for each data point, the current |
| 174 |
value of |/data point/|\meta{attribute} is examined and the minimum value |
| 175 |
of all of these values as well as the maximum value is recorded internally. |
| 176 |
Note that this works even when very large numbers like |100000000000| are |
| 177 |
involved. |
| 178 |
|
| 179 |
Here is a real-life example. The |scientific axes| create two axes, called |
| 180 |
|x axis| and |y axis|, respectively. |
| 181 |
% |
| 182 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 183 |
\tikz \datavisualization [scientific axes, |
| 184 |
x axis={attribute=people, length=2.5cm, ticks=few}, |
| 185 |
y axis={attribute=year}, |
| 186 |
visualize as scatter] |
| 187 |
data { |
| 188 |
year, people |
| 189 |
1900, 100 |
| 190 |
1910, 200 |
| 191 |
1950, 200 |
| 192 |
1960, 250 |
| 193 |
2000, 150 |
| 194 |
}; |
| 195 |
\end{codeexample} |
| 196 |
% |
| 197 |
\end{key} |
| 198 |
|
| 199 |
|
| 200 |
\subsubsection{The Axis Attribute Range Interval} |
| 201 |
|
| 202 |
Once an attribute has been specified for an axis, the data visualization engine |
| 203 |
will start monitoring this value. This means that before anything actual |
| 204 |
visualization is done, a ``survey phase'' is used to determine the range of |
| 205 |
values encountered for the attribute for all data points. This range of values |
| 206 |
results in what is called the \emph{attribute range interval}. Its minimum is |
| 207 |
the smallest value encountered in the data and its maximum is the largest |
| 208 |
value. |
| 209 |
|
| 210 |
Even though the attribute range interval is computed automatically and even |
| 211 |
though you typically do not need to worry about it, there are some situations |
| 212 |
where you may wish to set or enlarge the attribute range interval: |
| 213 |
% |
| 214 |
\begin{itemize} |
| 215 |
\item You may wish to start the interval with $0$, even though the range of |
| 216 |
values contains only positive values. |
| 217 |
\item You may wish to slightly enlarge the interval so that, say, the |
| 218 |
maximum is some ``nice'' value like |100| or |60|. |
| 219 |
\end{itemize} |
| 220 |
|
| 221 |
The following keys can be used to influence the size of the attribute range |
| 222 |
interval: |
| 223 |
% |
| 224 |
\begin{key}{/tikz/data visualization/axis options/include value=\meta{list of value}} |
| 225 |
This key ``fakes'' data points for which the attribute's values are in the |
| 226 |
comma-separated \meta{list of values}. For instance, when you write |
| 227 |
|include value=0|, then the attribute range interval is guaranteed to |
| 228 |
contain |0| -- even if the actual data points are all positive or all |
| 229 |
negative. |
| 230 |
% |
| 231 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 232 |
\tikz \datavisualization [scientific axes, all axes={length=3cm}, |
| 233 |
visualize as line] |
| 234 |
data [format=function] { |
| 235 |
var x : interval [5:10]; |
| 236 |
func y = \value x * \value x; |
| 237 |
}; |
| 238 |
\end{codeexample} |
| 239 |
% |
| 240 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 241 |
\tikz \datavisualization [scientific axes, all axes={length=3cm}, |
| 242 |
visualize as line, |
| 243 |
x axis={include value=20}, |
| 244 |
y axis={include value=0}] |
| 245 |
data [format=function] { |
| 246 |
var x : interval [5:10]; |
| 247 |
func y = \value x * \value x; |
| 248 |
}; |
| 249 |
\end{codeexample} |
| 250 |
% |
| 251 |
\end{key} |
| 252 |
|
| 253 |
\begin{key}{/tikz/data visualization/axis options/min value=\meta{value}} |
| 254 |
This key allows you to simply set the minimum value, regardless of which |
| 255 |
values are present in the actual data. This key should be used with care: |
| 256 |
If there are data points for which the attribute's value is less than |
| 257 |
\meta{value}, they will still be depicted, but typically outside the normal |
| 258 |
visualization area. Usually, saying |include value=|\meta{value} will |
| 259 |
achieve the same as saying |min value=|\meta{value}, but with less danger |
| 260 |
of creating ill-formed visualizations. |
| 261 |
\end{key} |
| 262 |
|
| 263 |
\begin{key}{/tikz/data visualization/axis options/max value=\meta{value}} |
| 264 |
Works like |min value|. |
| 265 |
\end{key} |
| 266 |
|
| 267 |
|
| 268 |
\subsubsection{Scaling: The General Mechanism} |
| 269 |
|
| 270 |
The above key allows us specify which attribute should be ``monitored''. The |
| 271 |
next key is used to specify what should happen with the observed values. |
| 272 |
|
| 273 |
\begin{key}{/tikz/data visualization/axis options/scaling=\meta{scaling spec}} |
| 274 |
The \meta{scaling spec} must have the following form: |
| 275 |
% |
| 276 |
\begin{quote} |
| 277 |
\meta{$s_1$}| at |\meta{$t_1$}| and |\meta{$s_2$}| at |\meta{$t_2$} |
| 278 |
\end{quote} |
| 279 |
% |
| 280 |
This means that monitored values in the interval $[s_1,s_2]$ should be |
| 281 |
mapped to values the ``reasonable'' interval $[t_1,t_2]$, instead. For |
| 282 |
instance, we might write |
| 283 |
% |
| 284 |
\begin{codeexample}[code only] |
| 285 |
[y axis = {scaling = 1900 at 0cm and 2000 at 5cm}] |
| 286 |
\end{codeexample} |
| 287 |
% |
| 288 |
in order to map dates between 1900 and 2000 to the dimension interval |
| 289 |
$[0\mathrm{cm},5\mathrm{cm}]$. |
| 290 |
% |
| 291 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 292 |
\tikz \datavisualization |
| 293 |
[scientific axes, |
| 294 |
x axis={attribute=people, length=2.5cm, ticks=few}, |
| 295 |
y axis={attribute=year, scaling=1900 at 0cm and 2000 at 5cm}, |
| 296 |
visualize as scatter] |
| 297 |
data { |
| 298 |
year, people |
| 299 |
1900, 100 |
| 300 |
1910, 200 |
| 301 |
1950, 200 |
| 302 |
1960, 250 |
| 303 |
2000, 150 |
| 304 |
}; |
| 305 |
\end{codeexample} |
| 306 |
% |
| 307 |
So much for the basic idea. Let us now have a detailed look at what |
| 308 |
happens. |
| 309 |
|
| 310 |
|
| 311 |
\medskip |
| 312 |
\textbf{Number format and the min and max keywords.} |
| 313 |
The source values $s_1$ and $s_2$ are typically just numbers like |3.14| or |
| 314 |
|10000000000|. However, as described in |
| 315 |
Section~\ref{section-dv-expressions}, you can also specify expressions like |
| 316 |
|(pi/2)|, provided that (currently) you put them in parentheses. |
| 317 |
|
| 318 |
Instead of a number, you may alternatively also use the two key words |min| |
| 319 |
and |max| for $s_1$ and/or $s_2$. In this case, |min| evaluates to the |
| 320 |
smallest value observed for the attribute in the data, symmetrically |max| |
| 321 |
evaluates to the largest values. For instance, in the above example with |
| 322 |
the |year| attribute ranging from |1900| to |2000|, the keyword |min| would |
| 323 |
stand for |1900| and |max| for |2000|. Similarly, for the |people| |
| 324 |
attribute |min| stands for |100| and |max| for |250|. Note that |min| and |
| 325 |
|max| can only be used for $s_1$ and $s_2$, not for $t_1$ and $t_2$. |
| 326 |
|
| 327 |
A typical use of the |min| and |max| keywords is to say |
| 328 |
% |
| 329 |
\begin{codeexample}[code only] |
| 330 |
scaling = min at 0cm and max at 5cm |
| 331 |
\end{codeexample} |
| 332 |
% |
| 333 |
to map the complete range of values into an interval of length of 5cm. |
| 334 |
|
| 335 |
The interval $[s_1,s_2]$ need not contain all values that the |
| 336 |
\meta{attribute} may attain. It is permissible that values are less than |
| 337 |
$s_1$ or more than $s_2$. |
| 338 |
|
| 339 |
|
| 340 |
\medskip |
| 341 |
\textbf{Linear transformation of the attribute.} |
| 342 |
As indicated earlier, the main job of an axis is to map values from a |
| 343 |
``large'' interval $[s_1,s_2]$ to a more reasonable interval $[t_1,t_2]$. |
| 344 |
Suppose that for the current data point the value of the key |
| 345 |
|/data point/|\meta{attribute} is the number $v$. In the simplest case, the |
| 346 |
following happens: A new value $v'$ is computed so that $v' = t_1$ when |
| 347 |
$v=s_1$ and $v'=t_2$ when $v=s_2$ and $v'$ is some value in between $t_1$ |
| 348 |
and $t_2$ then $v$ is some value in between $s_1$ and $s_2$. (Formally, in |
| 349 |
this basic case $v' = t_1 + (v-s_1)\frac{t_2-t_1}{s_2-s_1}$.) |
| 350 |
|
| 351 |
Once $v'$ has been computed, it is stored in the key |
| 352 |
|/data point/|\meta{attribute}|/scaled|. Thus, the ``reasonable'' value |
| 353 |
$v'$ does not replace the value of the attribute, but it is placed in a |
| 354 |
different key. This means that both the original value and the more |
| 355 |
``scaled'' values are available when the data point is visualized. |
| 356 |
|
| 357 |
As an example, suppose you have written |
| 358 |
% |
| 359 |
\begin{codeexample}[code only] |
| 360 |
[x axis = {attribute = x, scaling=1000 at 20 and 2000 at 30}] |
| 361 |
\end{codeexample} |
| 362 |
% |
| 363 |
Now suppose that |/data point/x| equals |1200| for a data point. Then the |
| 364 |
key |/data point/x/scaled| will be set to |22| when the data point is being |
| 365 |
visualized. |
| 366 |
|
| 367 |
|
| 368 |
\medskip |
| 369 |
\textbf{Nonlinear transformations of the attribute.} |
| 370 |
By default, the transformation of $[s_1,s_2]$ to $[t_1,t_2]$ is the linear |
| 371 |
transformation described above. However, in some case you may be interested |
| 372 |
in a different kind of transformation: For example, in a logarithmic plot, |
| 373 |
values of an attribute may range between, say, |1| and |1000| and we want |
| 374 |
an axis of length |3cm|. So, we would write |
| 375 |
% |
| 376 |
\begin{codeexample}[code only] |
| 377 |
[x axis = {attribute = x, scaling=1 at 0cm and 1000 at 3cm}] |
| 378 |
\end{codeexample} |
| 379 |
% |
| 380 |
Indeed, |1| will now be mapped to position |0cm| and |1000| will be mapped |
| 381 |
to position |3cm|. Now, the value |10| will be mapped to approximately |
| 382 |
|0.03cm| because it is (almost) at one percent between |1| and |1000|. |
| 383 |
However, in a logarithmic plot we actually want |10| to be mapped to the |
| 384 |
position |1cm| rather than |0.03cm| and we want |100| to be mapped to the |
| 385 |
position |2cm|. Such a mapping a \emph{nonlinear} mapping between the |
| 386 |
intervals. |
| 387 |
|
| 388 |
In order to achieve such a nonlinear mapping, the |function| key can be |
| 389 |
used, whose syntax is described in a moment. The effect of this key is to |
| 390 |
specify a function $f \colon \mathbb{R} \to \mathbb{R}$ like, say, the |
| 391 |
logarithm function. When such a function is specified, the mapping of $v$ |
| 392 |
to $v'$ is computed as follows: |
| 393 |
% |
| 394 |
\begin{align*} |
| 395 |
v' = t_1 + (f(s_2) - f(v))\frac{t_2 - t_1}{f(s_2)-f(s_1)}. |
| 396 |
\end{align*} |
| 397 |
|
| 398 |
The syntax of the |function| key is described next, but you typically will |
| 399 |
not call this key directly. Rather, you will use a key like |logarithmic| |
| 400 |
that installs appropriate code for the |function| key for you. |
| 401 |
% |
| 402 |
\begin{key}{/tikz/data visualization/axis options/function=\meta{code}} |
| 403 |
The \meta{code} should specify a function $f$ that is applied during |
| 404 |
the transformation of the interval $[s_1,s_2]$ to the interval |
| 405 |
$[t_1,t_2]$ in the following way: When the \meta{code} is called, the |
| 406 |
macro |\pgfvalue| will have been set to an internal representation of |
| 407 |
the to-be-transformed value~$v$. You can then call the commands of the |
| 408 |
math-micro-kernel of the data visualization system, see |
| 409 |
Section~\ref{section-dv-math-kernel}, to compute a new value. This new |
| 410 |
value must once more be stored in |\pgfvalue|. |
| 411 |
|
| 412 |
The most common use of this key is to say |
| 413 |
% |
| 414 |
\begin{codeexample}[code only] |
| 415 |
some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}} |
| 416 |
\end{codeexample} |
| 417 |
% |
| 418 |
This specifies that the function $f$ is the logarithm function. |
| 419 |
% |
| 420 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 421 |
\tikz \datavisualization |
| 422 |
[scientific axes, |
| 423 |
x axis={ticks={major={at={1,10,100,1000}}}, |
| 424 |
scaling=1 at 0cm and 1000 at 3cm, |
| 425 |
function=\pgfdvmathln{\pgfvalue}{\pgfvalue}}, |
| 426 |
visualize as scatter] |
| 427 |
data [format=named] { |
| 428 |
x={1,100,...,1000}, y={1,2,3} |
| 429 |
}; |
| 430 |
\end{codeexample} |
| 431 |
% |
| 432 |
Another possibility might be to use the square-root function, instead: |
| 433 |
% |
| 434 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 435 |
\tikz \datavisualization |
| 436 |
[scientific axes, |
| 437 |
x axis={ticks=few, |
| 438 |
scaling=1 at 0cm and 1000 at 3cm, |
| 439 |
function=\pgfdvmathunaryop{\pgfvalue}{sqrt}{\pgfvalue}}, |
| 440 |
visualize as scatter] |
| 441 |
data [format=named] { |
| 442 |
x={0,100,...,1000}, y={1,2,3} |
| 443 |
}; |
| 444 |
\end{codeexample} |
| 445 |
\end{key} |
| 446 |
|
| 447 |
|
| 448 |
\medskip |
| 449 |
\textbf{Default scaling.} |
| 450 |
When no scaling is specified, it may seem natural to use $[0,1]$ both as |
| 451 |
the source and the target interval. However, this would not work when the |
| 452 |
logarithm function is used as transformations: In this case the logarithm |
| 453 |
of zero would be computed, leading to an error. Indeed, for a logarithmic |
| 454 |
axis it is far more natural to use $[1,10]$ as the source interval and |
| 455 |
$[0,1]$ as the target interval. |
| 456 |
|
| 457 |
For these reasons, the default value for the |scaling| that is used when no |
| 458 |
value is specified explicitly can be set using a special key: |
| 459 |
% |
| 460 |
\begin{key}{/tikz/data visualization/axis options/scaling/default=\meta{text}} |
| 461 |
The \meta{text} is used as |scaling| whenever no other scaling is |
| 462 |
specified. This key is mainly used when a transformation function is |
| 463 |
set using |function|; normally, you will not use this key directly. |
| 464 |
\end{key} |
| 465 |
\end{key} |
| 466 |
|
| 467 |
Most of the time, you will not use neither the |scaling| nor the |function| key |
| 468 |
directly, but rather you will use one of the following predefined styles |
| 469 |
documented in the following. |
| 470 |
|
| 471 |
|
| 472 |
\subsubsection{Scaling: Logarithmic Axes} |
| 473 |
|
| 474 |
\begin{key}{/tikz/data visualization/axis options/logarithmic} |
| 475 |
When this key is used with an axis, three things happen: |
| 476 |
% |
| 477 |
\begin{enumerate} |
| 478 |
\item The transformation |function| of the axis is setup to the |
| 479 |
logarithm. |
| 480 |
\item The strategy for automatically generating ticks and grid lines is |
| 481 |
set to the |exponential strategy|, see |
| 482 |
Section~\ref{section-dv-exponential-strategy} for details. |
| 483 |
\item The default scaling is setup sensibly. |
| 484 |
\end{enumerate} |
| 485 |
% |
| 486 |
All told, to turn an axis into a logarithmic axis, you just need to add |
| 487 |
this option to the axis. |
| 488 |
% |
| 489 |
\begin{codeexample}[ |
| 490 |
width=8cm, |
| 491 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 492 |
] |
| 493 |
\tikz \datavisualization [scientific axes, |
| 494 |
x axis={logarithmic}, |
| 495 |
y axis={logarithmic}, |
| 496 |
visualize as line] |
| 497 |
data [format=function] { |
| 498 |
var x : interval [0.01:100]; |
| 499 |
func y = \value x * \value x; |
| 500 |
}; |
| 501 |
\end{codeexample} |
| 502 |
% |
| 503 |
Note that this will work with any axis, including, say, the degrees on a |
| 504 |
polar axis: |
| 505 |
% |
| 506 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}] |
| 507 |
\tikz \datavisualization |
| 508 |
[new polar axes, |
| 509 |
angle axis={logarithmic, scaling=1 at 0 and 90 at 90}, |
| 510 |
radius axis={scaling=0 at 0cm and 100 at 3cm}, |
| 511 |
visualize as scatter] |
| 512 |
data [format=named] { |
| 513 |
angle={1,10,...,90}, radius={1,10,...,100} |
| 514 |
}; |
| 515 |
\end{codeexample} |
| 516 |
% |
| 517 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}] |
| 518 |
\tikz \datavisualization |
| 519 |
[new polar axes, |
| 520 |
angle axis={degrees}, |
| 521 |
radius axis={logarithmic, scaling=1 at 0cm and 100 at 3cm}, |
| 522 |
visualize as scatter] |
| 523 |
data [format=named] { |
| 524 |
angle={1,10,...,90}, radius={1,10,...,100} |
| 525 |
}; |
| 526 |
\end{codeexample} |
| 527 |
% |
| 528 |
\end{key} |
| 529 |
|
| 530 |
|
| 531 |
\subsubsection{Scaling: Setting the Length or Unit Length} |
| 532 |
|
| 533 |
\begin{key}{/tikz/data visualization/axis options/length=\meta{dimension}} |
| 534 |
Sets |scaling| to |min at 0cm and max at |\meta{dimension}. The effect is |
| 535 |
that the range of all values of the axis's attribute will be mapped to an |
| 536 |
interval of exact length \meta{dimension}. |
| 537 |
% |
| 538 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 539 |
\tikz \datavisualization [scientific axes, |
| 540 |
x axis={length=3cm}, |
| 541 |
y axis={length=2cm}, |
| 542 |
all axes={ticks=few}, |
| 543 |
visualize as line] |
| 544 |
data { |
| 545 |
x, y |
| 546 |
10, 10 |
| 547 |
20, 20 |
| 548 |
15, 30 |
| 549 |
13, 20 |
| 550 |
}; |
| 551 |
\end{codeexample} |
| 552 |
% |
| 553 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 554 |
\tikz \datavisualization [scientific axes, |
| 555 |
x axis={length=3cm}, |
| 556 |
y axis={length=4cm}, |
| 557 |
all axes={ticks=few}, |
| 558 |
visualize as line] |
| 559 |
data { |
| 560 |
x, y |
| 561 |
10, 10 |
| 562 |
20, 20 |
| 563 |
15, 30 |
| 564 |
13, 20 |
| 565 |
}; |
| 566 |
\end{codeexample} |
| 567 |
% |
| 568 |
\end{key} |
| 569 |
|
| 570 |
\begin{key}{/tikz/data visualization/axis options/unit length=\meta{dimension}\opt{| per |\meta{number}| units|}} |
| 571 |
Sets |scaling| to |0 at 0cm and 1 at |\meta{dimension}. In other words, |
| 572 |
this key allows you to specify how long a single unit should be. This key |
| 573 |
is particularly useful when you wish to ensure that the same scaling is |
| 574 |
used across multiple axes or pictures. |
| 575 |
% |
| 576 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 577 |
\tikz \datavisualization [scientific axes, |
| 578 |
all axes={ticks=few, unit length=1mm}, |
| 579 |
visualize as line] |
| 580 |
data { |
| 581 |
x, y |
| 582 |
10, 10 |
| 583 |
40, 20 |
| 584 |
15, 30 |
| 585 |
13, 20 |
| 586 |
}; |
| 587 |
\end{codeexample} |
| 588 |
% |
| 589 |
The optional |per |\meta{number}| units| allows you to apply more drastic |
| 590 |
scaling. Suppose that you want to plot a graph where one billion |
| 591 |
corresponds to one centimeter. Then the unit length would be need to be set |
| 592 |
to a hundredth of a nanometer -- much too small for \TeX\ to handle as a |
| 593 |
dimension. In this case, you can write |
| 594 |
|unit length=1cm per 1000000000 units|: |
| 595 |
% |
| 596 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 597 |
\tikz \datavisualization |
| 598 |
[scientific axes, |
| 599 |
x axis={unit length=1mm per 1000000000 units, ticks=few}, |
| 600 |
visualize as line] |
| 601 |
data { |
| 602 |
x, y |
| 603 |
10000000000, 10 |
| 604 |
40000000000, 20 |
| 605 |
15000000000, 30 |
| 606 |
13000000000, 20 |
| 607 |
}; |
| 608 |
\end{codeexample} |
| 609 |
% |
| 610 |
\end{key} |
| 611 |
% |
| 612 |
\begin{key}{/tikz/data visualization/axis options/power unit length=\meta{dimension}} |
| 613 |
This key is used in conjunction with the |logarithmic| setting. It cases |
| 614 |
the |scaling| to be set to |1 at 0cm and 10 at |\meta{dimension}. This |
| 615 |
causes a ``power unit'', that is, one power of ten in a logarithmic plot, |
| 616 |
to get a length of \meta{dimension}. Again, this key is useful for ensuring |
| 617 |
that the same scaling is used across multiple axes or pictures. |
| 618 |
% |
| 619 |
\begin{codeexample}[width=8cm,preamble={\usetikzlibrary{datavisualization}}] |
| 620 |
\tikz \datavisualization |
| 621 |
[scientific axes, |
| 622 |
y axis={logarithmic, power unit length=1mm, grid}, |
| 623 |
visualize as line] |
| 624 |
data { |
| 625 |
x, y |
| 626 |
0, 0.0000000001 |
| 627 |
1, 1 |
| 628 |
2, 100000 |
| 629 |
3, 100000000000 |
| 630 |
4, 10000000000000000000000000000000 |
| 631 |
5, 500000000 |
| 632 |
6, 5000000000000000000 |
| 633 |
}; |
| 634 |
\end{codeexample} |
| 635 |
% |
| 636 |
\end{key} |
| 637 |
|
| 638 |
|
| 639 |
\subsubsection{Axis Label} |
| 640 |
|
| 641 |
An axis can have a \emph{label}, which is a textual representation of the |
| 642 |
attribute according to which the axis varies the position of the page. You can |
| 643 |
set the attribute using the following key: |
| 644 |
|
| 645 |
\begin{key}{/tikz/data visualization/axis options/label=\opt{|\char`\{[|\meta{options}|]|}\meta{text}\opt{|\char`\}|} |
| 646 |
(default \normalfont axis's label in math mode)% |
| 647 |
} |
| 648 |
This key sets the label of an axis to \meta{text}. This text will typically |
| 649 |
be placed inside a |node| and the \meta{options} can be used to further |
| 650 |
configure the way this node is rendered. The \meta{options} will be |
| 651 |
executed with the path prefix |/tikz/data visualization/|, so you need to |
| 652 |
say |node style| to configure the styling of a node, see |
| 653 |
Section~\ref{section-dv-style}. |
| 654 |
% |
| 655 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 656 |
\tikz \datavisualization [ |
| 657 |
scientific axes, |
| 658 |
x axis = {label, length=2.5cm}, |
| 659 |
y axis = {label={[node style={fill=blue!20}]{$x^2$}}}, |
| 660 |
visualize as smooth line] |
| 661 |
data [format=function] { |
| 662 |
var x : interval [-3:5]; |
| 663 |
func y = \value x * \value x; |
| 664 |
}; |
| 665 |
\end{codeexample} |
| 666 |
% |
| 667 |
\end{key} |
| 668 |
|
| 669 |
Note that using the |label| key does not actually cause a node to be created, |
| 670 |
because it is somewhat unclear where the label should be placed. Instead, the |
| 671 |
|visualize label| key is used (typically internally by an axis system) to show |
| 672 |
the label at some sensible position. This key is documented in |
| 673 |
Section~\ref{section-dv-visualize-label}. |
| 674 |
|
| 675 |
|
| 676 |
\subsubsection{Reference: Axis Types} |
| 677 |
\label{section-dv-reference-axis-types} |
| 678 |
|
| 679 |
As explained earlier, when you use |new axis base| to create a new axis, a |
| 680 |
powerful scaling and attribute mapping mechanism is installed, but no mapping |
| 681 |
of values to positions on the page is performed. For this, a |
| 682 |
\emph{transformation object} must be installed. The following keys take care of |
| 683 |
this for you. Note, however, that even these keys do not cause a visual |
| 684 |
representation of the axis to be added to the visualization -- this is the job |
| 685 |
of an axis system, see Section~\ref{section-dv-axis-systems}. |
| 686 |
|
| 687 |
\begin{key}{/tikz/data visualization/new Cartesian axis=\meta{name}} |
| 688 |
This key creates a new ``Cartesian'' axis, named \meta{name}. For such an |
| 689 |
axis, the (scaled) values of the axis's attribute are transformed into a |
| 690 |
displacement on the page along a straight line. The following key is used |
| 691 |
to configure in which ``direction'' the axis points: |
| 692 |
% |
| 693 |
\begin{key}{/tikz/data visualization/axis options/unit vector=\meta{coordinate} (initially {(1pt,0pt)})} |
| 694 |
Recall that an axis takes the values of an attribute and rescales them |
| 695 |
so that they fit into a ``reasonable'' interval $[t_1,t_2]$. Suppose |
| 696 |
that $v'$ is the rescaled dimension in (\TeX) points. Then when the |
| 697 |
data point is visualized, the coordinate system will be shifted by $v'$ |
| 698 |
times the \meta{coordinate}. |
| 699 |
|
| 700 |
As an example, suppose that you have said |
| 701 |
|scaling=0 and 10pt and 50 and 20pt|. Then when the underlying |
| 702 |
attribute has the value |25|, it will be mapped to a $v'$ of $15$ |
| 703 |
(because |25| lies in the middle of |0| and |50| and |15pt| lies in the |
| 704 |
middle of |10pt| and |20pt|). This, in turn, causes the data point to |
| 705 |
be displaced by $15$ times the \meta{coordinate}. |
| 706 |
|
| 707 |
The bottom line is that the \meta{coordinate} should usually denote a |
| 708 |
point that is at distance |1pt| from the origin and that points into |
| 709 |
the direction of the axis. |
| 710 |
% |
| 711 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 712 |
\begin{tikzpicture} |
| 713 |
\draw [help lines] (0,0) grid (3,2); |
| 714 |
|
| 715 |
\datavisualization |
| 716 |
[new Cartesian axis=x axis, x axis={attribute=x}, |
| 717 |
new Cartesian axis=y axis, y axis={attribute=y}, |
| 718 |
x axis={unit vector=(0:1pt)}, |
| 719 |
y axis={unit vector=(60:1pt)}, |
| 720 |
visualize as scatter] |
| 721 |
data { |
| 722 |
x, y |
| 723 |
0, 0 |
| 724 |
1, 0 |
| 725 |
2, 0 |
| 726 |
1, 1 |
| 727 |
2, 1 |
| 728 |
1, 1.5 |
| 729 |
2, 1.5 |
| 730 |
}; |
| 731 |
\end{tikzpicture} |
| 732 |
\end{codeexample} |
| 733 |
\end{key} |
| 734 |
\end{key} |
| 735 |
|
| 736 |
|
| 737 |
\subsection{Axis Systems} |
| 738 |
\label{section-dv-axis-systems} |
| 739 |
|
| 740 |
An \emph{axis system} is, as the name suggests, a whole family of axes that act |
| 741 |
in concert. For example, in the ``standard'' axis system there is a horizontal |
| 742 |
axis called the $x$-axis that monitors the |x| attribute (by default, you can |
| 743 |
change this easily) and a vertical axis called the $y$-axis. Furthermore, a |
| 744 |
certain number of ticks are added and labels are placed at sensible positions. |
| 745 |
|
| 746 |
|
| 747 |
\subsubsection{Usage} |
| 748 |
|
| 749 |
Using an axis system is usually pretty easy: You just specify a key like |
| 750 |
|scientific axes| and the necessary axes get initialized with sensible default |
| 751 |
values. You can then start to modify these default values, if necessary. |
| 752 |
|
| 753 |
First, you can (and should) set the attributes to which the difference axes |
| 754 |
refer. For instance, if the |time| attribute is plotted along the $x$-axis, you |
| 755 |
would write |
| 756 |
% |
| 757 |
\begin{codeexample}[code only] |
| 758 |
x axis = {attribute = time} |
| 759 |
\end{codeexample} |
| 760 |
|
| 761 |
Second, you may wish to modify the lengths of the axes. For this, you can use |
| 762 |
keys like |length| or further keys as described in the references later on. |
| 763 |
|
| 764 |
Third, you may often wish to modify how many ticks and grid lines are shown. By |
| 765 |
default, no grid lines are shown, but you can say the following in order to |
| 766 |
cause grid lines to be shown: |
| 767 |
% |
| 768 |
\begin{codeexample}[code only] |
| 769 |
all axes={grid} |
| 770 |
\end{codeexample} |
| 771 |
% |
| 772 |
Naturally, instead of |all axes| you can also specify a single axis, causing |
| 773 |
only grid lines to be shown for this axis. In order to change the number of |
| 774 |
ticks that are shown, you can say |
| 775 |
% |
| 776 |
\begin{codeexample}[code only] |
| 777 |
all axes={ticks=few} |
| 778 |
\end{codeexample} |
| 779 |
% |
| 780 |
or also |many| instead of |few| or even |none|. Far more fine-grained control |
| 781 |
over the tick placement and rendering is possible, see |
| 782 |
Section~\ref{section-dv-ticks-and-grids} for details. |
| 783 |
|
| 784 |
Fourth, consider adding units (like ``cm'' for centimeters or |
| 785 |
``$\mathrm{m}/\mathrm{s}^2$'' for acceleration) to your ticks: |
| 786 |
% |
| 787 |
\begin{codeexample}[code only] |
| 788 |
x axis={ticks={tick unit=cm}}, y axis={ticks={tick unit=m/s^2}} |
| 789 |
\end{codeexample} |
| 790 |
|
| 791 |
Finally, consider adding labels to your axes. For this, use the label option: |
| 792 |
% |
| 793 |
\begin{codeexample}[code only] |
| 794 |
x axes={time $t$ (ms)}, y axis={distance $d$ (mm)} |
| 795 |
\end{codeexample} |
| 796 |
|
| 797 |
Here is an example that employs most of the above features: |
| 798 |
% |
| 799 |
\begin{codeexample}[width=8.5cm,preamble={\usetikzlibrary{datavisualization}}] |
| 800 |
\tikz \datavisualization [ |
| 801 |
scientific axes=clean, |
| 802 |
x axis={attribute=time, ticks={tick unit=ms}, |
| 803 |
label={elapsed time}}, |
| 804 |
y axis={attribute=v, ticks={tick unit=m/s}, |
| 805 |
label={speed of disc}}, |
| 806 |
all axes=grid, |
| 807 |
visualize as line] |
| 808 |
data { |
| 809 |
time, v |
| 810 |
0, 0 |
| 811 |
1, 0.001 |
| 812 |
2, 0.002 |
| 813 |
3, 0.004 |
| 814 |
4, 0.0035 |
| 815 |
5, 0.0085 |
| 816 |
6, 0.0135 |
| 817 |
}; |
| 818 |
\end{codeexample} |
| 819 |
|
| 820 |
|
| 821 |
\subsubsection{Reference: Scientific Axis Systems} |
| 822 |
|
| 823 |
\begin{key}{/tikz/data visualization/scientific axes=\opt{\meta{options}}} |
| 824 |
This key installs a two-dimensional coordinate system based on the |
| 825 |
attributes |/data point/x| and |/data point/y|. |
| 826 |
% |
| 827 |
\begin{codeexample}[ |
| 828 |
width=7cm, |
| 829 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 830 |
] |
| 831 |
\begin{tikzpicture} |
| 832 |
\datavisualization [scientific axes, |
| 833 |
visualize as smooth line] |
| 834 |
data [format=function] { |
| 835 |
var x : interval [0:100]; |
| 836 |
func y = sqrt(\value x); |
| 837 |
}; |
| 838 |
\end{tikzpicture} |
| 839 |
\end{codeexample} |
| 840 |
|
| 841 |
This axis system is usually a good choice to depict ``arbitrary two |
| 842 |
dimensional data''. Because the axes are automatically scaled, you do not |
| 843 |
need to worry about how large or small the values will be. The name |
| 844 |
|scientific axes| is intended to indicate that this axis system is often |
| 845 |
used in scientific publications. |
| 846 |
|
| 847 |
You can use the \meta{options} to fine tune the axis system. The |
| 848 |
\meta{options} will be executed with the following path prefix: |
| 849 |
% |
| 850 |
\begin{codeexample}[code only] |
| 851 |
/tikz/data visualization/scientific axes |
| 852 |
\end{codeexample} |
| 853 |
% |
| 854 |
All keys with this prefix can thus be passed as \meta{options}. |
| 855 |
|
| 856 |
This axis system will always distort the relative magnitudes of the units |
| 857 |
on the two axis. If you wish the units on both axes to be equal, consider |
| 858 |
directly specifying the unit length ``by hand'': |
| 859 |
% |
| 860 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 861 |
\begin{tikzpicture} |
| 862 |
\datavisualization [visualize as smooth line, |
| 863 |
scientific axes, |
| 864 |
all axes={unit length=1cm per 10 units, ticks={few}}] |
| 865 |
data [format=function] { |
| 866 |
var x : interval [0:100]; |
| 867 |
func y = sqrt(\value x); |
| 868 |
}; |
| 869 |
\end{tikzpicture} |
| 870 |
\end{codeexample} |
| 871 |
|
| 872 |
The |scientific axes| have the following properties: |
| 873 |
% |
| 874 |
\begin{itemize} |
| 875 |
\item The |x|-values are surveyed and the $x$-axis is then scaled and |
| 876 |
shifted so that it has the length specified by the following key. |
| 877 |
% |
| 878 |
\begin{key}{/tikz/data visualization/scientific axes/width=\meta{dimension} (initially 5cm)} |
| 879 |
\end{key} |
| 880 |
% |
| 881 |
The minimum value is at the left end of the axis and at the canvas |
| 882 |
origin. The maximum value is at the right end of the axis. \item |
| 883 |
The |y|-values are surveyed and the $y$-axis is then scaled so that |
| 884 |
is has the length specified by the following key. |
| 885 |
% |
| 886 |
\begin{key}{/tikz/data visualization/scientific axes/height=\meta{dimension}} |
| 887 |
By default, the |height| is the golden ratio times the |width|. |
| 888 |
\end{key} |
| 889 |
% |
| 890 |
The minimum value is at the bottom of the axis and at the canvas |
| 891 |
origin. The maximum value is at the top of the axis. |
| 892 |
\item Lines (forming a frame) are depicted at the minimum and maximum |
| 893 |
values of the axes in 50\% black. |
| 894 |
\end{itemize} |
| 895 |
|
| 896 |
The following keys are executed by default as options: |outer ticks| and |
| 897 |
|standard labels|. |
| 898 |
|
| 899 |
You can use the following style to overrule the defaults: |
| 900 |
|
| 901 |
\begin{stylekey}{/tikz/data visualization/every scientific axes} |
| 902 |
\end{stylekey} |
| 903 |
\end{key} |
| 904 |
|
| 905 |
The keys described in the following can be used to fine-tune the way the |
| 906 |
scientific axis system is rendered. |
| 907 |
|
| 908 |
\begin{key}{/tikz/data visualization/scientific axes/outer ticks} |
| 909 |
This causes the ticks to be drawn `` on the outside'' of the frame so that |
| 910 |
they interfere as little as possible with the data. It is the default. |
| 911 |
% |
| 912 |
\begin{codeexample}[ |
| 913 |
width=7cm, |
| 914 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 915 |
] |
| 916 |
\begin{tikzpicture} |
| 917 |
\datavisualization [scientific axes=outer ticks, |
| 918 |
visualize as smooth line] |
| 919 |
data [format=function] { |
| 920 |
var x : interval [-12:12]; |
| 921 |
func y = \value x*\value x*\value x; |
| 922 |
}; |
| 923 |
\end{tikzpicture} |
| 924 |
\end{codeexample} |
| 925 |
% |
| 926 |
\end{key} |
| 927 |
|
| 928 |
\begin{key}{/tikz/data visualization/scientific axes/inner ticks} |
| 929 |
This axis system works like |scientific axes|, only the ticks are on the |
| 930 |
``inside'' of the frame. |
| 931 |
% |
| 932 |
\begin{codeexample}[ |
| 933 |
width=7cm, |
| 934 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 935 |
] |
| 936 |
\begin{tikzpicture} |
| 937 |
\datavisualization [scientific axes=inner ticks, |
| 938 |
visualize as smooth line] |
| 939 |
data [format=function] { |
| 940 |
var x : interval [-12:12]; |
| 941 |
func y = \value x*\value x*\value x; |
| 942 |
}; |
| 943 |
\end{tikzpicture} |
| 944 |
\end{codeexample} |
| 945 |
|
| 946 |
This axis system is also common in publications, but the ticks tend to |
| 947 |
interfere with marks if they are near to the border as can be seen in the |
| 948 |
following example: |
| 949 |
% |
| 950 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 951 |
\begin{tikzpicture} |
| 952 |
\datavisualization [scientific axes={inner ticks, width=3.2cm}, |
| 953 |
style sheet=cross marks, |
| 954 |
visualize as scatter/.list={a,b}] |
| 955 |
data [set=a] { |
| 956 |
x, y |
| 957 |
0, 0 |
| 958 |
1, 1 |
| 959 |
0.5, 0.5 |
| 960 |
2, 1 |
| 961 |
} |
| 962 |
data [set=b] { |
| 963 |
x, y |
| 964 |
0.05, 0 |
| 965 |
1.5, 1 |
| 966 |
0.5, 0.75 |
| 967 |
2, 0.5 |
| 968 |
}; |
| 969 |
\end{tikzpicture} |
| 970 |
\end{codeexample} |
| 971 |
% |
| 972 |
\end{key} |
| 973 |
|
| 974 |
\begin{key}{/tikz/data visualization/scientific axes/clean} |
| 975 |
The axes and the ticks are completely removed from the actual data, making |
| 976 |
this axis system especially useful for scatter plots, but also for most |
| 977 |
other scientific plots. |
| 978 |
% |
| 979 |
\begin{codeexample}[ |
| 980 |
width=7.5cm, |
| 981 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 982 |
] |
| 983 |
\tikz \datavisualization [ |
| 984 |
scientific axes=clean, |
| 985 |
visualize as smooth line] |
| 986 |
data [format=function] { |
| 987 |
var x : interval [-12:12]; |
| 988 |
func y = \value x*\value x*\value x; |
| 989 |
}; |
| 990 |
\end{codeexample} |
| 991 |
|
| 992 |
The distance of the axes from the actual plot is given by the padding of |
| 993 |
the axes. |
| 994 |
\end{key} |
| 995 |
|
| 996 |
For all scientific axis systems, different label placement strategies can be |
| 997 |
specified. They are discussed in the following. |
| 998 |
|
| 999 |
\begin{key}{/tikz/data visualization/scientific axes/standard labels} |
| 1000 |
As the name suggests, this is the standard placement strategy. The label of |
| 1001 |
the $x$-axis is placed below the center of the $x$-axis, the label of the |
| 1002 |
$y$-axis is rotated by $90^\circ$ and placed left of the center of the |
| 1003 |
$y$-axis. |
| 1004 |
% |
| 1005 |
\begin{codeexample}[ |
| 1006 |
width=8cm, |
| 1007 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 1008 |
] |
| 1009 |
\tikz \datavisualization |
| 1010 |
[scientific axes={clean, standard labels}, |
| 1011 |
visualize as smooth line, |
| 1012 |
x axis={label=degree $d$, |
| 1013 |
ticks={tick unit={}^\circ}}, |
| 1014 |
y axis={label=$\sin d$}] |
| 1015 |
data [format=function] { |
| 1016 |
var x : interval [-10:10] samples 10; |
| 1017 |
func y = sin(\value x); |
| 1018 |
}; |
| 1019 |
\end{codeexample} |
| 1020 |
% |
| 1021 |
\end{key} |
| 1022 |
|
| 1023 |
\begin{key}{/tikz/data visualization/scientific axes/upright labels} |
| 1024 |
Works like |scientific axes standard labels|, only the label of the |
| 1025 |
$y$-axis is not rotated. |
| 1026 |
% |
| 1027 |
\begin{codeexample}[ |
| 1028 |
width=8cm, |
| 1029 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 1030 |
] |
| 1031 |
\tikz \datavisualization [ |
| 1032 |
scientific axes={clean, upright labels}, |
| 1033 |
visualize as smooth line, |
| 1034 |
x axis={label=degree $d$, |
| 1035 |
ticks={tick unit={}^\circ}}, |
| 1036 |
y axis={label=$\cos d$, include value=1, |
| 1037 |
ticks={style={ |
| 1038 |
/pgf/number format/precision=4, |
| 1039 |
/pgf/number format/fixed zerofill}}}] |
| 1040 |
data [format=function] { |
| 1041 |
var x : interval [-10:10] samples 10; |
| 1042 |
func y = cos(\value x); |
| 1043 |
}; |
| 1044 |
\end{codeexample} |
| 1045 |
% |
| 1046 |
\end{key} |
| 1047 |
|
| 1048 |
\begin{key}{/tikz/data visualization/scientific axes/end labels} |
| 1049 |
Places the labels at the end of the $x$- and the $y$-axis, similar to the |
| 1050 |
axis labels of a school book axis system. |
| 1051 |
% |
| 1052 |
\begin{codeexample}[ |
| 1053 |
width=8cm, |
| 1054 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 1055 |
] |
| 1056 |
\tikz \datavisualization [ |
| 1057 |
scientific axes={clean, end labels}, |
| 1058 |
visualize as smooth line, |
| 1059 |
x axis={label=degree $d$, |
| 1060 |
ticks={tick unit={}^\circ}}, |
| 1061 |
y axis={label=$\tan d$}] |
| 1062 |
data [format=function] { |
| 1063 |
var x : interval [-80:80]; |
| 1064 |
func y = tan(\value x); |
| 1065 |
}; |
| 1066 |
\end{codeexample} |
| 1067 |
% |
| 1068 |
\end{key} |
| 1069 |
|
| 1070 |
|
| 1071 |
\subsubsection{Reference: School Book Axis Systems} |
| 1072 |
|
| 1073 |
\begin{key}{/tikz/data visualization/school book axes=\meta{options}} |
| 1074 |
This axis system is intended to ``look like'' the coordinate systems often |
| 1075 |
used in school books: The axes are drawn in such a way that they intersect |
| 1076 |
to origin. Furthermore, no automatic scaling is done to ensure that the |
| 1077 |
lengths of units are the same in all directions. |
| 1078 |
|
| 1079 |
This axis system must be used with care -- it is nearly always necessary to |
| 1080 |
specify the desired unit length by hand using the option |unit length|. If |
| 1081 |
the magnitudes of the units on the two axes differ, different unit lengths |
| 1082 |
typically need to be specified for the different axes. |
| 1083 |
|
| 1084 |
Finally, if the data is ``far removed'' from the origin, this axis system |
| 1085 |
will also ``look bad''. |
| 1086 |
% |
| 1087 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1088 |
\begin{tikzpicture} |
| 1089 |
\datavisualization [school book axes, visualize as smooth line] |
| 1090 |
data [format=function] { |
| 1091 |
var x : interval [-1.3:1.3]; |
| 1092 |
func y = \value x*\value x*\value x; |
| 1093 |
}; |
| 1094 |
\end{tikzpicture} |
| 1095 |
\end{codeexample} |
| 1096 |
|
| 1097 |
The stepping of the ticks is one unit by default. Using keys like |
| 1098 |
|ticks=some| may help to give better steppings. |
| 1099 |
|
| 1100 |
The \meta{options} are executed with the key itself as path prefix. Thus, |
| 1101 |
the following subkeys are permissible options: |
| 1102 |
% |
| 1103 |
\begin{key}{/tikz/data visualization/school book axes/unit=\meta{value}} |
| 1104 |
Sets the scaling so that 1\,cm corresponds to \meta{value} units. At |
| 1105 |
the same time, the stepping of the ticks will also be set to |
| 1106 |
\meta{value}. |
| 1107 |
% |
| 1108 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1109 |
\begin{tikzpicture} |
| 1110 |
\datavisualization [school book axes={unit=10}, |
| 1111 |
visualize as smooth line, |
| 1112 |
clean ticks, |
| 1113 |
x axis={label=$x$}, |
| 1114 |
y axis={label=$f(x)$}] |
| 1115 |
data [format=function] { |
| 1116 |
var x : interval [-20:20]; |
| 1117 |
func y = \value x*\value x/10; |
| 1118 |
}; |
| 1119 |
\end{tikzpicture} |
| 1120 |
\end{codeexample} |
| 1121 |
\end{key} |
| 1122 |
|
| 1123 |
\begin{key}{/tikz/data visualization/school book axes/standard labels} |
| 1124 |
This key makes the label of the $x$-axis appear at the right end of |
| 1125 |
this axis and it makes the label of the $y$-axis appear at the top of |
| 1126 |
the $y$-axis. |
| 1127 |
|
| 1128 |
Currently, this is the only supported placement strategy for the school |
| 1129 |
book axis system. |
| 1130 |
% |
| 1131 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1132 |
\begin{tikzpicture} |
| 1133 |
\datavisualization [school book axes={standard labels}, |
| 1134 |
visualize as smooth line, |
| 1135 |
clean ticks, |
| 1136 |
x axis={label=$x$}, |
| 1137 |
y axis={label=$f(x)$}] |
| 1138 |
data [format=function] { |
| 1139 |
var x : interval [-1:1]; |
| 1140 |
func y = \value x*\value x + 1; |
| 1141 |
}; |
| 1142 |
\end{tikzpicture} |
| 1143 |
\end{codeexample} |
| 1144 |
\end{key} |
| 1145 |
\end{key} |
| 1146 |
|
| 1147 |
|
| 1148 |
\subsubsection{Advanced Reference: Underlying Cartesian Axis Systems} |
| 1149 |
|
| 1150 |
The axis systems described in the following are typically not used directly by |
| 1151 |
the user. The systems setup \emph{directions} for several axes in some sensible |
| 1152 |
way, but they do not actually draw anything on these axes. For instance, the |
| 1153 |
|xy Cartesian| creates two axes called |x axis| and |y axis| and makes the |
| 1154 |
$x$-axis point right and the $y$-axis point up. In contrast, an axis system |
| 1155 |
like |scientific axes| uses the axis system |xy Cartesian| internally and then |
| 1156 |
proceeds to setup a lot of keys so that the axis lines are drawn, ticks and |
| 1157 |
grid lines are drawn, and labels are placed at the correct positions. |
| 1158 |
|
| 1159 |
\begin{key}{/tikz/data visualization/xy Cartesian} |
| 1160 |
This axis system creates two axes called |x axis| and |y axis| that point |
| 1161 |
right and up, respectively. By default, one unit is mapped to one cm. |
| 1162 |
% |
| 1163 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1164 |
\begin{tikzpicture} |
| 1165 |
\datavisualization [xy Cartesian, visualize as smooth line] |
| 1166 |
data [format=function] { |
| 1167 |
var x : interval [-1.25:1.25]; |
| 1168 |
func y = \value x*\value x*\value x; |
| 1169 |
}; |
| 1170 |
\end{tikzpicture} |
| 1171 |
\end{codeexample} |
| 1172 |
|
| 1173 |
\begin{key}{/tikz/data visualization/xy axes=\meta{options}} |
| 1174 |
This key applies the \meta{options} both to the |x axis| and the |
| 1175 |
|y axis|. |
| 1176 |
\end{key} |
| 1177 |
\end{key} |
| 1178 |
|
| 1179 |
\begin{key}{/tikz/data visualization/xyz Cartesian cabinet} |
| 1180 |
This axis system works like |xy Cartesian|, only it \emph{additionally} |
| 1181 |
creates an axis called |z axis| that points left and down. For this axis, |
| 1182 |
one unit corresponds to $\frac{1}{2}\sin 45^\circ\mathrm{cm}$. This is also |
| 1183 |
known as a cabinet projection. |
| 1184 |
|
| 1185 |
\begin{key}{/tikz/data visualization/xyz axes=\meta{options}} |
| 1186 |
This key applies the \meta{options} both to the |x axis| and the |
| 1187 |
|y axis|. |
| 1188 |
\end{key} |
| 1189 |
\end{key} |
| 1190 |
|
| 1191 |
\begin{key}{/tikz/data visualization/uv Cartesian} |
| 1192 |
This axis system works like |xy Cartesian|, but it introduces two axes |
| 1193 |
called |u axis| and |v axis| rather than the |x axis| and the |y axis|. The |
| 1194 |
idea is that in addition to a ``major'' $xy$-coordinate system this is also |
| 1195 |
a ``smaller'' or ``minor'' coordinate system in use for depicting, say, |
| 1196 |
small vectors with respect to this second coordinate system. |
| 1197 |
|
| 1198 |
\begin{key}{/tikz/data visualization/uv axes=\meta{options}} |
| 1199 |
Applies the \meta{options} to both the |u axis| and the |y axis|. |
| 1200 |
\end{key} |
| 1201 |
\end{key} |
| 1202 |
|
| 1203 |
\begin{key}{/tikz/data visualization/uvw Cartesian cabinet} |
| 1204 |
Like |xyz Cartesian cabinet|, but for the $uvw$-system. |
| 1205 |
|
| 1206 |
\begin{key}{/tikz/data visualization/uvw axes=\meta{options}} |
| 1207 |
Like |xyz axes|. |
| 1208 |
\end{key} |
| 1209 |
\end{key} |
| 1210 |
|
| 1211 |
|
| 1212 |
\subsection{Ticks and Grids} |
| 1213 |
\label{section-dv-ticks-and-grids} |
| 1214 |
|
| 1215 |
\subsubsection{Concepts} |
| 1216 |
|
| 1217 |
A \emph{tick} is a small visual indication on an axis of the value of the |
| 1218 |
axis's attribute at the position where the tick is shown. A tick may be |
| 1219 |
accompanied additionally by a textual representation, but it need not. A |
| 1220 |
\emph{grid line} is similar to a tick, but it is not an indication on the axis, |
| 1221 |
but rather a whole line that indicates all positions where the attribute has a |
| 1222 |
certain value. Unlike ticks, grid lines (currently) are not accompanied by a |
| 1223 |
textual representation. |
| 1224 |
|
| 1225 |
Just as for axes, the data visualization system decouples the specification of |
| 1226 |
which ticks are present \emph{in principle} from where they are visualized. In |
| 1227 |
the following, I describe how you specify which ticks and grid lines you would |
| 1228 |
like to be drawn and how they should look like (their styling). The axis system |
| 1229 |
of your choice will then visualize the ticks at a sensible position for the |
| 1230 |
chosen system. For details on how to change where whole axis is shown along |
| 1231 |
with its ticks, see Section~\ref{section-dv-visualize-ticks}. |
| 1232 |
|
| 1233 |
Specifying which ticks you are interested in is done as follows: First, you use |
| 1234 |
|ticks| key (or, for specifying which grid lines should be present, the |grid| |
| 1235 |
key). This key takes several possible options, described in detail in the |
| 1236 |
following, which have different effects: |
| 1237 |
% |
| 1238 |
\begin{enumerate} |
| 1239 |
\item Keys like |step=10| or |minor steps between steps| cause a |
| 1240 |
``semi-automatic'' computation of possible steps. Here, you explicitly |
| 1241 |
specify the stepping of steps, but the first stepping and their number |
| 1242 |
are computed automatically according to the range of possible values |
| 1243 |
for the attribute. |
| 1244 |
\item Keys like |few|, |some|, or |many| can be passed to |ticks| in order |
| 1245 |
to have \tikzname\ compute good tick positions automatically. This is |
| 1246 |
usually what you want to happen, which is why most axis system will |
| 1247 |
implicitly say |ticks={some}|. |
| 1248 |
\item Keys like |at| or |also at| provide ``absolute control'' over which |
| 1249 |
ticks or grid lines are shown. For these keys, you can not only specify |
| 1250 |
at what value a tick should be shown, but also its styling and also |
| 1251 |
whether it is a major, minor, or subminor tick or grid line. |
| 1252 |
\end{enumerate} |
| 1253 |
|
| 1254 |
In the following, the main keys |ticks| and |grids| are documented first. Then |
| 1255 |
the different kinds of ways of specifying where ticks or grid lines should be |
| 1256 |
shown are explained. |
| 1257 |
|
| 1258 |
|
| 1259 |
\subsubsection{The Main Options: Tick and Grid} |
| 1260 |
|
| 1261 |
\begin{key}{/tikz/data visualization/axis options/ticks=\meta{options} (default some)} |
| 1262 |
This key can be passed to an axis in order to configure which ticks are |
| 1263 |
present for the axis. The possible \meta{options} include, for instance, |
| 1264 |
keys like |step|, which is used to specify a stepping for the ticks, but |
| 1265 |
also keys like |major| or |minor| for specifying the positions of major and |
| 1266 |
minor ticks in detail. The list of possible options is described in the |
| 1267 |
rest of this section. |
| 1268 |
|
| 1269 |
Note that the |ticks| option will only configure which ticks should be |
| 1270 |
shown in principle. The actual rendering is done only when the |
| 1271 |
|visualize ticks| key is used, documented in |
| 1272 |
Section~\ref{section-dv-visualize-ticks}, which is typically done only |
| 1273 |
internally by an axis system. |
| 1274 |
|
| 1275 |
The \meta{options} will be executed with the path prefix |
| 1276 |
|/tikz/data visualization/|. When the |ticks| key is used multiple times |
| 1277 |
for an axis, the \meta{options} accumulate. |
| 1278 |
% |
| 1279 |
\begin{codeexample}[width=6cm,preamble={\usetikzlibrary{datavisualization}}] |
| 1280 |
\tikz \datavisualization [ |
| 1281 |
scientific axes, visualize as line, |
| 1282 |
x axis={ticks={step=24, minor steps between steps=3}, |
| 1283 |
label=hours}] |
| 1284 |
data { |
| 1285 |
x, y |
| 1286 |
0, 0 |
| 1287 |
10, 0 |
| 1288 |
20, 0.5 |
| 1289 |
30, 0.75 |
| 1290 |
40, 0.7 |
| 1291 |
50, 0.6 |
| 1292 |
60, 0.5 |
| 1293 |
70, 0.45 |
| 1294 |
80, 0.47 |
| 1295 |
}; |
| 1296 |
\end{codeexample} |
| 1297 |
% |
| 1298 |
\end{key} |
| 1299 |
|
| 1300 |
\begin{key}{/tikz/data visualization/axis options/grid=\meta{options} (default at default ticks)} |
| 1301 |
This key is similar to |ticks|, only it is used to configure where grid |
| 1302 |
lines should be shown rather than ticks. In particular, the options that |
| 1303 |
can be passed to the |ticks| key can also be passed to the |grid| key. Just |
| 1304 |
like |ticks|, the \meta{options} only specify which grid lines should be |
| 1305 |
drawn in principle; it is the job of the |visualize grid| key to actually |
| 1306 |
cause any grid lines to be shown. |
| 1307 |
|
| 1308 |
If you do not specify any \meta{options}, the default text |
| 1309 |
|at default ticks| is used. This option causes grid lines to be drawn at |
| 1310 |
all positions where ticks are shown by default. Since this usually exactly |
| 1311 |
what you would like to happen, most of the time you just need to |
| 1312 |
|all axes=grid| to cause a grid to be shown. |
| 1313 |
\end{key} |
| 1314 |
|
| 1315 |
\begin{key}{/tikz/data visualization/axis options/ticks and grid=\meta{options}} |
| 1316 |
This key passes the \meta{options} to both the |ticks| key and also to the |
| 1317 |
|grid| key. This is useful when you want to specify some special points |
| 1318 |
explicitly where you wish a tick to be shown and also a grid line. |
| 1319 |
% |
| 1320 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1321 |
\tikz \datavisualization |
| 1322 |
[scientific axes, |
| 1323 |
visualize as smooth line, |
| 1324 |
all axes= {grid, unit length=1.25cm}, |
| 1325 |
y axis={ ticks=few }, |
| 1326 |
x axis={ ticks=many, ticks and grid={ major also at={(pi/2) as $\frac{\pi}{2}$}}}] |
| 1327 |
data [format=function] { |
| 1328 |
var x : interval [-pi/2:3*pi] samples 50; |
| 1329 |
func y = sin(\value x r); |
| 1330 |
}; |
| 1331 |
\end{codeexample} |
| 1332 |
% |
| 1333 |
\end{key} |
| 1334 |
|
| 1335 |
|
| 1336 |
\subsubsection{Semi-Automatic Computation of Tick and Grid Line Positions} |
| 1337 |
\label{section-dv-concept-tick-placement-strategies} |
| 1338 |
|
| 1339 |
Consider the following problem: The data visualization engine determines that |
| 1340 |
in a plot the $x$-values vary between $17.4$ and $34.5$. In this case, we |
| 1341 |
certainly do not want, say, ten ticks at exactly ten evenly spaced positions |
| 1342 |
starting with $17.4$ and ending with $34.5$, because this would yield ticks at |
| 1343 |
positions like $32.6$. Ticks should be placed at ``nice'' positions like $20$, |
| 1344 |
$25$, and $30$. |
| 1345 |
|
| 1346 |
Determining which positions are ``nice'' is somewhat difficult. In the above |
| 1347 |
example, the positions $20$, $25$, and $30$ are certainly nice, but only three |
| 1348 |
ticks may be a bit few of them. Better might be the tick positions $17.5$, |
| 1349 |
$20$, $22.5$, through to $32.5$. However, users might prefer even numbers over |
| 1350 |
fractions like $2.5$ as the stepping. |
| 1351 |
|
| 1352 |
A \emph{tick placement strategy} is a method of automatically deciding which |
| 1353 |
positions are \emph{good} for placing ticks. The data visualization engine |
| 1354 |
comes with a number of predefined strategies, but you can also define new ones |
| 1355 |
yourself. When the data visualization is requested to automatically determine |
| 1356 |
``good'' positions for the placement of ticks on an axis, it uses one of |
| 1357 |
several possible \emph{basic strategies}. These strategies differ dramatically |
| 1358 |
in which tick positions they will choose: For a range of values between $5$ and |
| 1359 |
$1000$, a |linear steps| strategy might place ticks at positions $100$, $200$, |
| 1360 |
through to $1000$, while an |exponential steps| strategy would prefer the tick |
| 1361 |
positions $10$, $100$ and $1000$. The exact number and values of the tick |
| 1362 |
positions chosen by either strategy can be fine-tuned using additional options |
| 1363 |
like |step| or |about|. |
| 1364 |
|
| 1365 |
Here is an example of the different stepping chosen when one varies the tick |
| 1366 |
placement strategy: |
| 1367 |
% |
| 1368 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1369 |
\begin{tikzpicture} |
| 1370 |
\datavisualization [scientific axes, visualize as smooth line] |
| 1371 |
data [format=function] { |
| 1372 |
var x : interval [1:11]; |
| 1373 |
func y = \value x*\value x; |
| 1374 |
}; |
| 1375 |
\end{tikzpicture} |
| 1376 |
\qquad |
| 1377 |
\begin{tikzpicture} |
| 1378 |
\datavisualization [scientific axes, visualize as smooth line, |
| 1379 |
y axis={exponential steps}, |
| 1380 |
x axis={ticks={quarter about strategy}}, |
| 1381 |
] |
| 1382 |
data [format=function] { |
| 1383 |
var x : interval [1:11]; |
| 1384 |
func y = \value x*\value x; |
| 1385 |
}; |
| 1386 |
\end{tikzpicture} |
| 1387 |
\end{codeexample} |
| 1388 |
|
| 1389 |
Two strategies are always available: |linear steps|, which yields |
| 1390 |
(semi)automatic ticks are evenly spaced positions, and |exponential steps|, |
| 1391 |
which yields (semi)automatic steps at positions at exponentially increasing |
| 1392 |
positions -- which is exactly what is needed for logarithmic plots. These |
| 1393 |
strategies are details in Section~\ref{section-dv-strategies}. |
| 1394 |
|
| 1395 |
The following options are used to configure tick placement strategies like |
| 1396 |
|linear steps|. Unlike the basic choice of a placement strategy, which is an |
| 1397 |
axis option, the following should be passed to the option |ticks| or |grid| |
| 1398 |
only. So, you would write things like |x axis={ticks={step=2}}|, but |
| 1399 |
|x axis={linear steps}|. |
| 1400 |
|
| 1401 |
\begin{key}{/tikz/data visualization/step=\meta{value} (initially 1)} |
| 1402 |
The value of this key is used to determine the spacing of the major ticks. |
| 1403 |
The key is used by the |linear steps| and |exponential steps| strategies, |
| 1404 |
see the explanations in Section~\ref{section-dv-strategies} for details. |
| 1405 |
Basically, all ticks are placed at all multiples of \meta{value} that lie |
| 1406 |
in the attribute range interval. |
| 1407 |
% |
| 1408 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1409 |
\tikz \datavisualization [ |
| 1410 |
school book axes, visualize as smooth line, |
| 1411 |
y axis={ticks={step=1.25}}, |
| 1412 |
] |
| 1413 |
data [format=function] { |
| 1414 |
var x : interval [0:3]; |
| 1415 |
func y = \value x*\value x/2; |
| 1416 |
}; |
| 1417 |
\end{codeexample} |
| 1418 |
% |
| 1419 |
\end{key} |
| 1420 |
|
| 1421 |
\begin{key}{/tikz/data visualization/minor steps between steps=\meta{number} (default 9)} |
| 1422 |
Specifies that between any two major steps (whose positions are specified |
| 1423 |
by the |step| key), there should be \meta{number} many minor steps. Note |
| 1424 |
that the default of |9| is exactly the right number so that each interval |
| 1425 |
between two minor steps is exactly a tenth of the size of a major step. See |
| 1426 |
also Section~\ref{section-dv-strategies} for further details. |
| 1427 |
% |
| 1428 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1429 |
\begin{tikzpicture} |
| 1430 |
\datavisualization [school book axes, visualize as smooth line, |
| 1431 |
x axis={ticks={minor steps between steps=3}}, |
| 1432 |
y axis={ticks={minor steps between steps}}, |
| 1433 |
] |
| 1434 |
data [format=function] { |
| 1435 |
var x : interval [-1.5:1.5]; |
| 1436 |
func y = \value x*\value x; |
| 1437 |
}; |
| 1438 |
\end{tikzpicture} |
| 1439 |
\end{codeexample} |
| 1440 |
% |
| 1441 |
\end{key} |
| 1442 |
|
| 1443 |
\begin{key}{/tikz/data visualization/phase=\meta{value} (initially 0)} |
| 1444 |
See Section~\ref{section-dv-strategies} for details on how the phase of |
| 1445 |
steps influences the tick placement. |
| 1446 |
\end{key} |
| 1447 |
|
| 1448 |
|
| 1449 |
\subsubsection{Automatic Computation of Tick and Grid Line Positions} |
| 1450 |
|
| 1451 |
The |step| option gives you ``total control'' over the stepping of ticks on an |
| 1452 |
axis, but you often do not know the correct stepping in advance. In this case, |
| 1453 |
you may prefer to have a good value for |step| being computed for you |
| 1454 |
automatically. |
| 1455 |
|
| 1456 |
Like the |step| key, these options are passed to the |ticks| option. So, for |
| 1457 |
instance, you would write |x axis={ticks={about=4}}| to request about four |
| 1458 |
ticks to be placed on the $x$-axis. |
| 1459 |
|
| 1460 |
\begin{key}{/tikz/data visualization/about=\meta{number}} |
| 1461 |
This key asks the data visualization to place \emph{about} \meta{number} |
| 1462 |
many ticks on an axis. It is not guaranteed that \emph{exactly} |
| 1463 |
\meta{number} many ticks will be used, rather the actual number will be the |
| 1464 |
closest number of ticks to \meta{number} so that their stepping is still |
| 1465 |
``good''. For instance, when you say |about=10|, it may happen that exactly |
| 1466 |
|10|, but perhaps even |13| ticks are actually selected, provided that |
| 1467 |
these numbers of ticks lead to good stepping values like |5| or |2.5| |
| 1468 |
rather than numbers like |3.4| or |7|. The method that is used to determine |
| 1469 |
which steppings a deemed to be ``good'' depends on the current tick |
| 1470 |
placement strategy. |
| 1471 |
|
| 1472 |
|
| 1473 |
\medskip |
| 1474 |
\textbf{Linear steps.} |
| 1475 |
Let us start with |linear steps|: First, the difference between the maximum |
| 1476 |
value $v_{\max}$ and the minimum value $v_{\min}$ on the axis is computed; |
| 1477 |
let us call it $r$ for ``range''. Then, $r$ is divided by \meta{number}, |
| 1478 |
yielding a target stepping~$s$. If $s$ is a number like $1$ or $5$ or $10$, |
| 1479 |
then this number could be used directly as the new value of |step|. |
| 1480 |
However, $s$ will typically something strange like $0.023\,45$ or |
| 1481 |
$345\,223.76$, so $s$ must be replaced by a better value like $0.02$ in the |
| 1482 |
first case and perhaps $250\,000$ in the second case. |
| 1483 |
|
| 1484 |
In order to determine which number is to be used, $s$ is rewritten in the |
| 1485 |
form $m \cdot 10^k$ with $1 \le m < 10$ and $k \in \mathbb Z$. For |
| 1486 |
instance, $0.023\,45$ would be rewritten as $2.345 \cdot 10^{-2}$ and |
| 1487 |
$345\,223.76$ as $3.452\,2376 \cdot 10^5$. The next step is to replace the |
| 1488 |
still not-so-good number $m$ like $2.345$ or $3.452\,237$ by a ``good'' |
| 1489 |
value $m'$. For this, the current value of the |about strategy| is used: |
| 1490 |
% |
| 1491 |
\begin{key}{/tikz/data visualization/about strategy=\meta{list}} |
| 1492 |
The \meta{list} is a comma-separated sequence of pairs |
| 1493 |
\meta{threshold}/\meta{value} like for instance |1.5/1.0| or |2.3/2.0|. |
| 1494 |
When a good value $m'$ is sought for a given $m$, we iterate over the |
| 1495 |
list and find the first pair \meta{threshold}/\meta{value} where |
| 1496 |
\meta{threshold} exceeds~$m$. Then $m'$ is set to \meta{value}. For |
| 1497 |
instance, if \meta{list} is |1.5/1.0,2.3/2.0,4/2.5,7/5,11/10|, which is |
| 1498 |
the default, then for $m=3.141$ we would get $m'=2.5$ since $4 > |
| 1499 |
3.141$, but $2.3 \le 3.141$. For $m=6.3$ we would get $m'=5$. |
| 1500 |
\end{key} |
| 1501 |
% |
| 1502 |
Once $m'$ has been determined, the stepping is set to $s' = m' \cdot 10^k$. |
| 1503 |
|
| 1504 |
% Define an axis type |
| 1505 |
\tikzdatavisualizationset{ |
| 1506 |
one dimensional axis/.style={ |
| 1507 |
new Cartesian axis=axis, |
| 1508 |
axis={ |
| 1509 |
attribute=main, |
| 1510 |
unit vector={(0pt,1pt)}, |
| 1511 |
visualize axis={style=->}, |
| 1512 |
visualize ticks={major={tick text at low},direction axis=perpendicular}, |
| 1513 |
length=3cm |
| 1514 |
}, |
| 1515 |
new Cartesian axis=perpendicular, |
| 1516 |
perpendicular={ |
| 1517 |
attribute=perp, |
| 1518 |
unit vector={(1pt,0pt)}, |
| 1519 |
include value=0, |
| 1520 |
include value=1 |
| 1521 |
} |
| 1522 |
} |
| 1523 |
} |
| 1524 |
|
| 1525 |
\def\showstrategy#1{ |
| 1526 |
% Show the effect for the different strategies |
| 1527 |
\medskip |
| 1528 |
\begin{tikzpicture} |
| 1529 |
\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} |
| 1530 |
{ |
| 1531 |
\begin{scope}[xshift=\c pt*30] |
| 1532 |
\datavisualization [#1, |
| 1533 |
one dimensional axis, |
| 1534 |
axis={ |
| 1535 |
ticks={about=\about}, |
| 1536 |
include value=0, |
| 1537 |
include value=\max |
| 1538 |
} |
| 1539 |
]; |
| 1540 |
|
| 1541 |
\node at (0,-5mm) [anchor=mid] {\texttt{\about}}; |
| 1542 |
\end{scope} |
| 1543 |
} |
| 1544 |
|
| 1545 |
\node at (30pt,-5mm) [anchor=mid east] {\texttt{about=\ \ }}; |
| 1546 |
\end{tikzpicture} |
| 1547 |
} |
| 1548 |
|
| 1549 |
The net effect of all this is that for the default strategy the only valid |
| 1550 |
stepping are the values $1$, $2$, $2.5$ and $5$ and every value obtainable |
| 1551 |
by multiplying one of these values by a power of ten. The following example |
| 1552 |
shows the effects of, first, setting |about=5| (corresponding to the |some| |
| 1553 |
option) and then having axes where the minimum value is always |0| and |
| 1554 |
where the maximum value ranges from |10| to |100| and, second, setting |
| 1555 |
|about| to the values from |3| (corresponding to the |few| option) and to |
| 1556 |
|10| (corresponding to the |many| option) while having the minimum at |0| |
| 1557 |
and the maximum at |100|: |
| 1558 |
|
| 1559 |
\showstrategy{standard about strategy} |
| 1560 |
|
| 1561 |
\medskip |
| 1562 |
\textbf{Exponential steps.} |
| 1563 |
For |exponential steps| the strategy for determining a good stepping value |
| 1564 |
is similar to |linear steps|, but with the following differences: |
| 1565 |
% |
| 1566 |
\begin{itemize} |
| 1567 |
\item Naturally, since the stepping value refers to the exponent, the |
| 1568 |
whole computation of a good stepping value needs to be done ``in |
| 1569 |
the exponent''. Mathematically spoken, instead of considering the |
| 1570 |
difference $r = v_{\max} - v_{\min}$, we consider the difference $r |
| 1571 |
= \log v_{\max} - \log v_{\min}$. With this difference, we still |
| 1572 |
compute $s = r / \meta{number}$ and let $s = m \cdot 10^k$ with $1 |
| 1573 |
\le m < 10$. |
| 1574 |
\item It makes no longer sense to use values like $2.5$ for $m'$ since |
| 1575 |
this would yield a fractional exponent. Indeed, the only sensible |
| 1576 |
values for $m'$ seem to be $1$, $3$, $6$, and $10$. Because of |
| 1577 |
this, the |about strategy| is ignored and one of these values or a |
| 1578 |
multiple of one of them by a power of ten is used. |
| 1579 |
\end{itemize} |
| 1580 |
|
| 1581 |
The following example shows the chosen steppings for a maximum varying from |
| 1582 |
$10^1$ to $10^5$ and from $10^{10}$ to $10^{50}$ as well as for $10^{100}$ |
| 1583 |
for |about=3|: |
| 1584 |
|
| 1585 |
\medskip |
| 1586 |
\begin{tikzpicture} |
| 1587 |
\foreach \max [count=\c] in {1,...,5,10,20,...,50,100} |
| 1588 |
{ |
| 1589 |
\begin{scope}[xshift=\c pt*40] |
| 1590 |
\datavisualization [ |
| 1591 |
one dimensional axis, |
| 1592 |
axis={ |
| 1593 |
logarithmic, |
| 1594 |
ticks={about=3}, |
| 1595 |
include value=1, |
| 1596 |
include value=1e\max |
| 1597 |
} |
| 1598 |
]; |
| 1599 |
\end{scope} |
| 1600 |
} |
| 1601 |
\end{tikzpicture} |
| 1602 |
|
| 1603 |
|
| 1604 |
\medskip |
| 1605 |
\textbf{Alternative strategies.} |
| 1606 |
|
| 1607 |
In addition to the standard |about strategy|, there are some additional |
| 1608 |
strategies that you might wish to use instead: |
| 1609 |
|
| 1610 |
\begin{key}{/tikz/data visualization/standard about strategy} |
| 1611 |
Permissible values for $m'$ are: $1$, $2$, $2.5$, and~$5$. This |
| 1612 |
strategy is the default strategy. |
| 1613 |
\end{key} |
| 1614 |
|
| 1615 |
\begin{key}{/tikz/data visualization/euro about strategy} |
| 1616 |
Permissible values for $m'$ are: $1$, $2$, and~$5$. These are the same |
| 1617 |
values as for the Euro coins, hence the name. |
| 1618 |
|
| 1619 |
\showstrategy{euro about strategy} |
| 1620 |
\end{key} |
| 1621 |
|
| 1622 |
\begin{key}{/tikz/data visualization/half about strategy} |
| 1623 |
Permissible values for $m'$: $1$ and $5$. Use this strategy if only |
| 1624 |
powers of $10$ or halves thereof seem logical. |
| 1625 |
|
| 1626 |
\showstrategy{half about strategy} |
| 1627 |
\end{key} |
| 1628 |
|
| 1629 |
\begin{key}{/tikz/data visualization/decimal about strategy} |
| 1630 |
The only permissible value for $m'$ is $1$. This is an even more |
| 1631 |
radical version of the previous strategy. |
| 1632 |
|
| 1633 |
\showstrategy{decimal about strategy} |
| 1634 |
\end{key} |
| 1635 |
|
| 1636 |
\begin{key}{/tikz/data visualization/quarter about strategy} |
| 1637 |
Permissible values for $m'$ are: $1$, $2.5$, and $5$. |
| 1638 |
|
| 1639 |
\showstrategy{quarter about strategy} |
| 1640 |
\end{key} |
| 1641 |
|
| 1642 |
\begin{key}{/tikz/data visualization/int about strategy} |
| 1643 |
Permissible values for $m'$ are: $1$, $2$, $3$, $4$, and $5$. |
| 1644 |
|
| 1645 |
\showstrategy{int about strategy} |
| 1646 |
\end{key} |
| 1647 |
\end{key} |
| 1648 |
|
| 1649 |
\begin{key}{/tikz/data visualization/many} |
| 1650 |
This is an abbreviation for |about=10|. |
| 1651 |
\end{key} |
| 1652 |
|
| 1653 |
\begin{key}{/tikz/data visualization/some} |
| 1654 |
This is an abbreviation for |about=5|. |
| 1655 |
\end{key} |
| 1656 |
|
| 1657 |
\begin{key}{/tikz/data visualization/few} |
| 1658 |
This is an abbreviation for |about=3|. |
| 1659 |
\end{key} |
| 1660 |
|
| 1661 |
\begin{key}{/tikz/data visualization/none} |
| 1662 |
Switches off the automatic step computation. Unless you use |step=| |
| 1663 |
explicitly to set a stepping, no ticks will be (automatically) added. |
| 1664 |
\end{key} |
| 1665 |
|
| 1666 |
|
| 1667 |
\subsubsection{Manual Specification of Tick and Grid Line Positions} |
| 1668 |
|
| 1669 |
The automatic computation of ticks and grid lines will usually do a good job, |
| 1670 |
but not always. For instance, you might wish to have ticks exactly at, say, |
| 1671 |
prime numbers or at Fibonacci numbers or you might wish to have an additional |
| 1672 |
tick at $\pi$. In these cases you need more direct control over the |
| 1673 |
specification of tick positions. |
| 1674 |
|
| 1675 |
First, it is important to understand that the data visualization system |
| 1676 |
differentiates between three kinds of ticks and grid lines: major, minor, and |
| 1677 |
subminor. The major ticks are the most prominent ticks where, typically, a |
| 1678 |
textual representation of the tick is shown; and the major grid lines are the |
| 1679 |
thickest. The minor ticks are smaller, more numerous, and lie between major |
| 1680 |
ticks. They are used, for instance, to indicate positions in the middle between |
| 1681 |
major ticks or at all integer positions between major ticks. Finally, subminor |
| 1682 |
ticks are even smaller than minor ticks and they lie between minor ticks. |
| 1683 |
|
| 1684 |
Four keys are used to configure the different kinds: |
| 1685 |
|
| 1686 |
\begin{key}{/tikz/data visualization/major=\meta{options}} |
| 1687 |
The key can be passed as an option to the |ticks| key and also to the |
| 1688 |
|grid| key, which in turn is passed as an option to an axis. The |
| 1689 |
\meta{options} passed to |major| specify at which positions major |
| 1690 |
ticks/grid lines should be shown (using the |at| option and |also at| |
| 1691 |
option) and also any special styling. The different possible options are |
| 1692 |
described later in this section. |
| 1693 |
% |
| 1694 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1695 |
\tikz \datavisualization |
| 1696 |
[ school book axes, visualize as smooth line, |
| 1697 |
x axis={ticks={major={at={1, 1.5, 2}}}}] |
| 1698 |
data [format=function] { |
| 1699 |
var x : interval [-1.25:2]; |
| 1700 |
func y = \value x * \value x / 2; |
| 1701 |
}; |
| 1702 |
\end{codeexample} |
| 1703 |
% |
| 1704 |
\end{key} |
| 1705 |
|
| 1706 |
\begin{key}{/tikz/data visualization/minor=\meta{options}} |
| 1707 |
Like |major|, only for minor ticks/grid lines. |
| 1708 |
% |
| 1709 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1710 |
\tikz \datavisualization |
| 1711 |
[ school book axes, visualize as smooth line, |
| 1712 |
x axis={grid={minor={at={1, 1.5, 2}}}}] |
| 1713 |
data [format=function] { |
| 1714 |
var x : interval [-1.25:2]; |
| 1715 |
func y = \value x * \value x / 2; |
| 1716 |
}; |
| 1717 |
\end{codeexample} |
| 1718 |
% |
| 1719 |
\end{key} |
| 1720 |
|
| 1721 |
\begin{key}{/tikz/data visualization/subminor=\meta{options}} |
| 1722 |
Like |major|, only for subminor ticks/grid lines. |
| 1723 |
\end{key} |
| 1724 |
|
| 1725 |
\begin{key}{/tikz/data visualization/common=\meta{options}} |
| 1726 |
This key allows you to specify \meta{options} that apply to |major|, |
| 1727 |
|minor| and |subminor| alike. It does not make sense to use |common| to |
| 1728 |
specify positions (since you typically do not want both a major and a minor |
| 1729 |
tick at the same position), but it can be useful to configure, say, the |
| 1730 |
size of all kinds of ticks: |
| 1731 |
% |
| 1732 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1733 |
\tikz \datavisualization |
| 1734 |
[ school book axes, visualize as smooth line, |
| 1735 |
x axis={ticks={minor steps between steps, common={low=0}}} ] |
| 1736 |
data [format=function] { |
| 1737 |
var x : interval [-1.25:2]; |
| 1738 |
func y = \value x * \value x / 2; |
| 1739 |
}; |
| 1740 |
\end{codeexample} |
| 1741 |
% |
| 1742 |
\end{key} |
| 1743 |
|
| 1744 |
The following keys can now be passed to the |major|, |minor|, and |subminor| |
| 1745 |
keys to specify where ticks or grid lines should be shown: |
| 1746 |
|
| 1747 |
\begin{key}{/tikz/data visualization/at=\meta{list}} |
| 1748 |
Basically, the \meta{list} must be a list of values that is processed with |
| 1749 |
the |\foreach| macro (thus, it can contain ellipses to specify ranges of |
| 1750 |
value). Empty values are skipped. |
| 1751 |
|
| 1752 |
The effect of passing |at| to a |major|, |minor|, or |subminor| key is that |
| 1753 |
ticks or grid lines on the axis will be placed exactly at the values in |
| 1754 |
\meta{list}. Here is an example: |
| 1755 |
% |
| 1756 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1757 |
\tikz \datavisualization |
| 1758 |
[ school book axes, visualize as smooth line, |
| 1759 |
x axis={ticks={major={at={-1,0.5,(pi/2)}}}}] |
| 1760 |
data [format=function] { |
| 1761 |
var x : interval [-1.25:2]; |
| 1762 |
func y = \value x * \value x / 2; |
| 1763 |
}; |
| 1764 |
\end{codeexample} |
| 1765 |
When this option is used, any previously specified tick positions are |
| 1766 |
overwritten by the values in \meta{list}. Automatically computed ticks are |
| 1767 |
also overwritten. Thus, this option gives you complete control over where |
| 1768 |
ticks should be placed. |
| 1769 |
|
| 1770 |
Normally, the individual values inside the \meta{list} are just numbers |
| 1771 |
that are specified in the same way as an attribute value. However, such a |
| 1772 |
value may also contain the keyword |as|, which allows you so specify the |
| 1773 |
styling of the tick in detail. Section~\ref{section-dv-ticks-styling} |
| 1774 |
details how this works. |
| 1775 |
|
| 1776 |
It is often a bit cumbersome that one has to write things like |
| 1777 |
% |
| 1778 |
\begin{codeexample}[code only] |
| 1779 |
some axis = {ticks = {major = {at = {...}}}} |
| 1780 |
\end{codeexample} |
| 1781 |
% |
| 1782 |
A slight simplification is given by the following keys, which can be passed |
| 1783 |
directly to |ticks| and |grid|: |
| 1784 |
% |
| 1785 |
\begin{key}{/tikz/data visualization/major at=\meta{list}} |
| 1786 |
A shorthand for |major={at={|\meta{list}|}}|. |
| 1787 |
\end{key} |
| 1788 |
% |
| 1789 |
\begin{key}{/tikz/data visualization/minor at=\meta{list}} |
| 1790 |
A shorthand for |major={at={|\meta{list}|}}|. |
| 1791 |
\end{key} |
| 1792 |
% |
| 1793 |
\begin{key}{/tikz/data visualization/subminor at=\meta{list}} |
| 1794 |
A shorthand for |major={at={|\meta{list}|}}|. |
| 1795 |
\end{key} |
| 1796 |
\end{key} |
| 1797 |
|
| 1798 |
\begin{key}{/tikz/data visualization/also at=\meta{list}} |
| 1799 |
This key is similar to |at|, but it causes ticks or grid lines to be placed |
| 1800 |
at the positions in the \meta{list} \emph{in addition} to the ticks that |
| 1801 |
have already been specified either directly using |at| or indirectly using |
| 1802 |
keys like |step| or |some|. The effect of multiple calls of this key |
| 1803 |
accumulate. However, when |at| is used after an |also at| key, the |at| key |
| 1804 |
completely resets the positions where ticks or grid lines are shown. |
| 1805 |
% |
| 1806 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1807 |
\tikz \datavisualization |
| 1808 |
[ school book axes, visualize as smooth line, |
| 1809 |
x axis={grid, ticks and grid={major={also at={0.5}}}}] |
| 1810 |
data [format=function] { |
| 1811 |
var x : interval [-1.25:2]; |
| 1812 |
func y = \value x * \value x / 2; |
| 1813 |
}; |
| 1814 |
\end{codeexample} |
| 1815 |
% |
| 1816 |
As for |at|, there are some shorthands available: |
| 1817 |
% |
| 1818 |
\begin{key}{/tikz/data visualization/major also at=\meta{list}} |
| 1819 |
A shorthand for |major={also at={|\meta{list}|}}|. |
| 1820 |
\end{key} |
| 1821 |
% |
| 1822 |
\begin{key}{/tikz/data visualization/minor also at=\meta{list}} |
| 1823 |
A shorthand for |major={also at={|\meta{list}|}}|. |
| 1824 |
\end{key} |
| 1825 |
% |
| 1826 |
\begin{key}{/tikz/data visualization/subminor also at=\meta{list}} |
| 1827 |
A shorthand for |major={also at={|\meta{list}|}}|. |
| 1828 |
\end{key} |
| 1829 |
\end{key} |
| 1830 |
|
| 1831 |
|
| 1832 |
\subsubsection{Styling Ticks and Grid Lines: Introduction} |
| 1833 |
\label{section-dv-ticks-styling} |
| 1834 |
|
| 1835 |
When a tick, a tick label, or a grid line is visualized on the page, a whole |
| 1836 |
regiment of styles influences the appearance. The reason for this large number |
| 1837 |
of interdependent styles is the fact that we often wish to influence only a |
| 1838 |
very certain part of how a tick is rendered while leaving the other aspects |
| 1839 |
untouched: Sometimes we need to modify just the font of the tick label; |
| 1840 |
sometimes we wish to change the length of the tick label and the tick label |
| 1841 |
position at the same time; sometimes we wish to change the color of grid line, |
| 1842 |
tick, and tick label; and sometimes we wish to generally change the thickness |
| 1843 |
of all ticks. |
| 1844 |
|
| 1845 |
Let us go over the different kinds of things that can be styled (grid lines, |
| 1846 |
ticks, and tick labels) one by one and let us have a look at which styles are |
| 1847 |
involved. We will start with the grid lines, since they turn out to be the most |
| 1848 |
simple, but first let us have a look at the general |style| and |styling| |
| 1849 |
mechanism that is used in many placed in the following: |
| 1850 |
|
| 1851 |
|
| 1852 |
\subsubsection{Styling Ticks and Grid Lines: The Style and Node Style Keys} |
| 1853 |
\label{section-dv-style} |
| 1854 |
|
| 1855 |
All keys of the data visualization system have the path prefix |
| 1856 |
|/tikz/data visualization|. This is not only true for the main keys like |
| 1857 |
|scientific axes| or |visualize as line|, but also for keys that govern how |
| 1858 |
ticks are visualized. In particular, a style like |every major grid| has the |
| 1859 |
path prefix |/tikz/data visualization| and all keys stored in this style are |
| 1860 |
also executed with this path prefix. |
| 1861 |
|
| 1862 |
Normally, this does not cause any trouble since most of the keys and even |
| 1863 |
styles used in a data visualization are intended to configure what is shown in |
| 1864 |
the visualization. However, at some point, we may also with to specify options |
| 1865 |
that no longer configure the visualization in general, but specify the |
| 1866 |
appearance of a line or a node on the \tikzname\ layer. |
| 1867 |
|
| 1868 |
Two keys are used to ``communicate'' with the \tikzname\ layer: |
| 1869 |
|
| 1870 |
\begin{key}{/tikz/data visualization/style=\meta{\tikzname\ options}} |
| 1871 |
This key takes options whose path prefix is |/tikz|, not |
| 1872 |
|/tikz/data visualization|. These options will be \emph{appended} to a |
| 1873 |
current list of such options (thus, multiple calls of this key accumulate). |
| 1874 |
The resulting list of keys is not executed immediately, but it will be |
| 1875 |
executed whenever the data visualization engine calls the \tikzname\ layer |
| 1876 |
to draw something (this placed will be indicated in the following). |
| 1877 |
% |
| 1878 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1879 |
\tikz \datavisualization |
| 1880 |
[scientific axes, |
| 1881 |
all axes={ticks={style=blue}, length=3cm}, |
| 1882 |
y axis={grid, grid={minor steps between steps, major={style=red}}}, |
| 1883 |
visualize as line] |
| 1884 |
data [format=function] { |
| 1885 |
var x : interval [5:10]; |
| 1886 |
func y = \value x * \value x; |
| 1887 |
}; |
| 1888 |
\end{codeexample} |
| 1889 |
% |
| 1890 |
\end{key} |
| 1891 |
|
| 1892 |
\begin{key}{/tikz/data visualization/styling} |
| 1893 |
Executing this key will cause all ``accumulated'' \tikzname\ options from |
| 1894 |
previous calls to the key |/tikz/data visualization/style| to be executed. |
| 1895 |
Thus, you use |style| to set \tikzname\ options, but you use |styling| to |
| 1896 |
actually apply these options. Usually, you do not call this option directly |
| 1897 |
since this application is only done deep inside the data visualization |
| 1898 |
engine. |
| 1899 |
\end{key} |
| 1900 |
|
| 1901 |
Similar to |style| (and |styling|) there also exist the |node style| (and |
| 1902 |
|node styling|) key that takes \tikzname\ options that apply to nodes only -- |
| 1903 |
in addition to the usual |style|. |
| 1904 |
|
| 1905 |
\begin{key}{/tikz/data visualization/node style=\meta{\tikzname\ options}} |
| 1906 |
This key works like |style|, but it has an effect only on nodes that are |
| 1907 |
created during a data visualization. This includes tick labels and axis |
| 1908 |
labels: |
| 1909 |
% |
| 1910 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1911 |
\tikz \datavisualization |
| 1912 |
[scientific axes, |
| 1913 |
all axes={ticks={node style=red}, length=3cm}, |
| 1914 |
visualize as line] |
| 1915 |
data [format=function] { |
| 1916 |
var x : interval [5:10]; |
| 1917 |
func y = \value x * \value x; |
| 1918 |
}; |
| 1919 |
\end{codeexample} |
| 1920 |
% |
| 1921 |
Note that in the example the ticks themselves (the little thicker lines) |
| 1922 |
are not red. |
| 1923 |
\end{key} |
| 1924 |
|
| 1925 |
\begin{key}{/tikz/data visualization/node styling} |
| 1926 |
Executing this key will cause all ``accumulated'' node stylings to be |
| 1927 |
executed. |
| 1928 |
\end{key} |
| 1929 |
|
| 1930 |
|
| 1931 |
\subsubsection{Styling Ticks and Grid Lines: Styling Grid Lines} |
| 1932 |
\label{section-dv-styling-grid-lines} |
| 1933 |
|
| 1934 |
When a grid line is visualized, see |
| 1935 |
Section~\ref{section-dv-visualize-gridlines} for details on when this happens, |
| 1936 |
the following styles are executed in the specified order. |
| 1937 |
% |
| 1938 |
\begin{enumerate} |
| 1939 |
\item |grid layer|. |
| 1940 |
\item |every grid|. |
| 1941 |
\item |every major grid| or |every minor grid| or |every subminor grid|, |
| 1942 |
depending on the kind of grid line. |
| 1943 |
\item locally specified options for the individual grid line, see |
| 1944 |
Section~\ref{section-dv-local-styles}. |
| 1945 |
\item |styling|, see Section~\ref{section-dv-style}. |
| 1946 |
\end{enumerate} |
| 1947 |
|
| 1948 |
All of these keys have the path prefix |/tikz/data visualization|. However, the |
| 1949 |
options stored in the first style (|grid layer|) and also in the last |
| 1950 |
(|styling|) are executed with the path prefix |/tikz| (see |
| 1951 |
Section~\ref{section-dv-style}). |
| 1952 |
|
| 1953 |
Let us now have a look at these keys in detail: |
| 1954 |
|
| 1955 |
\begin{stylekey}{/tikz/data visualization/grid layer (initially on background layer)} |
| 1956 |
\label{section-dv-grid-layer}% |
| 1957 |
This key is used to specified the \emph{layer} on which grid lines should |
| 1958 |
be drawn (layers are explained in Section~\ref{section-tikz-backgrounds}). |
| 1959 |
By default, all grid lines are placed on the |background| layer and thus |
| 1960 |
behind the data visualization. This is a sensible strategy since it avoids |
| 1961 |
obscuring the more important data with the far less important grid lines. |
| 1962 |
However, you can change this style to ``get the grid lines to the front'': |
| 1963 |
% |
| 1964 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 1965 |
\tikz \datavisualization |
| 1966 |
[scientific axes, |
| 1967 |
all axes={ |
| 1968 |
length=3cm, |
| 1969 |
grid, |
| 1970 |
grid={minor steps between steps} |
| 1971 |
}, |
| 1972 |
grid layer/.style=, % none, so on top of data (bad idea) |
| 1973 |
visualize as line] |
| 1974 |
data [format=function] { |
| 1975 |
var x : interval [5:10]; |
| 1976 |
func y = \value x * \value x; |
| 1977 |
}; |
| 1978 |
\end{codeexample} |
| 1979 |
% |
| 1980 |
When this style is executed, the keys stored in the style will be executed |
| 1981 |
with the prefix |/tikz|. Normally, you should only set this style to be |
| 1982 |
empty or to |on background layer|. |
| 1983 |
\end{stylekey} |
| 1984 |
|
| 1985 |
\begin{stylekey}{/tikz/data visualization/every grid} |
| 1986 |
This style provides overall configuration options for grid lines. By |
| 1987 |
default, it is set to the following: |
| 1988 |
% |
| 1989 |
\begin{codeexample}[code only] |
| 1990 |
low=min, high=max |
| 1991 |
\end{codeexample} |
| 1992 |
% |
| 1993 |
This causes grid lines to span all possible values when they are |
| 1994 |
visualized, which is usually the desired behavior (the |low| and |high| |
| 1995 |
keys are explained in Section~\ref{section-dv-visualize-ticks}. You can |
| 1996 |
append the |style| key to this style to configure the overall appearance of |
| 1997 |
grid lines. It should be noted that settings to |style| inside |every grid| |
| 1998 |
will take precedence over ones in |every major grid| and |every minor grid|. |
| 1999 |
In the following example we cause all grid lines to be dashed (which is not |
| 2000 |
a good idea in general since it creates a distracting background pattern). |
| 2001 |
% |
| 2002 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2003 |
\tikz \datavisualization |
| 2004 |
[scientific axes, |
| 2005 |
all axes={length=3cm, grid}, |
| 2006 |
every grid/.append style={style=densely dashed}, |
| 2007 |
visualize as line] |
| 2008 |
data [format=function] { |
| 2009 |
var x : interval [5:10]; |
| 2010 |
func y = \value x * \value x; |
| 2011 |
}; |
| 2012 |
\end{codeexample} |
| 2013 |
% |
| 2014 |
\end{stylekey} |
| 2015 |
|
| 2016 |
\begin{stylekey}{/tikz/data visualization/every major grid} |
| 2017 |
This style configures the appearance of major grid lines. It does so by |
| 2018 |
calling the |style| key to setup appropriate \tikzname\ options for |
| 2019 |
visualizing major grid lines. The default definition of this style is: |
| 2020 |
% |
| 2021 |
\begin{codeexample}[code only] |
| 2022 |
style = {help lines, thin, black!25} |
| 2023 |
\end{codeexample} |
| 2024 |
% |
| 2025 |
In the following example, we use thin major blue grid lines: |
| 2026 |
% |
| 2027 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2028 |
\tikz \datavisualization |
| 2029 |
[scientific axes, |
| 2030 |
all axes={ |
| 2031 |
length=3cm, |
| 2032 |
grid, |
| 2033 |
grid={minor steps between steps} |
| 2034 |
}, |
| 2035 |
every major grid/.style = {style={blue, thin}}, |
| 2036 |
visualize as line] |
| 2037 |
data [format=function] { |
| 2038 |
var x : interval [5:10]; |
| 2039 |
func y = \value x * \value x; |
| 2040 |
}; |
| 2041 |
\end{codeexample} |
| 2042 |
% |
| 2043 |
As can be seen, this is not exactly visually pleasing. The default settings |
| 2044 |
for the grid lines should work in most situations; you may wish to increase |
| 2045 |
the blackness level, however, when you experience trouble during printing |
| 2046 |
or projecting graphics. |
| 2047 |
\end{stylekey} |
| 2048 |
|
| 2049 |
\begin{stylekey}{/tikz/data visualization/every minor grid} |
| 2050 |
Works like |every major grid|. The default is |
| 2051 |
% |
| 2052 |
\begin{codeexample}[code only] |
| 2053 |
style = {help lines, black!25} |
| 2054 |
\end{codeexample} |
| 2055 |
% |
| 2056 |
\end{stylekey} |
| 2057 |
|
| 2058 |
\begin{stylekey}{/tikz/data visualization/every subminor grid} |
| 2059 |
Works like |every major grid|. The default is |
| 2060 |
% |
| 2061 |
\begin{codeexample}[code only] |
| 2062 |
style = {help lines, black!10} |
| 2063 |
\end{codeexample} |
| 2064 |
% |
| 2065 |
\end{stylekey} |
| 2066 |
|
| 2067 |
|
| 2068 |
\subsubsection{Styling Ticks and Grid Lines: Styling Ticks and Tick Labels} |
| 2069 |
\label{section-dv-styling-ticks} |
| 2070 |
|
| 2071 |
Styling ticks and tick labels is somewhat similar to styling grid lines. Let us |
| 2072 |
start with the tick \emph{mark}, that is, the small line that represents the |
| 2073 |
tick. When this mark is drawn, the following styles are applied: |
| 2074 |
% |
| 2075 |
\begin{enumerate} |
| 2076 |
\item |every ticks|. |
| 2077 |
\item |every major ticks| or |every minor ticks| or |every subminor ticks|, |
| 2078 |
depending on the kind of ticks to be visualized. |
| 2079 |
\item locally specified options for the individual tick, see |
| 2080 |
Section~\ref{section-dv-local-styles}. |
| 2081 |
\item |tick layer| |
| 2082 |
\item |every odd tick| or |every even tick|, see |
| 2083 |
Section~\ref{section-dv-stacking}. |
| 2084 |
\item |draw| |
| 2085 |
\item |styling|, see Section~\ref{section-dv-style}. |
| 2086 |
\end{enumerate} |
| 2087 |
|
| 2088 |
For the tick label node (the node containing the textual representation of the |
| 2089 |
attribute's value at the tick position), the following styles are applied: |
| 2090 |
% |
| 2091 |
\begin{enumerate} |
| 2092 |
\item |every ticks|. |
| 2093 |
\item |every major ticks| or |every minor ticks| or |every subminor ticks|, |
| 2094 |
depending on the kind of ticks to be visualized. |
| 2095 |
\item locally specified options for the individual tick, see |
| 2096 |
Section~\ref{section-dv-local-styles}. |
| 2097 |
\item |tick node layer| |
| 2098 |
\item |every odd tick| or |every even tick|, see |
| 2099 |
Section~\ref{section-dv-stacking}. |
| 2100 |
\item |styling|, see Section~\ref{section-dv-style}. |
| 2101 |
\item |node styling|, see Section~\ref{section-dv-style}. |
| 2102 |
\end{enumerate} |
| 2103 |
|
| 2104 |
\begin{stylekey}{/tikz/data visualization/every ticks} |
| 2105 |
This style allows you to configure the appearance of ticks using the |
| 2106 |
|style| and |node style| key. Here is (roughly) the default definition of |
| 2107 |
this style: |
| 2108 |
% |
| 2109 |
\begin{codeexample}[code only] |
| 2110 |
node style={ |
| 2111 |
font=\footnotesize, |
| 2112 |
inner sep=1pt, |
| 2113 |
outer sep=.1666em, |
| 2114 |
rounded corners=1.5pt |
| 2115 |
} |
| 2116 |
\end{codeexample} |
| 2117 |
% |
| 2118 |
\end{stylekey} |
| 2119 |
|
| 2120 |
\begin{stylekey}{/tikz/data visualization/every major ticks} |
| 2121 |
The default is |
| 2122 |
% |
| 2123 |
\begin{codeexample}[code only] |
| 2124 |
style={line cap=round}, tick length=2pt |
| 2125 |
\end{codeexample} |
| 2126 |
% |
| 2127 |
\end{stylekey} |
| 2128 |
|
| 2129 |
\begin{stylekey}{/tikz/data visualization/every minor ticks} |
| 2130 |
The default is |
| 2131 |
% |
| 2132 |
\begin{codeexample}[code only] |
| 2133 |
style={help lines,thin, line cap=round}, tick length=1.4pt |
| 2134 |
\end{codeexample} |
| 2135 |
% |
| 2136 |
\end{stylekey} |
| 2137 |
|
| 2138 |
\begin{stylekey}{/tikz/data visualization/every subminor ticks} |
| 2139 |
The default is |
| 2140 |
% |
| 2141 |
\begin{codeexample}[code only] |
| 2142 |
style={help lines, line cap=round}, tick length=0.8pt |
| 2143 |
\end{codeexample} |
| 2144 |
% |
| 2145 |
\end{stylekey} |
| 2146 |
|
| 2147 |
\begin{stylekey}{/tikz/data visualization/tick layer (initially on background layer)} |
| 2148 |
Like |grid layer|, this key specifies on which layer the ticks should be |
| 2149 |
placed. |
| 2150 |
\end{stylekey} |
| 2151 |
|
| 2152 |
\begin{stylekey}{/tikz/data visualization/tick node layer (initially \normalfont empty)} |
| 2153 |
Like |tick layer|, but now for the nodes. By default, tick nodes are placed |
| 2154 |
on the main layer and thus on top of the data in case that the tick nodes |
| 2155 |
are inside the data. |
| 2156 |
\end{stylekey} |
| 2157 |
|
| 2158 |
|
| 2159 |
\subsubsection{Styling Ticks and Grid Lines: Exceptional Ticks} |
| 2160 |
|
| 2161 |
You may sometimes wish to style a few ticks differently from the other ticks. |
| 2162 |
For instance, in the axis system |school book axes| there should be a tick |
| 2163 |
label at the |0| position only on one axis and then this label should be offset |
| 2164 |
a bit. In many cases this is easy to achieve: When you add a tick ``by hand'' |
| 2165 |
using the |at| or |also at| option, you can add any special options in square |
| 2166 |
brackets. |
| 2167 |
|
| 2168 |
However, in some situations the special tick position has been computed |
| 2169 |
automatically for you, for instance by the |step| key or by saying |tick=some|. |
| 2170 |
In this case, adding a tick mark with the desired options using |also at| would |
| 2171 |
cause the tick mark with the correct options to be shown in addition to the |
| 2172 |
tick mark with the wrong options. In cases like this one, the following option |
| 2173 |
may be helpful: |
| 2174 |
|
| 2175 |
\begin{key}{/tikz/data visualization/options at=\meta{value} |as [|\meta{options}|]|} |
| 2176 |
This key causes the \meta{options} to be executed for any tick mark(s) at |
| 2177 |
\meta{value} in addition to any options given already for this position: |
| 2178 |
% |
| 2179 |
\begin{codeexample}[ |
| 2180 |
width=7cm, |
| 2181 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 2182 |
] |
| 2183 |
\tikz \datavisualization [ |
| 2184 |
scientific axes, |
| 2185 |
visualize as smooth line, |
| 2186 |
x axis={ticks={major={ |
| 2187 |
options at = 3 as [no tick text], |
| 2188 |
also at = (pi) as |
| 2189 |
[{tick text padding=1ex}] $\pi$}}}] |
| 2190 |
data [format=function] { |
| 2191 |
var x : interval[0:2*pi]; |
| 2192 |
func y = sin(\value x r); |
| 2193 |
}; |
| 2194 |
\end{codeexample} |
| 2195 |
% |
| 2196 |
\end{key} |
| 2197 |
|
| 2198 |
\begin{key}{/tikz/data visualization/no tick text at=\meta{value}} |
| 2199 |
Shorthand for |options at=|\meta{value}| as [no tick text]|. |
| 2200 |
\end{key} |
| 2201 |
|
| 2202 |
|
| 2203 |
\subsubsection{Styling Ticks and Grid Lines: Styling and Typesetting a Value} |
| 2204 |
\label{section-dv-local-styles} |
| 2205 |
\label{section-dv-tick-labels} |
| 2206 |
|
| 2207 |
The \todosp{why 2 labels?} |at| and |also at| key allow you to provide a |
| 2208 |
comma-separated \meta{list} of \meta{value}s where ticks or grid lines should |
| 2209 |
be placed. In the simplest case, the \meta{value} is simply a number. However, |
| 2210 |
the general syntax allows three different kinds of \meta{value}s: |
| 2211 |
% |
| 2212 |
\begin{enumerate} |
| 2213 |
\item \meta{value} |
| 2214 |
\item \meta{value} |as| |[|\meta{local options}|]| |
| 2215 |
\item \meta{value} |as| \opt{|[|\meta{local options}|]|} \meta{text} |
| 2216 |
\end{enumerate} |
| 2217 |
|
| 2218 |
In the first case, the \meta{value} is just a number that is interpreted like |
| 2219 |
any other attribute value. |
| 2220 |
|
| 2221 |
In the second case, where the keyword |as| is present, followed by some option |
| 2222 |
in square brackets, but nothing following the closing square bracket, when the |
| 2223 |
tick or grid line at position \meta{value} is shown, the \meta{local options} |
| 2224 |
are executed first. These can use the |style| key or the |node style| key to |
| 2225 |
configure the appearance of this single tick or grid line. You can also use |
| 2226 |
keys like |low| or |high| to influence how large the grid lines or the ticks |
| 2227 |
are or keys like |tick text at low| to explicitly hide or show a tick label. |
| 2228 |
|
| 2229 |
In the third case, which is only important for |ticks| and not for |grid|, the |
| 2230 |
same happens as in the second case, but the text that is shown as tick label is |
| 2231 |
\meta{text} rather than the automatically generated tick label. This automatic |
| 2232 |
generation of tick labels is explained in the following. |
| 2233 |
% |
| 2234 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2235 |
\tikz \datavisualization |
| 2236 |
[scientific axes=clean, |
| 2237 |
x axis={length=2.5cm, ticks={major at={ |
| 2238 |
5, |
| 2239 |
6 as [style=red], |
| 2240 |
7 as [{style=blue, low=-1em}], |
| 2241 |
8 as [style=green] $2^3$, |
| 2242 |
10 as ten |
| 2243 |
}}}, |
| 2244 |
visualize as line] |
| 2245 |
data [format=function] { |
| 2246 |
var x : interval [5:10]; |
| 2247 |
func y = \value x * \value x; |
| 2248 |
}; |
| 2249 |
\end{codeexample} |
| 2250 |
|
| 2251 |
A value like ``2'' or ``17'' could just be used as \meta{text} to be displayed |
| 2252 |
in the node of a tick label. However, things are more difficult when the |
| 2253 |
to-be-shown value is $0.0000000015$, because we then would typically (but not |
| 2254 |
always) prefer something like $1.5 \cdot 10^{-9}$ to be shown. Also, we might |
| 2255 |
wish a unit to be added like $23\mathrm{m}/\mathrm{s}$. Finally, we might wish |
| 2256 |
a number like $3.141$ to be replaced by $\pi$. For these reasons, the data |
| 2257 |
visualization system does not simply put the to-be-shown value in a node as |
| 2258 |
plain text. Instead, the number is passed to a \emph{typesetter} whose job it |
| 2259 |
is to typeset this number nicely using \TeX's typesetting capabilities. The |
| 2260 |
only exception is, as indicated above, the third syntax version of the |at| and |
| 2261 |
|also at| keys, where \meta{text} is placed in the tick label's node, |
| 2262 |
regardless of what the typesetting would usually do. |
| 2263 |
|
| 2264 |
The text produced by the automatic typesetting is computed as follows: |
| 2265 |
% |
| 2266 |
\begin{enumerate} |
| 2267 |
\item The current contents of the key |tick prefix| is put into the node. |
| 2268 |
\item This is followed by a call of the key |tick typesetter| which gets |
| 2269 |
the \meta{value} of the tick as its argument in scientific notation. |
| 2270 |
\item This is followed by the contents of the key |tick suffix|. |
| 2271 |
\end{enumerate} |
| 2272 |
|
| 2273 |
Let us have a look at these keys in detail: |
| 2274 |
|
| 2275 |
\begin{key}{/tikz/data visualization/tick prefix=\meta{text} (initially \normalfont empty)} |
| 2276 |
The \meta{text} will be put in front of every typeset tick: |
| 2277 |
% |
| 2278 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2279 |
\tikz \datavisualization |
| 2280 |
[scientific axes, all axes={ticks=few, length=2.5cm}, |
| 2281 |
x axis={ticks={tick prefix=$\langle$, tick suffix=$]$}}, |
| 2282 |
visualize as line] |
| 2283 |
data [format=function] { |
| 2284 |
var x : interval [5:10]; |
| 2285 |
func y = \value x * \value x; |
| 2286 |
}; |
| 2287 |
\end{codeexample} |
| 2288 |
% |
| 2289 |
\end{key} |
| 2290 |
|
| 2291 |
\begin{key}{/tikz/data visualization/tick suffix=\meta{text} (initially \normalfont empty)} |
| 2292 |
Works like |tick prefix|. This key is especially useful for adding units |
| 2293 |
like ``cm'' or ``$\mathrm m/\mathrm s$'' to every tick label. For this |
| 2294 |
reason, there is a (near) alias that is easier to memorize: |
| 2295 |
% |
| 2296 |
\begin{key}{/tikz/data visualization/tick unit=\meta{roman math text}} |
| 2297 |
A shorthand for |tick suffix={$\,\rm|\meta{roman math text}|$}|: |
| 2298 |
% |
| 2299 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2300 |
\tikz \datavisualization |
| 2301 |
[scientific axes, all axes={length=3cm}, |
| 2302 |
x axis={ticks={tick unit=s}}, |
| 2303 |
y axis={ticks={tick unit=m/s^2}}, |
| 2304 |
visualize as line] |
| 2305 |
data [format=function] { |
| 2306 |
var x : interval [5:10]; |
| 2307 |
func y = \value x * \value x; |
| 2308 |
}; |
| 2309 |
\end{codeexample} |
| 2310 |
\end{key} |
| 2311 |
\end{key} |
| 2312 |
|
| 2313 |
\begin{key}{/tikz/data visualization/tick typesetter=\meta{value}} |
| 2314 |
The key gets called for each number that should be typeset. The argument |
| 2315 |
\meta{value} will be in scientific notation (like |1.0e1| for $10$). By |
| 2316 |
default, this key applies |\pgfmathprintnumber| to its argument. This |
| 2317 |
command is a powerful number printer whose configuration is documented in |
| 2318 |
Section~\ref{pgfmath-numberprinting}. |
| 2319 |
|
| 2320 |
You are invited to code underlying this key so that a different typesetting |
| 2321 |
mechanism is used. Here is a (not quite finished) example that shows how, |
| 2322 |
say, numbers could be printed in terms of multiples of $\pi$: |
| 2323 |
% |
| 2324 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2325 |
\def\mytypesetter#1{% |
| 2326 |
\pgfmathparse{#1/pi}% |
| 2327 |
\pgfmathprintnumber{\pgfmathresult}$\pi$% |
| 2328 |
} |
| 2329 |
\tikz \datavisualization |
| 2330 |
[school book axes, all axes={unit length=1.25cm}, |
| 2331 |
x axis={ticks={step=(0.5*pi), tick typesetter/.code=\mytypesetter{##1}}}, |
| 2332 |
y axis={include value={-1,1}}, |
| 2333 |
visualize as smooth line] |
| 2334 |
data [format=function] { |
| 2335 |
var x : interval [0.5:7]; |
| 2336 |
func y = sin(\value x r); |
| 2337 |
}; |
| 2338 |
\end{codeexample} |
| 2339 |
% |
| 2340 |
\end{key} |
| 2341 |
|
| 2342 |
|
| 2343 |
\subsubsection{Stacked Ticks} |
| 2344 |
\label{section-dv-stacking} |
| 2345 |
|
| 2346 |
Sometimes, the text of tick labels are so long or so numerous that the text of |
| 2347 |
adjacent tick labels overlap (or have too little padding): |
| 2348 |
% |
| 2349 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2350 |
\tikz \datavisualization [scientific axes, |
| 2351 |
all axes={length=2.5cm}, |
| 2352 |
visualize as smooth line] |
| 2353 |
data [format=function] { |
| 2354 |
var y : interval[-100:100]; |
| 2355 |
func x = \value y*\value y; |
| 2356 |
}; |
| 2357 |
\end{codeexample} |
| 2358 |
% |
| 2359 |
There are two ways to address this problem: |
| 2360 |
% |
| 2361 |
\begin{itemize} |
| 2362 |
\item One can rotate the labels on horizontal axes: |
| 2363 |
% |
| 2364 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2365 |
\tikz \datavisualization [scientific axes, |
| 2366 |
all axes={length=2.5cm}, |
| 2367 |
x axis={ticks={node style={rotate=90, anchor=east}}}, |
| 2368 |
visualize as smooth line] |
| 2369 |
data [format=function] { |
| 2370 |
var y : interval[-100:100]; |
| 2371 |
func x = \value y*\value y; |
| 2372 |
}; |
| 2373 |
\end{codeexample} |
| 2374 |
% |
| 2375 |
This is often a good solution, but may be hard to read. Also consider |
| 2376 |
rotating labels only by $45^\circ$ or $30^\circ$. |
| 2377 |
\item One can specify different shifts of the nodes for the different |
| 2378 |
ticks, whereby the ticks text no longer overlap. |
| 2379 |
% |
| 2380 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2381 |
\tikz \datavisualization [scientific axes, |
| 2382 |
all axes={length=2.5cm}, |
| 2383 |
x axis={ticks={major at={0,4000,8000, |
| 2384 |
2000 as [node style={yshift=-1em}], |
| 2385 |
6000 as [node style={yshift=-1em}], |
| 2386 |
10000 as [node style={yshift=-1em}]}}}, |
| 2387 |
visualize as smooth line] |
| 2388 |
data [format=function] { |
| 2389 |
var y : interval[-100:100]; |
| 2390 |
func x = \value y*\value y; |
| 2391 |
}; |
| 2392 |
\end{codeexample} |
| 2393 |
% |
| 2394 |
However, specifying shifts ``by hand'' in the above way is not always |
| 2395 |
an option, especially when the tick positions should be computed |
| 2396 |
automatically. Instead, the |stack| option can be used, which is much |
| 2397 |
easier to use and gives better results: |
| 2398 |
% |
| 2399 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2400 |
\tikz \datavisualization [scientific axes, |
| 2401 |
all axes={length=2.5cm}, x axis={ticks=stack}, |
| 2402 |
visualize as smooth line] |
| 2403 |
data [format=function] { |
| 2404 |
var y : interval[-100:100]; |
| 2405 |
func x = \value y*\value y; |
| 2406 |
}; |
| 2407 |
\end{codeexample} |
| 2408 |
% |
| 2409 |
\end{itemize} |
| 2410 |
|
| 2411 |
The |stack| option is actually just a style that gives you access to the |
| 2412 |
general even/odd mechanism for ticks with labels. Whenever a tick mark is |
| 2413 |
created where a tick label is also to be drawn, two special things happen: |
| 2414 |
% |
| 2415 |
\begin{enumerate} |
| 2416 |
\item For every odd tick mark, the |every odd tick| style is executed, for |
| 2417 |
every even tick mark the |every even tick|. Here, ``odd'' and ``even'' |
| 2418 |
are with respect to the order in which the ticks have been added to the |
| 2419 |
list of |at| positions for each major, minor, or subminor tick list, |
| 2420 |
not with respect to the order in which they will appear on the axis. |
| 2421 |
Thus, when you write |
| 2422 |
% |
| 2423 |
\begin{codeexample}[code only] |
| 2424 |
ticks={major at={1,2,3,4}, major at={0,-1,-2}, minor at={9,8,7}} |
| 2425 |
\end{codeexample} |
| 2426 |
% |
| 2427 |
then for |1|, |3|, |0|, and |-2| as well as |9| and |7| the key |
| 2428 |
|every odd tick| will be executed, while |every even tick| will be |
| 2429 |
executed for positions |2|, |4|, |-1|, and also |8|. |
| 2430 |
\item When a tick node label is shown at the |low| position of the tick |
| 2431 |
mark, the dimension stored in the key |tick text low even padding| is |
| 2432 |
added to the |low| value. Provided that this padding is not zero (which |
| 2433 |
is the default), the length of the even tick marks will be increased |
| 2434 |
and the tick label node will be placed at a greater distance from the |
| 2435 |
axis. |
| 2436 |
|
| 2437 |
Similar keys exist for padding ticks with labels at high positions and |
| 2438 |
also at even positions. |
| 2439 |
\end{enumerate} |
| 2440 |
|
| 2441 |
\begin{key}{/tikz/data visualization/tick text low even padding=\meta{dimension} (initially 0pt)} |
| 2442 |
When a tick label is shown at the low position of an even tick, the |
| 2443 |
\meta{distance} is added to the |low| value, see also |
| 2444 |
Section~\ref{section-dv-visualize-ticks}. |
| 2445 |
% |
| 2446 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2447 |
\tikz \datavisualization [scientific axes, |
| 2448 |
all axes={length=2.5cm}, |
| 2449 |
x axis={ticks={tick text low even padding=-1em}}, |
| 2450 |
visualize as smooth line] |
| 2451 |
data [format=function] { |
| 2452 |
var y : interval[-100:100]; |
| 2453 |
func x = \value y*\value y; |
| 2454 |
}; |
| 2455 |
\end{codeexample} |
| 2456 |
% |
| 2457 |
Note that \meta{dimension} should usually be non-positive. |
| 2458 |
\end{key} |
| 2459 |
|
| 2460 |
The following keys work similarly: |
| 2461 |
% |
| 2462 |
\begin{key}{/tikz/data visualization/tick text low odd padding=\meta{dimension} (initially 0pt)} |
| 2463 |
\end{key} |
| 2464 |
% |
| 2465 |
\begin{key}{/tikz/data visualization/tick text high even padding=\meta{dimension} (initially 0pt)} |
| 2466 |
\end{key} |
| 2467 |
% |
| 2468 |
\begin{key}{/tikz/data visualization/tick text high odd padding=\meta{dimension} (initially 0pt)} |
| 2469 |
\end{key} |
| 2470 |
|
| 2471 |
\begin{key}{/tikz/data visualization/tick text odd padding=\meta{dimension}} |
| 2472 |
A shorthand for setting |tick text odd low padding| and |
| 2473 |
|tick text odd high padding| at the same time. |
| 2474 |
\end{key} |
| 2475 |
|
| 2476 |
\begin{key}{/tikz/data visualization/tick text even padding=\meta{dimension}} |
| 2477 |
A shorthand for setting |tick text even low padding| and |
| 2478 |
|tick text even high padding| at the same time. |
| 2479 |
\end{key} |
| 2480 |
|
| 2481 |
\begin{key}{/tikz/data visualization/tick text padding=\meta{dimension}} |
| 2482 |
Sets all text paddings to \meta{dimension}. |
| 2483 |
\end{key} |
| 2484 |
|
| 2485 |
\begin{key}{/tikz/data visualization/stack=\meta{dimension} (default 1em)} |
| 2486 |
Shorthand for |tick text even padding=|\meta{dimension}. |
| 2487 |
% |
| 2488 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2489 |
\tikz \datavisualization [scientific axes, |
| 2490 |
all axes={length=2.5cm}, |
| 2491 |
x axis={ticks={stack=1.5em}}, |
| 2492 |
visualize as smooth line] |
| 2493 |
data [format=function] { |
| 2494 |
var y : interval[-100:100]; |
| 2495 |
func x = \value y*\value y; |
| 2496 |
}; |
| 2497 |
\end{codeexample} |
| 2498 |
% |
| 2499 |
\end{key} |
| 2500 |
|
| 2501 |
\begin{key}{/tikz/data visualization/stack'=\meta{dimension}} |
| 2502 |
Shorthand for |tick text odd padding=|\meta{dimension}. The difference to |
| 2503 |
|stack| is that the set of value that are ``lowered'' is exactly exchanged |
| 2504 |
with the set of value ``lowered'' by |stack|. |
| 2505 |
% |
| 2506 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 2507 |
\tikz \datavisualization [scientific axes, |
| 2508 |
all axes={length=2.5cm}, |
| 2509 |
x axis={ticks=stack'}, |
| 2510 |
visualize as smooth line] |
| 2511 |
data [format=function] { |
| 2512 |
var y : interval[-100:100]; |
| 2513 |
func x = \value y*\value y; |
| 2514 |
}; |
| 2515 |
\end{codeexample} |
| 2516 |
% |
| 2517 |
\end{key} |
| 2518 |
|
| 2519 |
Note that the above keys have an effect on all tick labels of an axis, also on |
| 2520 |
special ticks that you may have added using the |also at| key. When using the |
| 2521 |
|stack| key, you should specify a |tick text padding| explicitly for such keys: |
| 2522 |
% |
| 2523 |
\begin{codeexample}[ |
| 2524 |
width=7cm, |
| 2525 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 2526 |
] |
| 2527 |
\tikz \datavisualization |
| 2528 |
[scientific axes, |
| 2529 |
x axis={ticks={stack, many, major also at= |
| 2530 |
{(pi) as [{tick text padding=2.5em}] $\pi$}}}, |
| 2531 |
visualize as smooth line] |
| 2532 |
data [format=function] { |
| 2533 |
var x : interval[0:(2*pi)]; |
| 2534 |
func y = sin(\value x r); |
| 2535 |
}; |
| 2536 |
\end{codeexample} |
| 2537 |
|
| 2538 |
|
| 2539 |
\subsubsection{Reference: Basic Strategies} |
| 2540 |
\label{section-dv-strategies} |
| 2541 |
|
| 2542 |
\begin{key}{/tikz/data visualization/axis options/linear steps} |
| 2543 |
This strategy places ticks at positions that are evenly spaced by the |
| 2544 |
current value of |step|. |
| 2545 |
|
| 2546 |
In detail, the following happens: Let $a$ be the minimum value of the data |
| 2547 |
values along the axis and let $b$ be the maximum. Let the current |
| 2548 |
\emph{stepping} be $s$ (the stepping is set using the |step| option, see |
| 2549 |
below) and let the current \emph{phasing} be $p$ (set using the |phase|) |
| 2550 |
option. Then ticks are placed all positions $i\cdot s + p$ that lie in the |
| 2551 |
interval $[a,b]$, where $i$ ranges over all integers. |
| 2552 |
|
| 2553 |
The tick positions computed in the way described above are \emph{major} |
| 2554 |
step positions. In addition to these, if the key |
| 2555 |
|minor steps between steps| is set to some number $n$, then $n$ many minor |
| 2556 |
ticks are introduced between each two major ticks (and also before and |
| 2557 |
after the last major tick, provided the values still lie in the interval |
| 2558 |
$[a,b]$). Note that is $n$ is $1$, then one minor tick will be added in the |
| 2559 |
middle between any two major ticks. Use a value of $9$ (not $10$) to |
| 2560 |
partition the interval between two major ticks into ten equally sized minor |
| 2561 |
intervals. |
| 2562 |
% |
| 2563 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 2564 |
\begin{tikzpicture} |
| 2565 |
\datavisualization |
| 2566 |
[scientific axes={inner ticks, width=3cm}, |
| 2567 |
x axis={ticks={step=3, minor steps between steps=2}}, |
| 2568 |
y axis={ticks={step=.36}}, |
| 2569 |
visualize as scatter] |
| 2570 |
data { |
| 2571 |
x, y |
| 2572 |
17, 30 |
| 2573 |
34, 32 |
| 2574 |
}; |
| 2575 |
\end{tikzpicture} |
| 2576 |
\end{codeexample} |
| 2577 |
% |
| 2578 |
\end{key} |
| 2579 |
|
| 2580 |
\label{section-dv-exponential-strategy} |
| 2581 |
|
| 2582 |
\begin{key}{/tikz/data visualization/axis options/exponential steps} |
| 2583 |
This strategy produces ticks at positions that are appropriate for |
| 2584 |
logarithmic plots. It is automatically selected when you use the |
| 2585 |
|logarithmic| option with an axis. |
| 2586 |
|
| 2587 |
In detail, the following happens: As for |linear steps| let numbers $a$, |
| 2588 |
$b$, $s$, and $p$ be given. Then, major ticks are placed at all positions |
| 2589 |
$10^{i\cdot s+p}$ that lie in the interval $[a,b]$ for $i \in \mathbb{Z}$. |
| 2590 |
|
| 2591 |
The minor steps are added in the same way as for |linear steps|. In |
| 2592 |
particular, they interpolate \emph{linearly} between major steps. |
| 2593 |
% |
| 2594 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 2595 |
\begin{tikzpicture} |
| 2596 |
\datavisualization |
| 2597 |
[scientific axes, |
| 2598 |
x axis={logarithmic, length=2cm, ticks={step=1.5}}, |
| 2599 |
y axis={logarithmic, ticks={step=1, minor steps between steps=9}}, |
| 2600 |
visualize as scatter] |
| 2601 |
data { |
| 2602 |
x, y |
| 2603 |
1, 10 |
| 2604 |
1000, 1000000 |
| 2605 |
}; |
| 2606 |
\end{tikzpicture} |
| 2607 |
\end{codeexample} |
| 2608 |
% |
| 2609 |
\end{key} |
| 2610 |
|
| 2611 |
|
| 2612 |
\subsubsection{Advanced: Defining New Placement Strategies} |
| 2613 |
|
| 2614 |
\begin{key}{/tikz/data visualization/axis options/tick placement strategy=\meta{macro}} |
| 2615 |
This key can be used to install a so-called \emph{tick placement strategy}. |
| 2616 |
Whenever |visualize ticks| is used to request some ticks to be visualized, |
| 2617 |
it is checked whether some automatic ticks should be created. This is the |
| 2618 |
case when the following key is set: |
| 2619 |
% |
| 2620 |
\begin{key}{/tikz/data visualization/compute step=\meta{code}} |
| 2621 |
The \meta{code} should compute a suitable value for the stepping to be |
| 2622 |
used by the \meta{macro} in the tick placement strategy. |
| 2623 |
|
| 2624 |
For instance, the |step| key sets |compute step| to |
| 2625 |
|\def\tikz@lib@dv@step{#1}|. Thus, when you say |step=5|, then the |
| 2626 |
desired stepping of |5| is communicated to the \meta{macro} via the |
| 2627 |
macro |\tikz@lib@dv@step|. |
| 2628 |
\end{key} |
| 2629 |
|
| 2630 |
Provided |compute step| is set to some nonempty value, upon visualization |
| 2631 |
of ticks the \meta{macro} is executed. Typically, \meta{macro} will first |
| 2632 |
call the \meta{code} stored in the key |compute step|. Then, it should |
| 2633 |
implement some strategy then uses the value of the computed or desired |
| 2634 |
stepping to create appropriate |at| commands. To be precise, it should set |
| 2635 |
the keys |major|, |minor|, and/or |subminor| with some appropriate |at| |
| 2636 |
values. |
| 2637 |
|
| 2638 |
Inside the call of \meta{macro}, the macro |\tikzdvaxis| will have been set |
| 2639 |
to the name of the axis for which default ticks need to be computed. This |
| 2640 |
allows you to access the minimum and the maximum value stored in the |
| 2641 |
|scaling mapper| of that axis. |
| 2642 |
% |
| 2643 |
\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}] |
| 2644 |
\def\silly{ |
| 2645 |
\tikzdatavisualizationset{major={at={ |
| 2646 |
2,3,5,7,11,13}}} |
| 2647 |
} |
| 2648 |
\begin{tikzpicture} |
| 2649 |
\datavisualization [ |
| 2650 |
scientific axes, visualize as scatter, |
| 2651 |
x axis={tick placement strategy=\silly} |
| 2652 |
] |
| 2653 |
data { |
| 2654 |
x, y |
| 2655 |
0, 0 |
| 2656 |
15, 15 |
| 2657 |
}; |
| 2658 |
\end{tikzpicture} |
| 2659 |
\end{codeexample} |
| 2660 |
% |
| 2661 |
\end{key} |
| 2662 |
|
| 2663 |
|
| 2664 |
\subsection{Advanced: Creating New Axis Systems} |
| 2665 |
|
| 2666 |
The |datavisualization| library comes with a number of predefined axis systems, |
| 2667 |
like |scientific axes=clean|, but it is also possible and to define new axis |
| 2668 |
systems. Doing so involves the following steps: |
| 2669 |
% |
| 2670 |
\begin{enumerate} |
| 2671 |
\item Creating a number of axes. |
| 2672 |
\item Configuring attributes of these axes like their length or default |
| 2673 |
scaling. |
| 2674 |
\item Creating visual representations of the axes. |
| 2675 |
\item Creating visual representations of the ticks and grid lines. |
| 2676 |
\end{enumerate} |
| 2677 |
|
| 2678 |
The first step uses |new ... axis| keys to create new axes, the last steps use |
| 2679 |
|visualize ...| keys to create the visual representations of the axes. |
| 2680 |
|
| 2681 |
Note that the axis system has no control over the actual attribute value ranges |
| 2682 |
and neither over which ticks need to be drawn. The axis system can only provide |
| 2683 |
good defaults and then specify \emph{how} the ticks or labels should be drawn |
| 2684 |
and \emph{where} on the page -- but not at which values. |
| 2685 |
|
| 2686 |
In the following, as a running example let us develop an axis system |
| 2687 |
|our system| that does the following: For the $x$-axis is looks like a normal |
| 2688 |
scientific axis system, but there are actually two $y$-axes: One at the left |
| 2689 |
and one at the right, each using a different attribute, but both coexisting in |
| 2690 |
the same picture. |
| 2691 |
|
| 2692 |
|
| 2693 |
\subsubsection{Creating the Axes} |
| 2694 |
|
| 2695 |
A new axis system is created as a style key with the prefix |
| 2696 |
|/tikz/data visualization|. Thus, we would write: |
| 2697 |
% |
| 2698 |
\begin{codeexample}[code only] |
| 2699 |
\tikzset{ |
| 2700 |
data visualization/our system/.style={ |
| 2701 |
... |
| 2702 |
} |
| 2703 |
} |
| 2704 |
\end{codeexample} |
| 2705 |
|
| 2706 |
In our system we need three axis: The $x$-axis, the left axis and the right |
| 2707 |
axis. Since all of these axes are Cartesian axes, we write the following: |
| 2708 |
% |
| 2709 |
\begin{codeexample}[code only] |
| 2710 |
\tikzset{ |
| 2711 |
data visualization/our system/.style={ |
| 2712 |
new Cartesian axis=x axis, |
| 2713 |
new Cartesian axis=left axis, |
| 2714 |
new Cartesian axis=right axis, |
| 2715 |
x axis={attribute=x}, |
| 2716 |
left axis={unit vector={(0cm,1pt)}}, |
| 2717 |
right axis={unit vector={(0cm,1pt)}}, |
| 2718 |
} |
| 2719 |
} |
| 2720 |
\end{codeexample} |
| 2721 |
% |
| 2722 |
As can be seen, we also configure things so that the $x$-axis will use the |x| |
| 2723 |
attribute by default (users can later change this by saying |
| 2724 |
|x axis={attribute=|\meta{some other attribute}|}|), but we do not configure |
| 2725 |
the attributes of the |left axis| nor the |right axis|. We also make the left |
| 2726 |
and right axis point upward (the |x axis| needs no configuration here since a |
| 2727 |
Cartesian axis points right by default). The reason is the |left| would not be |
| 2728 |
a particularly good attribute name and this way we ensure that users have to |
| 2729 |
pick names themselves (hopefully good ones). |
| 2730 |
|
| 2731 |
The next step is to define a standard scaling for the axes. Here, we can use |
| 2732 |
the same as for |scientific axes|, so we would add the following keys to the |
| 2733 |
definition of |our system|: |
| 2734 |
% |
| 2735 |
\begin{codeexample}[code only] |
| 2736 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 2737 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 2738 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} |
| 2739 |
\end{codeexample} |
| 2740 |
|
| 2741 |
We now already have enough to try our system, although we will not yet see any |
| 2742 |
axes or ticks, but we will see the correct scaling of the attributes. Let us |
| 2743 |
first define a data group: |
| 2744 |
% |
| 2745 |
\begin{codeexample}[setup code] |
| 2746 |
\tikz \datavisualization data group {people and money} = { |
| 2747 |
data [set=people 1] { |
| 2748 |
time, people |
| 2749 |
1900, 1000000000 |
| 2750 |
1920, 1500000000 |
| 2751 |
1930, 2000000000 |
| 2752 |
1980, 3000000000 |
| 2753 |
} |
| 2754 |
data [set=people 2] { |
| 2755 |
time, people |
| 2756 |
1900, 2000000000 |
| 2757 |
1920, 2500000000 |
| 2758 |
1940, 4000000000 |
| 2759 |
2000, 5700000000 |
| 2760 |
} |
| 2761 |
data [set=money 1] { |
| 2762 |
time, money |
| 2763 |
1910, 1.1 |
| 2764 |
1920, 2 |
| 2765 |
1930, 5 |
| 2766 |
1980, 2 |
| 2767 |
} |
| 2768 |
data [set=money 2] { |
| 2769 |
time, money |
| 2770 |
1950, 3 |
| 2771 |
1960, 3 |
| 2772 |
1970, 4 |
| 2773 |
1990, 3.5 |
| 2774 |
} |
| 2775 |
}; |
| 2776 |
\end{codeexample} |
| 2777 |
|
| 2778 |
\begin{codeexample}[setup code,hidden] |
| 2779 |
\tikzdatavisualizationset{ |
| 2780 |
our system/.style={ |
| 2781 |
new Cartesian axis=x axis, |
| 2782 |
new Cartesian axis=left axis, |
| 2783 |
new Cartesian axis=right axis, |
| 2784 |
x axis={attribute=x}, |
| 2785 |
left axis={unit vector={(0cm,1pt)}}, |
| 2786 |
right axis={unit vector={(0cm,1pt)}}, |
| 2787 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 2788 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 2789 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} |
| 2790 |
} |
| 2791 |
} |
| 2792 |
\end{codeexample} |
| 2793 |
% |
| 2794 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 2795 |
\tikz \datavisualization [ |
| 2796 |
our system, |
| 2797 |
x axis={attribute=time, length=4cm}, |
| 2798 |
left axis ={attribute=money}, |
| 2799 |
right axis={attribute=people}, |
| 2800 |
visualize as line/.list={people 1, people 2, money 1, money 2}, |
| 2801 |
people 1={style={visualizer color=blue}}, |
| 2802 |
people 2={style={visualizer color=blue!50}}, |
| 2803 |
money 1={style={visualizer color=red}}, |
| 2804 |
money 2={style={visualizer color=red!50}}] |
| 2805 |
data group {people and money}; |
| 2806 |
\end{codeexample} |
| 2807 |
|
| 2808 |
|
| 2809 |
\subsubsection{Visualizing the Axes} |
| 2810 |
\label{section-dv-visualize-axis} |
| 2811 |
|
| 2812 |
We must now show the axes themselves. For this we can use the |visualize axis| |
| 2813 |
key: |
| 2814 |
|
| 2815 |
\begin{key}{/tikz/data visualization/axis options/visualize axis=\meta{options}} |
| 2816 |
This key is passed to an axis as an option. It causes a visual |
| 2817 |
representation of the axis to be created during the data visualization. The |
| 2818 |
\meta{options} are used to determine where the axis should be drawn and how |
| 2819 |
long it should be. We can specify, for instance, that an axis should be |
| 2820 |
drawn at the minimum value of another axis or where another axis has the |
| 2821 |
value |0|. |
| 2822 |
|
| 2823 |
|
| 2824 |
\medskip |
| 2825 |
\textbf{The goto, high, and low Keys.} |
| 2826 |
In our example, the |left axis| should be shown at the left hand side. This |
| 2827 |
is the position where the |x axis| has its minimum value. To specify this, |
| 2828 |
we would use the following code: |
| 2829 |
% |
| 2830 |
\begin{codeexample}[code only] |
| 2831 |
left axis={ visualize axis={ x axis={ goto=min } } |
| 2832 |
\end{codeexample} |
| 2833 |
% |
| 2834 |
As can be seen, we can pass another axis as an \meta{option} to |
| 2835 |
|visualize axis|, where we pass the following key to the axis in turn: |
| 2836 |
% |
| 2837 |
\begin{key}{/tikz/data visualization/axis options/goto=\meta{value}} |
| 2838 |
The key can be passed to an axis. It will set the attribute monitored |
| 2839 |
by the axis to the given \meta{value}, which is usually some number. |
| 2840 |
However, \meta{value} may also be one of the following, which causes a |
| 2841 |
special behavior: |
| 2842 |
% |
| 2843 |
\begin{itemize} |
| 2844 |
\item |min|: The attribute is set to the minimal value that the |
| 2845 |
attribute has attained along this axis. |
| 2846 |
\item |max|: Like |min|. |
| 2847 |
\item |padded min|: This will also set the \meta{attribute} |
| 2848 |
monitored by the axis to the same value as |min|. |
| 2849 |
Additionally, however, the subkey |
| 2850 |
|/data point/|\meta{attribute}|/offset| is set to the current |
| 2851 |
padding for the minimum, see the description of |padding min| |
| 2852 |
later on. The effect of this is that the actual point ``meant'' |
| 2853 |
by the attribute is offset by this padding along the |
| 2854 |
attribute's axis. |
| 2855 |
\item |padded max|: Like |padded min|. |
| 2856 |
\end{itemize} |
| 2857 |
\end{key} |
| 2858 |
|
| 2859 |
The |right axis| would be visualized the same way, only at |goto=max|. The |
| 2860 |
$x$-axis actually needs to be visualized \emph{twice}: Once at the bottom |
| 2861 |
and once at the top. Thus, we need to call |visualize axis| twice for this |
| 2862 |
axis: |
| 2863 |
% |
| 2864 |
\tikzdatavisualizationset{ |
| 2865 |
our system/.style={ |
| 2866 |
new Cartesian axis=x axis, |
| 2867 |
new Cartesian axis=left axis, |
| 2868 |
new Cartesian axis=right axis, |
| 2869 |
x axis={attribute=x}, |
| 2870 |
left axis={unit vector={(0cm,1pt)}}, |
| 2871 |
right axis={unit vector={(0cm,1pt)}}, |
| 2872 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 2873 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 2874 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} |
| 2875 |
} |
| 2876 |
} |
| 2877 |
\begin{codeexample}[ |
| 2878 |
preamble={\usetikzlibrary{datavisualization}}, |
| 2879 |
pre={\tikzdatavisualizationset{ |
| 2880 |
our system/.style={ |
| 2881 |
new Cartesian axis=x axis, |
| 2882 |
new Cartesian axis=left axis, |
| 2883 |
new Cartesian axis=right axis, |
| 2884 |
x axis={attribute=x}, |
| 2885 |
left axis={unit vector={(0cm,1pt)}}, |
| 2886 |
right axis={unit vector={(0cm,1pt)}}, |
| 2887 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 2888 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 2889 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} |
| 2890 |
} |
| 2891 |
}}] |
| 2892 |
\tikzset{ |
| 2893 |
data visualization/our system/.append style={ |
| 2894 |
left axis= {visualize axis={x axis= {goto=min}}}, |
| 2895 |
right axis={visualize axis={x axis= {goto=max}}}, |
| 2896 |
x axis= {visualize axis={left axis={goto=min}}, |
| 2897 |
visualize axis={left axis={goto=max}}}, |
| 2898 |
} |
| 2899 |
} |
| 2900 |
\tikz \datavisualization [ |
| 2901 |
our system, |
| 2902 |
x axis={attribute=time, length=4cm}, |
| 2903 |
left axis ={attribute=money}, |
| 2904 |
right axis={attribute=people}, |
| 2905 |
visualize as line/.list={people 1, people 2, money 1, money 2}] |
| 2906 |
data group {people and money}; |
| 2907 |
\end{codeexample} |
| 2908 |
|
| 2909 |
There is another key that is similar to |goto|, but has a slightly |
| 2910 |
different semantics: |
| 2911 |
% |
| 2912 |
\begin{key}{/tikz/data visualization/axis options/goto pos=\meta{fraction}} |
| 2913 |
The key works like |goto|, only the \meta{fraction} is not interpreted |
| 2914 |
as a value but as a fraction of the way between the minimum and the |
| 2915 |
maximum value for this axis. |
| 2916 |
|
| 2917 |
Suppose that for an axis the attribute range interval is $[500,1000]$ |
| 2918 |
and the reasonable interval is $[1,3]$. Then for a \meta{fraction} of |
| 2919 |
|0|, the mapping process would choose value $1$ from the reasonable |
| 2920 |
interval, for a \meta{fraction} of |1| the position $3$ from the |
| 2921 |
reasonable interval, and for a \meta{fraction} or |0.25| the position |
| 2922 |
$1.5$ since it is one quarter at the distance from $1$ to $3$. |
| 2923 |
|
| 2924 |
Note that neither the attribute range interval nor the transformation |
| 2925 |
function for the attribute are important for the |goto pos| option -- |
| 2926 |
the \meta{fraction} is computed with respect to the reasonable |
| 2927 |
interval. Also note that the values of the actual attribute |
| 2928 |
corresponding to the fractional positions in the reasonable interval |
| 2929 |
are not computed. |
| 2930 |
% |
| 2931 |
\begin{codeexample}[ |
| 2932 |
preamble={\usetikzlibrary{datavisualization}}, |
| 2933 |
pre={\tikzdatavisualizationset{ |
| 2934 |
our system/.style={ |
| 2935 |
new Cartesian axis=x axis, |
| 2936 |
new Cartesian axis=left axis, |
| 2937 |
new Cartesian axis=right axis, |
| 2938 |
x axis={attribute=x}, |
| 2939 |
left axis={unit vector={(0cm,1pt)}}, |
| 2940 |
right axis={unit vector={(0cm,1pt)}}, |
| 2941 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 2942 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 2943 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} |
| 2944 |
} |
| 2945 |
}}] |
| 2946 |
\tikzset{ |
| 2947 |
data visualization/our system/.append style={ |
| 2948 |
x axis= {visualize axis={left axis={goto pos=0.25}}, |
| 2949 |
visualize axis={left axis={goto pos=0.5}}}, |
| 2950 |
} |
| 2951 |
} |
| 2952 |
\tikz \datavisualization [ |
| 2953 |
our system, |
| 2954 |
x axis={attribute=time, length=4cm}, |
| 2955 |
left axis ={attribute=money}, |
| 2956 |
right axis={attribute=people}, |
| 2957 |
visualize as line/.list={people 1, people 2, money 1, money 2}] |
| 2958 |
data group {people and money}; |
| 2959 |
\end{codeexample} |
| 2960 |
\end{key} |
| 2961 |
|
| 2962 |
By default, when an axis is visualized, it spans the set of all possible |
| 2963 |
values for the monitored attribute, that is, from |min| to |max|. However, |
| 2964 |
there are actually two keys that allow you to adjust this: |
| 2965 |
% |
| 2966 |
\begin{key}{/tikz/data visualization/low=\meta{value}} |
| 2967 |
This is the attribute value where the axis visualization starts. The |
| 2968 |
same special values as for |goto| are permissible (like |min| or |
| 2969 |
|padded min|, but also |0| or |1|). |
| 2970 |
\end{key} |
| 2971 |
% |
| 2972 |
\begin{key}{/tikz/data visualization/high=\meta{value}} |
| 2973 |
Like |low|, only for where the axis ends. |
| 2974 |
\end{key} |
| 2975 |
|
| 2976 |
By default, |low=min| and |high=max| are set for an axis visualization. |
| 2977 |
Another sensible setting is |low=padded min| and |high=padded max|. The |
| 2978 |
following key provides a shorthand for this: |
| 2979 |
% |
| 2980 |
\begin{key}{/tikz/data visualization/padded} |
| 2981 |
Shorthand for |low=padded min, high=padded max|. |
| 2982 |
\end{key} |
| 2983 |
% |
| 2984 |
As an example, consider the |scientific axes=clean|. Here, each axis is |
| 2985 |
actually drawn three times: Once at the minimum, once at the maximum and |
| 2986 |
then once more at the padded minimum. |
| 2987 |
|
| 2988 |
|
| 2989 |
\medskip |
| 2990 |
\textbf{The axis line.} |
| 2991 |
When an axis is drawn, \tikzname\ does not simply draw a straight line from |
| 2992 |
the |low| position to the |high| position. In reality, the data |
| 2993 |
visualization system uses the two commands |\pgfpathdvmoveto| and |
| 2994 |
|\pgfpathdvlineto| internally. These will replace the straight line by a |
| 2995 |
curve in certain situations. For instance, in a polar coordinate system, if |
| 2996 |
an axis should be drawn along an angle axis for a fixed radius, an arc will |
| 2997 |
be used instead of a straight line. |
| 2998 |
|
| 2999 |
|
| 3000 |
\medskip |
| 3001 |
\textbf{Styling the axis.} |
| 3002 |
As can be seen, we now get the axis we want (but without the ticks, |
| 3003 |
visualizing them will be explained later). The axis is, however, simply a |
| 3004 |
black line. We can \emph{style} the axis in a manner similar to styling |
| 3005 |
ticks and grid lines, see Section~\ref{section-dv-style}. In detail, the |
| 3006 |
following styles get executed: |
| 3007 |
% |
| 3008 |
\begin{enumerate} |
| 3009 |
\item |axis layer| |
| 3010 |
\item |every axis| |
| 3011 |
\item |styling| |
| 3012 |
\end{enumerate} |
| 3013 |
% |
| 3014 |
Additionally, even before |every axis| is executed, |low=min| and |
| 3015 |
|high=max| are executed. |
| 3016 |
|
| 3017 |
\begin{stylekey}{/tikz/data visualization/axis layer (initially on background layer)} |
| 3018 |
The layer on which the axis is drawn. See the description of |
| 3019 |
|grid layer| on page~\pageref{section-dv-grid-layer} for details. |
| 3020 |
\end{stylekey} |
| 3021 |
|
| 3022 |
\begin{stylekey}{/tikz/data visualization/every axis} |
| 3023 |
Put styling of the axis here. It is usually a good idea to set this |
| 3024 |
style to |style={black!50}|. |
| 3025 |
\end{stylekey} |
| 3026 |
|
| 3027 |
Recall that the |styling| key is set using the |style| key, see |
| 3028 |
Section~\ref{section-dv-style}. |
| 3029 |
% |
| 3030 |
% TODOsp: codeexamples: What is this empty `\tikzset` good for? |
| 3031 |
\tikzset{ |
| 3032 |
} |
| 3033 |
\begin{codeexample}[ |
| 3034 |
preamble={\usetikzlibrary{datavisualization}}, |
| 3035 |
pre={\tikzdatavisualizationset{ |
| 3036 |
our system/.style={ |
| 3037 |
new Cartesian axis=x axis, |
| 3038 |
new Cartesian axis=left axis, |
| 3039 |
new Cartesian axis=right axis, |
| 3040 |
x axis={attribute=x}, |
| 3041 |
left axis={unit vector={(0cm,1pt)}}, |
| 3042 |
right axis={unit vector={(0cm,1pt)}}, |
| 3043 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 3044 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 3045 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} |
| 3046 |
} |
| 3047 |
}}] |
| 3048 |
\tikzset{ |
| 3049 |
data visualization/our system/.append style={ |
| 3050 |
every axis/.style={style=black!50}, % make this the default |
| 3051 |
left axis= {visualize axis={x axis= {goto=min}, style=red!75}}, |
| 3052 |
right axis={visualize axis={x axis= {goto=max}, style=blue!75}}, |
| 3053 |
x axis= {visualize axis={left axis={goto=min}}, |
| 3054 |
visualize axis={left axis={goto=max}}}, |
| 3055 |
} |
| 3056 |
} |
| 3057 |
\tikz \datavisualization [ |
| 3058 |
our system, |
| 3059 |
x axis={attribute=time, length=4cm}, |
| 3060 |
left axis ={attribute=money}, |
| 3061 |
right axis={attribute=people}, |
| 3062 |
visualize as line/.list={people 1, people 2, money 1, money 2}] |
| 3063 |
data group {people and money}; |
| 3064 |
\end{codeexample} |
| 3065 |
\tikzset{ |
| 3066 |
data visualization/our system/.append style={ |
| 3067 |
every axis/.style={style=black!50}, % make this the default |
| 3068 |
left axis= {visualize axis={x axis= {goto=min}, style=red!75}}, |
| 3069 |
right axis={visualize axis={x axis= {goto=max}, style=blue!75}}, |
| 3070 |
x axis= {visualize axis={left axis={goto=min}}, |
| 3071 |
visualize axis={left axis={goto=max}}}, |
| 3072 |
} |
| 3073 |
} |
| 3074 |
|
| 3075 |
|
| 3076 |
\medskip |
| 3077 |
\textbf{Padding the Axis.} |
| 3078 |
When an axis is visualized, it is often a good idea to make it ``a little |
| 3079 |
bit longer'' or to ``remove it a bit from the border'', because the |
| 3080 |
visualization of an axis should not interfere with the actual data. For |
| 3081 |
this reason, a \emph{padding} can be specified for axes: |
| 3082 |
|
| 3083 |
\begin{key}{/tikz/data visualization/axis options/padding min=\meta{dimension}} |
| 3084 |
This is the dimension that is used whenever |goto=padded min| is used. |
| 3085 |
The \meta{dimension} is then put into the |offset| subkey of the |
| 3086 |
attribute monitored by the axis. When a data point is transformed by a |
| 3087 |
linear transformer and when this subkey is nonzero, this offset is |
| 3088 |
added. (For an angle axis of a polar transformer, the \meta{dimension} |
| 3089 |
is interpreted as an additional angle rather than as an additional |
| 3090 |
distance). Note that \meta{dimension} should typically be negative |
| 3091 |
since ``adding the \meta{dimension}'' will then make the axis longer |
| 3092 |
(because it starts at a smaller value). The standard axis systems set |
| 3093 |
the padding to some default and take its value into account: |
| 3094 |
% |
| 3095 |
\begin{codeexample}[ |
| 3096 |
width=8cm, |
| 3097 |
preamble={\usetikzlibrary{datavisualization.formats.functions}}, |
| 3098 |
] |
| 3099 |
\begin{tikzpicture} |
| 3100 |
\datavisualization [scientific axes=clean, |
| 3101 |
x axis={padding min=-1cm}, |
| 3102 |
visualize as smooth line] |
| 3103 |
data [format=function] { |
| 3104 |
var x : interval [-3:5]; |
| 3105 |
func y = \value x * \value x; |
| 3106 |
}; |
| 3107 |
\end{tikzpicture} |
| 3108 |
\end{codeexample} |
| 3109 |
|
| 3110 |
Using padded and using the |padded| key, we can visualize our axis ``a |
| 3111 |
little removed from the actual data'': |
| 3112 |
% |
| 3113 |
\begin{codeexample}[ |
| 3114 |
preamble={\usetikzlibrary{datavisualization}}, |
| 3115 |
pre={\tikzdatavisualizationset{ |
| 3116 |
our system/.style={ |
| 3117 |
new Cartesian axis=x axis, |
| 3118 |
new Cartesian axis=left axis, |
| 3119 |
new Cartesian axis=right axis, |
| 3120 |
x axis={attribute=x}, |
| 3121 |
left axis={unit vector={(0cm,1pt)}}, |
| 3122 |
right axis={unit vector={(0cm,1pt)}}, |
| 3123 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 3124 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 3125 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} |
| 3126 |
} |
| 3127 |
}% |
| 3128 |
\tikzset{ |
| 3129 |
data visualization/our system/.append style={ |
| 3130 |
every axis/.style={style=black!50}, % make this the default |
| 3131 |
left axis= {visualize axis={x axis= {goto=min}, style=red!75}}, |
| 3132 |
right axis={visualize axis={x axis= {goto=max}, style=blue!75}}, |
| 3133 |
x axis= {visualize axis={left axis={goto=min}}, |
| 3134 |
visualize axis={left axis={goto=max}}}, |
| 3135 |
} |
| 3136 |
}}] |
| 3137 |
\tikzset{ |
| 3138 |
data visualization/our system/.append style={ |
| 3139 |
all axes= {padding=.5em}, |
| 3140 |
left axis= {visualize axis={x axis= {goto=padded min}, padded}}, |
| 3141 |
right axis={visualize axis={x axis= {goto=padded max}, padded}}, |
| 3142 |
x axis= {visualize axis={left axis={goto=padded min}, padded}, |
| 3143 |
visualize axis={left axis={goto=padded max}, padded}}, |
| 3144 |
} |
| 3145 |
} |
| 3146 |
\tikz \datavisualization [ |
| 3147 |
our system, |
| 3148 |
x axis={attribute=time, length=3cm}, |
| 3149 |
left axis ={attribute=money}, |
| 3150 |
right axis={attribute=people}, |
| 3151 |
visualize as line/.list={people 1, people 2, money 1, money 2}] |
| 3152 |
data group {people and money}; |
| 3153 |
\end{codeexample} |
| 3154 |
\end{key} |
| 3155 |
|
| 3156 |
\begin{key}{/tikz/data visualization/axis options/padding max=\meta{dimension}} |
| 3157 |
Works like |padding min|, but \meta{dimension} should typically be |
| 3158 |
positive. |
| 3159 |
\end{key} |
| 3160 |
|
| 3161 |
\begin{key}{/tikz/data visualization/axis options/padding=\meta{dimension}} |
| 3162 |
Sets both |padding min| to the negated value of \meta{dimension} and |
| 3163 |
|padding max| to \meta{dimension}. |
| 3164 |
\end{key} |
| 3165 |
\end{key} |
| 3166 |
|
| 3167 |
|
| 3168 |
\subsubsection{Visualizing Grid Lines} |
| 3169 |
\label{section-dv-visualize-gridlines} |
| 3170 |
|
| 3171 |
As explained earlier, the |grid| key is used to specify at which positions grid |
| 3172 |
lines should be drawn in principle. However, this key does not actually cause |
| 3173 |
any grid lines to be drawn. Instead, the |visualize grid| key is used by the |
| 3174 |
axis system to specify how grid lines are drawn. |
| 3175 |
|
| 3176 |
\begin{key}{/tikz/data visualization/axis options/visualize grid=\meta{options}} |
| 3177 |
This key is passed to an axis. It causes grid lines to be drawn at the |
| 3178 |
positions specified by the |grid| key for this axis. The \meta{options} |
| 3179 |
govern where and how the grid lines will be drawn. |
| 3180 |
|
| 3181 |
|
| 3182 |
\medskip |
| 3183 |
\textbf{The direction axis.} |
| 3184 |
At first sight, one might expect that the grid lines for an axis should |
| 3185 |
simply be drawn perpendicular to the axis between the minimum and maximum |
| 3186 |
value of the axis. However, things are somewhat more difficult in reality: |
| 3187 |
% |
| 3188 |
\begin{enumerate} |
| 3189 |
\item A grid line is supposed to indicate all positions where a certain |
| 3190 |
attribute attains a fixed value. But, then, a grid line does not |
| 3191 |
really need to be a grid \emph{line}. Consider for instance a three |
| 3192 |
dimensional axis system. A ``grid line'' for the $x$-coordinate |3| |
| 3193 |
would actually be a ``grid plane''. |
| 3194 |
\item For a polar coordinate system and a fixed radius, this set of |
| 3195 |
positions at a certain radius is not a straight line, but an arc. |
| 3196 |
For more complicated coordinate systems such as the one arising |
| 3197 |
from three-dimensional spherical projections, a grid line may well |
| 3198 |
be a fairly involved curve. |
| 3199 |
\end{enumerate} |
| 3200 |
% |
| 3201 |
The |visualize grid| command addresses these complications as follows: |
| 3202 |
% |
| 3203 |
\begin{enumerate} |
| 3204 |
\item A grid line is always a line, not a plane or a volume. This means |
| 3205 |
that in the example of a three dimensional axis system and the |
| 3206 |
$x$-attribute being |3|, one would have to choose whether the grid |
| 3207 |
line should go ``along'' the $y$-axis or ``along'' the $z$-axis for |
| 3208 |
this position. One can, however, call the |visualize grid| command |
| 3209 |
twice, once for each direction, to cause grid lines to be shown for |
| 3210 |
both directions. |
| 3211 |
\item A grid line is created by moving to a start position and then |
| 3212 |
doing a lineto to the target position. However, the ``moveto'' and |
| 3213 |
``lineto'' are done by calling special commands of the data |
| 3214 |
visualization system. These special commands allow coordinate |
| 3215 |
system to ``notice'' that the line is along an axis and will allow |
| 3216 |
them to replace the straight line by an appropriate curve. The |
| 3217 |
polar axes systems employ this strategy, for instance. |
| 3218 |
\end{enumerate} |
| 3219 |
|
| 3220 |
By the above discussion, in order to create a grid line for attribute $a$ |
| 3221 |
having value $v$, we need to specify an axis ``along'' which the line |
| 3222 |
should be drawn. When there are only two axes, this is usually ``the other |
| 3223 |
axis''. This ``other axis'' is specified using the following key: |
| 3224 |
% |
| 3225 |
\begin{key}{/tikz/data visualization/direction axis=\meta{axis name}} |
| 3226 |
You must pass this key as an \meta{option} each time you use |
| 3227 |
|visualize axis|. When the grid line is drawn, the attribute $a$ is set |
| 3228 |
to $v$ and the axis \meta{axis name}'s attribute is set once to the |
| 3229 |
current value of |low| and once to |high|. Then a line is drawn between |
| 3230 |
these two positions using |\pgfpathdvlineto|. |
| 3231 |
\end{key} |
| 3232 |
% |
| 3233 |
The |low| and |high| keys are the same as the ones used in the |
| 3234 |
|visualize axis| key. |
| 3235 |
% |
| 3236 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 3237 |
\tikz \datavisualization [ |
| 3238 |
xyz Cartesian cabinet, |
| 3239 |
all axes={visualize axis={low=0, style=->}}, |
| 3240 |
x axis={visualize grid={direction axis=y axis}, grid=many}, |
| 3241 |
visualize as scatter] |
| 3242 |
data { |
| 3243 |
x, y, z |
| 3244 |
0, 0, 1 |
| 3245 |
0, 1, 0 |
| 3246 |
2, 2, 2 |
| 3247 |
}; |
| 3248 |
\end{codeexample} |
| 3249 |
% |
| 3250 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 3251 |
\tikz \datavisualization [ |
| 3252 |
xyz Cartesian cabinet, |
| 3253 |
all axes={visualize axis={low=0, style=->}, grid=many}, |
| 3254 |
x axis={visualize grid={direction axis=z axis}}, |
| 3255 |
z axis={visualize grid={direction axis=x axis}, |
| 3256 |
visualize grid={direction axis=y axis},}, |
| 3257 |
visualize as scatter] |
| 3258 |
data { |
| 3259 |
x, y, z |
| 3260 |
0, 0, 1 |
| 3261 |
0, 1, 0 |
| 3262 |
2, 2, 2 |
| 3263 |
}; |
| 3264 |
\end{codeexample} |
| 3265 |
|
| 3266 |
|
| 3267 |
\medskip |
| 3268 |
\textbf{Styling the grid lines.} |
| 3269 |
When a grid line is draw, styles are applied as described in |
| 3270 |
Section~\ref{section-dv-styling-grid-lines}. |
| 3271 |
|
| 3272 |
|
| 3273 |
\medskip |
| 3274 |
\textbf{The major, minor, and subminor grid lines.} |
| 3275 |
The |grid| option allows you to specify for each kind of grid line (major, |
| 3276 |
minor, or subminor) a set of different values for which these grid lines |
| 3277 |
should be drawn. Correspondingly, it is also possible to configure for each |
| 3278 |
kind of grid line how it should be drawn. For this, the |major|, |minor|, |
| 3279 |
|subminor|, and also the |common| keys can be used inside the |
| 3280 |
\meta{options} of |visualize grid|. While as option to |grid| these keys |
| 3281 |
are used to specify |at| values, as options of |visualize grid| they are |
| 3282 |
used to configure the different kinds of grid lines. |
| 3283 |
|
| 3284 |
Most of the time, no special configuration is necessary since all styling |
| 3285 |
is best done by configuring keys like |every major grid|. You need to use a |
| 3286 |
key like |major| only if you wish to configure for instance the |low| or |
| 3287 |
|high| values of a |major| grid line differently from those of |minor| grid |
| 3288 |
lines -- are rather unlikely setting -- or when the styling should deviate |
| 3289 |
from the usual settings. |
| 3290 |
% |
| 3291 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 3292 |
\tikz \datavisualization [ |
| 3293 |
xy Cartesian, |
| 3294 |
all axes={visualize axis={low=0, style=->}, |
| 3295 |
grid={some, minor steps between steps}}, |
| 3296 |
x axis= {visualize grid={ |
| 3297 |
direction axis=y axis, |
| 3298 |
minor={low=0.25, high=1.75, style=red!50}}}, |
| 3299 |
visualize as scatter] |
| 3300 |
data { |
| 3301 |
x, y |
| 3302 |
0, 0 |
| 3303 |
3, 3 |
| 3304 |
}; |
| 3305 |
\end{codeexample} |
| 3306 |
% |
| 3307 |
\end{key} |
| 3308 |
|
| 3309 |
Returning to the example of |our system| with the two axis systems, it is |
| 3310 |
straight-forward to configure the grid lines of the $x$-axis: The direction |
| 3311 |
axis is either of the other two axis (they point in the same direction and they |
| 3312 |
have the same range). For the other two axes, we visualize one grid |
| 3313 |
independently of the other, using different colors. |
| 3314 |
% |
| 3315 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 3316 |
\tikzset{ |
| 3317 |
data visualization/our system/.append style={ |
| 3318 |
x axis= {visualize grid={direction axis=left axis}}, |
| 3319 |
left axis= {visualize grid={direction axis=x axis, |
| 3320 |
common={style=red!50}}}, |
| 3321 |
right axis={visualize grid={direction axis=x axis, |
| 3322 |
common={style=blue!50}}}, |
| 3323 |
} |
| 3324 |
} |
| 3325 |
\tikz \datavisualization [ |
| 3326 |
our system, |
| 3327 |
x axis={attribute=time, length=3cm, grid=many}, |
| 3328 |
left axis ={attribute=money, grid=some}, |
| 3329 |
right axis={attribute=people, grid=few}, |
| 3330 |
visualize as line/.list={people 1, people 2, money 1, money 2}] |
| 3331 |
data group {people and money}; |
| 3332 |
\end{codeexample} |
| 3333 |
|
| 3334 |
|
| 3335 |
\subsubsection{Visualizing the Ticks and Tick Labels} |
| 3336 |
\label{section-dv-visualize-ticks} |
| 3337 |
|
| 3338 |
\begin{key}{/tikz/data visualization/axis options/visualize ticks=\meta{options}} |
| 3339 |
Visualizing a tick involves (possibly) drawing a tick mark and adding |
| 3340 |
(possibly) the tick node. The process is similar to |visualize grid|: Users |
| 3341 |
use the |ticks| key to configure how many ticks they would like for an axis |
| 3342 |
and at which positions. The axis system uses the |visualize ticks| key to |
| 3343 |
specify where these ticks should actually be shown. |
| 3344 |
|
| 3345 |
Unlike grid lines, which are typically only visualized once for each |
| 3346 |
combination of an axis and a direction axis, tick marks might be visualized |
| 3347 |
at different places for the same axis. Consider for instance the |
| 3348 |
|scientific axes|: |
| 3349 |
% |
| 3350 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 3351 |
\tikz \datavisualization [scientific axes, all axes={length=3cm}, |
| 3352 |
x axis={ticks={stack}}, |
| 3353 |
visualize as smooth line] |
| 3354 |
data [format=function] { |
| 3355 |
var x : interval [0:2]; |
| 3356 |
func y = \value x*\value x; |
| 3357 |
}; |
| 3358 |
\end{codeexample} |
| 3359 |
% |
| 3360 |
Have a look at the ticks on the $y$-axis: There are ticks at values |0|, |
| 3361 |
|1|, |2|, |3|, and~|4|. These are visualized both at the left side (where |
| 3362 |
the tick nodes are also shown) and additionally also at the right side, but |
| 3363 |
only as small marks. Similarly, the ticks on the $x$-axis appear at the |
| 3364 |
bottom, but also (in much simpler versions) at the top. Both for the |
| 3365 |
$x$-axis and for the $y$-axis the |visualize ticks| key was called twice. |
| 3366 |
|
| 3367 |
|
| 3368 |
\medskip |
| 3369 |
\textbf{The tick marks.} |
| 3370 |
Drawing a tick mark is quite similar to visualizing a grid line; indeed a |
| 3371 |
tick mark can be thought of as a ``mini grid line'': Just like a grid line |
| 3372 |
it ``points a long an axis''. However, a tick will always be a short |
| 3373 |
straight line -- even when the coordinate system is actually twisted |
| 3374 |
(experimentation has shown that ticks that follow the curvature of the |
| 3375 |
coordinate system like grid lines are hard to recognize). For this reason, |
| 3376 |
the |low| and |high| keys have a different meaning from the one used with |
| 3377 |
the |visualize grid| key. In detail to configure the size and position of a |
| 3378 |
tick mark for the value $v$ of attribute $a$, proceed as follows: |
| 3379 |
% |
| 3380 |
\begin{itemize} |
| 3381 |
\item The |visualize ticks| key will have setup attribute $a$ to be |
| 3382 |
equal to $v$. |
| 3383 |
\item You should now use the |goto| or |goto pos| key together with all |
| 3384 |
\emph{other} axes to configure at which position with respect to |
| 3385 |
these other options the tick mark should be shown. For instance, |
| 3386 |
suppose we want tick marks in |our system| for the $x$-axis at the |
| 3387 |
bottom and at the top. This corresponds to once setting the |
| 3388 |
|left axis| to its minimal value and once to its maximal value: |
| 3389 |
% |
| 3390 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 3391 |
\tikzset{ |
| 3392 |
data visualization/our system/.append style={ |
| 3393 |
x axis={visualize ticks={direction axis=left axis, left axis={goto=min}}, |
| 3394 |
visualize ticks={direction axis=left axis, left axis={goto=max}}, |
| 3395 |
} |
| 3396 |
} |
| 3397 |
} |
| 3398 |
\tikz \datavisualization [ |
| 3399 |
our system, |
| 3400 |
x axis={attribute=time, length=3cm, ticks=many}, |
| 3401 |
left axis ={attribute=money}, |
| 3402 |
right axis={attribute=people}, |
| 3403 |
visualize as line/.list={people 1, people 2, money 1, money 2}] |
| 3404 |
data group {people and money}; |
| 3405 |
\end{codeexample} |
| 3406 |
% |
| 3407 |
\item In the above example, we may wish to shorten the ticks a bit at |
| 3408 |
the bottom and at the top. For this, we use the |low| and |high| |
| 3409 |
key: |
| 3410 |
% |
| 3411 |
\begin{key}{/tikz/data visualization/low=\meta{dimension}} |
| 3412 |
When used with the |visualize ticks| option, the |low| key |
| 3413 |
contains a dimension that specifies the extend of the tick |
| 3414 |
going ``toward the minimum'' of the direction axis. More |
| 3415 |
precisely, when a tick mark is visualized, a unit tangent |
| 3416 |
vector at the current data point in the direction of the |
| 3417 |
|direction axis| is computed and this vector is multiplied by |
| 3418 |
\meta{dimension} to compute the start position of the tick |
| 3419 |
line. The end position is given by this vector times the |high| |
| 3420 |
value. |
| 3421 |
|
| 3422 |
Note that the \meta{dimension} should usually be negative for |
| 3423 |
the |low| key and positive for the |high| key. |
| 3424 |
|
| 3425 |
For tick marks where a tick label node is shown, the |
| 3426 |
\meta{dimension} is increased by the current values of keys |
| 3427 |
like |tick text even low padding|, see |
| 3428 |
Section~\ref{section-dv-stacking} for details. |
| 3429 |
\end{key} |
| 3430 |
% |
| 3431 |
\begin{key}{/tikz/data visualization/high=\meta{dimension}} |
| 3432 |
Like |low|. |
| 3433 |
\end{key} |
| 3434 |
% |
| 3435 |
\begin{key}{/tikz/data visualization/tick length=\meta{dimension}} |
| 3436 |
Shorthand for |low=-|\meta{dimension}|, high=|\meta{dimension}. |
| 3437 |
\end{key} |
| 3438 |
|
| 3439 |
What we want to happen is that in the upper visualization of the |
| 3440 |
ticks the |low| value is |0pt|, while in the lower one the |high| |
| 3441 |
value is |0pt|: |
| 3442 |
% |
| 3443 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 3444 |
\tikzset{ |
| 3445 |
data visualization/our system/.append style={ |
| 3446 |
x axis={ |
| 3447 |
visualize ticks={direction axis=left axis,high=0pt,left axis={goto=min}}, |
| 3448 |
visualize ticks={direction axis=left axis,low=0pt,left axis={goto=max}}, |
| 3449 |
} |
| 3450 |
} |
| 3451 |
} |
| 3452 |
\tikz \datavisualization [ |
| 3453 |
our system, |
| 3454 |
x axis={attribute=time, length=3cm, ticks=many}, |
| 3455 |
left axis ={attribute=money}, |
| 3456 |
right axis={attribute=people}, |
| 3457 |
visualize as line/.list={people 1, people 2, money 1, money 2}] |
| 3458 |
data group {people and money}; |
| 3459 |
\end{codeexample} |
| 3460 |
% |
| 3461 |
\end{itemize} |
| 3462 |
% |
| 3463 |
In order to style the tick mark, use the styling mechanism that is detailed |
| 3464 |
in Section~\ref{section-dv-styling-ticks}. |
| 3465 |
|
| 3466 |
|
| 3467 |
\medskip |
| 3468 |
\textbf{The tick label node.} |
| 3469 |
At certain tick positions, we may wish to add a node indicating the value |
| 3470 |
of the attribute at the given position. The |visualize ticks| command has |
| 3471 |
no influence over which text should be shown at a node -- the text is |
| 3472 |
specified and typeset as explained in Section~\ref{section-dv-tick-labels}. |
| 3473 |
|
| 3474 |
Each time |visualize ticks|, for each tick position up to two tick label |
| 3475 |
nodes will be created: One at the |low| position and one at the |high| |
| 3476 |
position. The following keys are used to configure which of these cases |
| 3477 |
happen: |
| 3478 |
% |
| 3479 |
\begin{key}{/tikz/data visualization/tick text at low=\opt{\meta{true or false}} (default true)} |
| 3480 |
Pass this option to |visualize ticks| when you want tick label nodes to |
| 3481 |
be placed at the |low| position of each tick mark. |
| 3482 |
% |
| 3483 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}] |
| 3484 |
\tikzset{ |
| 3485 |
data visualization/our system/.append style={ |
| 3486 |
x axis={ |
| 3487 |
visualize ticks={direction axis=left axis, left axis={goto=min}, |
| 3488 |
high=0pt, tick text at low, stack}, |
| 3489 |
visualize ticks={direction axis=left axis, left axis={goto=max}, |
| 3490 |
low=0pt, tick text at high, stack} |
| 3491 |
} |
| 3492 |
} |
| 3493 |
} |
| 3494 |
\tikz \datavisualization [ |
| 3495 |
our system, |
| 3496 |
x axis={attribute=time, length=3cm, ticks=some}, |
| 3497 |
left axis ={attribute=money}, |
| 3498 |
right axis={attribute=people}, |
| 3499 |
visualize as line/.list={people 1, people 2, money 1, money 2}] |
| 3500 |
data group {people and money}; |
| 3501 |
\end{codeexample} |
| 3502 |
\end{key} |
| 3503 |
% |
| 3504 |
\begin{key}{/tikz/data visualization/tick text at high=\opt{\meta{true or false}} (default true)} |
| 3505 |
Like |tick text at low|. |
| 3506 |
\end{key} |
| 3507 |
|
| 3508 |
\begin{key}{/tikz/data visualization/no tick text} |
| 3509 |
Shorthand for |tick text at low=false, tick text at high=false|. |
| 3510 |
% |
| 3511 |
\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}] |
| 3512 |
\tikz \datavisualization [scientific axes, all axes={length=3cm}, |
| 3513 |
x axis={ticks={ |
| 3514 |
major also at={6.5 as [no tick text]}}}, |
| 3515 |
visualize as smooth line] |
| 3516 |
data [format=function] { |
| 3517 |
var x : interval [5:10]; |
| 3518 |
func y = \value x * \value x; |
| 3519 |
}; |
| 3520 |
\end{codeexample} |
| 3521 |
\end{key} |
| 3522 |
|
| 3523 |
When a tick label node is to be placed at the low or the high position, the |
| 3524 |
next step is to determine the exact position and the correct anchor of the |
| 3525 |
node. This is done as follows: |
| 3526 |
% |
| 3527 |
\begin{itemize} |
| 3528 |
\item In order to compute an appropriate |anchor|, the tick mark is |
| 3529 |
considered: This is a short line pointing in a certain direction. |
| 3530 |
For a tick label node at the |low| position, the |anchor| attribute |
| 3531 |
is setup in such a way that the node label will be below the |low| |
| 3532 |
position when the tick mark direction points up, it will be to the |
| 3533 |
right when the direction points left, above when it points down, |
| 3534 |
and so on also for diagonal directions. Similarly, for the |high| |
| 3535 |
position, when the direction points up, the node will be placed |
| 3536 |
above the tick mark and so on. |
| 3537 |
|
| 3538 |
This computation is done automatically. |
| 3539 |
\item The tick label node is styled. The styles that are applied are |
| 3540 |
described in Section~\ref{section-dv-styling-ticks}. |
| 3541 |
\item A tick label node for the |low| position is usually anchored at |
| 3542 |
this |low| position, but an additional padding will be added as |
| 3543 |
described in Section~\ref{section-dv-stacking}. |
| 3544 |
\end{itemize} |
| 3545 |
\end{key} |
| 3546 |
|
| 3547 |
|
| 3548 |
\subsubsection{Visualizing the Axis Labels} |
| 3549 |
\label{section-dv-visualize-label} |
| 3550 |
|
| 3551 |
The |label| option can be used with an axis to specify a text should be shown |
| 3552 |
next to the axis to indicates which attribute this axis refers to. Like |ticks| |
| 3553 |
or |grid|, the |label| option does not actually draw the label, this is the job |
| 3554 |
of the |visualize label| key, which is configured by the axis system. |
| 3555 |
|
| 3556 |
\begin{key}{/tikz/data visualization/axis options/visualize label=\meta{options}} |
| 3557 |
The \meta{options} should be used to configure a ``good place'' for the |
| 3558 |
axis label. Usually, you will use the |goto| or the |goto pos| key. |
| 3559 |
|
| 3560 |
For the example of |our system|, we would like the label of the |x axis| to |
| 3561 |
be placed below at the middle of the axis, so we use |goto pos=.5| to |
| 3562 |
determine this position. Concerning the other axes, we want it to be placed |
| 3563 |
at the minimum position of the |left axis| with a lot of padding. |
| 3564 |
% |
| 3565 |
\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}] |
| 3566 |
\tikzdatavisualizationset{ |
| 3567 |
our system/.append style={ |
| 3568 |
x axis={visualize label={ |
| 3569 |
x axis={goto pos=.5}, |
| 3570 |
left axis={padding=1.5em, goto=padded min}}} |
| 3571 |
} |
| 3572 |
} |
| 3573 |
\tikz \datavisualization [ |
| 3574 |
our system, |
| 3575 |
x axis={attribute=time, ticks=some, label}, |
| 3576 |
left axis ={attribute=money}, |
| 3577 |
right axis={attribute=people}, |
| 3578 |
visualize as line/.list={ |
| 3579 |
people 1, people 2, money 1, money 2}] |
| 3580 |
data group {people and money}; |
| 3581 |
\end{codeexample} |
| 3582 |
|
| 3583 |
In the above example, the |padding| of |1.5em| was rather arbitrary and |
| 3584 |
``suboptimal''. It would be outright wrong if the labels on the |x axis| |
| 3585 |
were larger or if they were missing. It would be better if the vertical |
| 3586 |
position of the |x axis| label were always ``below'' all other options. For |
| 3587 |
such cases a slightly strange approach is useful: You position the node |
| 3588 |
using |node style={at=...}| where |at| is now the normal \tikzname\ option |
| 3589 |
that is used to specify the position of a node. Inside the |...|, you |
| 3590 |
specify that the horizontal position should be the bottom of |
| 3591 |
up-to-now-constructed data visualization and the vertical position should |
| 3592 |
be at the ``origin'', which is, however, the position computed by the |
| 3593 |
|goto| keys for the axes: |
| 3594 |
% |
| 3595 |
\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}] |
| 3596 |
\tikzdatavisualizationset{ |
| 3597 |
our system/.append style={ |
| 3598 |
x axis={visualize label={ |
| 3599 |
x axis={goto pos=.5}, |
| 3600 |
node style={ |
| 3601 |
at={(0,0 |- data visualization bounding box.south)}, |
| 3602 |
below |
| 3603 |
} } } } } |
| 3604 |
\tikz \datavisualization [ |
| 3605 |
our system, |
| 3606 |
x axis={attribute=time, ticks=some, label=Year}, |
| 3607 |
left axis ={attribute=money}, |
| 3608 |
right axis={attribute=people}, |
| 3609 |
visualize as line/.list={ |
| 3610 |
people 1, people 2, money 1, money 2}] |
| 3611 |
data group {people and money}; |
| 3612 |
\end{codeexample} |
| 3613 |
|
| 3614 |
Two additional keys are useful for positioning axis labels: |
| 3615 |
% |
| 3616 |
\begin{key}{/tikz/data visualization/axis option/anchor at min} |
| 3617 |
When passed to an axis, this key sets the |anchor| so that a node |
| 3618 |
positioned at either the |min| or the |padded min| value of the axis |
| 3619 |
will be placed ``nicely'' with respect to the axis. For instance, if |
| 3620 |
the axis points upwards from the |min| value to the |max| value, the |
| 3621 |
|anchor| would be set to |north| since this gives a label below the |
| 3622 |
axis's start. Similarly, if the axis points right, the anchor would be |
| 3623 |
set to |east|, and so on. |
| 3624 |
\end{key} |
| 3625 |
% |
| 3626 |
\begin{key}{/tikz/data visualization/axis option/anchor at max} |
| 3627 |
Like |anchor at min|. |
| 3628 |
\end{key} |
| 3629 |
\end{key} |
| 3630 |
|
| 3631 |
|
| 3632 |
\subsubsection{The Complete Axis System} |
| 3633 |
|
| 3634 |
Here is the code for the complete axis system developed above and an example of |
| 3635 |
how it is used: |
| 3636 |
% |
| 3637 |
\begin{codeexample}[code only] |
| 3638 |
\tikzdatavisualizationset{ our system/.style={ |
| 3639 |
% The axes |
| 3640 |
new Cartesian axis=x axis, new Cartesian axis=left axis, new Cartesian axis=right axis, |
| 3641 |
% The directions of the axes |
| 3642 |
all axes={padding=.5em}, left axis={unit vector={(0cm,1pt)}}, right axis={unit vector={(0cm,1pt)}}, |
| 3643 |
% The default attributes, other attributes must be configured |
| 3644 |
x axis={attribute=x}, |
| 3645 |
% The lengths of the axes |
| 3646 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 3647 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 3648 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 3649 |
% The styling of the axes |
| 3650 |
every axis/.style={style=black!50}, % make this the default |
| 3651 |
% Visualizing the axes themselves |
| 3652 |
left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}}, |
| 3653 |
right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}}, |
| 3654 |
x axis= {visualize axis={left axis={goto=padded min}, padded}, |
| 3655 |
visualize axis={left axis={goto=padded max}, padded}}, |
| 3656 |
% Visualizing the grid, when requested |
| 3657 |
x axis= {visualize grid={direction axis=left axis}}, |
| 3658 |
left axis= {visualize grid={direction axis=x axis, common={style=red!50}}}, |
| 3659 |
right axis={visualize grid={direction axis=x axis, common={style=blue!50}}}, |
| 3660 |
% Visualizing the ticks, when requested |
| 3661 |
left axis={visualize ticks={style={red!50!black}, direction axis=x axis, |
| 3662 |
x axis={goto=padded min}, high=0pt, tick text at low}}, |
| 3663 |
right axis={visualize ticks={style={blue!80!black}, direction axis=x axis, |
| 3664 |
x axis={goto=padded max}, low=0pt, tick text at high}}, |
| 3665 |
x axis={visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt, |
| 3666 |
tick text at low}, |
| 3667 |
visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt}}, |
| 3668 |
% By default, there are ticks on all axes |
| 3669 |
all axes={ticks}, |
| 3670 |
% Visualizing the axis labels, when requested |
| 3671 |
x axis={visualize label={x axis={goto pos=.5}, node style={ |
| 3672 |
at={(0,0 |- data visualization bounding box.south)}, below}}}, |
| 3673 |
left axis={visualize label={left axis={goto pos=.5}, node style={ |
| 3674 |
at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}}, |
| 3675 |
right axis={visualize label={right axis={goto pos=.5}, node style={ |
| 3676 |
at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}}, |
| 3677 |
}} |
| 3678 |
\end{codeexample} |
| 3679 |
|
| 3680 |
\begin{codeexample}[ |
| 3681 |
preamble={\usetikzlibrary{datavisualization}}, |
| 3682 |
pre={\tikzdatavisualizationset{ |
| 3683 |
our system/.style={ |
| 3684 |
% The axes |
| 3685 |
new Cartesian axis=x axis, |
| 3686 |
new Cartesian axis=left axis, |
| 3687 |
new Cartesian axis=right axis, |
| 3688 |
% The default attributes, other attributes must be configured |
| 3689 |
x axis={attribute=x}, |
| 3690 |
% The directions of the axes |
| 3691 |
all axes={padding=.5em}, |
| 3692 |
left axis={unit vector={(0cm,1pt)}}, |
| 3693 |
right axis={unit vector={(0cm,1pt)}}, |
| 3694 |
% The lengths of the axes |
| 3695 |
x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, |
| 3696 |
left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 3697 |
right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, |
| 3698 |
% The styling of the axes |
| 3699 |
every axis/.style={style=black!50}, % make this the default |
| 3700 |
% Visualizing the axes themselves |
| 3701 |
left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}}, |
| 3702 |
right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}}, |
| 3703 |
x axis= {visualize axis={left axis={goto=padded min}, padded}, |
| 3704 |
visualize axis={left axis={goto=padded max}, padded}}, |
| 3705 |
% Visualizing the grid, when requested |
| 3706 |
x axis= {visualize grid={direction axis=left axis, padded}}, |
| 3707 |
left axis= {visualize grid={direction axis=x axis, padded, common={style=red!50}}}, |
| 3708 |
right axis={visualize grid={direction axis=x axis, padded, common={style=blue!50}}}, |
| 3709 |
% Visualizing the ticks, when requested |
| 3710 |
left axis={ |
| 3711 |
visualize ticks={style={red!50!black}, direction axis=x axis, x axis={goto=padded min}, high=0pt, tick text at low}}, |
| 3712 |
right axis={ |
| 3713 |
visualize ticks={style={blue!80!black}, direction axis=x axis, x axis={goto=padded max}, low=0pt, tick text at high}}, |
| 3714 |
x axis={ |
| 3715 |
visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt, tick text at low}, |
| 3716 |
visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt} |
| 3717 |
}, |
| 3718 |
% By default, there are ticks on all axes |
| 3719 |
all axes={ticks}, |
| 3720 |
% Visualizing the axis labels, when requested |
| 3721 |
x axis={visualize label={ |
| 3722 |
x axis={goto pos=.5}, node style={at={(0,0 |- data visualization bounding box.south)}, below}}}, |
| 3723 |
left axis={visualize label={ |
| 3724 |
left axis={goto pos=.5}, node style={ |
| 3725 |
at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}}, |
| 3726 |
right axis={visualize label={ |
| 3727 |
right axis={goto pos=.5}, node style={ |
| 3728 |
at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}}, |
| 3729 |
} |
| 3730 |
}}] |
| 3731 |
\tikz \datavisualization [ |
| 3732 |
our system, |
| 3733 |
x axis={attribute=time, label=Year, |
| 3734 |
ticks={tick text padding=2pt, style={/pgf/number format/set thousands separator=}}}, |
| 3735 |
left axis={attribute=money, label=Spending, |
| 3736 |
padding min=0, include value=0, grid, |
| 3737 |
ticks={tick prefix=\$, style={/pgf/number format/fixed, |
| 3738 |
/pgf/number format/fixed zerofill, /pgf/number format/precision=2}}}, |
| 3739 |
right axis={attribute=people, |
| 3740 |
label=Population, |
| 3741 |
padding min=0, include value=0, |
| 3742 |
ticks={style=/pgf/number format/fixed}}, |
| 3743 |
visualize as line/.list={ |
| 3744 |
people 1, people 2, money 1, money 2}, |
| 3745 |
people 1={style={visualizer color=blue}}, |
| 3746 |
people 2={style={visualizer color=blue!50}}, |
| 3747 |
money 1={style={visualizer color=red}}, |
| 3748 |
money 2={style={visualizer color=red!50}} ] |
| 3749 |
data group {people and money}; |
| 3750 |
\end{codeexample} |
| 3751 |
|
| 3752 |
|
| 3753 |
\subsubsection{Using the New Axis System Key} |
| 3754 |
|
| 3755 |
The axis system |our system| that we developed in the course of the previous |
| 3756 |
section is not yet ``configurable''. The only configuration that was possible |
| 3757 |
was to ``misuse'' the |width| and |height| keys of the |scientific axes|. |
| 3758 |
|
| 3759 |
In order to make |our system| configurable so that we can say |
| 3760 |
|our system=|\meta{options}, where \meta{options} are executed with the path |
| 3761 |
prefix |
| 3762 |
% |
| 3763 |
\begin{codeexample}[code only] |
| 3764 |
/tikz/data visualization/our system |
| 3765 |
\end{codeexample} |
| 3766 |
% |
| 3767 |
we can use the following key: |
| 3768 |
|
| 3769 |
\begin{key}{/tikz/data visualization/new axis system=\marg{axis system |
| 3770 |
name}\marg{axis setup}\marg{default options}\\ \marg{application |
| 3771 |
options}% |
| 3772 |
} |
| 3773 |
The |new axis system| key takes four parameters. The first one, |
| 3774 |
\meta{system name}, is the name of the to-be-created axis system, |
| 3775 |
|our system| in our case. The |new axis system| will create the following |
| 3776 |
new key: |
| 3777 |
% |
| 3778 |
\begin{key}{/tikz/data visualization/\meta{axis system name}=\opt{\meta{options}}} |
| 3779 |
When the key \meta{axis system name} is used, the following keys will be |
| 3780 |
executed in the following order: |
| 3781 |
% |
| 3782 |
\begin{enumerate} |
| 3783 |
\item The \meta{axis setup} with the path prefix |
| 3784 |
|/tikz/data visualization/|. |
| 3785 |
\item The \meta{default options} with the same path prefix. |
| 3786 |
\item The following style: |
| 3787 |
% |
| 3788 |
\begin{stylekey}{/tikz/data visualization/every \meta{axis system name}} |
| 3789 |
Even though this style has the path prefix |
| 3790 |
|/tikz/data visualization| itself, the keys stored in this |
| 3791 |
style will be executed with the path prefix |
| 3792 |
|/tikz/data visualization/|\meta{axis system name}. |
| 3793 |
\end{stylekey} |
| 3794 |
\item The \meta{options} with the path prefix |
| 3795 |
|/tikz/data visualization/|\meta{axis system name}. |
| 3796 |
\item The \meta{application options} with the path prefix |
| 3797 |
|/tikz/data visualization/| |
| 3798 |
\end{enumerate} |
| 3799 |
\end{key} |
| 3800 |
|
| 3801 |
Let us now have a look at what all of this means. First, the \meta{axis |
| 3802 |
setup} will contain all options that setup the axis system in all ways that |
| 3803 |
need not be configured. For instance, the \meta{axis setup} for the |
| 3804 |
|scientific axes| will create an |x axis| and also a |y axis| (because |
| 3805 |
these are always present), but will not setup the label visualization |
| 3806 |
(because this can be configured in different ways). For |our system|, which |
| 3807 |
cannot be configured at all, we would place all of our configuration in the |
| 3808 |
\meta{axis setup}. |
| 3809 |
|
| 3810 |
The \meta{default options} can be used to pick default values that would |
| 3811 |
usually be passed to the \meta{options} of the newly created axis system. |
| 3812 |
For instance, for |scientific axis|, the \meta{default options} are set to |
| 3813 |
|outer ticks,standard labels|, because these are the defaults. |
| 3814 |
|
| 3815 |
Finally, the \meta{application options} can be used to actually apply the |
| 3816 |
configuration that has been chosen by the \meta{options}. The idea is that |
| 3817 |
\meta{default options}, \meta{options}, and also |every| \meta{axis system |
| 3818 |
name} all have a chance of changing, re-changing and re-setting all sorts |
| 3819 |
of styles and keys. Then, with the last change ``winning'', the resulting |
| 3820 |
setting of a style can be executed, which may then cause a label |
| 3821 |
visualization to be installed. |
| 3822 |
\end{key} |