summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex
blob: 4c79e5d593c612295989dec2f1103b1ad46ce42d (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
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Package pgfplots.sty documentation. 
%
% Copyright 2007/2008 by Christian Feuersaenger.
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
% 
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
% 
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\input{pgfplots.preamble.tex}
%\RequirePackage[german,english,francais]{babel}

\def\matlabcolormaptext{This colormap is similar to one shipped with Matlab (tm) under a similar name.}

\IfFileExists{tikzlibraryspy.code.tex}{%
\usetikzlibrary{spy}
}{%
	\message{ERROR: tikz SPY library NOT available. The manual will only compile partially.^^J}%
}%

\usepgfplotslibrary{%
	ternary,
	smithchart,
	patchplots,
	polar,
	colormaps,
}
\pgfqkeys{/codeexample}{%
	every codeexample/.append style={
		/pgfplots/every ternary axis/.append style={
			/pgfplots/legend style={fill=graphicbackground},
		}
	},
	tabsize=4,
}

\pgfplotsmanualexternalexpensivetrue

%\usetikzlibrary{external}
%\tikzexternalize[prefix=figures/]{pgfplots}

\title{%
	Manual for Package \PGFPlots\\
	{\small 2D/3D Plots in \LaTeX, Version \pgfplotsversion}\\
	{\small\href{http://sourceforge.net/projects/pgfplots}{http://sourceforge.net/projects/pgfplots}}
	%\\{\small Attention: you are using an unstable development version.}
}

%\includeonly{pgfplots.libs}


\begin{document}

\def\plotcoords{%
\addplot coordinates {
(5,8.312e-02)    (17,2.547e-02)   (49,7.407e-03)
(129,2.102e-03)  (321,5.874e-04)  (769,1.623e-04)
(1793,4.442e-05) (4097,1.207e-05) (9217,3.261e-06)
};

\addplot coordinates{
(7,8.472e-02)    (31,3.044e-02)    (111,1.022e-02)
(351,3.303e-03)  (1023,1.039e-03)  (2815,3.196e-04)
(7423,9.658e-05) (18943,2.873e-05) (47103,8.437e-06)
};

\addplot coordinates{
(9,7.881e-02)     (49,3.243e-02)    (209,1.232e-02)
(769,4.454e-03)   (2561,1.551e-03)  (7937,5.236e-04)
(23297,1.723e-04) (65537,5.545e-05) (178177,1.751e-05)
};

\addplot coordinates{
(11,6.887e-02)    (71,3.177e-02)     (351,1.341e-02)
(1471,5.334e-03)  (5503,2.027e-03)   (18943,7.415e-04)
(61183,2.628e-04) (187903,9.063e-05) (553983,3.053e-05)
};

\addplot coordinates{
(13,5.755e-02)     (97,2.925e-02)     (545,1.351e-02)
(2561,5.842e-03)   (10625,2.397e-03)  (40193,9.414e-04)
(141569,3.564e-04) (471041,1.308e-04) 
(1496065,4.670e-05)
};
}%
\maketitle
\begin{abstract}%
\PGFPlots\ draws high--quality function plots in normal or logarithmic scaling with a user-friendly interface directly in \TeX. The user supplies axis labels, legend entries and the plot coordinates for one or more plots and \PGFPlots\ applies axis scaling, computes any logarithms and axis ticks and draws the plots. It supports line plots, scatter plots, piecewise constant plots, bar plots, area plots, mesh-- and surface plots, patch plots, contour plots, quiver plots, histogram plots, polar axes, ternary diagrams, smith charts and some more. It is based on Till Tantau's package \PGF/\Tikz.
\end{abstract}
\tableofcontents
\section{Introduction}
This package provides tools to generate plots and labeled axes easily. It draws normal plots, logplots and semi-logplots, in two and three dimensions. Axis ticks, labels, legends (in case of multiple plots) can be added with key-value options. It can cycle through a set of predefined line/marker/color specifications. In summary, its purpose is to simplify the generation of high-quality function and/or data plots, and solving the problems of
\begin{itemize}
	\item consistency of document and font type and font size,
	\item direct use of \TeX\ math mode in axis descriptions,
	\item consistency of data and figures (no third party tool necessary),
	\item inter-document consistency using preamble configurations and styles.
\end{itemize}
Although not necessary, separate |.pdf| or |.eps| graphics can be generated using the |external| library developed as part of \Tikz.

You are invited to use \PGFPlots\ for visualization of medium sized data sets in two and three dimensions.


\section[About PGFPlots: Preliminaries]{About {\normalfont\PGFPlots}: Preliminaries}
This section contains information about upgrades, the team, the installation (in case you need to do it manually) and troubleshooting. You may skip it completely except for the upgrade remarks.

\PGFPlots\ is built completely on \Tikz/\PGF. Knowledge of \Tikz\ will simplify the work with \PGFPlots, although it is not required.

However, note that this library requires at least \PGF\ version $2.00$. At the time of this writing, many \TeX-distributions still contain the older \PGF\ version $1.18$, so it may be necessary to install a recent \PGF\ prior to using \PGFPlots.

\subsection{Components}
\PGFPlots\ comes with two components:
\begin{enumerate}
	\item the plotting component (which you are currently reading) and
	\item the \PGFPlotstable\ component which simplifies number formatting and postprocessing of numerical tables. It comes as a separate package and has its own manual \href{file:pgfplotstable.pdf}{pgfplotstable.pdf}.
\end{enumerate}

\subsection{Upgrade remarks}
This release provides a lot of improvements which can be found in all detail in \texttt{ChangeLog} for interested readers. However, some attention is useful with respect to the following changes.

\subsubsection{New Optional Features}
\begin{enumerate}
	\item \PGFPlots\ 1.4 has fixed several smaller bugs which might produce differences of about $1$--$2\text{pt}$ compared to earlier releases. If you experience problems, use |\pgfplotsset{compat=1.3}|.

	\item \PGFPlots\ 1.3 comes with user interface improvements. The technical distinction between ``behavior options'' and ``style options'' of older versions is no longer necessary (although still fully supported).

	\item \PGFPlots\ 1.3 has a new feature which allows to \emph{move axis labels tight to tick labels} automatically.

	Since this affects the spacing, it is not enabled be default.

	Use
\begin{codeexample}[code only]
\usepackage{pgfplots}
\pgfplotsset{compat=1.4}
\end{codeexample}
	in your preamble to benefit from the improved spacing\footnote{The |compat=1.3| setting is necessary for new features which move axis labels around like reversed axis. However, \PGFPlots\ will still work as it does in earlier versions, your documents will remain the same if you don't set it explicitly.}.
	Take a look at the next page for the precise definition of |compat|.

	\item \PGFPlots\ 1.3 now supports reversed axes. It is no longer necessary to use workarounds with negative units.
\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/,}{}}

	Take a look at the |x dir=reverse| key.

	Existing workarounds will still function properly. Use |\pgfplotsset{compat=1.3}| together with |x dir=reverse| to switch to the new version.
\end{enumerate}

\subsubsection{Old Features Which May Need Attention}
\begin{enumerate}
	\item The |scatter/classes| feature produces proper legends as of version 1.3. This may change the appearance of existing legends of plots with |scatter/classes|.

	\item Due to a small math bug in \PGF\ $2.00$, you \emph{can't} use the math expression `|-x^2|'. It is necessary to use `|0-x^2|' instead. The same holds for
		`|exp(-x^2)|'; use `|exp(0-x^2)|' instead.

		This will be fixed with \PGF\ $>2.00$.

	\item Starting with \PGFPlots\ $1.1$, |\tikzstyle| should \emph{no longer be used} to set \PGFPlots\ options.
	
	Although |\tikzstyle| is still supported for some older \PGFPlots\ options, you should replace any occurance of |\tikzstyle| with |\pgfplotsset{|\meta{style name}|/.style={|\meta{key-value-list}|}}| or the associated |/.append style| variant. See Section~\ref{sec:styles} for more detail.
\end{enumerate}
I apologize for any inconvenience caused by these changes.

\begin{pgfplotskey}{compat=\mchoice{1.5,1.4,1.3,pre 1.3,default,newest} (initially default)}
	The preamble configuration 
\begin{codeexample}[code only]
\usepackage{pgfplots}
\pgfplotsset{compat=1.4}
\end{codeexample}
	allows to choose between backwards compatibility and most recent features.

	\PGFPlots\ version 1.5 with |compat=1.5| or |compat=newest| enables |log origin=0|. Older versions keep |log origin=infty|.

	\PGFPlots\ version 1.4 with |compat=1.4| or |compat=newest| fixes some small bugs related to axis scaling. This might lead to differences of $1$--$2\text{pt}$ compared to earlier versions. Use the choice |1.3| (or earlier) to disable these fixes.

	\PGFPlots\ version 1.3 with |compat=1.3| comes with new features which may lead to significiantly different spacings compared to earlier versions:
	\begin{enumerate}
		\item Version 1.3 comes with the |xlabel near ticks| feature which places (in this case $x$) axis labels ``near'' the tick labels, taking the size of tick labels into account.
		
		Older versions used |xlabel absolute|, i.e.\ an absolute distance between the axis and axis labels (now matter how large or small tick labels are).

		The initial setting \emph{keeps backwards compatibility}.

		You are encouraged to use
\begin{codeexample}[code only]
\usepackage{pgfplots}
\pgfplotsset{compat=1.4}
\end{codeexample}
		in your preamble.
		
		\item Version 1.3 fixes a bug with |anchor=south west| which occurred mainly for reversed axes: the anchors where upside--down. This is fixed now.

		
		If you have written some workaround and want to keep it going, use

		|\pgfplotsset{compat/anchors=pre 1.3}|\pgfmanualpdflabel{/pgfplots/compat/anchors}{} 

		to disable the bug fix.
	\end{enumerate}

	Occasionally, you might want to use different versions in the same document. Then, provide
\begin{codeexample}[code only]
\begin{figure}
	\pgfplotsset{compat=1.4}
	...
	\caption{...}
\end{figure}
\end{codeexample}
	\noindent in order to restrict the compatibility setting to the actual context (in this case, the |figure| environment.

	Use |\pgfplotsset{compat=default}| to restore the factory settings.

	The setting |\pgfplotsset{compat=newest}| will always use features of the most recent version. This might result in small changes in the document's appearance.
\end{pgfplotskey}

\subsection{The Team}
\PGFPlots\ has been written mainly by Christian Feuersänger with many improvements of Pascal Wolkotte and Nick Papior Andersen as a spare time project. We hope it is useful and provides valuable plots.

If you are interested in writing something but don't know how, consider reading the auxiliary manual \href{file:TeX-programming-notes.pdf}{TeX-programming-notes.pdf} which comes with \PGFPlots. It is far from complete, but maybe it is a good starting point (at least for more literature).

\subsection{Acknowledgements}
I thank God for all hours of enjoyed programming. I thank Pascal Wolkotte and Nick Papior Andersen for their programming efforts and contributions as part of the development team. I thank Stefan Tibus, who contributed the |plot shell| feature. I thank Tom Cashman for the contribution of the |reverse legend| feature. Special thanks go to Stefan Pinnow whose tests of \PGFPlots\ lead to numerous quality improvements. Furthermore, I thank Dr.~Schweitzer for many fruitful discussions and Dr.~Meine for his ideas and suggestions. Special thanks go to Markus B\"ohning for proof-reading all the manuals of \PGF, \PGFPlots, and \PGFPlotstable. Thanks as well to the many international contributors who provided feature requests or identified bugs or simply improvements of the manual!

Last but not least, I thank Till Tantau and Mark Wibrow for their excellent graphics (and more) package \PGF\ and \Tikz, which is the base of \PGFPlots.

\include{pgfplots.install}%
\include{pgfplots.intro}%
\include{pgfplots.reference}%
\include{pgfplots.libs}%
\include{pgfplots.resources}%
\include{pgfplots.importexport}%
\include{pgfplots.basic.reference}%

\printindex

\bibliographystyle{abbrv} %gerapali} %gerabbrv} %gerunsrt.bst} %gerabbrv}% gerplain}
\nocite{pgfplotstable}
\nocite{programmingnotes}
\bibliography{pgfplots}
\end{document}