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.tex245
1 files changed, 148 insertions, 97 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 f2b4ad810de..a97eb068e5e 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
@@ -7,14 +7,14 @@ This section describes how to \emph{modify} the placement of titles, labels, leg
There are different methods to place axis descriptions. One of them is to provide coordinates relative to the axis' rectangle such that |(0,0)| is the lower left corner and |(1,1)| is the upper right corner -- this is very useful for figure titles or legends. Coordinates of this type, i.e.\ without unit like |(0,0)| or |(1.03,1)|, are called |axis description cs| (the |cs| stands for ``coordinate system''). One other method is of primary interest for axis labels -- they should be placed near the tick labels, but it a way that they don't overlap or obscure tick labels. Furthermore, axis labels shall be placed such that they are automatically moved if the axis is rotated (or tick labels are moved to the right side of the figure). There is a special coordinate system to realize these two demands, the |ticklabel cs|.
-In the following, the two coordinate systems |axis description cs| and |ticklabel cs| are described in more details. It should be noted that |axis description cs| is used automatically, so it might never be necessary to use it explicitly.
+In the following, the two coordinate systems |axis description cs| and |ticklabel cs| are described in more detail. It should be noted that |axis description cs| is used automatically, so it might never be necessary to use it explicitly.
\begin{coordinatesystem}{axis description cs}
\label{pgfplots:sec:axis:description:cs}
A coordinate system which is used to place axis descriptions. Whenever the option `|at={(|\meta{x}|,|\meta{y}|)}|' occurs in |label style|, |legend style| or any other axis description, |(|\meta{x}|,|\meta{y}|)| is interpreted to be a coordinate in |axis description cs|.
- The point $(0,0)$ is always the lower left corner of the tightest bounding box around the axis (without any descriptions or ticks) while the point $(1,1)$ is the upper right corner of this bounding box.
+ The point $(0,0)$ is always the lower left corner of the tightest bounding box around the axes (without any descriptions or ticks) while the point $(1,1)$ is the upper right corner of this bounding box.
In most cases, it is \emph{not} necessary to explicitly write |axis description cs| as it is the default coordinate system for any axis description. An example for how coordinates are placed is shown below.
@@ -60,7 +60,7 @@ Axis descriptions are \Tikz\ nodes, that means all placement and detail options
\paragraph{Remarks:}
\begin{itemize}
- \item Each of the anchors described in section~\ref{pgfplots:sec:align} can be described by |axis description cs| as well.
+ \item Each of the anchors described in Section~\ref{pgfplots:sec:align} can be described by |axis description cs| as well.
\item The |axis description cs| is independent of axis reversals or skewed axes.
Only for the default configuration of boxed axes is it the same as |rel axis cs|, i.e.\ |(0,0)| is the same as the smallest axis coordinate and |(1,1)| is the largest one in case of standard boxed axes\footnote{This was different in versions before 1.3: earlier versions did not have the distinction between \texttt{axis description cs} and \texttt{rel axis cs}.}.
@@ -163,7 +163,7 @@ Of course, it is relatively simple to get the same coordinates as in the two dim
\end{tikzpicture}
\end{codeexample}
- The coordinate |ticklabel cs:0| is associated to the lower axis limit while |ticklabel cs:1| is near the upper axis limit. The value |0.5| is in the middle of the axis, any other values (including negative values or values beyond $1$) are linearly interpolated inbetween.
+ The coordinate |ticklabel cs:0| is associated with the lower axis limit while |ticklabel cs:1| is near the upper axis limit. The value |0.5| is in the middle of the axis, any other values (including negative values or values beyond $1$) are linearly interpolated inbetween.
The |ticklabel cs| also accepts a second (optional) argument: a shift ``away'' from the tick labels. The shift points to a vector which is orthogonal to the associated axis, away from the tick labels. A shift of |0pt| is directly at the edge of the tick labels in direction of the normal vector, positive values move the position away and negative closer to the tick labels.
\begin{codeexample}[width=4cm]
@@ -194,18 +194,18 @@ Of course, it is relatively simple to get the same coordinates as in the two dim
Whenever the |ticklabel cs| is used, the anchor should be set to |anchor=near ticklabel| (see below).
- There is one speciality: if you reverse an axis (with |x dir=reverse|), points provided by |ticklabel cs| will be \emph{unaffected} by the axis reversal. This is intented to provide consistent placement even for reversed axes. Use |allow reversal of rel axis cs=false| to disable this feature.
+ There is one specialty: if you reverse an axis (with |x dir=reverse|), points provided by |ticklabel cs| will be \emph{unaffected} by the axis reversal. This is intented to provide consistent placement even for reversed axes. Use |allow reversal of rel axis cs=false| to disable this feature.
\end{coordinatesystemlist}
-Besides the mentioned positioning methods, there is also the predefined node |current axis|. The anchors of |current axis| can also be used to place descriptions: At the time when axis descriptions are drawn, all anchors which refer to the axis origin (that means the ``real'' point $(0,0)$) or any of the axis corners can be referenced using |current axis.|\meta{anchor name}. Please see section~\ref{pgfplots:sec:align}, Alignment, for further details.
+Besides the mentioned positioning methods, there is also the predefined node |current axis|. The anchors of |current axis| can also be used to place descriptions: At the time when axis descriptions are drawn, all anchors which refer to the axis origin (that means the ``real'' point $(0,0)$) or any of the axis corners can be referenced using |current axis.|\meta{anchor name}. Please see Section~\ref{pgfplots:sec:align}, Alignment, for further details.
\subsubsection{Alignment of Axis Descriptions}
This section describes how to modify the default alignment of axis descriptions. It can be skipped at first reading.
The two topics positioning and alignment always work together: \emph{positioning} means to select an appropriate coordinate and \emph{alignment} means to select an anchor inside of the description which will actually be moved to the desired position.
-\Tikz\ uses many anchors to provide alignment; most of them are named like |north|, |north east| etc. These names hold for any axis description as well (as axis description are \Tikz\ nodes). Readers can learn details about this topic in the \Tikz\ manual~\cite{tikz} or some more advice in section~\ref{pgfplots:sec:align}.
+\Tikz\ uses many anchors to provide alignment; most of them are named like |north|, |north east| etc. These names hold for any axis description as well (as axis descriptions are \Tikz\ nodes). Readers can learn details about this topic in the \Tikz\ manual~\cite{tikz} or some more advice in Section~\ref{pgfplots:sec:align}.
When it comes to axis descriptions, \PGFPlots\ offers some specialized anchors and alignment methods which are described below.
\begin{anchorlist}{near xticklabel,near yticklabel,near zticklabel,near ticklabel}
@@ -255,12 +255,15 @@ When it comes to axis descriptions, \PGFPlots\ offers some specialized anchors a
In more detail, the anchor is placed such that first, the node's center is on a line starting in the node's |at| position going in direction of the inwards normal vector of the axis line which contains the tick labels and second, the node does not intrude the axis. This normal vector is the same which is used for the shift argument in |ticklabel cs|: it is orthogonal to the tick label axis. Furthermore, |near ticklabel| inverts the transformation matrix before it computes this intersection point.
- The |near ticklabel| anchor and its friends will be added temporarily to any shape used inside of an axis. This includes axis description, but it is not limited to them: it applies to every \Tikz\ |\node[anchor=near xticklabel] ...| setting.
+ The |near ticklabel| anchor and its friends will be added temporarily to any shape used inside of an axis. This includes axis descriptions, but it is not limited to them: it applies to every \Tikz\ |\node[anchor=near xticklabel] ...| setting.
Note that it is not necessary at all to \emph{have} tick labels in an axis. The anchor will be placed such that it is near the axis on which tick labels \emph{would} be drawn. In fact, every tick label uses |anchor=near ticklabel| as initial configuration.
\end{anchorlist}
-\begin{pgfplotsxykeylist}{/tikz/sloped like \x\space axis}
+\begin{pgfplotsxykeylist}{%
+ /tikz/sloped like \x\space axis,%
+ /tikz/sloped like \x\space axis=\marg{options}
+}
A key which replaces the rotational / scaling parts of the transformation matrix such that the node is sloped like the provided axis. For two dimensional plots, |sloped like y axis| is effectively the same as |rotate=90|. For a three dimensional axis, this will lead to a larger difference:
\pgfplotsexpensiveexample
\begin{codeexample}[]
@@ -277,21 +280,37 @@ When it comes to axis descriptions, \PGFPlots\ offers some specialized anchors a
\end{axis}
\end{tikzpicture}
\end{codeexample}
-
- Inside of axis labels, |sloped| is an alias |sloped like |\meta{char}| axis| with the correct \meta{char} chosen automatically.
+
+ Inside of axis labels, |sloped| is an alias for |sloped like |\meta{char}| axis| with the correct \meta{char} chosen automatically.
Please note that rotated text might not look very good (neither on screen nor printed).
+
+ It is possible to customize |sloped like x axis| by means of the following keys, which need to be provided as \meta{options} (simply ignore the lengthy gray key prefixes):
+\pgfkeys{
+ /pgfmanual/gray key prefixes={/pgfplots/sloped/},
+}
+ \begin{key}{/pgfplots/sloped/allow upside down=\mchoice{true,false} (initially false)}
+ Use |sloped like x axis=allow upside down| to enable upside down labels.
+ \end{key}
+ \begin{key}{/pgfplots/sloped/execute for upside down=\mchoice{code} (initially empty)}
+ Use |sloped like x axis={execute for upside down=\tikzset{anchor=north}}| or something like that to handle upside down text nodes in a customized way (this is used by the |smithchart| library).
+ \end{key}
+ \begin{key}{/pgfplots/sloped/reset nontranslations=\mchoice{true,false} (initially true)}
+ Use |sloped like x axis={reset nontranslations=false}| to \emph{append} the transformations to the actual transformation matrix (instead of replacing it).
+ \end{key}
\end{pgfplotsxykeylist}
\subsubsection{Labels}
\begin{pgfplotsxykey}{\x label=\marg{text}}
-These options set axis labels to \marg{text} which is any \TeX\ text. Use curly braces to include special characters, for example ``|xlabel={, = characters}|'' if characters like `|=|' or `|,|' need to be included literally.
+ These options set axis labels to \meta{text} which is any \TeX\ text.
+
+ To include special characters, you can use curly braces: ``|xlabel={, = characters}|''. This is necessary if characters like `|=|' or `|,|' need to be included literally.
Use |xlabel/.add=|\marg{prefix}\marg{suffix} to modify an already assigned label.
-Labels are \Tikz-Nodes which are placed with
+Labels are \Tikz-nodes which are placed with
\begin{codeexample}[code only]
% for x:
\node
@@ -305,12 +324,22 @@ Labels are \Tikz-Nodes which are placed with
\end{codeexample}
so their position and appearance can be customized.
-\paragraph{Upgrade notice:} Since version 1.3, label placement \emph{can} respect the size of adjacent tick labels. Use |\pgfplotsset{compat=1.3}| in the preamble to activate this feature. See |xlabel near ticks| for details.
+ For example, a multiline |xlabel| can be configured using
+ \index{xlabel!Multiline}
+ \index{xlabel!Line break}
+\begin{codeexample}[code only]
+\begin{axis}[xlabel style={align=right,text width=3cm},xlabel=A quite long label with a line break]
+...
+\end{axis}
+\end{codeexample}
+ \noindent See \cite{tikz} to learn more about |align| and |text width|.
+
+\paragraph{Upgrade notice:} Since version 1.3, label placement \emph{can} respect the size of adjacent tick labels. Use |\pgfplotsset{compat=1.3}| (or newer) in the preamble to activate this feature. See |xlabel near ticks| for details.
\begin{pgfplotsxykeylist}{\x label shift=\marg{dimension} (initially 0pt),label shift=\marg{dimension}}
- Shifts labels in direction of the outer normal vector of the axis by an amount of \marg{dimension}. The |label shift| sets all three label shifts to the same value.
+ Shifts labels in direction of the outer normal vector of the axis by an amount of \meta{dimension}. The |label shift| sets all three label shifts to the same value.
- \paragraph{Attention:} This does only work if |\pgfplotsset{compat=1.3}| has been called (More precisely: if |xlabel near ticks| is active for the respective axis).
+ \paragraph{Attention:} This does only work if |\pgfplotsset{compat=1.3}| (or newer) has been called (more precisely: if |xlabel near ticks| is active for the respective axis).
\end{pgfplotsxykeylist}
\begin{pgfplotsxykeylist}{\x label near ticks,compat=1.3}
@@ -334,7 +363,7 @@ so their position and appearance can be customized.
It is encouraged to write
\begin{codeexample}[code only]
-\pgfplotsset{compat=1.3}
+\pgfplotsset{compat=1.3} % or newer
\end{codeexample}
\noindent in your preamble to install the styles document-wide -- it leads to the best output (it avoids unnecessary space). It is not activated initially for backwards compatibility with older versions which used fixed distances from the tick labels.
\end{pgfplotsxykeylist}
@@ -372,7 +401,7 @@ Whenever possible, consider using |/.append style| instead of overwriting the de
\end{pgfplotsxykey}
\begin{pgfplotskey}{title=\marg{text}}
-Adds a caption to the plot. This will place a \Tikz-Node with
+Adds a caption to the plot. This will place a \Tikz-node with
\begin{codeexample}[code only]
\node[every axis title] {text};
\end{codeexample}
@@ -419,7 +448,7 @@ to the current axis.
% \end{loglogaxis}
% \end{tikzpicture}
%--------------------------------------------------
-The title's appearance and/or placing can be reconfigured with
+The title's appearance and/or placement can be reconfigured with
\begin{codeexample}[code only]
\pgfplotsset{title style={at={(0.75,1)}}}
% or, equivalently,
@@ -431,7 +460,7 @@ Use |title/.add=|\marg{prefix}\marg{suffix} to modify an already assigned title.
\end{pgfplotskey}
\begin{pgfplotscodekey}{extra description}
-Allows to insert \marg{commands} after axis labels, titles and legends have been typeset.
+Allows to insert \meta{commands} after axis labels, titles and legends have been typeset.
As all other axis descriptions, the code can use $(0,0)$ to access the lower left corner and $(1,1)$ to access the upper right one. It won't be clipped.
\begin{codeexample}[]
@@ -502,7 +531,7 @@ Using |\addlegendentry| disables the key |legend entries|.
The invocation |\addlegendentryexpanded{$x^\p$}| is equivalent to calling |\addlegendentry{$x^2$}| if |\p| expands to |2|.
- The argument \meta{\TeX\ text} is expanded until nothing but un-expandable material remains (i.e.\ it uses the \TeX\ primitive |\edef|). Occasionally, \marg{\TeX\ text} contains parts which should be expanded (like |\p|) and other parts which should be left unexpanded (for example |\pgfmathprintnumber{\p}|). Then, use
+ The argument \meta{\TeX\ text} is expanded until nothing but un-expandable material remains (i.e.\ it uses the \TeX\ primitive |\edef|). Occasionally, \meta{\TeX\ text} contains parts which should be expanded (like |\p|) and other parts which should be left unexpanded (for example |\pgfmathprintnumber{\p}|). Then, use
|\noexpand\pgfmathprintnumber{\p}|
@@ -521,7 +550,7 @@ You can use |\legend|\marg{list} to assign a complete legend.
\begin{codeexample}[code only]
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{codeexample}
-The argument of |\legend| is list of entries, one for each plot.
+The argument of |\legend| is a list of entries, one for each plot.
Two different delimiters are supported:
\begin{enumerate}
@@ -541,7 +570,7 @@ Two different delimiters are supported:
\end{codeexample}
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|.
+The short marker/line combination shown in legends is acquired from the \meta{style options} argument of |\addplot|.
Using |\legend| overwrites any other existing legend entries.
\end{command}
@@ -568,16 +597,16 @@ Using |\legend| overwrites any other existing legend entries.
\end{axis}
\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).
+ Please be careful with whitespaces in \meta{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).
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$}]
+\begin{axis}[legend entries={$x$,[red]$x^2$,$x^3$}]
\addplot {x};
\addplot {x^2};
\addplot {x^3};
- \end{axis}
+\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).
@@ -606,7 +635,7 @@ will draw it at the lower left corner of the axis while
means the upper right corner. The `|anchor|' option determines which point \emph{of the legend} will be placed at $(0,0)$ or $(1,1)$.
The legend is a \Tikz-matrix, so one can use any \Tikz\ option which affects
-nodes and matrizes (see~\cite[section 13~and~14]{tikz}). The matrix is created by something like
+nodes and matrices (see~\cite[section 13~and~14]{tikz}). The matrix is created by something like
\begin{codeexample}[code only]
\matrix[style=every axis legend] {
draw plot specification 1 & \node{legend 1}\\
@@ -710,6 +739,28 @@ Whenever possible, consider using |/.append style| to keep the default styles ac
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={...}}
\end{codeexample}
+
+Note that in order to disable drawing of the legend box, you can use |draw=none| as style argument:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[tiny,title=With legend box]
+\addplot[blue]{x};
+\addplot[red]{2*x};
+\legend{$x$,$2x$}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[tiny,title=Without legend box,
+ legend style={draw=none}]
+\addplot[blue]{x};
+\addplot[red]{2*x};
+\legend{$x$,$2x$}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
\end{stylekey}
\pgfplotsshortstylekey legend style=every axis legend\pgfeov
@@ -814,7 +865,7 @@ Whenever possible, consider using |/.append style| to keep the default styles ac
\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.
+ They are actually just styles for commonly used alignment choices: the choice |left| is equivalent to |legend style={cells={anchor=west}}|; the second 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}
}
@@ -840,7 +891,7 @@ Configures where the small line specifications will be drawn: left of the descri
coordinates {(0.5,0.75) (1,1) (1.5,0.75)};
\addplot+[mark=none,smooth,domain=0:2]
{-x*(x-2)};
- \addlegendentry{Parable}
+ \addlegendentry{Parabola}
\end{axis}
\end{tikzpicture}
\end{codeexample}
@@ -852,7 +903,7 @@ Configures where the small line specifications will be drawn: left of the descri
\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 \texttt{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 allow 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|.
@@ -877,7 +928,7 @@ The default is the style |line legend|.
}
\end{codeexample}
- 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).
+ The style |line legend| can also be used to apply a different legend style to one particular plot (see the documentation on |area legend| for an example).
\end{stylekey}
\begin{stylekey}{/pgfplots/empty legend}
@@ -935,7 +986,7 @@ The default is the style |line legend|.
\end{axis}
\end{tikzpicture}
\end{codeexample}
-The initial values for these styles might be interesting if someone wants to modify them. Here are they:
+The initial values for these styles might be interesting if someone wants to modify them. Here they are:
\begin{codeexample}[code only]
\pgfplotsset{
/pgfplots/xbar legend/.style={
@@ -1005,7 +1056,7 @@ The initial values for these styles might be interesting if someone wants to mod
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:
+ Consider a set of $3$ experiments, each consisting of $2$ parameters. We might want to draw them together as in the following example:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
@@ -1087,7 +1138,7 @@ It appears the model \ref{pgfplots:label2} fits the data appropriately.
Finally, \ref{pgfplots:label3} is only here to get three examples.
\begin{commandlist}{\label\marg{label name},\label\oarg{reference}\marg{label name}}
- When used after |\addplot|, this command creates a \LaTeX\ label named \marg{label name}\footnote{This feature is \emph{only} available in \LaTeX, sorry.}. If this label is cross-referenced with |\ref|\marg{label name} somewhere, the associated plot specification will be inserted.
+ When used after |\addplot|, this command creates a \LaTeX\ label named \meta{label name}\footnote{This feature is \emph{only} available in \LaTeX, sorry.}. If this label is cross-referenced with |\ref|\marg{label name} somewhere, the associated plot specification will be inserted.
\begin{codeexample}[]
Label3 = \ref{pgfplots:label3};
Label2 = \ref{pgfplots:label2}
@@ -1103,7 +1154,7 @@ Label2 = \ref{pgfplots:label2}
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.
+ 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}}
@@ -1132,7 +1183,7 @@ Label2 = \ref{pgfplots:label2}
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}|.
+ The initial configuration checks if the |external| library is in effect. If so, it modifies the generated figure names by means of |\tikzappendtofigurename{_crossref}|.
\index{crossref file suffix}
\end{pgfplotskeylist}
@@ -1204,9 +1255,9 @@ Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside
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 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.
+ Note furthermore that this |.aux| file related stuff is (currently) only supported, if \PGFPlots\ is run by means of \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}
@@ -1214,8 +1265,8 @@ Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside
\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
+ Thus, you can redefine this style to set alignment options (such as |baseline|).
+ For example, the initialization
\begin{codeexample}[code only]
\pgfplotsset{
legend style={matrix anchor=west,at={(0pt,0pt)}},
@@ -1223,7 +1274,7 @@ Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside
}
...
\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).
+ \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}
@@ -1234,7 +1285,7 @@ Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside
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.
+ 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 issued. Not even the current plot's index is advanced.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -1270,7 +1321,7 @@ Occasionally, one may want multiple lines for legend entries. That is possible a
\addplot {x^3}; \addlegendentry{$x^3$}
\addlegendimage{empty legend}
\addlegendentry[text width=25pt,text depth=]
- {Neg Sign:}
+ {Neg. Sign:}
\addplot {x^(-1)}; \addlegendentry{$x^{-1}$}
\addplot {x^(-2)}; \addlegendentry{$x^{-2}$}
\addplot {x^(-3)}; \addlegendentry{$x^{-3}$}
@@ -1325,7 +1376,7 @@ Note that legend texts are realized using |\node|\oarg{options} \marg{text}|;|,
These keys allow to choose the locations of the axis lines. The last one, |axis lines| sets the same value for every axis.
Ticks and tick labels are placed according to the chosen value as well.
-The choice |bottom| will draw the $x$ line at $y=y_\text{min}$, |middle| will draw the $x$~line at $y=0$, and |top| will draw it at $y=y_\text{max}$. Finally, |box| is a combination of options |top| and |bottom|. The $y$~variant works similarly.
+The choice |bottom| will draw the $x$ line at $y=y_{\text{min}}$, |middle| will draw the $x$~line at $y=0$, and |top| will draw it at $y=y_{\text{max}}$. Finally, |box| is a combination of options |top| and |bottom|. The $y$~variant works similarly.
The case |center| is a synonym for |middle|, both draw the line through the respective coordinate~$0$. If this coordinate is not part of the axis limit, the lower axis limit is chosen instead.
@@ -1333,7 +1384,7 @@ The case |center| is a synonym for |middle|, both draw the line through the resp
The starred versions $\dotsc$|line*| \emph{only} affect the axis lines, without correcting the positions of axis labels, tick lines or other keys which are (possibly) affected by a changed axis line. The non-starred versions are actually styles which set the starred key \emph{and} some other keys which also affect the figure layout:
\begin{itemize}
\item In case |axis x line=box|, the style |every boxed x axis| will be installed immediately.
- \item In case |axis x line|$\neq$|box|, the style |every non boxed x axis| will be installed immediately. Furthermore, axis labels positions will be adjusted to fit the choosen value.
+ \item In case |axis x line|$\neq$|box|, the style |every non boxed x axis| will be installed immediately. Furthermore, axis labels positions will be adjusted to fit the chosen value.
\end{itemize}
The same holds true for the |y|-variants. The default styles are defined as
\begin{codeexample}[code only]
@@ -1422,7 +1473,7 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas
In case |middle|, the style |every inner axis x line| allows to adjust the appearance.
-Note that three dimensional axes only support to use the same value for every axis, i.e.\ three dimensional axes support only the |axis lines| key (or, preferably for 3D axes, the |axis lines*| key -- check what looks best). See section~\ref{sec:pgfplots:axislines:3d} for examples of three dimensional axis line variations.
+Note that three dimensional axes only support to use the same value for every axis, i.e.\ three dimensional axes support only the |axis lines| key (or, preferably for 3D axes, the |axis lines*| key -- check what looks best). See Section~\ref{sec:pgfplots:axislines:3d} for examples of three dimensional axis line variations.
\end{pgfplotskeylist}
\begin{pgfplotsxykey}{every inner \x\ axis line}
@@ -1467,6 +1518,40 @@ Note that three dimensional axes only support to use the same value for every ax
\end{codeexample}
\end{pgfplotsxykey}
+\label{pgfplots:page:axislines}
+\begin{pgfplotskey}{axis line style=\marg{key-value-list}}
+ A command which appends \meta{key-value-list} to \emph{all} axis line appearance styles.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{inner axis line style=\marg{key-value-list}}
+ A command which appends \meta{key-value-list} to both, |every inner x axis line| and the $y$ variant.
+\end{pgfplotskey}
+\begin{pgfplotskey}{outer axis line style=\marg{key-value-list}}
+ A command which appends \meta{key-value-list} to both, |every outer x axis line| and the $y$ variant.
+\end{pgfplotskey}
+\begin{pgfplotsxykey}{\x\ axis line style=\marg{key-value-list}}
+ A command which appends \meta{key-value-list} to all axis lines styles for either $x$ or $y$ axis.
+\end{pgfplotsxykey}
+
+\begin{pgfplotsxykey}{every boxed \x\ axis}
+ A style which will be installed as soon as |axis x line=box| (|y|) is set.
+
+ The default is simply empty.
+\end{pgfplotsxykey}
+\begin{pgfplotsxykey}{every non boxed \x\ axis}
+ A style which will be installed as soon as |axis x line| (|y|) will be set to something different than |box|.
+
+ The default is
+\begin{codeexample}[code only]
+\pgfplotsset{
+ every non boxed x axis/.style={
+ xtick align=center,
+ enlarge x limits=false,
+ x axis line style={-stealth}}}
+\end{codeexample}
+ \noindent with similar values for the |y|-variant. Feel free to redefine this style to your needs and taste.
+\end{pgfplotsxykey}
+
\begin{pgfplotskey}{separate axis lines=\marg{true,false} (default true)}
Enables or disables separate path commands for every axis line. This option affects \emph{only} the case if axis lines are drawn as a \emph{box}.
@@ -1513,40 +1598,6 @@ Note that three dimensional axes only support to use the same value for every ax
\end{pgfplotskey}
-\label{pgfplots:page:axislines}
-\begin{pgfplotskey}{axis line style=\marg{key-value-list}}
- A command which appends \marg{key-value-list} to \emph{all} axis line appearance styles.
-\end{pgfplotskey}
-
-\begin{pgfplotskey}{inner axis line style=\marg{key-value-list}}
- A command which appends \marg{key-value-list} to both, |every inner x axis line| and the $y$ variant.
-\end{pgfplotskey}
-\begin{pgfplotskey}{outer axis line style=\marg{key-value-list}}
- A command which appends \marg{key-value-list} to both, |every outer x axis line| and the $y$ variant.
-\end{pgfplotskey}
-\begin{pgfplotsxykey}{\x\ axis line style=\marg{key-value-list}}
- A command which appends \marg{key-value-list} to all axis lines styles for either $x$ or $y$ axis.
-\end{pgfplotsxykey}
-
-\begin{pgfplotsxykey}{every boxed \x\ axis}
- A style which will be installed as soon as |axis x line=box| (|y|) is set.
-
- The default is simply empty.
-\end{pgfplotsxykey}
-\begin{pgfplotsxykey}{every non boxed \x\ axis}
- A style which will be installed as soon as |axis x line| (|y|) will be set to something different than |box|.
-
- The default is
-\begin{codeexample}[code only]
-\pgfplotsset{
- every non boxed x axis/.style={
- xtick align=center,
- enlarge x limits=false,
- x axis line style={-stealth}}}
-\end{codeexample}
- \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) or Multiple Axes}
{%
\pgfplotsset{every axis/.append style={width=4.5cm}}%
@@ -1618,7 +1669,7 @@ It is also possible to use only the axis, without any plots:
Insert a discontinuity decoration on the $x$ (or $y$, respectively) axis.
This is to visualize that the $y$ axis does cross the $x$ axis at its $0$ value, because the minimum $x$ axis value is positive or the maximum value is negative.
-The description applies |axis y discontinuity| as well, with interchanged meanings of $x$~and~$y$.
+The description applies to |axis y discontinuity| and |axis z discontinuity| as well, simply substitute $x$ by $y$ or $z$, respectively.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -1715,7 +1766,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\subsubsection{Color Bars}
\label{pgfplots:colorbar}
-\PGFPlots\ supports mesh, surface and scatter plots which can use color maps. While color maps can be chosen as described in section~\ref{pgfplots:colormap}, they can be visualized using color bars.
+\PGFPlots\ supports mesh, surface and scatter plots which can use color maps. While color maps can be chosen as described in Section~\ref{pgfplots:colormap}, they can be visualized using color bars.
\begin{pgfplotskey}{colorbar=\mchoice{true,false} (initially false)}
Activates or deactivates color bars.
@@ -1765,7 +1816,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{pgfplotskey}
\begin{stylekey}{/pgfplots/colorbar right}
- A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed right of their parent axis.
+ A style which redefines |every colorbar| and |colorbar shift| such that color bars are placed right of their parent axis.
This is the initial configuration.
\begin{codeexample}[]
@@ -1777,7 +1828,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{tikzpicture}
\end{codeexample}
- The style |colorbar right| is defined to be
+ The style |colorbar right| is defined as
\begin{codeexample}[code only]
\pgfplotsset{
colorbar right/.style={
@@ -1816,7 +1867,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
},
}
\end{codeexample}
- \paragraph{Attention:} |colorbar right| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar right|:
+ \paragraph{Attention:} |colorbar right| \emph{re}defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar right|:
\begin{codeexample}[code only]
% correct:
\begin{axis}[colorbar right, colorbar style={<some customization>}]
@@ -1836,7 +1887,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{tikzpicture}
\end{codeexample}
- The style |colorbar left| is defined to be
+ The style |colorbar left| is defined as
\begin{codeexample}[code only]
\pgfplotsset{
colorbar left/.style={
@@ -1850,7 +1901,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
}
}
\end{codeexample}
- \paragraph{Attention:} |colorbar left| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar left| (see also the documentation for |colorbar right|).
+ \paragraph{Attention:} |colorbar left| \emph{re}defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar left| (see also the documentation for |colorbar right|).
\end{stylekey}
\begin{stylekey}{/pgfplots/colorbar horizontal}
@@ -1865,7 +1916,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{tikzpicture}
\end{codeexample}
- This style is defined to be
+ This style is defined as
\begin{codeexample}[code only]
\pgfplotsset{
colorbar horizontal/.style={
@@ -1932,7 +1983,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
colorbar shift/.style={xshift=0.3cm}
}
\end{codeexample}
- \noindent places the colorbar in a way that its top-left (north west) corner is aligned right of the top right corner (|right of north east|) of its parent axis. Combining this with the |colorbar shift| is actually the same as the initial setting.
+ \noindent places the colorbar in a way that its top left (north west) corner is aligned right of the top right corner (|right of north east|) of its parent axis. Combining this with the |colorbar shift| is actually the same as the initial setting.
Since color bars depend on some of its parent's properties, these properties are available as values of the following keys:
\begin{pgfplotskeylist}{point meta min,point meta max}
@@ -1953,7 +2004,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
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.
+ If there are more than one |\addplot| commands with |colorbar source|, the last one is selected.
\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}|.
@@ -2034,7 +2085,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{tikzpicture}
\end{codeexample}
- For vertical color bars, this sets the height.
+ For horizontal color bars, this sets the height.
\end{pgfplotskey}
@@ -2049,13 +2100,13 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\end{stylekey}
\begin{predefinednode}{current colorbar axis}
- A predefined node for the color bar of an axis. After |\end{axis}|, this node can be used to align further graphical elements at the color bar. Note that |current axis| refers to the axis as such while |current colorbar axis| refers to the color bar (which is an axis itsself).
+ A predefined node for the color bar of an axis. After |\end{axis}|, this node can be used to align further graphical elements at the color bar. Note that |current axis| refers to the axis as such while |current colorbar axis| refers to the color bar (which is an axis itself).
\end{predefinednode}
\begin{pgfplotscodekey}{colorbar/draw}
- This code key belongs to the low level interface of colorbars. It is invoked whenever a color bar needs to be drawn. Usually, it won't be necessary to use or modify this key explicitly.
+ This code key belongs to the low level interface of color bars. It is invoked whenever a color bar needs to be drawn. Usually, it won't be necessary to use or modify this key explicitly.
- In the context when this key is invoked, the styles inherited from the parent axis are already set and the required variables (see the documentation of |every colorbar|) are initialised.
+ When this key is invoked, the styles inherited from the parent axis are already set and the required variables (see the documentation of |every colorbar|) are initialized.
This code key can be replaced if one needs more than one color bar (or other wrinkles).
@@ -2081,7 +2132,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\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.
+ The style uses |\addplot3|\oarg{options} to draw the |colorbar|, with |domain| set to the color range and the current value of the |samples| key to determine the number of samples. 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}]
@@ -2089,7 +2140,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\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.
+ 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 color bar.
\end{stylekey}
\begin{stylekey}{/pgfplots/colorbar sampled line=\marg{optional options} (default scatter,only marks)}
@@ -2103,7 +2154,7 @@ Axis scaling and clipping will be done as if you did not use |hide axis|.
\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|).
+ Furthermore, the axis appearance is changed using |axis y line*=|\mchoice{left,right}, depending on the position of the color bar (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.