summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex
blob: ed18c1a5ffef55e7449a6486c0da5f3113542ec5 (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
\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} 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{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}

Here the various available options of the library reside. 

\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 has 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 determines 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 axis gets 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 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.

	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 both 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| again after to jump to the next plot. 
\end{pgfplotskey}
}