☰
tikz.dev / PGFplots Manual

Manual for Package pgfplots
2D/3D Plots in LA, Version 1.18.1
http://sourceforge.net/projects/pgfplots

About PGFPlots: Preliminaries

\(\newcommand{\footnotename}{footnote}\) \(\def \LWRfootnote {1}\) \(\newcommand {\footnote }[2][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\newcommand {\footnotemark }[1][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\let \LWRorighspace \hspace \) \(\renewcommand {\hspace }{\ifstar \LWRorighspace \LWRorighspace }\) \(\newcommand {\mathnormal }[1]{{#1}}\) \(\newcommand \ensuremath [1]{#1}\) \(\newcommand {\LWRframebox }[2][]{\fbox {#2}} \newcommand {\framebox }[1][]{\LWRframebox } \) \(\newcommand {\setlength }[2]{}\) \(\newcommand {\addtolength }[2]{}\) \(\newcommand {\setcounter }[2]{}\) \(\newcommand {\addtocounter }[2]{}\) \(\newcommand {\arabic }[1]{}\) \(\newcommand {\number }[1]{}\) \(\newcommand {\noalign }[1]{\text {#1}\notag \\}\) \(\newcommand {\cline }[1]{}\) \(\newcommand {\directlua }[1]{\text {(directlua)}}\) \(\newcommand {\luatexdirectlua }[1]{\text {(directlua)}}\) \(\newcommand {\protect }{}\) \(\def \LWRabsorbnumber #1 {}\) \(\def \LWRabsorbquotenumber "#1 {}\) \(\newcommand {\LWRabsorboption }[1][]{}\) \(\newcommand {\LWRabsorbtwooptions }[1][]{\LWRabsorboption }\) \(\def \mathchar {\ifnextchar "\LWRabsorbquotenumber \LWRabsorbnumber }\) \(\def \mathcode #1={\mathchar }\) \(\let \delcode \mathcode \) \(\let \delimiter \mathchar \) \(\def \oe {\unicode {x0153}}\) \(\def \OE {\unicode {x0152}}\) \(\def \ae {\unicode {x00E6}}\) \(\def \AE {\unicode {x00C6}}\) \(\def \aa {\unicode {x00E5}}\) \(\def \AA {\unicode {x00C5}}\) \(\def \o {\unicode {x00F8}}\) \(\def \O {\unicode {x00D8}}\) \(\def \l {\unicode {x0142}}\) \(\def \L {\unicode {x0141}}\) \(\def \ss {\unicode {x00DF}}\) \(\def \SS {\unicode {x1E9E}}\) \(\def \dag {\unicode {x2020}}\) \(\def \ddag {\unicode {x2021}}\) \(\def \P {\unicode {x00B6}}\) \(\def \copyright {\unicode {x00A9}}\) \(\def \pounds {\unicode {x00A3}}\) \(\let \LWRref \ref \) \(\renewcommand {\ref }{\ifstar \LWRref \LWRref }\) \( \newcommand {\multicolumn }[3]{#3}\) \(\require {textcomp}\) \( \newcommand {\meta }[1]{\langle \textit {#1}\rangle } \) \(\newcommand {\toprule }[1][]{\hline }\) \(\let \midrule \toprule \) \(\let \bottomrule \toprule \) \(\def \LWRbooktabscmidruleparen (#1)#2{}\) \(\newcommand {\LWRbooktabscmidrulenoparen }[1]{}\) \(\newcommand {\cmidrule }[1][]{\ifnextchar (\LWRbooktabscmidruleparen \LWRbooktabscmidrulenoparen }\) \(\newcommand {\morecmidrules }{}\) \(\newcommand {\specialrule }[3]{\hline }\) \(\newcommand {\addlinespace }[1][]{}\) \(\require {colortbl}\) \(\let \LWRorigcolumncolor \columncolor \) \(\renewcommand {\columncolor }[2][named]{\LWRorigcolumncolor [#1]{#2}\LWRabsorbtwooptions }\) \(\let \LWRorigrowcolor \rowcolor \) \(\renewcommand {\rowcolor }[2][named]{\LWRorigrowcolor [#1]{#2}\LWRabsorbtwooptions }\) \(\let \LWRorigcellcolor \cellcolor \) \(\renewcommand {\cellcolor }[2][named]{\LWRorigcellcolor [#1]{#2}\LWRabsorbtwooptions }\) \(\newcommand {\intertext }[1]{\text {#1}\notag \\}\) \(\let \Hat \hat \) \(\let \Check \check \) \(\let \Tilde \tilde \) \(\let \Acute \acute \) \(\let \Grave \grave \) \(\let \Dot \dot \) \(\let \Ddot \ddot \) \(\let \Breve \breve \) \(\let \Bar \bar \) \(\let \Vec \vec \) \(\newcommand {\nicefrac }[3][]{\mathinner {{}^{#2}\!/\!_{#3}}}\)

2.2Upgrade remarks

This release provides a lot of improvements which can be found in all detail in 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 compatibility level. The precise impact of the compat key, its choices and implications are described in the following sections.

2.2.1New Optional Features

pgfplots has been written with backwards compatibility in mind: old 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.1

Any new features or bugfixes which cause backwards compatibility problems need to be activated manually and explicitly. In order to do so, you should use

\usepackage{pgfplots} \pgfplotsset{compat=1.18}

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 .

Here is a list of changes which are inactive unless one uses a suitable compat level:

  • 1. pgfplots 1.18 and 1.17 have no additional constraints and is the same as 1.16 with respect to compatibility levels.

  • 2. pgfplots 1.16 has no additional constraints and is the same as 1.15 with respect to compatibility levels.

  • 3. pgfplots 1.15 activates 3d log sampling and repairs issues with clip limits for bar plots.

  • 4. pgfplots 1.14 changes the way nonuniform colormaps are handled by the system and activates advanced colormap operations (see of colormap).

  • 5. 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.

  • 6. pgfplots 1.12 activates lua backend and defines boxplot/estimator=Excel.

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

  • 8. pgfplots 1.10 has no differences to 1.9 with respect to compatibility.

  • 9. 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.

  • 10. 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 necessary to repair axis lines=center in three-dimensional axes.

  • 11. pgfplots 1.7 added new options for bar widths defined in terms of axis units. These are enabled with compat=1.7 or higher.

  • 12. 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.

  • 13. pgfplots 1.5.1 interprets circle and ellipse radii as pgfplots coordinates (older versions used pgf 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 pgf as in earlier versions.

  • 14. 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.

  • 15. 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.

  • 16. 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.

  • 17. pgfplots 1.3 has a new feature which allows to 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.

  • 18. pgfplots 1.3 supports reversed axes. It is no longer necessary to use workarounds with negative units.

    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.

1 In case of broken backwards compatibility, we apologize – and ask you to submit a bug report. We will take care of it.

2.2.2Old Features Which May Need Attention

  • 1. 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.

  • 2. Starting with pgfplots 1.1, \tikzstyle should 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{(math image)style name(math image)/.style={(math image)key-value-list(math image)}} or the associated /.append style variant. See Section 4.18 for more detail.

I apologize for any inconvenience caused by these changes.

  • /pgfplots/compat=1.18|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

    \usepackage{pgfplots} \pgfplotsset{compat=1.18}

    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{figure} \pgfplotsset{compat=1.4} ... \caption{...} \end{figure}

    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:

    The value (math image)version(math image) 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 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.