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

One thing which is common to \PGFPlots{} is the key |compat|: it is strongly
suggested to always write it into your |.tex| files. While this key imposes
some work to end-users, it also solves a common requirement: it ensures that
your |.tex| files always result in the same output, even if you install a new
version of \PGFPlots{}. On the other hand, it allows us as maintainers to solve
software defects and introduce changes in behavior, assuming that these changes
only affect documents with a decent |compat|ibility level. The precise impact
of the |compat| key, its choices and implications are described in the
following sections.


\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
%
\input pgfplots.preliminaries.compatcurrent.tmp

%
\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.17 has no additional constraints and is the same as
        1.16 with respect to compatibility levels.
    \item \PGFPlots{} 1.16 has no additional constraints and is the same as
        1.15 with respect to compatibility levels.
    \item \PGFPlots{} 1.15 activates |3d log sampling| and repairs issues
        with |clip limits| for bar plots.
    \item \PGFPlots{} 1.14 changes the way nonuniform 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{necessary} 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 interprets 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 occurrence 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.17,
        1.16,
        1.15,
        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
    %
\input pgfplots.preliminaries.compatcurrent.tmp
    %
    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 |\addplot 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}
