\chapter[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.10$. 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.

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

\section{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.

\subsection{New Optional Features}
\PGFPlots\ has been written with backwards compatibility in mind: old \TeX\ files should compile without modifications and without changes in the appearance. However, new features occasionally lead to a different behavior. In such a case, \PGFPlots\ will deactivate the new feature\footnote{In case of broken backwards compatibility, we apologize -- and ask you to submit a bug report. We will take care of it.}.

Any new features or bugfixes which cause backwards compatibility problems need to be activated \emph{manually} and \emph{explicitly}. In order to do so, you should use 
\begin{codeexample}[code only]
\usepackage{pgfplots}
\pgfplotsset{compat=1.14}
\end{codeexample}
\noindent in your preamble. This will configure the compatibility layer.

You should have at least |compat=1.3|. The suggested value is printed to the |.log| file after running \TeX.

Here is a list of changes which are inactive unless one uses a suitable |compat| level:
\begin{enumerate}
	\item \PGFPlots\ 1.14 changes the way non-uniform colormaps are handled by the system and activates advanced |colormap| operations (see |of colormap|).
	
	\item \PGFPlots\ 1.13 repairs axis labels in polar axis and ensures that the color chosen by |shader=flat| is independent of |z buffer| and |mesh/ordering|. Furthermore, it enables |stack negative=separate| for all stacked bar plots. Older compatibility levels are present to keep workarounds by end-users.
	
	\item \PGFPlots\ 1.12 activates |lua backend| and defines |boxplot/estimator=Excel|.

  \item \PGFPlots\ 1.11 changes the |axis cs|: it is now the default coordinate system. If you write |\draw (1,2) -- (2,2);| \PGFPlots\ will automatically treat it as |\draw (axis cs:1,2) -- (axis cs:2,2);|.

  \item \PGFPlots\ 1.10 has no differences to 1.9 with respect to compatibility.

	\item \PGFPlots\ 1.9 comes with a preset to combine |ybar stacked| and |nodes near coords|. Furthermore, it suppresses empty increments in stacked bar plots. In order to activate the new preset, you have to use |compat=1.9| or higher.

	\item \PGFPlots\ 1.8 comes with a new revision for alignment of label- and tick scale label alignment. Furthermore, it improves the bounding box for |hide axis|. This revision is enabled with |compat=1.8| or higher.
	
	The configuration |compat=1.8| is \emph{nessecary} to repair |axis lines=center| in three--dimensional axes.

	\item \PGFPlots\ 1.7 added new options for bar widths defined in terms of axis units. These are enabled with |compat=1.7| or higher.

	\item \PGFPlots\ 1.6 added new options for more accurate scaling and more scaling options for |\addplot3 graphics|. These are enabled with |compat=1.6| or higher.

	\item \PGFPlots\ 1.5.1 interpretes circle- and ellipse radii as \PGFPlots\ coordinates (older versions used \pgfname\ unit vectors which have no direct relation to \PGFPlots). In other words: starting with version 1.5.1, it is possible to write |\draw circle[radius=5]| inside of an axis. This requires |\pgfplotsset{compat=1.5.1}| or higher. 

	Without this compatibility setting, circles and ellipses use low--level canvas units of \pgfname\ as in earlier versions.

	\item \PGFPlots\ 1.5 uses |log origin=0| as default (which influences logarithmic bar plots or stacked logarithmic plots). Older versions keep |log origin=infty|. This requires |\pgfplotsset{compat=1.5}| or higher.

	\item \PGFPlots\ 1.4 has fixed several smaller bugs which might produce differences of about $1$--$2\text{pt}$ compared to earlier releases. This requires |\pgfplotsset{compat=1.4}| or higher.

	\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).

	This is always activated.

	\item \PGFPlots\ 1.3 has a new feature which allows to \emph{move axis labels tight to tick labels} automatically. This is strongly recommended. It requires |\pgfplotsset{compat=1.3}| or higher.

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

	\item \PGFPlots\ 1.3 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}| or higher together with |x dir=reverse| to switch to the new version.
\end{enumerate}

\subsection{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 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.14,1.13,1.12,1.11,1.10,1.9,1.8,1.7,1.6,1.5.1,1.5,1.4,1.3,pre 1.3,default} (initially default)}
	The preamble configuration 
\begin{codeexample}[code only]
\usepackage{pgfplots}
\pgfplotsset{compat=1.14}
\end{codeexample}
	allows to choose between backwards compatibility and most recent features. This key is designed to be the first encountered \PGFPlots\ key in a document as it prepares global options.

	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).

	See the output of your |.log| file to get a suggested value for |compat|.

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

	Although typically unnecessary, it is also possible to activate only selected changes and keep compatibility to older versions in general:
	\begin{pgfplotskeylist}{%
		compat/path replacement=\meta{version},%
		compat/labels=\meta{version},%
		compat/scaling=\meta{version},%
		compat/scale mode=\meta{version},%
		compat/empty line=\meta{version},%
		compat/plot3graphics=\meta{version},%
		compat/bar nodes=\meta{version},%
		compat/BB=\meta{version},%
		compat/bar width by units=\meta{version},%
		compat/pgfpoint substitution=\meta{version},%
		compat/general=\meta{version}%
	}
	Let us assume that we have a document with |\pgfplotsset{compat=1.3}| and you want to keep it this way.

	In addition, you realized that version 1.5.1 supports circles and ellipses. Then, use
\begin{codeexample}[]
% preamble:
\pgfplotsset{compat=1.3,compat/path replacement=1.5.1}
\begin{tikzpicture}
\begin{axis}[
	extra x ticks={-2,2},
	extra y ticks={-2,2},
	extra tick style={grid=major}]
	\addplot {x};
	\draw (axis cs:0,0) circle[radius=2];
\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	All of these keys accept the possible values of the |compat| key.

	The |compat/path replacement| key controls how radii of circles and ellipses are interpreted.

	The |compat/labels| key controls how axis labels are aligned: either uses adjacent to ticks or with an absolute offset. As of |1.8|, it also enables an entirely new revision of the axis label styles. In most cases, you will see no difference -- but it repairs |axis lines=center| in three--dimensional axes.

	The |compat/scaling| key controls some bugfixes introduced in version 1.4 and 1.6: they might introduce slight scaling differences in order to improve the accuracy.

	The |compat/plot3graphics| controls new features for |\addplot3 graphics|.

	The |compat/scale mode| allows to enable/disable the warning ``The content of your 3d axis has CHANGED compared to previous versions'' because the |axis equal| and |unit vector ratio| features where broken for all versions before~1.6 and have been fixed in~1.6.

	The |compat/empty line| allows to write empty lines into input files in order to generate a jump. This requires |compat=1.4| or newer. See |empty line| for details.

	The |compat/BB| changes to bounding box to be tight even in case of |hide axis|.

	The |compat/bar width by units| allows to express |bar width=1| (i.e.\ in terms of axis units).

	The |compat/bar nodes| activates presets for |ybar stacked| and |nodes near coords|. In addition, it enables |stacked ignores zero| for stacked bar plots.

	The |compat/general| key controls |log origin|, |lua backend|, |enable tick line clipping|, and |boxplot/estimator|.

	The |compat/pgfpoint substitution| key determines if |axis cs| is the default coordinate system (as of 1.11).

	The detailed effects can be seen on the beginning of this section.
	\end{pgfplotskeylist}

	The value \meta{version} can be |default|, a version number, and |newest|. The value |default| is the same as |pre 1.3| (up to insignificant changes). The use of |newest| is strongly \emph{discouraged}: it might cause changes in your document, depending on the current version of \PGFPlots. Please inspect your |.log| file to see suggestions for the best possible version. 
\end{pgfplotskey}

\section{The Team}
\PGFPlots\ has been written mainly by Christian Feuers\"anger 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).

\section{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 J\"urnjakob Dugge for his contribution of |hist/density|, matlab scripts for \verbpdfref{\addplot3} |graphics|, excellent user forum help and helpful bug reports. 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 for his continuous efforts to test \PGFPlots, to discuss requirements, to request features and bug fixes which lead to numerous quality improvements, and to adapt and integrate the |colorbrewer| library. Furthermore, I thank Prof.~Schweitzer for many fruitful discussions and his initial encouragement to start such a package. Thanks to 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 to Vincent A.\ Traag for bringing |colorbrewer| colors to \PGFPlots. 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.


\input pgfplots.install
