pgfplots

The Reference

\(\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}}}\)

4.27Layers

It is important that several parts of an axis are drawn “on top” of others. Usually, pgfplots ensures this by drawing them in a suitable sequence (usually background followed by grid lines, followed by tick lines and tick labels, followed by plots and finally axis descriptions). While this works reasonable in most cases, there are cases where more control is desired. One common use case is if multiple axes shall be drawn into the same picture: here, the sequence from above should be applied to all involved axes simultaneously.

4.27.1Summary¶

This section is the technical reference for using and customizing layered graphics in pgfplots. As such, it is hard reading.

For most purposes, the following is completely sufficient for you: If you want to enable layered graphics, put the following statement into the tikzpicture which is supposed to have layered graphics:


                \begin{tikzpicture}


                        \pgfplotsset{set layers}


                    \begin{axis}

...


                    \end{axis}


                    % perhaps a second axis which should
                use the same layers?


                    \begin{axis}

...


                    \end{axis}


                \end{tikzpicture}

This enables layered graphics for that specific tikzpicture.

You may want layered graphics if you have multiple axes in the same picture, of if you have specific needs for your plot.

Consider reading on layer if you want to move particular elements of your axis to a different layer.

4.27.2Using Predefined Layers¶

The main key to control layered graphics with pgfplots is set layers:

/pgfplots/set layers=none|layer configuration name (initially none) ¶

This key enables layered graphics for either the current axis or for all following axes.

Enabling layered graphics has the effect that the order in which graphical elements are given is unrelated to the ordering in which they will be drawn. The main benefit is if you have multiple axes in the same figure: the axes can share the same layers.

The invocation set layers=none disables layered graphics.

The invocation set layers (without equal sign and without arguments) is the same as if you would write set layers=default.

In all other cases, set layers expects a (math image) layer configuration name. There are two predefined configurations available (the prefix /pgfplots/layers/ is optional):

/pgfplots/layers/standard(no value) ¶

A layer configuration which defines the layers axis background, axis grid, axis ticks, axis lines, axis tick labels, main, axis descriptions, axis foreground. They are drawn in the order of appearance.

/pgfplots/layers/axis on top(no value) ¶

A layer configuration which uses the same layer names as layers/standard, but with a different sequence: axis background, main, axis grid, axis ticks, axis lines, axis tick labels, axis descriptions, axis foreground.

This layer is automatically used if the key axis on top is used together with set layers= (math image) any layer configuration name.

As soon as the key set layers= (math image) layer configuration name is encountered, pgfplots starts the pgf command \pgfsetlayers{layer names} with the layer names of the respective configuration. Usually, this replaces the current layer configuration of the embedding tikzpicture. Furthermore, set layers stores the name of (math image) layer configuration name such that every following axis knows how to map graphical elements to layer names.

There is one huge difference to any other key which tunes pgfplots: layer configurations are properties of a complete tikzpicture whereas any other option affects only axis objects and their contents. Layers, however, affect every graphical element of the embedding picture. Due to this property, layer configurations need to be given at one of several supported positions:

1. Directly within the picture:

\begin{tikzpicture} \pgfplotsset{set layers=default} \begin{axis} ... \end{axis} \end{tikzpicture}

This option explicitly tells the reader of your source code that a significant portion of your picture has been changed: the complete picture has and uses a layer configuration name (in this case default).
2. As option for one or more axes which is/are directly within the picture:

\begin{tikzpicture} \begin{axis}[set layers] ... \end{axis} \end{tikzpicture}

Here, pgfplots implicitly communicates its layer configuration to the enclosing tikzpicture. Thus, the effect of set layers is not local to an axis; it survives until \end{tikzpicture}. Any other option only survives until \end{axis}.

In this case, only the last activated layer configuration will apply to the picture.

Limitation: no environments or local TeX groups allowed.

Standard usages as within the examples of this manual will always work. But since the layer name configuration is essentially part of a pgf picture (at a low level), one cannot arbitrarily set them; pgf will complain if they are changed within some nested TeX groups or LaTeX environments. Typically, you will never need to worry about this.

In short, the following examples are forbidden because the axis is within locally nested groups.


                  \begin{tikzpicture}


                      {% FORBIDDEN! Consider using case
                  (1) above!


                          \begin{axis}[set layers]

...


                          \end{axis}

}


                  \end{tikzpicture}


                  \begin{tikzpicture}


                      \begin{scope} % FORBIDDEN!
                  Consider using case (1) above!


                          \begin{axis}[set layers]

...


                          \end{axis}

\end{scope}


                  \end{tikzpicture}

These examples are forbidden because the layer configuration will be cleared by the ‘}’ of the first forbidden example and by the ‘\end{scope}’ of the second example. A solution would be one of the different placement options (i.e. choice 1 or 3).

3. outside of any picture:


                    \pgfplotsset{set layers=default}


                    \begin{tikzpicture}


                        \begin{axis}

...


                        \end{axis}


                    \end{tikzpicture}

This choice configures the layer configuration for every following tikzpicture.

Limitation: axis alignment restricted to inner anchors.

This applies only if you changed the default value of anchor (which is anchor=south west). Any axis which uses layered graphics should use one of the following values of anchor: north, north west, west, south west, south, south east, east, north east, north, center, origin, above origin, left of origin, right of origin, below origin. In case you really need another anchor, pgfplots requires the use of cell picture=true, causing the layers to be local for that specific axis.

The technical background for this limitation is a hen-and-egg problem: outer anchors (like outer south west) are only available after the complete axis has been generated – and layers can only be drawn after each drawing instruction has been issued. The technical keys for further reading are cell picture=false or cell picture=if necessary (one of them is active for layered graphics).

\pgfplotssetlayers ¶

An alias for \pgfplotsset{set layers}. It activates the layers/default layer configuration.

\pgfplotssetlayers{ (math image) layer configuration name}

An alias for \pgfplotsset{set layers={ (math image) layer configuration name}}.

Key handler (math image) key/.define layer set={ordered layer names}{style definitions} ¶

Allows to define a new layer set configuration named (math image) key. Afterwards, key can be specified as argument to set layers as follows:

• if key has the type /pgfplots/layers/name, you can write set layers=name.

Example: /pgfplots/layers/my layers/.define layer set=\(\cdots \) can be activated by means of the shorthand notation set layers=my layers.
• if key is an arbitrary key path, set layers expects the fully qualified key name.

Example: /user/my layers/.define layer set=\(\cdots \) can be activated by means of the full value set layers=/user/my layers.

The first argument (math image) ordered layer names is a comma-separated list of layer names. The names are arbitrary, and \pgfdeclarelayer will be called for every encountered argument.⁷⁹ There is just one “magic” name: the layer main should be part of every (math image) ordered layer names as it will contain every graphical element which is not associated with a specific layer.

The second argument (math image) style definitions contains options – just as if you would have written key/.style={style definitions}. The style definitions are supposed to contain pgfplots style redefinitions which make use of each encountered element of (math image) ordered layer names. This is probably best explained by an example: the layers/standard layer configuration is defined by


                    \pgfplotsset{


                        layers/standard/.define layer set={


                            axis
                    background,axis
                    grid,axis ticks,axis
                    lines,axis tick
                    labels,


                            pre
                    main,main,axis
                    descriptions,axis
                    foreground

}{


                            grid
                    style=
                            {/pgfplots/on
                    layer=axis grid},


                            tick
                    style=
                            {/pgfplots/on
                    layer=axis ticks},


                            axis
                    line style=
                       {/pgfplots/on layer=axis lines},


                            label
                    style=
                           {/pgfplots/on
                    layer=axis descriptions},


                            legend
                    style=
                          {/pgfplots/on
                    layer=axis descriptions},


                            title
                    style=
                           {/pgfplots/on
                    layer=axis descriptions},


                            colorbar
                    style=     {/pgfplots/on layer=axis
                    descriptions},


                            ticklabel
                    style=    {/pgfplots/on layer=axis tick
                    labels},


                            axis
                    background@ style={/pgfplots/on layer=axis background},


                            3d
                    box foreground style={/pgfplots/on layer=axis foreground},

}, }

This definition declares a couple of layers, and it adjusts pgfplots styles by adding on layer commands. The arguments for on layer are the elements of (math image) ordered layer names.

Note that if you have an element in (math image) ordered layer names which is never referenced inside of style definitions, this layer will always be empty. In other words: the only reference to the names in ordered layer names is style definitions (math image) , pgfplots has no hard-coded magic layer names (except for main as explained above).

Since the second argument (math image) style definitions defines key to be a normal style key, one can simply use key in order to set style definitions. This allows to inherit them. For example, the layers/axis on top layer configuration is defined by means of


                    \pgfplotsset{


                        /pgfplots/layers/axis on top/.define layer set={


                            axis
                    background,pre main,main,axis
                    grid,axis ticks,axis
                    lines,


                            axis
                    tick labels,axis
                    descriptions,axis
                    foreground


                        }{/pgfplots/layers/standard},

}

i.e. it only redefines the sequence of the layers and reuses the style definitions of layers/standard.

Any number of layer configurations can be defined.

⁷⁹ To be more precise: set layers calls \pgfdeclarelayer when it uses (math image) ordered layer names.

4.27.3Changing the Layer of Graphical Elements¶

There are a couple of keys which change the layer of a graphical element.

/pgfplots/on layer={ (math image) layer name} ¶

Providing this key somewhere in a pgfplots style or inside of a pgfplots axis will change the layer for all graphical elements for which the style applies.

For example,

...


                    \begin{axis}[set layers,grid style={/pgfplots/on layer=axis foreground}]

...

will change the layer for any grid lines to axis foreground.

The argument (math image) layer name is expected to be part of the current layer configuration, i.e. the argument of set layers should contain it.

Note that if you have two plots with different values of on layer, you may also want to enable clip mode=individual or to deactivate clipping altogether using clip=false. Clipping options need to be provided as option to the axis, not to the plot. The technical background is that clip paths needs to be replicated for the layer on which the drawing is supposed to happen – otherwise they will be applied to the wrong layer.

/pgfplots/mark layer=auto|like plot|layer name (initially auto) ¶

An advanced key which defines the layer for plot marks. It is typically the best choice to leave it at auto.

If you write \addplot[on layer= (math image) layer name], the layer will be used for the complete plot. Plot marks are treated with special care, so you can define an own layer for plot marks.

The initial choice auto will automatically define a “suitable” choice, leaving the responsibility with pgfplots. Here, “suitable” means to respect clip mode and clip marker paths in a way such that plot marks will not be clipped even though the default layer for your plot will be clipped.

The choice like plot will pack the marks onto the same layer as the plot they belong to. This might cause clipped markers, i.e. markers which are only displayed partially if they are close to the boundary of the axis.

Finally, one can provide any (math image) layer name, just as for on layer – but the layer can be different from the layer used for the plot.