summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex
blob: 9c8c9ccb9eabef821446c7dc4aba597df6139533 (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
364
365
366
367
368
369
370
371

\subsection{Alignment Options and Bounding Box Control}
\label{pgfplots:sec:align}

\subsubsection{Basic Alignment}
Alignment works with two main methods: a coordinate where the axis shall be drawn and an ``anchor'' inside of the axis which shall be drawn at this particular coordinate. This methodology is common for each \Tikz\ node -- and an axis is nothing but a (special) \Tikz\ node. The coordinate can be specified using the |at| key, while the anchor can be specified with the |anchor| key. In most cases, it is sufficient to provide only an anchor -- unless one needs more than one axis in the same picture environment.

\begin{pgfplotskey}{at=\marg{coordinate expression}}
Assigns a position for the complete axis image. This option works similarly to the |at|-option of |\node[at=|\marg{coordinate expression}|]|, see~\cite{tikz}. The common syntax is |at={|\parg{x,y}|}|.

The idea is to provide an \marg{coordinate expression} where the axis will be placed. The axis' anchor will be placed at \marg{coordinate expression}.
\end{pgfplotskey}

\begin{pgfplotskey}{anchor=\marg{name} (initially south west)}
\label{option:anchor}%
This option shifts the axis horizontally and vertically such that the axis anchor (a point on the axis) is placed at canvas coordinate $(0,0)$ (this is \emph{not} the logical coordinate, it is an image coordinate). For users who are familiar with \Tikz: an axis is actually a very special node, so anchors work as in~\cite{tikz}.

Anchors are useful in conjunction with horizontal or vertical alignment of plots, see the examples below.

There are four sets of anchors available: anchors positioned on the axis bounding box, anchors on the outer bounding box and anchors which have one coordinate on the outer bounding box and the other one at a position of the axis rectangle. Finally, one can place anchors near the origin.

{%
%\pgfplotsset{every picture/.append style={background rectangle/.style={help lines},show background rectangle}}%
\pgfplotstableread{pgfplots.testplot}\plottable
\def\plot{%
	\begin{axis}[
		width=5cm,
		name=test plot,
		xlabel=$x$,
		ylabel={$y$},% = \frac 12 \cdot x^3 - 4 x^2 -16 x$},
		legend style={at={(1.03,1)},anchor=north west},
		title=A test plot.
	]
		\addplot table from{\plottable};
		%\addplot coordinates {(0,0) (1,1)};
		\addlegendentry{$f(x)$}
		\addplot[red] plot[id=gnuplot_ppp,domain=-40:40,samples=120] gnuplot{10000*sin(x/3)};
		\addlegendentry{$g(x)$}
	\end{axis}
}%
\def\showit#1#2{%
	%\node[show them,#2] at (test plot.#1) {(s.#1)};
	\node[pin=#2:(s.#1),fill=black,circle,scale=0.3] at (test plot.#1) {};
}%
\tikzstyle{every pin}=[opacity=0.5,fill=yellow,rectangle,rounded corners=3pt,font=\tiny]%
In more detail, we have
Anchors on the axis rectangle (the bounding box around the axis)\footnote{Versions prior to \PGFPlots\ v.1.3 did \emph{not} use the bounding box of the axis, they used axis coordinates to orient these anchors. This has been fixed. If you \emph{really} want to undo the bugfix, see \texttt{\protect\pgfmanualpdfref{compat/anchors}{compat/anchors}}.},
		\begin{center}
			\begin{tikzpicture}
				\plot
				\showit{north}{90}
				\showit{north west}{135}
				\showit{west}{180}
				\showit{south west}{225}
				\showit{south}{270}
				\showit{south east}{305}
				\showit{east}{0}
				\showit{north east}{45}
				\showit{center}{90}
			\end{tikzpicture}
		\end{center}
Anchors on the outer bounding box,
		\begin{center}
			\begin{tikzpicture}
				\plot
				\showit{outer north}{90}
				\showit{outer north west}{135}
				\showit{outer west}{180}
				\showit{outer south west}{225}
				\showit{outer south}{270}
				\showit{outer south east}{305}
				\showit{outer east}{0}
				\showit{outer north east}{45}
				\showit{outer center}{90}
			\end{tikzpicture}
		\end{center}
There are anchors which have one coordinate on the outer bounding box, and one on the axis rectangle,
		\begin{center}
			\begin{tikzpicture}
				\plot
				{\pgfplotsset{every pin/.append style={pin distance=1cm}}%
				\showit{above north}{90}
				}%
				\showit{above north east}{90}
				\showit{right of north east}{0}
				\showit{right of east}{0}
				\showit{right of south east}{0}
				\showit{below south east}{-90}
				{\pgfplotsset{every pin/.append style={pin distance=1cm}}%
				\showit{below south}{-90}
				}%
				\showit{below south west}{-90}
				\showit{left of south west}{180}
				\showit{left of west}{180}
				\showit{left of north west}{180}
				\showit{above north west}{90}
			\end{tikzpicture}
		\end{center}
And finally, we have origin anchors which are especially useful when axis lines pass through the origin,
		\begin{center}
			\begin{tikzpicture}
					\begin{axis}[
						name=test plot,
						axis x line=center,
						axis y line=center,
						enlargelimits=false,
						minor tick num=3,
						tick style={semithick},
						tick align=center,
						xlabel=$x$,
						ylabel=$y$,
						every axis x label/.style={at={(current axis.right of origin)},anchor=north east},
						every axis y label/.style={at={(current axis.above origin)},anchor=north east},
						inner axis line style={->},
					]
					\addplot+[domain=-2:5] {20*x};
					\end{axis}
				{\pgfplotsset{every pin/.append style={pin distance=1cm}}%
				\showit{above origin}{45}
				}%
				\showit{right of origin}{45}
				{\pgfplotsset{every pin/.append style={pin distance=1cm}}%
				\showit{below origin}{0}
				}%
				\showit{left of origin}{135}
				\showit{origin}{135}
			\end{tikzpicture}
		\end{center}
The default value is |anchor=south west|. You can use anchors in conjunction with the \Tikz\ |baseline| option and/or |\begin{pgfinterruptboundingbox}| to perform alignment.

\paragraph{Remarks:} Each of the anchors on the axis rectangle has an equivalent to a coordinate in the |axis description cs| described in section~\ref{pgfplots:sec:axis:description:cs}. That means the first set of anchors actually lives on the \emph{tight bounding box around the axis} (without any ticks or descriptions). The |south west| anchor will always be the lower left corner of this bounding box, even in case of a rotated or skewed coordinate system\footnote{Note that this is only true for versions since 1.3.}. Similar statements hold for the other anchors.
}

\subsubsection{Vertical alignment with \texttt{baseline}}
\label{sec:align}%
\pgfmanualpdflabel{/tikz/baseline}{}%
The default axis anchor is |south west|, which means that the picture coordinate $(0,0)$ is the lower left corner of the axis. As a consequence, the \Tikz\ option ``|baseline|'' allows vertical alignment of adjacent plots:
\begin{codeexample}[]
\pgfplotsset{domain=-1:1}
\begin{tikzpicture}
	\begin{axis}[xlabel=A normal sized $x$ label]
	\addplot[smooth,blue,mark=*] {x^2};
	\end{axis}
\end{tikzpicture}%
\hspace{0.15cm}
\begin{tikzpicture}
	\begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }]
	\addplot[smooth,blue,mark=*] {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\pgfplotsset{domain=-1:1}
\begin{tikzpicture}[baseline]
	\begin{axis}[xlabel=A normal sized $x$ label]
	\addplot[smooth,blue,mark=*] {x^2};
	\end{axis}
\end{tikzpicture}%
\hspace{0.15cm}
\begin{tikzpicture}[baseline]
	\begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }]
	\addplot[smooth,blue,mark=*] {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
The |baseline| option configures \Tikz\ to shift position $y=0$ to the text's baseline and the |south west| anchor shifts the axis such the $y=0$ is at the lower left axis corner.

\subsubsection{Horizontal Alignment}
\label{sec:halign}%
If you place multiple |axes| into a single |tikzpicture| and use the `|anchor|'-option, you can control horizontal alignment:
\begin{codeexample}[]
\begin{tikzpicture}
\pgfplotsset{every axis/.append style={
cycle list={
	{red,only marks,mark options={
		fill=red,scale=0.8},mark=*},
	{black,only marks,mark options={
		fill=black,scale=0.8},mark=square*}}}}

\begin{axis}[width=4cm,scale only axis,
	name=main plot]
\addplot file 
	{plotdata/pgfplots_scatterdata1.dat};
\addplot file 
	{plotdata/pgfplots_scatterdata2.dat};
\addplot[blue] coordinates {
	(0.093947,	-0.011481)
	(0.101957,	0.494273)
	(0.109967,	1.000027)};
\end{axis}

% introduce named coordinate:
\path (main plot.below south west) ++(0,-0.1cm) 
	coordinate (lower plot position);

\begin{axis}[at={(lower plot position)},
	anchor=north west,
	width=4cm,scale only axis,height=0.8cm,
	ytick=\empty]

\addplot file 
  {plotdata/pgfplots_scatterdata1_latent.dat};
\addplot file 
  {plotdata/pgfplots_scatterdata2_latent.dat};
\end{axis}
\end{tikzpicture}
\end{codeexample}


\subsubsection{Bounding box restrictions}
Bounding box restrictions can be realized with several methods of \PGF:
\begin{enumerate}
	\item The |overlay| option,
	\item The |pgfinterruptboundingbox| environment,
	\item The |\useasboundingbox| path.
\end{enumerate}
\begin{key}{/tikz/overlay}
\index{Bounding Box Control!Excluding Image Parts}
	A special key of \PGF\ which disables bounding box updates for (parts of) the image. The effect is that those parts are an ``overlay'' over the document.

	For \PGFPlots, |overlay| can be useful to position legends or other axis descriptions outside of the axis~-- without affecting its size (and without affecting alignment).

For example, one may want to include only certain parts of the axis into the final bounding box. This would allow horizontal alignment (centering):
\begin{codeexample}[]
\begin{tikzpicture}%
   \begin{axis}[
      title=A title,
      ylabel style={overlay},
      yticklabel style={overlay},
      xlabel={$x$},
      ylabel={$y$},
      legend style={at={(0.5,0.97)},
         anchor=north,legend columns=-1},
      domain=-2:2
   ]
   \addplot {x^2};
   \addplot {x^3};
   \addplot {x^4};
   \legend{$x^2$,$x^3$,$x^4$}
   \end{axis}
\end{tikzpicture}%
\end{codeexample}
\noindent Now, the left axis descriptions ($y$ label and $y$ ticks) stick out of the bounding box.
	
The following example places a legend somewhere without affecting the bounding box.
\begin{codeexample}[]
\begin{tikzpicture}
   \begin{axis}[
      domain=0:6.2832,samples=200,
      legend style={
         overlay,
         at={(-0.5,0.5)},
         anchor=center},
      every axis plot post/.append style={mark=none},
      enlargelimits=false]

   \addplot {sin(deg(x)+3)+rand*0.05};
   \addplot {cos(deg(x)+2)+rand*0.05};
   \legend{Signal 1,Signal 2}
   \end{axis}
\end{tikzpicture}
\end{codeexample}

	More information about the |overlay| option can be found in the \PGF\ manual~\cite{tikz}.
\end{key}


\begin{environment}{{pgfinterruptboundingbox}}
\label{sec:bounding:box:example}%
\index{Bounding Box Control}
\index{Bounding Box Control!pgfinterruptboundingbox}
{%
\pgfmanualpdflabel{\textbackslash useasboundingbox}{}%
An alternative to |overlay| is shown below: the figure has a truncated bounding box with is shown using |\fbox|.
\begin{codeexample}[]
\setlength{\fboxsep}{0pt}%
\fbox{%
\begin{tikzpicture}%
	\begin{pgfinterruptboundingbox}
	\begin{axis}[
		name=my plot,
		title=A title,
		xlabel={$x$},
		ylabel={$y$},
		legend style={at={(0.5,0.97)},
			anchor=north,legend columns=-1},
		domain=-2:2
	]
	\addplot {x^2};
	\addplot {x^3};
	\addplot {x^4};
	\legend{$x^2$,$x^3$,$x^4$}
	\end{axis}
	\end{pgfinterruptboundingbox}

	\useasboundingbox 
			  (my plot.below south west)
	rectangle (my plot.above north east);
\end{tikzpicture}%
}%
\end{codeexample}%
}%
The |pgfinterruptboundingbox| environment does not include its content into the image's bounding box, and |\useasboundingbox| sets the pictures bounding box to the following argument (see~\cite{tikz}).
\end{environment}

\end{pgfplotskey}

\subsubsection{Alignment In Array Form (Subplots)}
\index{Subplots}%
\index{Alignment!Subplots}%
\index{Alignment!Array}%
\index{array!Array Alignment}%
\pgfmanualpdflabel{\textbackslash matrix}{}%
Sometimes alignment in array form is desired. One can use the following approach or use the library |groupplots| on page \ref{sec:group:plot} which does
not utilize \Tikz\ matrices. 

While it is possible to use (for example) |tabular| combined with the vertical and horizontal alignment methods discussed above, it might be better to use a \Tikz\ |matrix|.

A \Tikz\ matrix is some sort of ``graphical'' table. It knows everything about picture alignment and it has more flexibility than |tabular|. The complete documentation of a \Tikz\ matrix is beyond the scope of this manual, please refer to \cite{tikz} for details. But we provide an example here:
\pgfmanualpdflabel{/tikz/matrix}{}%
\begin{codeexample}[]
\begin{tikzpicture}
	\matrix {
		\begin{axis}
			\addplot {x};
		\end{axis}
		&
		% differently large labels are aligned automatically:
		\begin{axis}[ylabel={$f(x)=x^2$},ylabel style={font=\Huge}]
			\addplot {x^2};
		\end{axis}
		\\
		%
		\begin{axis}[xlabel=$x$,xlabel style={font=\Huge}]
			\addplot {x^3};
		\end{axis}
		&
		\begin{axis}
			\addplot {x^4};
		\end{axis}
		\\
	};
\end{tikzpicture}
\end{codeexample}
\noindent So, a matrix is a picture element inside of |tikzpicture|. Its cells are separated by `|&|' as in tabular (or, if `|&|' causes problems, with |\pgfmatrixnextcell|). Its rows are separated by `|\\|'. Each cell is aligned using the cells' anchor. Since, by default, the anchor of an axis is placed at the lower left corner, the example above is completely aligned, without the need for any bounding box modifications -- even the labels are aligned correctly. If another anchor shall be used, simply place 
\begin{codeexample}[code only]
\pgfplotsset{anchor=....}
\matrix {
  ...
};
\end{codeexample}
\noindent in front of the matrix. This will use the same configuration for every sub-plot.

\paragraph{Attention:} Unfortunately, the array alignment with |\matrix| is \emph{incompatible} with legends. A legend is also a matrix and, unfortunately,
\Tikz\ matrizes can't be nested. Of course, this does not affect the manually created legends by means of |\label| and |\ref|, see
section~\ref{pgfplots:legend:labelref} for details. 

If one wishes to have an easier approach of aligning one should refer to the library |groupplots| on p. \ref{sec:group:plot}.

\subsubsection{Miscellaneous for Alignment}

\begin{predefinednode}{current axis}
	A node which refers to the current axis or the last typeset axis.

	You can use this node in axis descriptions, for example to place axis labels or titles.

	\paragraph{Remark:} If you use |current axis| inside of axis descriptions, the ``current axis'' is not yet finished. That means you \emph{can't use any outer anchor} inside of axis descriptions.

	It is also possible to use |current axis| in any drawing or plotting commands inside of an axis (but no outer anchor as these are not defined when drawing commands are processed). This usage is similar to the |axis description cs|.
\end{predefinednode}