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

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

\index{Group library!Subplots}%


\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 this typesetting easy.
\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} gets
  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{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
\textbackslash|nextgroupplot| in order to create the first plot. The \oarg{options} are the options that are supplied to the following plot commands until
the next \textbackslash|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}

Here the various available options of the library resides. 

\begin{pgfplotskey}{group style=group/.cd,\marg{options}}
  This key allows one to faster reach the group options. Some of the options are very similar to the normal commands so they are supplied in another
  subdirectory |group|. So the following are 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}
It can thus decrease the size of your options with out destroying the clearness of where options belong.
\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 determines the total number of plots that can be in one environment |groupplot|. It is thus important not to add more
  \textbackslash|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/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 axis 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.
\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 \textbackslash|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 \textbackslash|nextgroupplot| again after to jump to the next plot. 
\end{pgfplotskey}
