summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex479
1 files changed, 447 insertions, 32 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
index 746c007d1eb..f2b4ad810de 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
@@ -454,7 +454,7 @@ As all other axis descriptions, the code can use $(0,0)$ to access the lower lef
Legends can be generated in two ways: the first is to use |\addlegendentry| or |\legend| inside of an axis. The other method is to use the key |legend entries|.
-\begin{command}{\addlegendentry\marg{name}}
+\begin{command}{\addlegendentry\oarg{options}\marg{name}}
Adds a single legend entry to the legend list. This will also enable legend drawing.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -479,11 +479,12 @@ Adds a single legend entry to the legend list. This will also enable legend draw
\end{codeexample}
It does not matter where |\addlegendentry| commands are placed, only the sequence matters. You will need one |\addlegendentry| for every |\addplot| command (unless you prefer an empty legend).
+The optional \meta{options} affect how the text is drawn; they apply only for this particular description text. For example, |\addlegendentry[red]{Text}| would yield a red legend text. Behind the scenes, the text is placed with |\node|\oarg{options} \marg{name}|;|, so \meta{options} can be any \Tikz\ option which affects nodes.
Using |\addlegendentry| disables the key |legend entries|.
\end{command}
-\begin{command}{\addlegendentryexpanded\marg{\TeX\ text}}
+\begin{command}{\addlegendentryexpanded\oarg{options}\marg{\TeX\ text}}
A variant of |\addlegendentry| which provides a method to deal with macros inside of \meta{\TeX\ text}.
Suppose \meta{\TeX\ text} contains some sort of parameter which varies \emph{for every plot}. Moreover, you like to use a loop to generate the plots. Then, it is simpler to use |\addlegendentryexpanded|:
@@ -528,12 +529,17 @@ Two different delimiters are supported:
\begin{codeexample}[code only]
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{codeexample}
- These lists are processed using the \PGF\ |\foreach| command.
+ These lists are processed using the \PGF\ |\foreach| command and are quite powerful.
+
+ The |\foreach| command supports a dots--notation to denote ranges like |\legend{1,2,...,5}| or even |\legend{$x^1$,$x^...$,$x^d$}|.
+
+ \paragraph{Attention with periods:} to avoid confusion with the dots |...| notation, you may need to encapsulate a legend entry containing periods by curly braces: |\legend{{ML spcm.},{CW spcm.},{ML AC}}| (or use the |\\| delimiter, see below).
+
\item It is also possible to delimit the list by `|\\|'. In this case, the \emph{last element must be terminated} by |\\| as well:
\begin{codeexample}[code only]
\legend{$a=1, b=2$\\,$a=2, b=3$\\$a=3, b=5$\\}
\end{codeexample}
- This syntax simplifies the use of `|,|' inside of legend entries.
+ This syntax simplifies the use of `|,|' inside of legend entries, but it does not support the dots--notation.
\end{enumerate}
The short marker/line combination shown in legends is acquired from the \marg{style options} argument of |\addplot|.
@@ -563,20 +569,20 @@ Using |\legend| overwrites any other existing legend entries.
\end{tikzpicture}
\end{codeexample}
Please be careful with whitespaces in \marg{comma separated list}: they will contribute to legend entries. Consider using `|%|' at the end of each line in multiline arguments (the end of line character is also a whitespace in \TeX).
-\end{pgfplotskey}
-
-
-\begin{command}{\addlegendimage\marg{options}}
- Adds a further ``plot style'' for legend creation.
- Each |\addplot| command appends its plot style options to a list, and |\addlegendimage| adds \meta{options} to the very same list.
-
- Thus, the effect is as if you had provided |\addplot|\oarg{options}, but |\addlegendimage| bypasses all the logic usually associated with a plot. In other words: except for the legend, the state of the axis remains as if the command would not have been drawn. Not even the current plot's index is advanced, making |\addlegendimage| compatible with any plot styles like |ybar|.
-
- Use |\addlegendimage| to provide custom styles into legends, for example to document custom |\draw| commands inside of an axis.
+ Just as for |\addlegendentry|, it is possible to provide \oarg{options} to single descriptions. To do so, place the options in square brackets right before the text:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[legend entries={$x$,[red]$x^2$,$x^3$}]
+ \addplot {x};
+ \addplot {x^2};
+ \addplot {x^3};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ If the square brackets contain a comma, you can enclose the complete entry in curly braces like |{[red,font=\Huge]Text}| (or you can use the `|\\|' delimiters).
+\end{pgfplotskey}
- You can call |\label| after |\addlegendimage| just as for a normal style.
-\end{command}
\subsubsection{Legend Appearance}
@@ -770,6 +776,46 @@ Whenever possible, consider using |/.append style| to keep the default styles ac
\end{codeexample}
\end{pgfplotskey}
+
+\begin{pgfplotskey}{legend cell align=\mchoice{left,right,center} (initially center)}
+ These keys provide horizontal alignment of legend cells.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[legend cell align=left,
+ legend pos=outer north east]
+\addplot coordinates {(0,0) (1,1)};
+\addplot coordinates {(0,1) (1,2)};
+\addplot coordinates {(0,2) (1,3)};
+\legend{a,fine,legend}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[legend cell align=center,
+ legend pos=outer north east]
+\addplot coordinates {(0,0) (1,1)};
+\addplot coordinates {(0,1) (1,2)};
+\addplot coordinates {(0,2) (1,3)};
+\legend{a,fine,legend}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[legend cell align=right,
+ legend pos=outer north east]
+\addplot coordinates {(0,0) (1,1)};
+\addplot coordinates {(0,1) (1,2)};
+\addplot coordinates {(0,2) (1,3)};
+\legend{a,fine,legend}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ They are actually just styles for commonly used alignment choices: the choice |left| is equivalent to |legend style={cells={anchor=west}}|, the choice |right| is equivalent to |legend style={cells={anchor=east}}| and |center| to |legend style={cells={anchor=center}}|. Using different values allows more control over cell alignment.
+\end{pgfplotskey}
}
\begin{pgfplotskey}{legend columns=\marg{number} (default 1)}
@@ -785,12 +831,28 @@ Configures where the small line specifications will be drawn: left of the descri
\begin{stylekey}{/pgfplots/every legend image post}
\label{key:legendimagepost}
A style which can be used to provide drawing options to every small legend image. These options apply after |current plot style| has been set, allowing users different line styles for legends than for plots.
+
+ For example, suppose you have a line plot and you plot selected markers on top of it (in the same color). Then, you may want to draw just a \emph{single} legend entry (which should contain both the line \emph{and} the markers). The following example shows a solution:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[legend image post style={mark=*}]
+ \addplot+[only marks,forget plot]
+ coordinates {(0.5,0.75) (1,1) (1.5,0.75)};
+ \addplot+[mark=none,smooth,domain=0:2]
+ {-x*(x-2)};
+ \addlegendentry{Parable}
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ \noindent The example has two |\addplot| commands, one for the line and one for markers. Due to the |forget plot| option, the marker plot (the first one) doesn't advance the |cycle list|. The axis has only one legend entry, and since |legend image post style={mark=*}| has been used, the legend has a plot mark as well. Due to the |forget plot| option, the marker plot will not get a separate legend label.
\end{stylekey}
+\pgfplotsshortstylekey legend image post style=every legend image post\pgfeov
+
\begin{pgfplotscodekey}{legend image code}
\label{opt:legend:image:code}
Allows to replace the default images which are drawn inside of legends. When this key is evaluated, the current plot specification has already been activated (using |\begin{scope}[current plot style]|)%
-\footnote{This was different in versions before 1.3. The new scope features allows plot styles to change |legend image code|.}, so any drawing operations use the same styles as the |\addplot| command.
+\footnote{This was different in versions before 1.3. The new scope features allows plot styles to change \texttt{legend image code}.}, so any drawing operations use the same styles as the |\addplot| command.
The default is the style |line legend|.
@@ -818,6 +880,9 @@ The default is the style |line legend|.
The style |line legend| can also be used to use a different legend style for one particular plot (see the docs for |area legend| for an example).
\end{stylekey}
+\begin{stylekey}{/pgfplots/empty legend}
+ A style which clears |legend image code|, thereby omitting the legend image.
+\end{stylekey}
\begin{stylekey}{/pgfplots/area legend}
A style which sets |legend image code| to
@@ -917,7 +982,9 @@ The initial values for these styles might be interesting if someone wants to mod
\end{codeexample}
\end{pgfplotskey}
-\begin{pgfplotskey}{reverse legend=\mchoice{true,false} (initially false)}
+\begin{pgfplotskeylist}{%
+ reverse legend=\mchoice{true,false} (initially false),%
+ legend reversed=\mchoice{true,false} (initially false)}
Allows to reverse the order in which the pairs (legend entry, plot style) are drawn.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -931,7 +998,62 @@ The initial values for these styles might be interesting if someone wants to mod
\end{axis}
\end{tikzpicture}
\end{codeexample}
-\end{pgfplotskey}
+\end{pgfplotskeylist}
+
+\begin{pgfplotskeylist}{%
+ transpose legend=\mchoice{true,false} (initially false),%
+ legend transposed=\mchoice{true,false} (initially false)}
+ Allows to transpose the order in which the pairs (legend entry, plot style) are drawn.
+
+ Consider a set of $3$ experiments, each consisting of $2$ parameter. We might want to draw them together as in the following example:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ legend columns=2,
+ legend pos=outer north east,
+ cycle multi list={%
+ color list\nextlist
+ [2 of]mark list
+ }]
+ \addplot {-x}; \addlegendentry{A1}
+ \addplot {-x+1}; \addlegendentry{A2}
+
+ \addplot {-1.2*x + 4}; \addlegendentry{B1}
+ \addplot {-1.2*x + 5}; \addlegendentry{B2}
+
+ \addplot {-1.3*x + 9}; \addlegendentry{C1}
+ \addplot {-1.4*x + 10}; \addlegendentry{C2}
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ An alternative might be to draw them horizontally -- then, we'd like to use |transpose legend| to get a flat legend:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ transpose legend,
+ legend columns=2,
+ legend style={at={(0.5,-0.1)},anchor=north},
+ cycle multi list={%
+ color list\nextlist
+ [2 of]mark list
+ }]
+ \addplot {-x}; \addlegendentry{A1}
+ \addplot {-x+1}; \addlegendentry{A2}
+
+ \addplot {-1.2*x + 4}; \addlegendentry{B1}
+ \addplot {-1.2*x + 5}; \addlegendentry{B2}
+
+ \addplot {-1.3*x + 9}; \addlegendentry{C1}
+ \addplot {-1.4*x + 10}; \addlegendentry{C2}
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ Thus, |legend columns| defines the \emph{input} columns, before the transposition (in other words, |legend columns| indicates the \emph{rows} of the resulting legend).
+
+ Transposing legends has only an effect if |legend columns|$>1$. Note that |reverse legend| has higher precedence: it is applied first.
+\end{pgfplotskeylist}
\subsubsection{Legends with \texttt{\textbackslash label} and \texttt{\textbackslash ref}}
@@ -970,8 +1092,8 @@ Finally, \ref{pgfplots:label3} is only here to get three examples.
Label3 = \ref{pgfplots:label3};
Label2 = \ref{pgfplots:label2}
\end{codeexample}
- The label is assembled using |legend image code| and the plot style of the last plot. Any \PGFPlots\ option is expanded until only \Tikz\ (or \pgfname) options remain; these options are used to get an independent label\footnote{Please note that you can't use the label/ref mechanism in conjunction with image externalization as this will (naturally) lead to undefined references.}.
-
+ The label is assembled using |legend image code| and the plot style of the last plot. Any \PGFPlots\ option is expanded until only \Tikz\ (or \pgfname) options remain; these options are used to get an independent label.
+
More precisely, the small image generated by |\ref|\marg{label name} is
\begin{codeexample}[code only]
\tikz[/pgfplots/every crossref picture] {...}
@@ -979,6 +1101,9 @@ Label2 = \ref{pgfplots:label2}
\noindent where the contents is determined by |legend image code| and the plot style.
The second syntax, |\label|\oarg{reference}\marg{label name} allows to label particular pieces of an |\addplot| command. It is (currently) only interesting for |scatter/classes|: there, it allows to reference particular classes of the scatter plot. See page~\pageref{pgfplots:scatterclasses} for more details.
+
+
+ Note that |\label| information, even the small \Tikz\ pictures here, can be combined with the |external| library for image externalization, see section~\ref{sec:pgfplots:export} for details (in particular, the |external/mode| key). In other words, references remain valid even if the defining axis has been externalized.
\end{commandlist}
\begin{command}{\ref\marg{label name}}
@@ -1002,6 +1127,186 @@ Label2 = \ref{pgfplots:label2}
\end{codeexample}
\end{stylekey}
+\begin{pgfplotskeylist}{%
+ invoke before crossref tikzpicture=\marg{\TeX\ code},
+ invoke after crossref tikzpicture=\marg{\TeX\ code}}
+ Code which is invoked just before or just after every cross reference picture. This applies to legend images generated with |\ref|, |legend to name| and |colorbar to name| images.
+
+ The initial configuration checks if the |external| library is in effect. If so, it calls |\tikzappendtofigurename{_crossref}|.
+ \index{crossref file suffix}
+\end{pgfplotskeylist}
+
+\subsubsection{Legends Outside Of an Axis}
+Occasionally, one has multiple adjacent plots, each with the same legend -- and just \emph{one} legend suffices. But where shall it be placed? And how? One solution is to use the |overlay| key to exclude the legend from bounding box computations, and place it absolutely such that it fits. Another is the |legend to name| feature:
+
+\begin{pgfplotskey}{legend to name=\marg{name} (initially empty)}
+\label{key:legend:to:name}
+ Enables a legend export mode: instead of drawing the legend, a self--contained, independent set of drawing commands will be stored using the label \meta{name}. The definition is done using |\label|\marg{name}, just like any other \LaTeX\ label. The name can be referenced using
+
+ |\ref|\marg{name}.
+
+Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside of any picture, will cause the legend to be drawn.
+{
+\pgfplotsmanualdisablecolorforref
+\begin{codeexample}[vbox]
+\pgfplotsset{footnotesize,samples=10}
+\begin{center}% note that \centering uses less vspace...
+\begin{tikzpicture}
+ \begin{axis}[
+ legend columns=-1,
+ legend entries={$(x+0)^k$;,$(x+1)^k$;,$(x+2)^k$;,$(x+3)^k$},
+ legend to name=named,
+ title={$k=1$}]
+ \addplot {x};
+ \addplot {x+1};
+ \addplot {x+2};
+ \addplot {x+3};
+ \end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+ \begin{axis}[title={$k=2$}]
+ \addplot {x^2};
+ \addplot {(x+1)^2};
+ \addplot {(x+2)^2};
+ \addplot {(x+3)^2};
+ \end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+ \begin{axis}[title={$k=3$}]
+ \addplot {x^3};
+ \addplot {(x+1)^3};
+ \addplot {(x+2)^3};
+ \addplot {(x+3)^3};
+ \end{axis}
+\end{tikzpicture}
+\\
+
+\ref{named}
+\end{center}
+\end{codeexample}
+}
+
+ Note that only the \emph{first} plot has |legend entries|. Thus, its legend will be created as usual, and stored under the name `|named|', but it won't be drawn. The stored legend can then be drawn with |\ref{named}| below the three plots. Since there is no picture in this context, a |\tikz| picture is created and a |\matrix[/pgfplots/every axis legend]| path is drawn inside of it, resulting in the legend as if it had been placed inside of the axis.
+
+ The stored legend will contain the currently active values of legend- and plot style related options. This includes |legend image code|, |every axis legend|, and any plot style options (and some more). The algorithm works in the same way as for |\label| and |\ref|, i.e.\ it keeps any options with |/tikz/| prefix and expands those with |/pgfplots/| prefix.
+
+ Note that the legend is drawn with |every axis legend|, even though the placement options might be chosen to fit into an axis. You may want to adjust the style in the same axis in which the stored legend has been defined (the value will be copied and restored as well).
+
+ \paragraph{About \texttt{\string\ref}\marg{name}} The |\ref|\marg{name} command retrieves a stored legend (one defined by |legend to name|) and draws it.
+
+{
+\pgfplotsmanualdisablecolorforref
+ |\ref{named}: | \ref{named}
+}
+
+
+ If you want the legend to be exported \emph{and} drawn inside of the current axis, consider using |extra description/.append code={\ref|\marg{name}|}|.
+
+ Note that |\ref| can be combined with the |external| library for image externalization. In other words, the legend will work even if the defining axis has been externalized, see section~\ref{sec:pgfplots:export} for details (in particular the |external/mode| key).
+
+ Note furthermore that this |.aux| file related stuff is (currently) only supported for \LaTeX, sorry.
+ \begin{command}{\pgfplotslegendfromname\marg{name}}
+ This command poses an equivalent alternative for |\ref|\marg{name}: it has essentially the same effect, but it does not create links when used with the |hyperref| package\footnote{Since this manual uses colored links, the text in \texttt{\string\ref} would usually be blue. Using \texttt{\string\pgfplotslegendfromname} avoids link text colors in the legend (this has been applied to the manual styles here).}.
+ \end{command}
+
+ \begin{stylekey}{/pgfplots/every legend to name picture}
+ A style which is installed when |\ref| is used outside of a picture: a new picture will be created with |\tikz[/pgfplots/every legend to name picture]|.
+
+ Thus, you can re-define this style to set alignment options (such as |baseline|).
+ For example, the initialisation
+\begin{codeexample}[code only]
+\pgfplotsset{
+ legend style={matrix anchor=west,at={(0pt,0pt)}},
+ every legend to name picture/.style={baseline},
+}
+...
+\end{codeexample}
+ \noindent will cause the legend to be positioned such that its |west| anchor is at |y=0pt|. The |baseline| option will align this point of the legend with the text baseline (please refer to the documentation for |baseline| in section~\ref{pgfplots:sec:align} for details).
+ \end{stylekey}
+\end{pgfplotskey}
+
+\subsubsection{Legends with Customized Texts or Multiple Lines}
+
+\begin{command}{\addlegendimage\marg{options}}
+ Adds a further legend image for legend creation.
+
+ Each |\addplot| command appends its plot style options to a list, and |\addlegendimage| adds \meta{options} to the very same list.
+
+ Thus, the effect is as if you had provided |\addplot|\oarg{options}, but |\addlegendimage| bypasses all the logic usually associated with a plot. In other words: except for the legend, the state of the axis remains as if the command would not have been drawn. Not even the current plot's index is advanced.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{semilogyaxis}[
+ domain=0:4,
+]
+ \addplot {x}; \addlegendentry{$x$}
+ \addplot {x^2}; \addlegendentry{$x^2$}
+ \addplot {x^3}; \addlegendentry{$x^3$}
+ \addlegendimage{empty legend}
+ \addlegendentry{---}
+ \addplot {x^(-1)}; \addlegendentry{$x^{-1}$}
+ \addplot {x^(-2)}; \addlegendentry{$x^{-2}$}
+ \addplot {x^(-3)}; \addlegendentry{$x^{-3}$}
+\end{semilogyaxis}
+\end{tikzpicture}
+\end{codeexample}
+ The example above has six plots, each with its legend entry. Furthermore, it has an |\addlegendimage| command and its separate legend entry. We see that |\addlegendimage| needs its own legend entry, but it is detached from the processing of plots as such. In our case, we chose |empty legend| as style for the separator.
+
+ Use |\addlegendimage| to provide custom styles into legends, for example to document custom |\draw| commands inside of an axis.
+
+ You can call |\label| after |\addlegendimage| just as for a normal style.
+\end{command}
+
+Occasionally, one may want multiple lines for legend entries. That is possible as well using a fixed |text width|:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{semilogyaxis}[
+ domain=0:4,
+]
+ \addplot {x}; \addlegendentry{$x$}
+ \addplot {x^2}; \addlegendentry{$x^2$}
+ \addplot {x^3}; \addlegendentry{$x^3$}
+ \addlegendimage{empty legend}
+ \addlegendentry[text width=25pt,text depth=]
+ {Neg Sign:}
+ \addplot {x^(-1)}; \addlegendentry{$x^{-1}$}
+ \addplot {x^(-2)}; \addlegendentry{$x^{-2}$}
+ \addplot {x^(-3)}; \addlegendentry{$x^{-3}$}
+\end{semilogyaxis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent The example provides options for the single multiline element. Note that the initial configuration of |legend style| employs |text depth=0.15em|, which needs to be reset manually to |text depth={}|\footnote{Perhaps I can reset \texttt{text depth} automatically in the future.}.
+
+\noindent There are two approaches with the same effect which are subject of the following example:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{semilogyaxis}[
+ domain=0:4,
+ legend entries={%
+ $x$,$x^2$,$x^3$,%
+ {[text width=25pt,text depth=]Neg. Sign:},%
+ $x^{-1}$,$x^{-2}$,$x^{-3}$},
+ % same effect:
+ % legend style={
+ % nodes={text width=25pt,text depth=}}
+]
+ \addplot {x};
+ \addplot {x^2};
+ \addplot {x^3};
+ \addlegendimage{empty legend}
+ \addplot {x^(-1)};
+ \addplot {x^(-2)};
+ \addplot {x^(-3)};
+\end{semilogyaxis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Here, the |legend entries| are provided using the single key syntax. Note that the special options are provided as part of the legend entry, using square brackets right before the text as such. The comments indicate that you could also add the |text width| stuff to |legend style|, in which case it would hold for every node.
+
+
+Note that legend texts are realized using |\node|\oarg{options} \marg{text}|;|, so anything which produces a valid \Tikz\ node is permitted (this includes |minipage| or |tabular| environments inside of \meta{text}).
+
\subsubsection{Axis Lines}
{\small \emph{An extension by Pascal Wolkotte}}
@@ -1242,17 +1547,17 @@ Note that three dimensional axes only support to use the same value for every ax
\noindent with similar values for the |y|-variant. Feel free to redefine this style to your needs / taste.
\end{pgfplotsxykey}
-\subsubsection[Two Ordinates]{Two Ordinates ($y$ axis)}
+\subsubsection[Two Ordinates]{Two Ordinates ($y$ axis) or Multiple Axes}
{%
\pgfplotsset{every axis/.append style={width=4.5cm}}%
-In some applications, more than one $y$ axis is used if the $x$ range is the same. This section demonstrates how to create them.
+In some applications, more than one $y$ axis is used if the $x$ range is the same. This section demonstrates how to create them. The idea in \PGFPlots\ is to draw two axes on top of each other, one with descriptions only on the left and the second with descriptions only on the right:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
scale only axis,
xmin=-5,xmax=5,
- axis y line=left,
+ axis y line*=left,% the '*' avoids arrow heads
xlabel=$x$,
ylabel=First ordinate]
\addplot {x^2};
@@ -1261,14 +1566,14 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam
\begin{axis}[
scale only axis,
xmin=-5,xmax=5,
- axis y line=right,
+ axis y line*=right,
axis x line=none,
ylabel=Second ordinate]
\addplot[red] {3*x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
-\noindent The basic idea is to draw two axis ``on top'' of each other -- one, which contains the $x$ axis and the left $y$ axis, and one which has \emph{only} the right $y$ axis. Since \PGFPlots\ does not really know what it's doing here, user attention in the following possibly non-obvious aspects is required:
+\noindent Thus, the two axes are drawn ``on top'' of each other -- one, which contains the $x$ axis and the left $y$ axis, and one which has \emph{only} the right $y$ axis. Since \PGFPlots\ does not really know what it's doing here, user attention in the following possibly non-obvious aspects is required:
\begin{enumerate}
\item Scaling. You should set |scale only axis| because this forces equal dimensions for both axis, without respecting any labels.
\item Same $x$ limits. You should set those limits explicitly.
@@ -1282,7 +1587,7 @@ It is also possible to use only the axis, without any plots:
\begin{axis}[
scale only axis,
xmin=-5,xmax=5,
- axis y line=left,
+ axis y line*=left,%'*' avoids arrow heads
xlabel=$x$,
ylabel=Absolute]
\addplot {x^2};
@@ -1294,9 +1599,8 @@ It is also possible to use only the axis, without any plots:
ymin=0,ymax=1000,
yticklabel=
{$\pgfmathprintnumber{\tick}$\textperthousand},
- axis y line=right,
+ axis y line*=right,
axis x line=none,
- y label style={yshift=-10pt},
ylabel=per thousand]
\end{axis}
\end{tikzpicture}
@@ -1440,8 +1744,8 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{tikzpicture}
\end{codeexample}
- A color bar is only useful for plots which actually use color data -- that is, the special data which is called ``point meta'' in \PGFPlots\ (see section~\ref{pgfplots:point:meta}). Activating color bars for a plot without color map results in an empty color bar.
-
+ A color bar is only useful for plots with non--zero color data range, more precisely, for which minimum and maximum |point meta| data is available. Usually, this is the case for |scatter|, |mesh| or |surf| (or similar) plots, but you can also set |point meta min| and |point meta max| manually in order to draw a |colorbar|.
+
Color bars are just normal axes which are placed right besides their parent axes. The only difference is that they inherit several styles such as line width and fonts and they contain a bar shaded with the color map of the current axis.
Color bars are drawn internally with
@@ -1454,7 +1758,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\paragraph{Remarks for special cases:}
\begin{itemize}
- \item Since there is always only one color bar per plot, this color bar uses the axis wide configurations of color map and color data.
+ \item Since there is always only one color bar per plot, this color bar uses the axis wide configurations of color map and color data. Consider using |colorbar source| to select color data limits of a particular |\addplot| command instead.
\item If someone needs more than one color bar, the draw command above needs to be updated. See the key
|colorbar/draw/.code| for this special case.
\end{itemize}
@@ -1610,6 +1914,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{stylekey}
\begin{stylekey}{/pgfplots/every colorbar}
+ \label{key:every:colorbar}
This style governs the placement, alignment and appearance of color bars. Any desired detail changes for color bars can be put into this style. Additionally, there is a style |colorbar shift| which is set after |every colorbar|. The latter style is intended to contain only shift transformations like |xshift| or |yshift| (making it easier to overwrite or deactivate them).
While a color bar is drawn, the predefined node |parent axis| can be used to align at the parent axis.
@@ -1634,7 +1939,22 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
The values of these keys contain the lower and upper bound of the color map, i.e.\ the lower and upper limit for the color bar.
The value is |\pgfkeysvalueof{/pgfplots/point meta min}| inside of |every colorbar|.
+
+ The value is usually determined using the axis wide point meta limits, i.e.\ they are computed as minimum and maximum value over all plots (unless the user provided limits manually). Consider the |colorbar source| key if you'd like to select point meta limits of one specific |\addplot| command.
\end{pgfplotskeylist}
+\begin{pgfplotskey}{colorbar source=\marg{true,false} (initially false)}
+ Allows to select a specific |\addplot| command whose point meta limits are taken as upper and lower limit of a |colorbar|'s data range. This affects the tick descriptions of the |colorbar|. It needs to be provided as argument to |\addplot|, i.e.\ using
+\begin{codeexample}[code only]
+\addplot[...,colorbar source] ...
+% or
+\addplot+[colorbar source] ...
+\end{codeexample}
+ \noindent or as key inside of a |cycle list|.
+
+ Using |colorbar source| automatically implies |point meta rel=per plot| for that specific plot.
+
+ If there are more than one |\addplot| commands with |colorbar source|, the last one is preferred.
+\end{pgfplotskey}
\begin{pgfplotskeylist}{parent axis width,parent axis height}
The values of these keys contain the size of the parent axis. They can be used as |width| and/or |height| arguments for |every colorbar| with |\pgfkeysvalueof{/pgfplots/parent axis width}|.
@@ -1752,6 +2072,101 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
Please note that a color bar axis is nothing special as such -- it is just a normal axis with one |plot graphics| command and it is invoked with a special set of options. The only special thing is that a set of styles and some variables are inherited from its parent axis.
\end{pgfplotscodekey}
+\begin{stylekey}{/pgfplots/colorbar sampled=\marg{optional options} (default surf,mark=none,shader=flat)}
+ A style which installs a discretely sampled color bar.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[colorbar sampled]
+ \addplot[mesh,samples=40] {sin(deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The style uses |\addplot3|\oarg{options} to draw the |colorbar|, with |domain| set to the color range. In other words: it uses |plot expression| and a surface plot to visualize the |colorbar|. Use |colorbar style={samples=10}| to change the number of samples.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[colorbar sampled,colorbar style={samples=8}]
+ \addplot[mesh,samples=40] {sin(deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The \meta{options} can be used to change the |\addplot3| options used for the colorbar visualization. For example, |colorbar sampled={surf,shader=interp}| will use gouraud shading which has visually the same effect as the standard colorbar.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colorbar sampled line=\marg{optional options} (default scatter,only marks)}
+ A style which draws a discrete colorbar. In contrast to |colorbar sampled|, it visualizes the |colorbar| using a line plot, not a |surf| plot.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[colorbar sampled line]
+ \addplot+[scatter] {sin(deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The initial configuration uses a |scatter| plot to visualize the |colorbar|, it can be changed by specifying \meta{options}.
+
+ Furthermore, the axis appearance is changed using |axis y line*=|\mchoice{left,right}, depending on the position of the color bar or (or |axis x line*=bottom| for |colorbar horizontal|).
+
+ Consider the |tick align=outside| feature if you prefer tick lines outside of the colorbar instead of inside.
+
+ \begin{stylekey}{/pgfplots/every colorbar sampled line}
+ A style which is used by |colorbar sampled line| to change the color of the line without ticks.
+
+ It is initially set to |help lines|.
+ \end{stylekey}
+\end{stylekey}
+
+\subsubsection{Color Bars Outside Of an Axis}
+
+Occasionally, one has multiple adjacent plots, each with the same |colormap| and the same |point meta min| and |point meta max| values and we'd like to show a \emph{single} |colorbar|. \PGFPlots\ supports the |colorbar to name| feature which is similar to the related method for legends, |legend to name|:
+
+
+\begin{pgfplotskey}{colorbar to name=\marg{name} (initially empty)}
+ Enables to detach a |colorbar| from its parent axis: instead of drawing the |colorbar|, a self--contained, independent set of drawing commands will be stored using the label \meta{name}. The label is defined using |\label|\marg{name}, just as for any other \LaTeX\ label. The name can be referenced using
+
+ |\ref|\marg{name}.
+
+Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside of any picture, will cause the |colorbar| to be drawn.
+
+{
+\pgfplotsmanualdisablecolorforref
+\begin{codeexample}[vbox]
+\pgfplotsset{footnotesize,samples=10, domain=0:1,point meta min=0, point meta max=1}
+\begin{center}% note that \centering uses less vspace...
+\begin{tikzpicture}
+ \begin{axis}[colorbar,colorbar horizontal,colorbar to name={storedcolorbar}]
+ \addplot[scatter,only marks,mark=*] {rnd};
+ \end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+ \begin{axis}
+ \addplot+[domain=0:1,mark=none,mesh] {x^2};
+ \end{axis}
+\end{tikzpicture}
+%
+\begin{tikzpicture}
+ \begin{axis}[view={0}{90}]
+ \addplot3[surf] {x*y};
+ \end{axis}
+\end{tikzpicture}
+\\
+
+\ref{storedcolorbar}
+\end{center}
+\end{codeexample}
+}
+
+ The feature works in the same way as described for |legend to name|, please refer to its description on page~\pageref{key:legend:to:name} for the details. We only summarize the differences here.
+ \begin{command}{\pgfplotscolorbarfromname\marg{name}}
+ This command poses an equivalent alternative for |\ref|\marg{name}: it has essentially the same effect, but it does not create links when used with the |hyperref| package.
+ \end{command}
+
+ \begin{stylekey}{/pgfplots/every colorbar to name picture}
+ A style which is installed when |\ref| is used outside of a picture: a new picture will be created with |\tikz[/pgfplots/every colorbar to name picture]|.
+
+ See also the |every legend to name picture| style.
+ \end{stylekey}
+\end{pgfplotskey}
+
\subsubsection{Scaling Descriptions: Predefined Styles}
\label{sec:scaling:styles}
It is reasonable to change font sizes, marker sizes etc. together with the overall plot size: Large plots should also have larger fonts and small plots should have small fonts and a smaller distance between ticks.