1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
\subsection{Symbolic Coordinates and User Transformations}
\label{pgfplots:sec:symbolic:coords}
\PGFPlots\ supports user transformations which can be applied to input and output coordinates. Suppose the plot shall display days versus account statements over time. Then, one wants to visualize date versus credit balance. But: dates need to be transformed to numbers before doing so! Furthermore, tick labels shall be displayed as dates as well. This, and more general transformations, can be realized using the |x coord trafo| and |y coord trafo| keys.
\paragraph{Remark:} This section applies to users who want to have non-standard input \emph{coordinates}. If you have normal numbers which don't need to be transformed and you like to have special symbols as tick labels, you should consider using the |xticklabels| (|yticklabels|) key described on page~\pageref{pgfplots:key:xticklabels}.
\begin{pgfplotsxycodekeylist}{
\x\ coord trafo,
\x\ coord inv trafo}
These code keys allow arbitrary coordinate transformations which are applied to input coordinates and output tick labels.
The |x coord trafo| and |y coord trafo| command keys take one argument which is the input coordinate. They are expected to set |\pgfmathresult| to the final value.
At this level, the input coordinate is provided as it is found in the |\addplot| statement. For example, if $x$ coordinates are actually of the form \meta{year}-\meta{month}-\meta{day}, for example |2008-01-05|, then a useful coordinate transformation would transform this string into a number (see below for a predefined realization).
In short, \emph{no} numerics has been applied to input coordinates when this transformation is applied\footnote{Of course, if coordinates have been generated by gnuplot or \pgfname, this does no longer hold.}.
The input coordinate transformation is applied to
\begin{itemize}
\item any input coordinates (specified with |\addplot| or |axis cs|),
\item any user-specified |xtick| or |ytick| options,
\item any user-specified |extra x ticks| and |extra y ticks| options,
\item any user-specified axis limits like |xmin| and |xmax|.
\end{itemize}
The output coordinate transformation |x coord inv trafo| is applied to tick positions just before evaluating the |xticklabel| and |yticklabel| keys. The argument to |x coord inv trafo| is a fixed point number (which may have trailing zeros after the period).
The tick label code may use additional macros defined by the inverse transformation.
Remark: \PGFPlots\ will continue to produce tick positions as usual, no extra magic is applied. It may be necessary to provide tick positions explicitly if the default doesn't respect the coordinate space properly.
The initial value of these keys is
\begin{codeexample}[code only]
\pgfplotsset{
x coord trafo/.code={},
x coord inv trafo/.code={}}
\end{codeexample}
\noindent which simply disables the transformation (the same for $y$, of course).
\paragraph{Remark:} It might be necessary to set
\begin{codeexample}[code only]
\pgfplotsset{
xticklabel={\tick},
scaled x ticks=false,
plot coordinates/math parser=false,
}
\end{codeexample}
\noindent in order to avoid number formatting routines on |\tick| or numerics for tick scale methods. This is done automatically by the predefined symbolic coordinate styles (see below).
\end{pgfplotsxycodekeylist}
\subsubsection{String Symbols as Input Coordinates}
It is possible to provide a string dictionary to \PGFPlots. An input coordinate can then use any symbol provided in that dictionary.
\begin{pgfplotsxykeylist}{symbolic \x\space coords=\marg{dictionary}}%
A style which sets |x coord trafo| and |x coord inv trafo| (or the respective |y| or |z| variants) such that any element in \meta{dictionary} is a valid input coordinate. The \meta{dictionary} can be a comma separated list or a list terminated with `|\\|'. In both cases, white space is considered to be part of the names (use `|%|' at end of lines).
The dictionary will assign integer numbers to every element. These integers are used internally for arithmetics. Finally, the inverse transformation takes a fixed point number and maps it to the nearest integer, and that integer is mapped into the dictionary.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[symbolic x coords={a,b,c,d,e,f,g,h,i}]
\addplot+[smooth] coordinates {
(a,42)
(b,50)
(c,80)
(f,60)
(g,62)
(i,90)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
The effect of the transformation is simply that input coordinates can be elements of the dictionary and tick labels will be chosen out of this dictionary as well.
Note that |symbolic x coords| is more-or-less equivalent to explicitly provided |xtick| positions and |xticklabels|:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
xtick={0,1,2,...,20},
xticklabels={a,b,c,d,e,f,g,h,i},
xticklabel style={
anchor=base,
yshift=-\baselineskip
},
]
\addplot+[smooth] coordinates {
(0,42)
(1,50)
(2,80)
(5,60)
(6,62)
(8,90)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent The difference is that the approach with |symbolic x coords| is simpler to read whereas the |xtick| approach is simpler with respect to coordinate arithmetics (for example to increase limits using |enlargelimits|). The |xticklabel style| here is an attempt to align all tick labels at their base line (which would be useful for |symbolic x coords| as well as soon as labels have characters which exceed the baseline).
\paragraph{See also} the option to add tick and/or grid lines at every encountered coordinate using |xtick=data| (or |minor xtick=data|).
\end{pgfplotsxykeylist}
\subsubsection{Dates as Input Coordinates}
\label{pgfplots:sec:date:coords}
The already mentioned application of using dates as input coordinates has been predefined, together with support for hours and minutes. It relies on the \pgfname\ calendar library which converts dates to numbers in the Julian calendar. Then, one coordinate unit is one day.
\begin{pgfplotslibrary}{dateplot}
Loads the coordinate transformation code.
\end{pgfplotslibrary}
\begin{stylekey}{/pgfplots/date coordinates in=\meta{coordinate}}
Installs |x coord trafo| and |x coord inv trafo| (or the respective variant for \meta{coordinate}) such that ISO dates of the form \meta{year}|-|\meta{month}|-|\meta{day} are accepted. Here, \meta{coordinate} is usually one of |x|, |y|, or |z|, but it can also contain stuff like |hist/data|.
After installing this style, input values like |2006-02-28| will be converted to an ``appropriate'' integer using the Julian calender. Input coordinates may be of the form
\meta{year}|-|\meta{month}|-|\meta{day}
\noindent or they may contain times as
\meta{year}|-|\meta{month}|-|\meta{day} \meta{hour}|:|\meta{minute}.
The result of the transformation are numbers where one unit is one day and times are fractional numbers.
The transformation is realized using the \pgfname-calendar module, see \cite[Calendar Library]{tikz}. This reference also contains more information about extended syntax options for dates.
The inverse transformation provides the following macros which are available during tick label evaluation (i.e. when used inside of |xticklabel| or |yticklabel|):
\begin{itemize}
\item \declareandlabel{\year} expands to the year component,
\item \declareandlabel{\month} expands to the month component,
\item \declareandlabel{\day} expands to the day component,
\item \declareandlabel{\hour} expands to the hour component (using two digits),
\item \declareandlabel{\Hour} expands to the hour component (but omits leading zeros),
\item \declareandlabel{\minute} expands to the minute component (two digits),
\item \declareandlabel{\Minute} expands to the minute component (omits leadings zeros),
\item \declareandlabel{\lowlevel} expands to the low level number representing the tick,
\item \declareandlabel{\second} will always be |00|.
\end{itemize}
This allows to use |\day.\month.\year| or |\day. \hour:\minute| inside of |xticklabel|, for example.
A complete example (with fictional data) is shown below.
\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}}
% \usepgfplotslibrary{dateplot}\usepackage{eurosym}
\begin{codeexample}[]
% requires \usepgfplotslibrary{dateplot} !
\pgfplotstabletypeset[string type]{plotdata/accounts.dat}
\begin{tikzpicture}
\begin{axis}[
date coordinates in=x,
xticklabel={\day.\month.},
xlabel={2008},
stack plots=y,
yticklabel={\pgfmathprintnumber{\tick}\EUR{}}, % <- requires \usepackage{eurosym}
ylabel=Total credit,
ylabel style={yshift=10pt},
legend style={
at={(0.5,-0.3)},anchor=north,legend columns=-1}]
\addplot table[x=date,y=account1] {plotdata/accounts.dat};
\addplot table[x=date,y=account2] {plotdata/accounts.dat};
\addplot table[x=date,y=account3] {plotdata/accounts.dat};
\legend{Giro,Tagesgeld,Sparbuch}
\end{axis}
\end{tikzpicture}
\end{codeexample}
% \usepgfplotslibrary{dateplot}\usepackage{eurosym}
\begin{codeexample}[]
% requires \usepgfplotslibrary{dateplot} !
\begin{tikzpicture}
\begin{axis}[
date coordinates in=x,
xtick=data,
xticklabel style=
{rotate=90,anchor=near xticklabel},
xticklabel=\day. \hour:\minute,
date ZERO=2009-08-18,% <- improves precision!
]
\addplot coordinates {
(2009-08-18 09:00, 050)
(2009-08-18 12:00, 100)
(2009-08-18 15:00, 100)
(2009-08-18 18:35, 100)
(2009-08-18 21:30, 040)
(2009-08-19, 020)
(2009-08-19 3:00, 000)
(2009-08-19 6:0, 035)
};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\paragraph{Attention:} If you intend to use hours and minutes, you should \emph{always} provide the |date ZERO| to maintain adequate precision!
\end{stylekey}
\begin{pgfplotskey}{date ZERO=\meta{year}-\meta{month}-\meta{day} (initially 2006-01-01)}
A technical key which defines the $0$ coordinate of |date coordinates in|. Users will never see the resulting numbers, so one probably never needs to change it. However, the resulting numbers may become very large and a mantisse of 6 significant digits may not be enough to get accurate results. In this case, |date ZERO| should be set to a number which falls into the input date range.
\end{pgfplotskey}
|
