path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex

\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}