path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex

\subsection{Grouping plots}
{
\label{sec:group:plot}

{\noindent {\emph{by Nick Papior Andersen}}}

\index{Group library!Subplots}%
\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/group/,}{}}



\begin{pgfplotslibrary}{groupplots}
  A library which allows the user to typeset several plots in a matrix like structure.
  Often one has to compare two plots to one another, or you simply need to display two plots in conjunction with each other. Either way the following
  section describes this library which makes matrix structure easier than alternative methods discussed in Section~\ref{sec:pgfplots:arrayform}.
\end{pgfplotslibrary}

\begin{environment}{{groupplot}\oarg{options}}
  Once you have loaded the |groupplots| library you will gain access to this environment. This environment is limited to the same restrictions as the |axis| environment. It actually utilizes this environment so consider it as an extension of this. What is important to note is that \oarg{options} are applied to all plots in the entire environment. This can be really handy when you need the same |xmin|, |xmax|, |ymin| and |ymax|.
\end{environment}

With such an environment one can typeset plots in matrix like styles
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
% Example using groupplots library
\begin{tikzpicture}
  \begin{groupplot}[group style={group size=2 by 2},height=3cm,width=3cm]
    \nextgroupplot
    \addplot coordinates {(0,0) (1,1) (2,2)};
    \nextgroupplot
    \addplot coordinates {(0,2) (1,1) (2,0)};
    \nextgroupplot
    \addplot coordinates {(0,2) (1,1) (2,1)};
    \nextgroupplot
    \addplot coordinates {(0,2) (1,1) (1,0)};      
  \end{groupplot}
\end{tikzpicture}
% Same example created as done without the library
\begin{tikzpicture}
  \begin{axis}[name=plot1,height=3cm,width=3cm]
    \addplot coordinates {(0,0) (1,1) (2,2)};
  \end{axis}
  \begin{axis}[name=plot2,at={($(plot1.east)+(1cm,0)$)},anchor=west,height=3cm,width=3cm]
    \addplot coordinates {(0,2) (1,1) (2,0)};
  \end{axis}
  \begin{axis}[name=plot3,at={($(plot1.south)-(0,1cm)$)},anchor=north,height=3cm,width=3cm]
    \addplot coordinates {(0,2) (1,1) (2,1)};
  \end{axis}
  \begin{axis}[name=plot4,at={($(plot2.south)-(0,1cm)$)},anchor=north,height=3cm,width=3cm]
    \addplot coordinates {(0,2) (1,1) (1,0)};
  \end{axis}
\end{tikzpicture}
\end{codeexample}

The equivalent code is seen as the second example and it is clear that you have to type a lot less. So how do you use it?
First of all you need to utilize the new environment |groupplot|. Within this environment the following command works.
\begin{command}{\nextgroupplot\oarg{axis options} \meta{normal plot commands}}
\label{cmd:pgfplots:nextgroupplot}
This command shifts the placement of the plot. Therefore one should always start the environment |groupplot| with the command
|\nextgroupplot| in order to create the first plot. The \oarg{axis options} are the options that are supplied to the following axes until
the next |\nextgroupplot| command is seen by \TeX.
The order in which figures are typeset are as seen in the next example.
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
\begin{tikzpicture}[shorten >=4pt,shorten <=4pt]
  \begin{groupplot}[group style={group size=2 by 2},
    height=3.5cm,width=3.5cm,/tikz/font=\small]
    \nextgroupplot%1
    \addplot coordinates {(0,1) (1,0)};
    \nextgroupplot%2
    \addplot coordinates {(0,1) (1,0)};
    \nextgroupplot%3
    \addplot coordinates {(0,1) (1,0)};
    \nextgroupplot%4
    \addplot coordinates {(0,1) (1,0)};
  \end{groupplot}
  \draw[thick,>=latex,->,red] 
    (group c1r1.center) node {1.}  -- 
    (group c2r1.center) node {2.};
  \draw[thick,>=latex,->,red] 
    (group c2r1.center)  -- 
    (group c1r2.center) node {3.};
  \draw[thick,>=latex,->,red] 
    (group c1r2.center)  -- 
    (group c2r2.center) node {4.};
\end{tikzpicture}
\end{codeexample}
The plot first fills the first row, then the next row and so on. Just like a table, thus the names |group c|\meta{column}|r|\meta{row}. The power of the |groupplot| is
to quickly create an aligned structure of plots. But you can also utilize it to structure data more creatively. Consider the next example.
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
\begin{tikzpicture}
 \begin{groupplot}[group style={group size=2 by 2,
      horizontal sep=0pt,vertical sep=0pt,
      xticklabels at=edge bottom},
      xmin=0,ymin=0,
      height=3.7cm,width=4cm,no markers]
  \nextgroupplot[group/empty plot]
  \nextgroupplot[xmin=5,xmax=10,ymin=50,ymax=100]
  \addplot[very thick] file {plotdata/group-1.dat};
  \nextgroupplot[xmax=5,ymax=50]
  \addplot[very thick] file {plotdata/group-1.dat};
  \nextgroupplot[xmin=5,xmax=10,ymax=50,
     yticklabels={}]
  \addplot[very thick] file {plotdata/group-1.dat};
 \end{groupplot}
\end{tikzpicture}
\end{codeexample}

Or for instance zooming in on data as in the next example.
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
\begin{tikzpicture}
  \begin{groupplot}[group style={group size=3 by 1},xmin=0,ymin=0,height=4cm,width=5cm,no markers]
    \nextgroupplot
    \addplot[very thick] file {plotdata/group-1.dat};
    \draw[red,dashed,thick] (axis cs:0,0) rectangle (axis cs:5,30);
    \nextgroupplot[xmax=5,ymax=30]
    \addplot[very thick] file {plotdata/group-1.dat};
    \draw[red,dashed,thick] (axis cs:3,10) rectangle (axis cs:5,25);
    \nextgroupplot[xmin=3,xmax=5,ymin=10,ymax=25]
    \addplot[very thick] file {plotdata/group-1.dat};
  \end{groupplot}
  \draw[thick,blue,->,shorten >=2pt,shorten <=2pt] 
  		(group c1r1.east) -- (group c2r1.west);
  \draw[thick,blue,->,shorten >=2pt,shorten <=2pt] 
  		(group c2r1.east) -- (group c3r1.west);
\end{tikzpicture}
\end{codeexample}
\end{command}


\subsubsection{Grouping options}
\label{sec:pgfplots:group:options}


\begin{pgfplotskey}{group style=\marg{options with {\normalfont\texttt{group/}} prefix}}
  This key sets all \meta{options} using the |/pgfplots/group/| prefix.
  
  Note that the distinction between |group/| and normal options is important as some of them are quite similar.

   For example, the following statements are all equivalent:
\begin{codeexample}[code only]
\pgfplotsset{group style={a=2,b=3}}
\pgfplotsset{group/a=2,group/b=3}
\pgfplotsset{group/.cd,a=2,b=3}
\end{codeexample}
\end{pgfplotskey}
All the following keys are in the subdirectory |group|.

\begin{pgfplotskeylist}{group/group size=\meta{columns} by \meta{rows} (initially 1 by 1),
      group/columns=\meta{columns} (initially 1),
      group/rows=\meta{rows} (initially 1)}
  These keys determine the total number of plots that can be in one environment |groupplot|. It is thus important not to add more
  |\nextgroupplot| in the environment than \meta{columns}$\times$\meta{rows}. This is critical to set if one uses more than 1 more plot. As
  the key |group size| uses |columns| and |rows| you should stick to either |group size| or both |columns| and |rows|.
\end{pgfplotskeylist}

\begin{pgfplotskeylist}{group/horizontal sep=\meta{dimension} (initially 1cm),
      group/vertical sep=\meta{dimension} (initially 1cm)}
  The spacing between the plots in the horizontal and vertical direction, respectively. If you thus want them to be \textit{glued} together you should set
  them both to a length of |0pt|.
\end{pgfplotskeylist}

\begin{pgfplotskey}{group/every plot/.style=\marg{style} (initially empty)}
      This style is used on every plot as the first style. It is thus equivalent as \meta{options} in the |groupplot| environment.
\end{pgfplotskey}

\begin{pgfplotskeylist}{%
	group/xlabels at=\mchoice{all,edge bottom,edge top} (initially all),%
	group/ylabels at=\mchoice{all,edge left,edge right} (initially all)}
  In order to determine which plots get labels typeset one can use these keys. By default all axes get typeset normally and thus have both $x$ and
  $y$ axis labels. 
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{groupplot}[
		group style={
			group name=my plots,
			group size=2 by 2,
			xlabels at=edge bottom,
			ylabels at=edge left,
		},
		footnotesize,
		width=4cm,
		height=4cm,
		%
		xlabel=time $t$ / h,
		ylabel=$c$ / mol/L,
	]
	\nextgroupplot
		\addplot coordinates{(0,0) (1,2) (2,1)};
	\nextgroupplot
		\addplot coordinates{(0,0) (1,2) (2,1)};
	\nextgroupplot
		\addplot coordinates{(0,0) (1,2) (2,1)};
	\nextgroupplot
		\addplot coordinates{(0,0) (1,2) (2,1)};
	\end{groupplot}
\end{tikzpicture}
\end{codeexample}
In the example above, only the bottom row gets the label defined in the beginning |groupplot|-environment on the $x$ axis and only the first column of plots gets labels on the
$y$ axis on their left side. These keys are especially handy when using \textit{glued} plots.
\end{pgfplotskeylist}

\begin{pgfplotskeylist}{%
	group/xticklabels at=\mchoice{all,edge top,edge bottom} (initially all),%
	group/yticklabels at=\mchoice{all,edge left,edge right} (initially all)}
  In order to determine which plots get tick labels typeset one can use these keys. By default all axes gets typeset normally and thus have both $x$ and
  $y$ axis tick labels. If one sets

\begin{codeexample}[code only]
\pgfplotsset{group/xticklabels at=edge bottom,group/yticklabels at=edge right}
\end{codeexample}
only the bottom row gets tick labels on the $x$ axis and only the last column gets tick labels on the $y$ axis on their right side. These keys are
specially handy when using \textit{glued} plots.

	Keep in mind that this is implies the same ticks for all plots.
\end{pgfplotskeylist}

\begin{pgfplotskeylist}{%
	group/x descriptions at=\mchoice{all,edge top,edge bottom} (initially all),%
	group/y descriptions at=\mchoice{all,edge left,edge right} (initially all)}
  These are simply a short hand for using both |xticklabels at| and |xlabels at| simultaneously:

% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{groupplot}[
		group style={
			group name=my plots,
			group size=2 by 2,
			%
			x descriptions at=edge bottom,
			y descriptions at=edge right,
			horizontal sep=0.5cm,
			vertical sep=0.5cm,
		},
		footnotesize,
		width=4cm,
		height=4cm,
		%
		xlabel=time $t$ / h,
		ylabel=$c$ / mol/L,
	]
	\nextgroupplot
		\addplot coordinates{(0,0) (1,2) (2,1)};
	\nextgroupplot
		\addplot coordinates{(0,0) (1,2) (2,1)};
	\nextgroupplot
		\addplot coordinates{(0,0) (1,2) (2,1)};
	\nextgroupplot
		\addplot coordinates{(0,0) (1,2) (2,1)};
	\end{groupplot}
\end{tikzpicture}
\end{codeexample}

Here, |x descriptions at=edge bottom| yields that $x$ descriptions (|xlabel| and |xticklabel|) are only used for the lowest row. Furthermore, |y descriptions at=edge right| places $y$ descriptions only for the rightmost column. Consider modifying the |horizontal sep| and |vertical sep| for your needs.

	As for |xticklabels at|, usage of this key implies the same ticks for all plots.

	This might \emph{require} |compat=1.3| (or newer).
\end{pgfplotskeylist}

\begin{pgfplotskey}{group/group name=\marg{name} (initially group)}
  This sets what you can refer the plots to after typesetting. Thus you can use their anchors later. See the following example
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
\begin{tikzpicture}
  \begin{groupplot}[group style={
        group name=my plots,group size=2 by 2},
    width=4cm,height=4cm]
    \nextgroupplot
    \addplot coordinates{(0,0) (1,2) (2,1)};
    \nextgroupplot
    \addplot coordinates{(0,0) (1,2) (2,1)};
    \nextgroupplot
    \addplot coordinates{(0,0) (1,2) (2,1)};
    \nextgroupplot
    \addplot coordinates{(0,0) (1,2) (2,1)};      
  \end{groupplot}
  \draw (my plots c1r1.east) 
  	circle (3pt) node {East};
  \draw (my plots c2r1.north) 
  	circle (3pt) node {north};
  \draw (my plots c1r2.center) 
  	circle (3pt) node {center};
  \draw (my plots c2r2.north west) 
  	circle (3pt) node {North west};
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}

\begin{pgfplotskey}{group/empty plot/.style=\marg{style} (initially /pgfplots/hide axis)}
  This key can be used as an option to the command |\nextgroupplot|. This makes the next plot invisible (only the axes) but maintains it anchors and
  name. If you want it to behave in another style then you can redefine it. Consider the same example as before.
% \usepgfplotslibrary{groupplots}
\begin{codeexample}[]
\begin{tikzpicture}
  \begin{groupplot}[group style={
        group name=my plots,group size=2 by 2},
    width=4cm,height=4cm]
    \nextgroupplot[group/empty plot]
    \nextgroupplot
    \addplot coordinates{(0,0) (1,2) (2,1)};
    \nextgroupplot
    \addplot coordinates{(0,0) (1,2) (2,1)};
    \nextgroupplot
    \addplot coordinates{(0,0) (1,2) (2,1)};      
  \end{groupplot}
  \draw (my plots c1r1.east)
  	circle (3pt) node {East};
  \draw (my plots c2r1.north)
  	circle (3pt) node {north};
  \draw (my plots c1r2.center)
  	circle (3pt) node {center};
  \draw (my plots c2r2.north west) 
  	circle (3pt) node {North west};
\end{tikzpicture}
\end{codeexample}
Notice that you need to call a |\nextgroupplot| againwards to jump to the next plot. 
\end{pgfplotskey}
}