summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
blob: e81c8fcb7d27ec2d60aad190dd88670fc8a0864c (plain)
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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
\section{Utilities and Basic Level Commands}
\label{sec:pgfplots:lowlevel}
This section documents commands which provide access to more basic elements of \PGFPlots. Most of them are closely related to the basic level of \pgfname, especially various point commands which are specific to an axis. Some of them are general purpose utilities like loops.

However, most elements in this section are only interesting for advanced users -- and perhaps only for special cases.

\subsection{Utility Commands}

\begin{command}{\foreach \meta{variables} |in| \meta{list} \marg{commands}}
	A powerful loop command provided by \Tikz, see~\cite[Section Utilities]{tikz}.
\begin{codeexample}[]
\foreach \x in {1,2,...,4} {Iterating \x. }%
\end{codeexample}

	A \PGFPlots\ related example could be
\begin{codeexample}[code only]
\foreach \i in {1,2,...,10} {\addplot table {datafile\i}; }%
\end{codeexample}
\end{command}

\begin{command}{\pgfplotsforeachungrouped \meta{variable} |in| \meta{list} \marg{command}}
	A specialised variant of |\foreach| which can do two things: it does not introduce extra groups while executing \meta{command} and it allows to invoke the math parser for (simple!) \meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$} expressions.

\begin{codeexample}[]
\def\allcollected{}
\pgfplotsforeachungrouped \x in {1,2,...,4} {Iterating \x. \edef\allcollected{\allcollected, \x}}%
All collected = \allcollected.
\end{codeexample}

	A more useful example might be to work with tables. The following example is taken from \PGFPlotstable:

\begin{codeexample}[code only]
\pgfplotsforeachungrouped \i in {1,2,...,10} {%
	\pgfplotstablevertcat{\output}{datafile\i} % appends `datafile\i' -> `\output'
}%
% since it was ungrouped, \output is still defined (would not work
% with \foreach)
\end{codeexample}

	\paragraph{Remark: } The special syntax \meta{list}=\meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$}, i.e.\ with two leading elements, followed by dots and a final element, invokes the math parser for the loop. Thus, it allows larger number ranges than any other syntax if |/pgf/fpu| is active.  In all other cases, |\pgfplotsforeachungrouped| invokes |\foreach| and provides the results without \TeX\ groups.
	
	Keep in mind that inside of an axis environment, all loop constructions (including custom loops, |\foreach| and |\pgfplotsforeachungrouped|) need to be handled with care: loop arguments can only be used in places where they are immediately evaluated; but \PGFPlots\ postpones the evaluation of many macros. For example, to loop over something and to generate axis descriptions of the form |\node at (axis cs:\i,0.5)....|, the loop macro |\i| will be evaluated in |\end{axis}| -- but at that time, the loop is over and its value is lost. The correct way to handle such an application is to \emph{expand} the loop variable \emph{explicitly}. For example:
\begin{codeexample}[code only]
\pgfplotsforeachungrouped \i/\j in {
	1 / a,
	2 / b,
	3 / c
}{
	\edef\temp{\noexpand\node at (axis cs: \i,0.5) {\j};}
	% \show\temp % lets TeX show you what \temp contains
	\temp
}
\end{codeexample}
	The example generates three loop iterations: |\i=1|, |\j=a|; then |\i=2|, |j=b|; then |\i=3|, |\j=c|. Inside of the loop body, it expands them and assigns the result to a macro using an ``expanded definition'', |\edef|. The result no longer contains either |\i| or |\j| (since these have been expanded). Then, it invokes the resulting macro. Details about the \TeX\ command |\edef| and expansion control can be found in the document \href{file:TeX-programming-notes.pdf}{TeX-programming-notes.pdf} which comes with \PGFPlots.
\end{command}

\begin{command}{\pgfplotsinvokeforeach\marg{list} \marg{command}}
	A variant of |\pgfplotsforeachungrouped| (and such also of |\foreach|) which replaces any occurrence of |#1| inside of \meta{command} once for every element in \meta{list}. Thus, it actually assumes that \marg{command} is like a |\newcommand| body.

	In other words, \meta{command} is invoked for every element of \meta{list}. The actual element of \meta{list} is available as |#1|.

	As |\pgfplotsforeachungrouped|, this command does \emph{not} introduce extra scopes (i.e.\ it is ungrouped as well).

	The difference to |\foreach \x in |\meta{list}\marg{command} is subtle: the |\x| would \emph{not} be expanded whereas |#1| is. 
\begin{codeexample}[]
\pgfkeys{
  otherstyle a/.code={[a]},
  otherstyle b/.code={[b]},
  otherstyle c/.code={[c]},
  otherstyle d/.code={[d]}}
\pgfplotsinvokeforeach{a,b,c,d}        	
	{\pgfkeys{key #1/.style={otherstyle #1}}}
Invoke them: 
\pgfkeys{key a} \pgfkeys{key b} 
\pgfkeys{key c} \pgfkeys{key d}
\end{codeexample}
The counter example would use a macro (here |\x|) as loop argument:
\begin{codeexample}[]
\pgfkeys{
  otherstyle a/.code={[a]},
  otherstyle b/.code={[b]},
  otherstyle c/.code={[c]},
  otherstyle d/.code={[d]}}
\pgfplotsforeachungrouped \x in {a,b,c,d}        	
	{\pgfkeys{key \x/.style={otherstyle \x}}}
Invoke them: 
\pgfkeys{key a} \pgfkeys{key b}
\pgfkeys{key c} \pgfkeys{key d}
\end{codeexample}

	\paragraph{Restrictions:} you can't nest this command yet (since it does not introduce protection by scopes).
\end{command}

\begin{command}{\pgfmathparse\marg{expression}}
	Invokes the \pgfname\ math parser for \meta{expression} and defines \declareandlabel{\pgfmathresult} to be the result.
\begin{codeexample}[]
\pgfmathparse{1+41}

The result is `\pgfmathresult'.
\end{codeexample}
	Please refer to \cite{tikz} for more details.
\end{command}


\begin{command}{\pgfplotstableread\marg{file}}
	Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle.
\end{command}
\begin{command}{\pgfplotstabletypeset\marg{\textbackslash macro}}
	Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle.
\end{command}

\begin{command}{\pgfplotsiffileexists\marg{filename}\marg{true code}\marg{false code}}
	Invokes \meta{true code} if \meta{filename} exists and \meta{false code} if not. Can be used in looping macros, for example to plot every data file until there are no more of them.
\end{command}
\begin{command}{\pgfplotsutilifstringequal\marg{first}\marg{second}\marg{true code}\marg{false code}}
	A simple ``strcmp'' tool which invokes \meta{true code} if \meta{first} $=$\meta{second} and \meta{false code} otherwise. This does not expand macros.
\end{command}


\begin{commandlist}{\pgfkeys,\pgfeov,\pgfkeysvalueof,\pgfkeysgetvalue}
	These commands are part of the \Tikz\ way of specifying options, its sub-package |pgfkeys|. The |\pgfplotsset| command is actually nothing but a wrapper around |\pgfkeys|.

	A short introduction into |\pgfkeys| can be found in~\cite{keyvalintro} whereas the complete reference is, of course, the \Tikz\ manual~\cite{tikz}.

	The key |\pgfkeysvalueof|\marg{key name} expands to the value of a key; |\pgfkeysgetvalue|\marg{key name}\marg{\textbackslash macro} stores the value of \meta{key name} into \meta{\textbackslash macro}. The |\pgfeov| macro is used to delimit arguments for code keys in |\pgfkeys|, please refer to the references mentioned above.
\end{commandlist}

\subsection[Commands Inside Of PGFPlots Axes]{Commands Inside Of {\normalfont\PGFPlots} Axes}
\begin{command}{\autoplotspeclist}
This command should no longer be used, although it will be kept as technical implementation detail. Please use the `|cycle list|' option, Section~\ref{sec:cycle:list}.
\end{command}

\begin{command}{\logten}
Expands to the constant $\log(10)$. Useful for logplots because $\log(10^i) = i\log(10)$. This command is only available inside of a \Tikz-picture.
\end{command}

\begin{command}{\pgfmathprintnumber\marg{number}}
Generates pretty--printed output\footnote{This method was previously \texttt{\textbackslash prettyprintnumber}. Its functionality has been included into \PGF\ and the old command is now deprecated.} for \meta{number}. This method is used for every tick label.

The number is printed using the current number printing options, see the manual of \PGFPlotstable\ which comes with this package for the different number styles, rounding precision and rounding methods.
\end{command}

\begin{command}{\numplots}
	Inside of any of the axis environments, associated style, option or command, |\numplots| expands to the total number of  plots.
\end{command}
\begin{command}{\numplotsofactualtype}
	Like |\numplots|, this macro returns the total number of plots which have the same plot handler. Thus, if you have |sharp plot| active, it returns the number of all |sharp plots|. If you have |ybar| active, it returns the number of |ybar| plots and so on.
\end{command}

\begin{command}{\plotnum}
	Inside of |\addplot| or any associated style, option or command, |\plotnum| expands to the current plot's number, starting with~$0$.
\end{command}

\begin{command}{\plotnumofactualtype}
	Like |\plotnum|, but it returns the number among all plots of the same type. The number of all such plots is available using |\numplotsofactualtype|.	
\end{command}

\begin{command}{\coordindex}
	Inside of an |\addplot| command, this macro expands to the number of the actual coordinate (starting with~$0$).

	It is useful together with |x filter| or |y filter| to (de)select coordinates.
\end{command}

\subsection{Path Operations}

\begin{commandlist}{\path,\draw,\fill,\node,\matrix}
	These commands are \Tikz\ drawing commands all of which are documented in~\cite{tikz}. They are used to draw or fill paths, generate text nodes or aligned text matrices. They are equivalent to 
	\pgfmanualpdflabel{/tikz/draw}{}|\path[draw]|, 
	\pgfmanualpdflabel{/tikz/fill}{}|\path[fill]|, 
	\pgfmanualpdflabel{/tikz/node}{}|\path[node]|, 
	\pgfmanualpdflabel{/tikz/matrix}{}|\path[matrix]|, 
	respectively.
\end{commandlist}
\begin{pathoperation}{--}{\meta{coordinate}}
	A \Tikz\ path operation which connects the current point (the last one before |--|) and \meta{coordinate} with a straight line.
\end{pathoperation}
{\catcode`\|=12
\begin{pathoperation}[noindex]{|-}{\meta{coordinate}}
\pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}%
	A \Tikz\ path operation which connects the current point and \meta{coordinate} with \emph{two} straight lines: first vertical, then horizontal.
\end{pathoperation}

\begin{pathoperation}[noindex]{-|}{\meta{coordinate}}
\pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}%
	A \Tikz\ path operation which connects the current point and \meta{coordinate} with \emph{two} straight lines: first horizontal, then vertical.
\end{pathoperation}
}

\begin{keylist}{/tikz/xshift=\marg{dimension},/tikz/yshift=\marg{dimension}}
	These \Tikz\ keys allow to shift something by \meta{dimension} which is any \TeX\ size (or expression).
\end{keylist}


\begin{command}{\pgfplotsextra\marg{low-level path commands}}
	A command to execute \meta{low-level path commands} in a \PGFPlots\ axis. Since any drawing commands inside of an axis need to be postponed until the axis is complete and the scaling has been initialised, it is not possible to simply draw any paths.
	Instead, it is necessary to draw them as soon as the axis is finished. This is done automatically for every \Tikz\ path -- and it is also done manually if you write |\pgfplotsextra|\marg{commands}.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[xmin=0,xmax=3,ymin=0,ymax=5]
	\pgfplotsextra{%
		\pgfpathmoveto{\pgfplotspointaxisxy{1}{2}}%
		\pgfpathlineto{\pgfplotspointaxisxy{2}{4}}%
		\pgfusepath{stroke}%
	}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The example above initializes an axis and executes the basic level path commands as soon as the axis is ready. The execution of multiple |\path|, |\addplot| and |\pgfplotsextra| commands is in the same sequence as they occur in the environment\footnote{Except for stacked plots where the sequence may be reverse, see the key \texttt{reverse stack plots}.}.%
\end{command}

\subsection{Specifying Basic Coordinates}

\begin{commandlist}{%
	\pgfplotspointaxisxy\marg{x coordinate}\marg{y coordinate},%
	\pgfplotspointaxisxyz\marg{x coordinate}\marg{y coordinate}\marg{z coordinate}}
	Point commands like |\pgfpointxy| which take logical, absolute coordinates and return a low--level point. Every transformation from user transformations to logarithms are applied.

	Since the transformations are initialized after the axis is complete, this command needs to be postponed (see |\pgfplotsextra|).
\end{commandlist}

\begin{commandlist}{%
	\pgfplotspointrelaxisxy\marg{rel x coordinate}\marg{rel y coordinate},%
	\pgfplotspointrelaxisxyz\marg{rel x coordinate}\marg{rel y coordinate}\marg{rel z coordinate}}
	Point commands which take \emph{relative} coordinates such that $x=0$ is the \emph{lower} $x$ axis limit and $x=1$ the \emph{upper} $x$ axis limit.

	These commands are used for |rel axis cs|.

	Please note that the transformations are only initialised if the axis is complete! This means you need to provide |\pgfplotsextra|.
\end{commandlist}

\begin{commandlist}{%
	\pgfplotspointdescriptionxy\marg{$x$ fraction}\marg{$y$ fraction},%
	\pgfplotsqpointdescriptionxy\marg{$x$ fraction}\marg{$y$ fraction}}%
	Point commands such that |{0}{0}| is the lower left corner of the axis' bounding box and |{1}{1}| the upper right one; everything else is in between. The `|q|' variant is quicker as it doesn't invoke the math parser on its arguments.

	They are used for |axis description cs|, see Section~\ref{pgfplots:sec:axis:description:cs}.
\end{commandlist}

\begin{commandlist}{%
	\pgfplotspointunitx,%
	\pgfplotspointunity,%
	\pgfplotspointunitz}%
	Low--level point commands which return the $x$, $y$ or $z$ unit vectors.

	The point |\pgfplotspointxyz{1}{0}{0}| is the same as |\pgfplotspointunitx|, the |{0}{1}{0}| coordinate the unit $y$ vector and the |{0}{0}{1}| coordinate the unit $z$ vector.

	The unit $z$ vector is only defined for three dimensional axes.
\end{commandlist}

\begin{commandlist}{%
	\pgfplotsunitxlength,%
	\pgfplotsunitylength,%
	\pgfplotsunitzlength,%
	\pgfplotsunitxinvlength,%
	\pgfplotsunityinvlength,%
	\pgfplotsunitzinvlength}%
	Macros which expand to the vector length $\lVert x_i \rVert$ of the respective unit vector $x_i$ or the inverse vector length, $1/\lVert x_i \rVert$. These macros can be used inside of |\pgfmathparse|, for example.

	The $x_i$ are the |\pgfplotspointunitx| variants.
\end{commandlist}

\begin{commandlist}{\pgfplotspointaxisorigin}
	A point coordinate at the origin, $(0,0,0)$. If the origin is not part of the axis limits, the nearest point on the boundary is returned instead.

	This is the same coordinate as returned by the |origin| anchor.
\end{commandlist}

\begin{command}{\pgfplotsqpointoutsideofaxis\marg{three-char-string}\marg{coordinate}\marg{normal distance}}
	Provides a point coordinate on one of the available four axes in case of a two dimensional figure or on one of the available twelve axes in case of a three dimensional figure.
	
	The desired axis is uniquely identified by a three character string, provided as first argument to the command. The first of the three characters is `|0|' if the $x$ coordinate of the specified axis passes through the lower axis limit. It is `|1|', if the $x$ coordinate of the specified axis passes through the upper axis limit. Furthermore, it is `|2|' if it passes through the origin. The second character is also either |0|, |1| or |2| and it characterizes the position on the $y$ axis. The third character is for the third dimension, the $z$ axis. It should be left at `|0|' for two dimensional plots. However, \emph{one} of the three characters should be `|v|', meaning the axis \underline varies. For example, |v01| denotes $\{ (x,y_{\text{min}},z_{\text{max}}) \vert x \in \R \}$.
	
	The second argument, \meta{coordinate} is the logical coordinate on that axis. Since two coordinates of the axis are fixed, \meta{coordinate} refers to the \underline varying component of the axis. It must be a number without unit; no math expressions are supported here.

	The third argument \meta{normal distance} is a dimension like |10pt|. It shifts the coordinate away from the designated axis in direction of the outer normal vector. The outer normal vector always points away from the axis. It is computed using
	|\pgfplotspointouternormalvectorofaxis|.

	There are several variants of this command which are documented in the source code. One of them is particularly useful:
\end{command}

\begin{command}{\pgfplotsqpointoutsideofaxisrel\marg{three-char-string}\marg{axis fraction}\marg{normal distance}}
	This point coordinate is a variant of |\pgfplotsqpointoutsideofaxis| which allows to provide an \meta{axis fraction} instead of an absolute coordinate. The fraction is a number between $0$ (lower axis limit) and $1$ (upper axis limit), i.e.\ it is given in percent of the total axis. It is possible to provide negative values or values larger than one.

	The |\pgfplotsqpointoutsideofaxisrel| command is similar in spirit to |rel axis cs|.

	There is one speciality in conjunction with reversed axes: if the axis has been reversed by |x dir=reverse| and, in addition, |allow reversal of rel axis cs| is true, the value $0$ denotes the \emph{upper} limit while $1$ denotes the \emph{lower} limit. The effect is that coordinates won't change just because of axis reversal.
\index{allow reversal of rel axis cs}%
\end{command}

\begin{command}{\pgfplotspointouternormalvectorofaxis\marg{three-char-string}}
	A point command which yields the outer normal vector of the respective axis. The normal vector has length $1$ (computed with |\pgfpointnormalised|). It is the same normal vector used inside of |\pgfplotsqpointoutsideofaxis| and its variants.

	The output of this command will be cached and re-used during the lifetime of an axis. 
\end{command}

\begin{command}{\pgfplotsticklabelaxisspec\marg{x, y or z}}
	Expands to the three-character-identification for the axis containing tick labels for the chosen axis, either \meta{x}, \meta{y} or \meta{z}.
\end{command}

\begin{command}{\pgfplotsvalueoflargesttickdimen\marg{x, y or z}}
	Expands to the largest distance of a tick position to its tick label bounding box in direction of the outer unit normal vector. It does also include the value of the |ticklabel shift| key.

	This value is used for |ticklabel cs|.
\end{command}

\begin{commandlist}{%
	\pgfplotstransformcoordinatex\marg{x coordinate of an axis},%
	\pgfplotstransformcoordinatey\marg{y coordinate of an axis},%
	\pgfplotstransformcoordinatey\marg{z coordinate of an axis}}
	Defines |\pgfmathresult| to be the low-level \PGF\ coordinate corresponding to the input argument.

	The command applies any |[xyz] coord trafo| keys, data scalings and/or logarithms or whatever \PGFPlots\ does to map input coordinates to internal coordinates.

	The result can be used inside of a |\pgfpointxy| statement (i.e.\ it still needs to be scaled with the respective \PGF\ unit vector).
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[xmin=0,xmax=2,ymin=0,ymax=5]
	\pgfplotsextra{%
		\pgfplotstransformcoordinatex{1}%
		\let\xcoord=\pgfmathresult
		\pgfplotstransformcoordinatey{1}%
		\let\ycoord=\pgfmathresult
		\pgfpathcircle
			{\pgfqpointxy{\xcoord}{\ycoord}}
			{5pt}%
		\pgfusepath{fill}%
	}%
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	Please note that the transformations are only initialised if the axis is complete! This means you need to provide |\pgfplotsextra| as is shown in the example above.
\end{commandlist}

\begin{command}{\pgfplotsconvertunittocoordinate\marg{x, y or z}\marg{dimension}}
	Converts a dimension (with unit!) to a corresponding $x$, $y$ or $z$ coordinate. The result will be written to |\pgfmathresult| (without units).

	It is possible to use the result as arguments for the |\pgfpointxyz| commands.

	The effect is to multiply \meta{dimension} with the inverse length of the unit vector for the specified axis. These lengths are precomputed in \PGFPlots\ so the operation is fast.
\begin{codeexample}[code only]
\pgfplotsconvertunittocoordinate{x}{5pt}
% now, the command uses exactly 5pt in x direction:
\pgfqpointxyz{\pgfmathresult}{4}{3}
\end{codeexample}
\end{command}

\begin{commandlist}{\pgfplotsmathfloatviewdepthxyz\marg{x}\marg{y}\marg{z},
	\pgfplotsmathviewdepthxyz\marg{x}\marg{y}\marg{z}}
	Both macros define |\pgfmathresult| to be the ``depth'' of a three dimensional point $\bar x = (x,y,z)$. The depth is defined to be the scalar product of $\bar x$ with $\vec d$, the view direction of the current axis.

	For |\pgfplotsmathfloatviewdepthxyz|, the arguments are parsed as floating point numbers and the result is encoded in floating point. A fixed point representation can be generated with |\pgfmathfloattofixed{\pgfmathresult}|.

	For |\pgfplotsmathviewdepthxyz|, \TeX\ arithmetics is employed for the inner product and the result is assigned in fixed point. This is slightly faster, but has considerably smaller data range.

	Both commands can only be used \emph{inside} of a three dimensional \PGFPlots\ axis (as soon as the axis is initialised, see |\pgfplotsextra|). 
\end{commandlist}

\begin{texif}{pgfplotsthreedim}
	A \TeX\ |\if| which evaluates the \meta{true code} if the axis is three dimensional and the \meta{else code} if not.
\end{texif}

\subsection{Accessing Axis Limits}
It is also possible to access axis limits during the visualization phase, i.e.\ during |\end{axis}|. Please refer to the reference documentation for |xmin| on page~\pageref{page:access:limits}.