
\section{Axis Descriptions}
Axis descriptions are labels for $x$ and $y$ axis, titles, legends and the like. Axis descriptions are drawn after the plot is finished and they are not subjected to clipping. 

\subsection{Placement of Axis Descriptions}
This section describes how to \emph{modify} the placement of titles, labels, legends and other axis descriptions. It may be skipped at first reading.

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 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 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.
	
\begin{codeexample}[width=4cm]
% [See the TikZ manual if you'd like to learn about nodes and pins]
\begin{tikzpicture}
	\tikzset{
		every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
		small dot/.style={fill=black,circle,scale=0.3}
	}
	\begin{axis}[
		clip=false,
		title=How \texttt{axis description cs} works
	]
	\addplot {x};

	\node[small dot,pin=120:{$(0,0)$}]      at (axis description cs:0,0) {};
	\node[small dot,pin=-30:{$(1,1)$}]      at (axis description cs:1,1) {};
	\node[small dot,pin=-90:{$(1.03,0.5)$}] at (axis description cs:1.03,0.5) {};
	\node[small dot,pin=125:{$(0.5,0.5)$}]  at (axis description cs:0.5,0.5) {};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

Axis descriptions are \Tikz\ nodes, that means all placement and detail options of \cite{tikz} apply. The point on the node's boundary which is actually shifted to the |at| coordinate needs to be provided with an anchor (cf~\cite[Nodes and Edges]{tikz}):
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		legend entries={$x$,$x^2$},
		legend style={
			at={(1.03,0.5)},
			anchor=west
		}
	]
	\addplot {x};
	\addplot {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	Standard anchors of nodes are |north|, |east|, |south|, |west| and mixed components like |north east|.
	Please refer to \cite{tikz} for a complete documentation of anchors.

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

	\item Even for three dimensional axes, the |axis description cs| is still two-dimensional: it always refers to coordinates relative to the tightest bounding box around the axis (without any descriptions or ticks).
\begin{codeexample}[width=4cm]
% the same as above for 3D ...
% [See the TikZ manual if you'd like to learn about nodes and pins]
\begin{tikzpicture}
	\tikzset{
		every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
		small dot/.style={fill=black,circle,scale=0.3}
	}
	\begin{axis}[
		clip=false,
		title=How \texttt{axis description cs} works in 3D
	]
	\addplot3 coordinates {(-5,-5,-5) (5,5,5)};

	\draw[black!15] (axis description cs:0,0) rectangle (axis description cs:1,1);

	\node[small dot,pin=120:{$(0,0)$}]      at (axis description cs:0,0) {};
	\node[small dot,pin=-30:{$(1,1)$}]      at (axis description cs:1,1) {};
	\node[small dot,pin=-90:{$(1.03,0.5)$}] at (axis description cs:1.03,0.5) {};
	\node[small dot,pin=125:{$(0.5,0.5)$}]  at (axis description cs:0.5,0.5) {};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	\item Since the view does not influence these positions, |axis description cs| might not be a good choice for axis labels in 3D. The |ticklabel cs| is used in this case.
\end{itemize}
\end{coordinatesystem}

\begin{coordinatesystemlist}{%
	xticklabel cs,%
	yticklabel cs,%
	zticklabel cs,%
	ticklabel cs,%
	xticklabel* cs,%
	yticklabel* cs,%
	zticklabel* cs,%
	ticklabel* cs%
}
	A set of special coordinate systems intended to place axis descriptions (or any other drawing operation) besides tick labels, in a way such that neither tick labels nor the axis as such are obscured.

	See also |xlabel near ticks| as one main application of |ticklabel cs|.

	The |xticklabel cs| (and its variants) always refer to one, uniquely identified axis: the one which is (or would be) annotated with tick labels. 
	
	The |ticklabel cs| (without explicit \texttt{x}, \texttt{y} or \texttt{z}) can only be used in contexts where the axis character is known from context (for example, inside of |xlabel style| -- there, the |ticklabel cs| is equivalent to |xticklabel cs|).

	The starred variants |xticklabel* cs| and its friends do not take the size of any tick labels into account.

	Each of these coordinate systems allows to specify points on a straight line which is placed parallel to an axis containing tick labels, moved away just far enough to avoid overlaps with the tick labels:
\begin{codeexample}[width=4cm]
\tikzset{
	every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
	small dot/.style={fill=black,circle,scale=0.3}
}
\begin{tikzpicture}
\begin{axis}[
	clip=false,
	ticklabel style={draw=red},
	title=Positioning with \texttt{xticklabel cs}]
	\addplot {x};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:0}}]     at (xticklabel cs:0) {};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:0.5}}]   at (xticklabel cs:0.5) {};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:1}}]     at (xticklabel cs:1) {};


	\node[small dot,pin=180:{\texttt{yticklabel cs:0}}]     at (yticklabel cs:0) {};
	\node[small dot,pin=180:{\texttt{yticklabel cs:0.5}}]   at (yticklabel cs:0.5) {};
	\node[small dot,pin=180:{\texttt{yticklabel cs:1}}]     at (yticklabel cs:1) {};
\end{axis}
\end{tikzpicture}
\end{codeexample}

The basic idea is to place coordinates on a straight line which is parallel to the axis containing tick labels -- but shifted such that the line does not cut through tick labels.

Note that an axis description which has been placed with |xticklabel cs| or its friends is also useful for skewed axes or the |axis x line| variants -- it is often the same value for all these variants. In particular, it is useful for three--dimensional axes, see below.


Typically, |xticklabel cs| places nodes exactly at the position where the largest associated tick label is finished. While this is very useful, it might be undesired -- for example if one wants to move into the opposite direction (here, the special anchor |near ticklabel opposite| might be of interest). To this end, there are the starred variants, i.e.\ |xticklabel* cs| and its friends:

\begin{codeexample}[width=4cm]
\tikzset{
	every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
	small dot/.style={fill=black,circle,scale=0.3}
}
\begin{tikzpicture}
\begin{axis}[
	clip=false,
	ticklabel style={draw=red},
	title=Starred variant \texttt{xticklabel* cs}]
	\addplot {x};
	\node[small dot,pin=-90:{\texttt{xticklabel* cs:0}}]     at (xticklabel* cs:0) {};
	\node[small dot,pin=-90:{\texttt{xticklabel* cs:0.5}}]   at (xticklabel* cs:0.5) {};
	\node[small dot,pin=-90:{\texttt{xticklabel* cs:1}}]     at (xticklabel* cs:1) {};


	\node[small dot,pin=180:{\texttt{yticklabel* cs:0}}]     at (yticklabel* cs:0) {};
	\node[small dot,pin=180:{\texttt{yticklabel* cs:0.5}}]   at (yticklabel* cs:0.5) {};
	\node[small dot,pin=180:{\texttt{yticklabel* cs:1}}]     at (yticklabel* cs:1) {};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent The preceding example places all the additional anchors precisely onto the axis on which tick labels are drawn. The starred version |xticklabel* cs| ignores the size of tick labels.

Of course, it is relatively simple to get the same coordinates as in the two dimensional example above with |axis description cs|, except that |ticklabel cs| always respects the tick label sizes appropriately. However, |ticklabel cs| becomes far superior when it comes to three dimensional positioning:

\begin{codeexample}[width=4cm]
% the same as above for 3D ...
\begin{tikzpicture}
	\tikzset{
		every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
		small dot/.style={fill=black,circle,scale=0.3}
	}
	\begin{axis}[
		ticklabel style={draw=red},
		clip=false,
		title=Positioning with \texttt{ticklabel cs} in 3D
	]
	\addplot3 coordinates {(-5,-5,-5) (5,5,5)};

	\node[small dot,pin=-90:{\texttt{xticklabel cs:0}}]     at (xticklabel cs:0) {};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:0.5}}]   at (xticklabel cs:0.5) {};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:1}}]     at (xticklabel cs:1) {};

	\node[small dot,pin=-45:{\texttt{yticklabel cs:0}}]     at (yticklabel cs:0) {};
	\node[small dot,pin=-45:{\texttt{yticklabel cs:0.5}}]   at (yticklabel cs:0.5) {};
	\node[small dot,pin=-45:{\texttt{yticklabel cs:1}}]     at (yticklabel cs:1) {};

	\node[small dot,pin=180:{\texttt{zticklabel cs:0}}]     at (zticklabel cs:0) {};
	\node[small dot,pin=180:{\texttt{zticklabel cs:0.5}}]   at (zticklabel cs:0.5) {};
	\node[small dot,pin=180:{\texttt{zticklabel cs:1}}]     at (zticklabel cs:1) {};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	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.

	All coordinate systems like |ticklabel cs| also accepts a second (optional) argument: a shift ``away'' from the tick labels. The shift points to a vector which is orthogonal\footnote{Actually, the outer normal has the impression of being ``orthogonal'' to its axis, which appears to be sufficient.} 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]
\tikzset{
	every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
	small dot/.style={fill=black,circle,scale=0.3}
}
\begin{tikzpicture}
	\begin{axis}[
		xticklabel style={draw=red},
		clip=false,
		title=\texttt{ticklabel cs} and its optional shift
	]
	\addplot3 coordinates {(-5,-5,-5) (5,5,5)};

	\draw[blue,thick,->]      (xticklabel cs:0,0)     -- (xticklabel cs:1,0);
	\draw[red,thick,->]       (xticklabel cs:0,5pt)   -- (xticklabel cs:1,5pt);
	\draw[magenta,thick,->]   (xticklabel cs:0,10pt)  -- (xticklabel cs:1,10pt);
	\draw[green,thick,->]     (xticklabel cs:0,15pt)  -- (xticklabel cs:1,15pt);
	\node[small dot,pin=0:{\texttt{xticklabel cs:1,0}}]      at (xticklabel cs:1,0) {};
	\node[small dot,pin=0:{\texttt{xticklabel cs:1,15pt}}]   at (xticklabel cs:1,15pt) {};

	\draw[blue,thick,->]      (xticklabel cs:0,0)     -- (xticklabel cs:0,15pt);
	\draw[blue,thick,->]      (xticklabel cs:1,0)     -- (xticklabel cs:1,15pt);
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	Whenever the |ticklabel cs| is used, the anchor should be set to |anchor=near ticklabel| (see below).

	Whenever the starred version |ticklabel* cs| is used, both anchors |anchor=near ticklabel| and |anchor=near ticklabel opposite| are useful choices.

	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.

	The purpose of |ticklabel cs| is to place nodes ``next to tick labels''. The position of tick labels as such is determined in a similar way to |ticklabel* cs| with a customized shift along the outer normal vector. The shift is typically 
	
	|\pgfkeysvalueof{/pgfplots/major tick length}| (or half of it for centered axes).
\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.

\subsection{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 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}
	These anchors can be used to align at the part of a node (for example, an axis description) which is \emph{nearest} to the tick labels of a particular axis (or nearest to the position where tick labels would have been drawn if there were any).

	These anchors are used for axis labels, especially for three dimensional axes. Furthermore, they are used for every tick label.

\label{key:near:ticklabel}
	Maybe it is best to demonstrate it by example:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		title=Without \texttt{near ticklabel},
		ylabel={$f(x)=x$},
		every axis y label/.style=
			{at={(ticklabel cs:0.5)},rotate=90,anchor=center},
		clip=false,% to display the \path below
		ylabel style={draw=red},
		yticklabel style={draw=red}
	]

		\addplot {x};

		% visualize the position:
		\fill (yticklabel cs:0.5) circle(2pt);
	\end{axis}
\end{tikzpicture}%
~
\begin{tikzpicture}
	\begin{axis}[
		title=With \texttt{near ticklabel},
		ylabel={$f(x)=x$},
		every axis y label/.style=
			{at={(ticklabel cs:0.5)},rotate=90,anchor=near ticklabel},
		clip=false,
		ylabel style={draw=red},
		yticklabel style={draw=red}
	]

		\addplot {x};
		\fill (yticklabel cs:0.5) circle(2pt);
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The motivation is to place nodes such that they are anchored next to the tick label, regardless of the node's rotation or the position of ticks. The special anchor |near ticklabel| is only available for axis labels (as they have a uniquely identified axis, either $x$, $y$ or $z$).

	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 (but see also the key |near ticklabel align| and the details in the lengthy elaboration in the documentation for |near xticklabel opposite| below). 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 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{anchorlist}{near xticklabel opposite,near yticklabel opposite,near zticklabel opposite,near ticklabel opposite}
	These anchors are similar to |near xticklabel| and its variants, except that they align at the \emph{opposite} direction.

	Mathematically speaking, the only difference to |near xticklabel| and its variants is the sign in front of the normal vector.

	But it is probably best explained by means of an example.
\begin{codeexample}[width=4cm]
\begin{tikzpicture}
    \begin{axis}[
		clip=false,
		small,
        title=\texttt{near ticklabel} (\texttt{opposite}),
		min=0, max=1
    ]
		\node[draw=yellow,anchor=near xticklabel,font=\small] 
			(namex) at (xticklabel cs:0.2) {\texttt{near xticklabel}.};
        \fill (xticklabel cs:0.2) circle(2pt);
		\draw[green,-stealth] (xticklabel* cs:0.2) -- (xticklabel cs:0.2);
		\draw[blue,-stealth] (xticklabel cs:0.2) -- (namex.center);
		\draw[red,-stealth]  (namex.north east) -- (xticklabel cs:0.2);

		\node[draw=yellow,anchor=near xticklabel opposite,font=\small] 
			(namexx) at (xticklabel* cs:0.6) {\texttt{near xticklabel opposite}.};
        \fill[red] (xticklabel* cs:0.6) circle(2pt);
		\draw[blue,-stealth] (xticklabel* cs:0.6) -- (namexx.center);
		\draw[red,thick,-stealth]  (namexx.south west) -- (xticklabel* cs:0.6);


		\node[draw=yellow,anchor=near yticklabel,font=\small] 
			(name) at (yticklabel cs:1) {\texttt{near yticklabel}.};
        \fill (yticklabel cs:1) circle(2pt);
		\draw[green,-stealth] (yticklabel* cs:1) -- (yticklabel cs:1);
		\draw[blue,-stealth] (yticklabel cs:1) -- (name.center);
		\draw[red,-stealth]  (name.north west) -- (yticklabel cs:1);
    \end{axis}
\end{tikzpicture}
\end{codeexample}
	The figure is a boxed three--dimensional axis with standard ranges. It has three manually placed nodes. The nodes are placed |at (xticklabel cs:0.2)|, |at (xticklabel* cs:0.6)|, and |at (yticklabel cs:1)|,  respectively. The `|at|' locations are visually emphasized using filled circles. 

	Despite the different locations, we clearly see the effect of |near xticklabel opposite|: it causes the node to be aligned into the box rather than outside of the box. Note that this is the \emph{only} essential difference between the two nodes `|near xticklabel opposite|' and `|near xticklabel|'.

	The figure also shows the difference between |xticklabel cs| and |xticklabel* cs| when we compare the `|at|' locations. Take, for example, the two nodes on the $x$ axis. The position |at (xticklabel cs:0.2)| is shifted by the green arrow. The length of this arrow is precisely the length of the largest $x$ tick label. The position |at (xticklabel* cs:0.6)| is exactly on the axis; it ignores the size of any tick labels. Note that the direction of the green arrow is the ``outer normal vector in $x$ direction'' (in our case, it is the vector sum of the $z$ and $y$ unit vectors with appropriate signs).

	The difference between |near xticklabel opposite| and |near xticklabel| is that the direction of the green arrow (the ``outer normal'') is flipped.

	The nodes also highlight how the anchoring works. This technique is almost the same for both |anchor=near xticklabel| and |anchor=near xticklabel opposite|. Let us discuss the technique for the node with text `|near yticklabel|'. The black circle is placed |at (yticklabel cs:1)|. This position has been computed by starting at $100\%$ of the $y$ axis\footnote{In our example, percentages and absolute values are accidentally the same.} and moving along the green vector whose magnitude is the size of the bounding box of the largest $y$ tick label. As soon as the `|at|' location is fixed, the algorithm for |near yticklabel| starts. First, it computes the anchor inside of the node for which we do not penetrate the $y$ axis. To this end, it checks the direction of the green vector. It came up with |north west|. Then, it considers the red line which starts at |(name.north west)| and has the same direction as the $y$ axis. Note that the red line and the $y$ axis are parallel. It also considers the blue line. This line points into the direction of the green line and is fixed by the current node's |center|. The precise intersection point of the red line and the blue line are the result of |anchor=near yticklabel|. The same applies for the other two nodes as well: the red line is always parallel to the axis under consideration and is anchored at the ``snap--to--nearest--anchor'' of the node. The blue line is always parallel to the outer normal vector of the axis under consideration, and is anchored at the current node's |center|.
\end{anchorlist}

\begin{pgfplotskey}{near ticklabel align=\mchoice{inside,center,outside} (initially center)}
	Allows to change the alignment algorithm of |anchor=near ticklabel|.
	
	In the default configuration, |anchor=near ticklabel| and its variants take the node's |center| in order to derive the final anchor. This corresponds to the target of the blue line in the illustration for |near xticklabel opposite|, see above.

	This key changes the node's anchor which is used here. The choice \declaretext{center} can move half of the node's bounding box beyond the associated axis. The choice \declaretext{inside} moves the complete node's bounding box in a way such that it is not beyond the associated axis. The choice \declaretext{outside} moves the entire node's bounding box in a way that it is beyond the associated axis:


\begin{codeexample}[width=4cm]
\begin{tikzpicture}
    \begin{axis}[
		clip=false,
		small,
        title=\texttt{near ticklabel align},
		min=0, max=1,
		/tikz/node style/.style={
			draw=yellow,
			anchor=near yticklabel,
			font=\tiny,
		},
    ]
		\node[node style,
			/pgfplots/near ticklabel align=center] 
			(C) at (yticklabel cs:0) {\texttt{center}.};

		\node[node style,
			/pgfplots/near ticklabel align=inside]
			(I) at (yticklabel cs:1) {\texttt{inside}.};

		\node[node style,
			/pgfplots/near ticklabel align=outside]
			(O) at (yticklabel cs:1) {\texttt{outside}.};

        \fill (yticklabel cs:0) circle(2pt);
        \fill (yticklabel cs:1) circle(2pt);

        \fill[blue] (C.center) circle(1pt);
        \fill[blue] (I.south west) circle(1pt);
        \fill[blue] (O.north east) circle(1pt);

		\draw[green,-stealth] (yticklabel* cs:0) -- (yticklabel cs:0);
		\draw[blue] (yticklabel cs:0) -- (C.center);
		\draw[red,-stealth]  (C.north west) -- (yticklabel cs:0);

		\draw[green,-stealth] (yticklabel* cs:1) -- (yticklabel cs:1);
		\draw[blue] (yticklabel cs:1) -- (O.north east);
		\draw[red,-stealth]  (O.north west) -- (yticklabel cs:1);
		\draw[red,-stealth]  (I.north west) -- (yticklabel cs:1);
    \end{axis}
\end{tikzpicture}
\end{codeexample}
	The example is similar to the one above: it generates an empty axis with a default range. Then, it creates three nodes: one for choice \declaretext{center}, one for choice \declaretext{inside}, and one for choice \declaretext{outside}. The node for |center| is placed |at (yticklabel cs:0)| (lower black circle). We see that its bounding box extends the size of the $y$~axis. This is because its anchor |C.center| is used for the alignment. Both the node for |inside| and the node for |outside| are placed |at (yticklabel cs:1)| (upper black circle). Their only difference is the choice for |near ticklabel align|. The node for |inside| does not extend the size of the $y$ axis; it is placed within its boundaries -- because its internal anchor |(I.north east)| (blue) has automatically been used in order to align the node. The node for |outside| is completely outside of the extends for the $y$~axis because its (blue) anchor |(O.south west)| has been chosen.
	
	Note that the red lines are always the same. They are the ``snap--to--nearest'' anchor such that the node is outside of the axis. Only the location of the blue anchors is affected by this key.

	Note that |near ticklabel align| always results in the same alignment, independent of the actual \emph{position} of the node. This is because an |anchor| is independent of the |at| location of a node. In this context, the names ``inside'' and ``outside'' might be a bad choice: they stress the intended meaning if the node is chosen at the upper end of the axis. However, if you say |at (yticklabel cs:0), near ticklabel align=inside|, it will actually end up \emph{outside} of the axis. This is because the ``inside'' anchor has been computed without considering where the node is.
%	FIXME : what is a better name!?
\end{pgfplotskey}

\begin{pgfplotskey}{near ticklabel at=\marg{coordinate} (initially empty)}
	Occasionally, |anchor=near ticklabel| results in a \emph{different} anchor depending on where the node is placed. This can happen for a |polaraxis|.
	
	If this key is needed, \PGFPlots\ will spit out the warning ``The anchor `near ticklabel' cannot be computed correctly because the position is missing. Please add `near ticklabel at=coordinate' with a suitable coordinate''.

	\PGFPlots\ uses context information to determine the correct information, so this may be unnecessary. If you encounter this warning, you should add |near ticklabel at=|\meta{value} with a suitable value.
\end{pgfplotskey}


\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}[]
\begin{tikzpicture}
	\begin{axis}[
		xlabel=Variable 1,
		ylabel=Variable 2,
		zlabel=value,
		xlabel style={sloped like x axis},
		ylabel style={sloped}
	]

	\addplot3[surf] {y*x*(1-x)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	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}
	\begin{key}{/pgfplots/sloped/at position=\marg{position} (initially empty)}
		This key can either be empty or a position. It is merely of interest for axes in which the transformation depends on the axis position as for |polaraxis|.
	\end{key}
\end{pgfplotsxykeylist}


\subsection{Labels}

\begin{pgfplotsxykey}{\x label=\marg{text}}
	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
\begin{codeexample}[code only]
% for x:
\node 
	[style=every axis label,
	style=every axis x label]

% for y:
\node 
	[style=every axis label,
	style=every axis y label] 
\end{codeexample}
so their position and appearance can be customized. 

	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 \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}| (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}
	These keys place axis labels (like |xlabel|) near the tick labels. If tick labels are small, labels will move closer to the axis. If tick labels are large, axis labels will move away from the axis. This is the default for every three dimensional plot, but it \emph{won't} be used initially for two--dimensional plots for backwards compatibility. Take a look at the definition of |near ticklabel| on page~\pageref{key:near:ticklabel} for an example.

	The definition of these styles is
\begin{codeexample}[code only]
\pgfplotsset{
	/pgfplots/xlabel near ticks/.style={
		/pgfplots/every axis x label/.style={
			at={(ticklabel cs:0.5)},anchor=near ticklabel
		}
	},
	/pgfplots/ylabel near ticks/.style={
		/pgfplots/every axis y label/.style={
			at={(ticklabel cs:0.5)},rotate=90,anchor=near ticklabel
		}
	}
}
\end{codeexample}
	
	It is encouraged to write
\begin{codeexample}[code only]
\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}

\begin{pgfplotsxykeylist}{\x label absolute,compat=pre 1.3}
	Installs placement styles for axis labels such that |xlabel| yields a description of absolute, fixed distance to the axis. This is the initial configuration (for backwards compatibility with versions before 1.3). Use |compat=1.3| to get the most recent, more flexible configuration. Take a look at the definition of |near ticklabel| on page~\pageref{key:near:ticklabel} for an example.

	These styles are defined by
\begin{codeexample}[code only]
\pgfplotsset{
	/pgfplots/xlabel absolute/.style={%
		/pgfplots/every axis x label/.style={at={(0.5,0)},below,yshift=-15pt},%
		/pgfplots/every x tick scale label/.style={
			at={(1,0)},yshift=-2em,left,inner sep=0pt
		},
	},
	/pgfplots/ylabel absolute/.style={%
		/pgfplots/every axis y label/.style={at={(0,0.5)},xshift=-35pt,rotate=90},
		/pgfplots/every y tick scale label/.style={
			at={(0,1)},above right,inner sep=0pt,yshift=0.3em
		},
	}
}
\end{codeexample}

	There is no predefined absolute placement style for three dimensional axes.
\end{pgfplotsxykeylist}

Whenever possible, consider using |/.append style| instead of overwriting the default styles to ensure compatibility with future versions.
\begin{codeexample}[code only]
\pgfplotsset{every axis label/.append style={...}}
\pgfplotsset{every axis x label/.append style={...}}
\pgfplotsset{every axis y label/.append style={...}}
\end{codeexample}
\end{pgfplotsxykey}

\begin{pgfplotskey}{title=\marg{text}}
Adds a caption to the plot. This will place a \Tikz-node with
\begin{codeexample}[code only]
\node[every axis title] {text};
\end{codeexample}
to the current axis.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}[
	xlabel=Dof,ylabel=Error,
	title={$\mu=0.1$, $\sigma=0.2$}]

	\addplot coordinates {
		(5,    8.312e-02)
		(17,   2.547e-02)
		(49,   7.407e-03)
		(129,  2.102e-03)
		(321,  5.874e-04)
		(769,  1.623e-04)
		(1793, 4.442e-05)
		(4097, 1.207e-05)
		(9217, 3.261e-06)
	};
\end{loglogaxis}
\end{tikzpicture}%
\end{codeexample}
%--------------------------------------------------
% \hfill
% \begin{tikzpicture}
% \begin{loglogaxis}[
% 	width=0.48\linewidth,
% 	xlabel=Dof,ylabel=Error,
% 	title={$\mu=1$, $\sigma=\frac{1}{2}$}]
% 
% 	\addplot[color=red,mark=*] coordinates {
% 		(7,		8.472e-02)
% 		(31,	3.044e-02)
% 		(111,	1.022e-02)
% 		(351,	3.303e-03)
% 		(1023,	1.039e-03)
% 		(2815,	3.196e-04)
% 		(7423,	9.658e-05)
% 		(18943,	2.873e-05)
% 		(47103,	8.437e-06)
% 	};
% \end{loglogaxis}
% \end{tikzpicture}
%-------------------------------------------------- 
The title's appearance and/or placement can be reconfigured with
\begin{codeexample}[code only]
\pgfplotsset{title style={at={(0.75,1)}}}
% or, equivalently,
\pgfplotsset{every axis title/.append style={at={(0.75,1)}}}
\end{codeexample}
This will place the title at~75\% of the $x$-axis. The coordinate~$(0,0)$ is the lower left corner and~$(1,1)$ the upper right one (see |axis description cs| for details).

Use |title/.add=|\marg{prefix}\marg{suffix} to modify an already assigned title.
\end{pgfplotskey}

\begin{pgfplotscodekey}{extra description}
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}[]
\pgfplotsset{every axis/.append style={
	extra description/.code={
		\node at (0.5,0.5) {Center!};
	}}}
\begin{tikzpicture}
	\begin{axis}
	\addplot {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotscodekey}


\subsection{Legends}
\label{pgfplots:sec:legendopts}
\label{pgfplots:sec:legendcmds}
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\oarg{options}\marg{name}}
Adds a single legend entry to the legend list. This will also enable legend drawing.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
\addplot[smooth,mark=*,blue] coordinates {
	(0,2)
	(2,3)
	(3,1)
};
\addlegendentry{Case 1}

\addplot[smooth,color=red,mark=x]
	coordinates {
		(0,0)
		(1,1)
		(2,1)
		(3,2)
	};
\addlegendentry{Case 2}
\end{axis}
\end{tikzpicture}
\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\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|:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
	\foreach \p in {1,2,3} {
	  \addplot {x^\p};
	  \addlegendentryexpanded{$x^\p$}
	}
\end{axis}
\end{tikzpicture}
\end{codeexample}
	Note that this example wouldn't have worked with |\addlegendentry{$x^\p$}| because the macro |\p| is no longer defined when \PGFPlots\ attempts to draw the legend.

	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, \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}|
	
	or, equivalently

		|\protect\pgfmathprintnumber{\p}|

	to avoid expansion of the macro which follows the |\protect| immediately.
\end{command}



\begin{command}{\legend\marg{list}}
\label{sec:legenddef}%
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 a list of entries, one for each plot. 

Two different delimiters are supported:
\begin{enumerate}
	\item There are comma--separated lists like 
\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 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, but it does not support the dots--notation.
\end{enumerate}
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}


\begin{pgfplotskey}{legend entries=\marg{comma separated list}}
	This key can be used to assign legend entries just like the commands |\addlegendentry| and |\legend|. Again, the positioning is relative to the axis rectangle (unless units like |cm| or |pt| are specified explicitly).
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend entries={$x$,$x^2$}]
	\addplot {x};
	\addplot {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The commands for legend creation take precedence: the key |legend entries| is only considered if there is no legend command in the current axis. 
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend entries={$x$,$x^2$}]
	\addplot {x};
	\addplot {x^2};
	\legend{$a$,$b$}% overrides the option
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	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$}]
	\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}


\subsection{Legend Appearance}

{%
\pgfplotsset{every axis/.append style={width=3cm,scale only axis,legend style={font=\footnotesize}}}%


\begin{stylekey}{/pgfplots/every axis legend}
The style ``|every axis legend|'' determines the legend's position and outer appearance:
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={
		at={(0,0)},
		anchor=south west}}
\end{codeexample}
will draw it at the lower left corner of the axis while
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={
		at={(1,1)},
		anchor=north east}}
\end{codeexample}
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 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}\\
	draw plot specification 2 & \node{legend 2}\\
	...
};
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	% this modifies 'every axis legend':
	legend style={font=\large}
]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	% align right:
	legend style={
		cells={anchor=east},
		legend pos=outer north east,
	}
]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$, legend $2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
% similar placement as previous example:
\pgfplotsset{every axis legend/.append style={
		at={(1.02,1)},
		anchor=north west}}
\begin{tikzpicture}
\begin{axis}
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

Use |legend columns=|\marg{number} to configure the number of horizontal legend entries.
\begin{codeexample}[]
\begin{tikzpicture}
\pgfplotsset{every axis legend/.append style={
		at={(0.5,1.03)},
		anchor=south}}
\begin{axis}[legend columns=4]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent
Instead of the |/.append style|, it is possible to use |legend style| as in the following example. It has the same effect.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	legend style={
		at={(1,0.5)},
		anchor=east}]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\noindent
The default |every axis legend| style is
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.style={
	cells={anchor=center},% Centered entries
	inner xsep=3pt,inner ysep=2pt,nodes={inner sep=2pt,text depth=0.15em},
	anchor=north east,
	shape=rectangle,
	fill=white,
	draw=black,
	at={(0.98,0.98)}
	}
}
\end{codeexample}
Whenever possible, consider using |/.append style| to keep the default styles active. This ensures compatibility with future versions.
\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


\begin{pgfplotskey}{legend pos=\mchoice{south west,south east,north west,north east,outer north east}}
	A style which provides shorthand access to some commonly used legend positions.

	Each of these styles appends |at={(|\meta{x}|,|\meta{y}|)},anchor=|\meta{name} values to |every axis legend|.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=south west]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=south east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=north east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=north west]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=outer north east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\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 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}
}

\begin{pgfplotskey}{legend columns=\marg{number} (default 1)}
Allows to configure the maximum number of adjacent legend entries. The default value~|1| places legend entries vertically below each other. 

Use |legend columns=-1| to draw all entries horizontally.
\end{pgfplotskey}

\begin{pgfplotskey}{legend plot pos=\mchoice{left,right,none} (initially left)}
Configures where the small line specifications will be drawn: left of the description, right of the description or not at all.
\end{pgfplotskey}

\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{Parabola}
	\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 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|.

\paragraph{Technical note:} At the time when legend images are drawn, the style |every axis legend| is in effect -- which have unwanted side-effects due to changed parameters (especially those concerning node placement, alignment, and shifting). It might be necessary to reset these parameters manually (\PGFPlots\ also attempts to reset the fill color).
\end{pgfplotscodekey}

\begin{stylekey}{/pgfplots/line legend}
	A style which sets |legend image code| (back) to its initial value. 

	Its initial value is
\begin{codeexample}[code only]
\pgfplotsset{
	/pgfplots/line legend/.style={
		legend image code/.code={
			\draw[mark repeat=2,mark phase=2,##1] 
				plot coordinates {
					(0cm,0cm) 
					(0.3cm,0cm)
					(0.6cm,0cm)
				};%
		}
	}
}
\end{codeexample}

	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}
	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
\begin{codeexample}[code only]
\pgfplotsset{
	legend image code/.code={%
		\draw[#1] (0cm,-0.1cm) rectangle (0.6cm,0.1cm);
	}
}	
\end{codeexample}
	
% \usetikzlibrary{patterns}
\begin{codeexample}[]
% \usetikzlibrary{patterns}
\begin{tikzpicture}
\begin{axis}[area legend,
	axis x line=bottom,
	axis y line=left,
	domain=0:1,
	legend style={at={(0.03,0.97)},
		anchor=north west},
	axis on top,xmin=0]
\addplot[pattern=crosshatch dots,
	pattern color=blue,draw=blue,
	samples=500] 
	{sqrt(x)}	\closedcycle;

\addplot[pattern=crosshatch,
	pattern color=blue!30!white,
	draw=blue!30!white]
	{x^2} \closedcycle;

\addplot[red,line legend] coordinates {(0,0) (1,1)};
\legend{$\sqrt x$,$x^2$,$x$}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{stylekey}

\begin{pgfplotsxykeylist}{\x bar legend,\x bar interval legend}
	These style keys redefine |legend image code| such that legends use |xbar|, |ybar| or the |xbar interval| and |ybar interval| handlers.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend pos=north west]
	\addplot {x^3};
	\addplot[ybar,fill=red,draw=red!60,
		ybar legend,mark=none,samples=5] 
		{-30*(x +4)};
	\legend{first,second}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
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={
		/pgfplots/legend image code/.code={%
			\draw[##1,/tikz/.cd,bar width=3pt,yshift=-0.2em,bar shift=0pt] 
			plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};},
	},
	/pgfplots/ybar legend/.style={
		/pgfplots/legend image code/.code={%
			\draw[##1,/tikz/.cd,bar width=3pt,yshift=-0.2em,bar shift=0pt] 
			plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};},
	},
	/pgfplots/xbar interval legend/.style={%
		/pgfplots/legend image code/.code={%
			\draw[##1,/tikz/.cd,yshift=-0.2em,bar interval width=0.7,bar interval shift=0.5]
			plot coordinates {(0cm,0.8em) (5pt,0.6em) (10pt,0.6em)};},
	},
	/pgfplots/ybar interval legend/.style={
		/pgfplots/legend image code/.code={%
			\draw[##1,/tikz/.cd,yshift=-0.2em,bar interval width=0.7,bar interval shift=0.5] 
			plot coordinates {(0cm,0.8em) (5pt,0.6em) (10pt,0.6em)};},
	},
}
\end{codeexample}
\end{pgfplotsxykeylist}

\begin{pgfplotskey}{mesh legend}
	Redefines |legend image code| such that it is compatible with |mesh| and |surf| plot handlers (for three dimensional visualization mainly).
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend pos=outer north east]
	\addplot3[surf,samples=9,domain=0:1] 
		{(1-abs(2*(x-0.5))) * (1-abs(2*(y-0.5)))};
	\addlegendentry{$\phi_x \phi_y$}

	\addplot3+[ultra thick] coordinates {(0,0,0) (0.5,0,1) (1,0,0)};
	\addlegendentry{$\phi_x $}

	\addplot3+[ultra thick] coordinates {(1,0,0) (1,0.5,1) (1,1,0)};
	\addlegendentry{$\phi_y $}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}

\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}
	\begin{axis}[reverse legend]
	\addplot {x};
	\addlegendentry{$x$}
	\addplot {x^2};
	\addlegendentry{$x^2$}
	\addplot {x^3};
	\addlegendentry{$x^3$}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\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$ parameters. 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}


\subsection{Legends with \texttt{\textbackslash label} and \texttt{\textbackslash ref}}
\label{pgfplots:legend:labelref}
\PGFPlots\ offers a |\label| and |\ref| feature for \LaTeX\ to assemble a legend manually, for example as part of the figure caption. These references work as usual \LaTeX\ references: a |\label| remembers where and what needs to be referenced and a |\ref| expands to proper text. In context of plots, a |\label| remembers the plot specification of one plot and a |\ref| expands to the small image which would also be used inside of legends.
\begin{codeexample}[]
\begin{tikzpicture}[baseline]
\begin{axis}
	\addplot+[only marks,
			samples=15,
			error bars/y dir=both,
			error bars/y fixed=2.5]
		{3*x+2.5*rand};
	\label{pgfplots:label1}

	\addplot+[mark=none] {3*x};
	\label{pgfplots:label2}

	\addplot {4*cos(deg(x))};
	\label{pgfplots:label3}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\begin{codeexample}[code only]
The picture shows the estimations \ref{pgfplots:label1} which are subjected to noise.
It appears the model \ref{pgfplots:label2} fits the data appropriately. 
Finally, \ref{pgfplots:label3} is only here to get three examples.
\end{codeexample}
\noindent The picture shows the estimations \ref{pgfplots:label1} which are subjected to noise.
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 \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}
\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.
	
	More precisely, the small image generated by |\ref|\marg{label name} is 
\begin{codeexample}[code only]
\tikz[/pgfplots/every crossref picture] {...}
\end{codeexample}
	\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}}
	Can be used to reference a labeled, single plot. See the example above.

	This will also work together with |hyperref| links and |\pageref|\footnote{Older versions of \PGFPlots\ required the use of \texttt{\textbackslash protect\textbackslash ref} when used inside of captions or section headings. This is no longer necessary.}.
\end{command}

\begin{key}{/pgfplots/refstyle=\marg{label name}}
	Can be used to set the \emph{styles} of a labeled, single plot. This allows to write
\begin{codeexample}[code only]
\addplot[/pgfplots/refstyle={pgfplots:label2}]
\end{codeexample}
	\noindent somewhere. Please note that it may be easier to define a style with |.style|.
\end{key}

\begin{stylekey}{/pgfplots/every crossref picture}
	A style which will be used by the cross-referencing feature for plots. The default is
\begin{codeexample}[code only]
\pgfplotsset{every crossref picture/.style={baseline,yshift=0.3em}}
\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 modifies the generated figure names by means of |\tikzappendtofigurename{_crossref}|.
	\index{crossref file suffix}
\end{pgfplotskeylist}

\subsection{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, 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}

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

\subsection{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 issued. 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}).

\subsection{Axis Lines}

{\small \emph{An extension by Pascal Wolkotte}}
\vspace{0.4cm}%

\label{sec:pgfplots:axislines}
\noindent By default the axis lines are drawn as a |box|, but it is possible to change the appearance of the $x$~and~$y$ axis lines.

\begin{pgfplotskeylist}{
	axis x line=\mchoice{box,top,middle,center,bottom,none} (initially box),
	axis x line*=\mchoice{box,top,middle,center,bottom,none} (initially box),
	axis y line=\mchoice{box,left,middle,center,right,none} (initially box),
	axis y line*=\mchoice{box,left,middle,center,right,none} (initially box),
	axis lines=\mchoice{box,left,middle,center,right,none},
	axis lines*=\mchoice{box,left,middle,center,right,none}}
	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 choice |axis x line=none| is an alias for |hide x axis|. The $y$- and $z$ variants work in a similar way. 

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.


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, some of these choices will modify axis label positions.
\end{itemize}
The handling of |axis y line| and |axis z line| is similar. The default styles are defined as
\begin{codeexample}[code only]
\pgfplotsset{
	every non boxed x axis/.style={
		xtick align=center,
		enlarge x limits=false,
		x axis line style={-stealth}
	},
	every boxed x axis/.style={}
}
\end{codeexample}
In addition, conditional modifications of axis label styles will be taken. For example, |axis x line=middle| will set
\begin{codeexample}[code only]
\pgfplotsset{every axis x label/.style={at={(current axis.left of origin)},anchor=south west}}
\end{codeexample}
if the matching $y$ style has value |axis y line=right| and 
\begin{codeexample}[code only]
\pgfplotsset{every axis x label/.style={at={(current axis.right of origin)},anchor=south east}}
\end{codeexample}
if |axis y line|$\neq$|right|.

Feel free to overwrite these styles if the default doesn't fit your needs or taste. Again, these styles will \emph{not} be used for |axis line*|. 

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	xlabel=$x$,ylabel=$\sin x$]

	\addplot[blue,mark=none,
		 domain=-10:0,samples=40]
		{sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=middle,
	axis y line=right,
	ymax=1.1, ymin=-1.1,
	xlabel=$x$,ylabel=$\sin x$
]
	\addplot[blue,mark=none,
		 domain=-10:0,samples=40]
		{sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}


\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=bottom,
	axis y line=left,
	xlabel=$x$,ylabel=$\sqrt{|x|}$
]
\addplot[blue,mark=none,
	 domain=-4:4,samples=501]
	{sqrt(abs(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	minor tick num=3,
	axis y line=center,
	axis x line=middle,
	xlabel=$x$,ylabel=$\sin x$
	]
	\addplot[smooth,blue,mark=none,
		 domain=-5:5,samples=40] 
		{sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	minor tick num=3,
	axis y line=left,
	axis x line=middle,
	xlabel=$x$,ylabel=$\sin x$
	]
	\addplot[smooth,blue,mark=none,
		 domain=-5:5,samples=40] 
		{sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

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.
\end{pgfplotskeylist}

\begin{pgfplotsxykey}{every inner \x\ axis line}
	A style key which can be redefined to customize the appearance of \emph{inner} axis lines. Inner axis lines are those drawn by the |middle| (or |center|) choice of |axis x line|, see above.

	This style affects \emph{only} the line as such.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	minor tick num=1,
	axis x line=middle,
	axis y line=middle,
	every inner x axis line/.append style=
		{|->>},
	every inner y axis line/.append style=
		{|->>},
	xlabel=$x$,ylabel=$y^3$
]
\addplot[blue,domain=-3:5] {x^3};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{every outer \x\ axis line}
	Similar to |every inner x axis line|, this style configures the appearance of all axis lines which are part of the outer box.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	separate axis lines, % important !
	every outer x axis line/.append style=
		{-stealth},
	every outer y axis line/.append style=
		{-stealth},
]
\addplot[blue,id=DoG,
		samples=100,
		domain=-15:15] 
  gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)};
\end{axis}
\end{tikzpicture}
\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}.

	Both cases have their advantages and disadvantages, I fear there is no reasonable default (suggestions are welcome).

	The case |separate axis lines=true| allows to draw arrow heads on each single axis line, but it can't close edges very well -- in case of thick lines, unsatisfactory edges occur.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	separate axis lines,
	every outer x axis line/.append style=
		{-stealth,red},
	every outer y axis line/.append style=
		{-stealth,green!30!black},
]
\addplot[blue,
		samples=100,
		domain=-15:15] 
	{1.3*exp(0-x^2/10) - exp(0-x^2/20)};
  % Unfortunately, there is a bug in PGF 2.00
  % something like exp(-10^2)
  % must be written as exp(0-10^2) :-(
\end{axis}
\end{tikzpicture}
\end{codeexample}

	The case |separate axis lines=false| issues just \emph{one} path for all axis lines. It draws a kind of rectangle, where some parts of the rectangle may be skipped over if they are not wanted. The advantage is that edges are closed properly. The disadvantage is that at most one arrow head is added to the path (and yes, only one drawing color is possible).
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	separate axis lines=false,
	every outer x axis line/.append style=
		{-stealth,red},
	every outer y axis line/.append style=
		{-stealth,green!30!black},
]
\addplot[blue,id=DoG,
		samples=100,
		domain=-15:15] 
  gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}

\subsection{Moving Axis Lines}
\PGFPlots\ offers styles to shift axis lines along their normal vector:
\begin{pgfplotsxykeylist}{
	axis \x\space line shift=\marg{dimension or unit} (initially empty),
	axis line shift=\marg{dimension or unit} (initially empty)}
	Allows to shift one or more axis lines together with all their descriptions.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		axis line shift=10pt,
		grid=major]
	\addplot+[samples=3] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The option takes the axis lines and shifts them along their ``outer normal vectors''. This direction is known for every axis; it is the direction which points away from the center.

	The operation is often combined with the |axis lines| variations, for example 
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		axis lines=left,
		axis line shift=10pt,
		grid=major]
	\addplot+[samples=3] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	Keep in mind that |axis lines=left| also reconfigures the axis such that it has an arrow head and |enlargelimits=false| (see also |axis lines*=left|). Customizations are, of course possible, for example an arrow tip which shows the end of the axis:

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		axis lines=left,
		axis line style={|-stealth},
		axis line shift=10pt,
		grid=major]
	\addplot+[samples=3] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	The argument \meta{dimension or unit} can be a dimension like |10pt| (as in the previous examples). However, it can also be given in terms of axis units:

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		axis lines=center,
		axis y line shift=2,
		axis x line shift=100,
		grid=major]
	\addplot+[samples=3] {30*x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	In this context, |axis y line shift=2| shifts the $y$ axis by $2$ units along the $x$~axis since the $x$~axis (with negative sign) is the ``outer normal''. Shifting by axis units is only possible for two--dimensional plots since the outer normal is well-defined here: it is the other available axis.
	

	The feature |axis line shift| can also be applied to three dimensional axes (with a \meta{dimension} argument, not a unit). In this case, the shift is also along the ``outer normal vector''. Note that this vector is a combination of the two other axes, so the resulting axis is no longer aligned with grid lines! Handle this option with care as it easily results in confusion when one tries to align the axis descriptions with grid lines.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		axis lines=left,
		axis line shift=10pt,
		grid=major]
	\addplot3[surf,shader=interp,samples=2] {x+y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The option |axis line shift| is a style which configures a shifts of \meta{dimension} for each axis.

	Note that |axis line shift| implies |separate axis lines| and will implicitly configure |hide obscured x ticks=false| and its variants.\index{separate axis lines!Combined with axis line shift}\index{!hide obscured x ticks!Combined with axis line shift}.
\end{pgfplotsxykeylist}



\subsection[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. 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}
  % let both axes use the same layers
  \pgfplotsset{set layers}
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    axis y line*=left,% the '*' avoids arrow heads
    xlabel=$x$,
    ylabel=First ordinate]
  \addplot {x^2};
  \end{axis}
  
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    axis y line*=right,
    axis x line=none,
    ylabel=Second ordinate]
  \addplot[red] {3*x};
  \end{axis}
\end{tikzpicture}
\end{codeexample}
\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.
	\item You need to tell \PGFPlots\ that it should share the same graphics layers for both axes. In this case, \PGFPlots\ will draw plots of the first axis and of the second axis onto the same layer. It will also draw background(s) into the background layer and descriptions into the foreground layer. Use the key |\pgfplotsset{set layers}| in front of the first axis to prepare the complete picture for layered graphics.
\end{enumerate}
You may want to consider different legend styles.
It is also possible to use only the axis, without any plots:
% \usepackage{textcomp}
\begin{codeexample}[]
% \usepackage{textcomp}
\begin{tikzpicture}
  % let both axes use the same layers
  \pgfplotsset{set layers}
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    axis y line*=left,%'*' avoids arrow heads
    xlabel=$x$,
    ylabel=Absolute]
  \addplot {x^2};
  \end{axis}
  
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    ymin=0,ymax=1000,
    yticklabel=
{$\pgfmathprintnumber{\tick}$\textperthousand},
    axis y line*=right,
    axis x line=none,
    ylabel=per thousand]
  \end{axis}
\end{tikzpicture}
\end{codeexample}
}

\subsection{Axis Discontinuities}

{\small \emph{An extension by Pascal Wolkotte}}
\vspace{0.4cm}%

\noindent In case the range of either of the axis do not include the zero value, it is possible to visualize this with a discontinuity decoration on the corresponding axis line.

\begin{pgfplotsxykey}{axis \x\ discontinuity=\mchoice{crunch,parallel,none} (initially none)}
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 to |axis y discontinuity| and |axis z discontinuity| as well, simply substitute $x$ by $y$ or $z$, respectively.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=bottom,
	axis x discontinuity=parallel,
	axis y line=left,
	xmin=360, xmax=600,
	ymin=0, ymax=7,
 	enlargelimits=false
]
	\addplot coordinates {
		(420,2)
		(500,6)
		(590,4)
	};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=bottom,
	axis y line=center,
	tick align=outside,
	axis y discontinuity=crunch,
	ymin=95, enlargelimits=false
]
	\addplot[blue,mark=none,
		 domain=-4:4,samples=20] 
		{x*x+x+104};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykey}

A problem might occur with the placement of the ticks on the axis.
This can be solved by specifying the minimum or maximum axis value for which a tick will be placed.

\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord} (default axis limits), \x tickmax=\marg{coord} (default axis limits)}
\label{key:xytickminmax}
The options |xtickmin|, |xtickmax| and |ytickmin|, |ytickmax| allow to define the axis tick limits, i.e.\ the axis values before respectively after no ticks will be placed.
Everything outside of the axis tick limits will be not drawn.
Their default values are equal to the axis limits.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=bottom,
	axis y line=center,
	tick align=outside,
	axis y discontinuity=crunch,
	xtickmax=3,
	ytickmin=110,
	ymin=95, enlargelimits=false
]
	\addplot[blue,mark=none,
		 domain=-4:4,samples=20] 
		{x*x+x+104};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykeylist}

\begin{pgfplotsxykeylist}{%
	hide \x\ axis=\mchoice{true,false} (initially false),
	hide axis=\mchoice{true,false} (initially false)}
\tikzset{external/figure name/.add={}{hideaxis_}}%
Allows to hide either a selected axis or all of them. No outer rectangle, no tick marks and no labels will be drawn. Only titles and legends will be processed as usual.

Axis scaling and clipping (!) will be done as if you did not use |hide axis|.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		hide x axis,
		hide y axis,
		title={$x^2\cos(x)$}]
	\addplot {cos(x)*x^2};
	\end{axis}
\end{tikzpicture}% <- eliminate space.
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		hide x axis,
		axis y line=left,
		title={$x^2\cos(x)$}]
	\addplot {cos(x)*x^2};
	\end{axis}
\end{tikzpicture}% <- eliminate space
\end{codeexample}

Note that a hidden axis contributes nothing to the resulting picture's bounding box\footnote{Since version 1.8.}, see |clip bounding box|.\index{Bounding Box Control!hide axis}%
\pgfplotsexpensiveexample
% \usepgfplotslibrary{patchplots}
\begin{codeexample}[]
% requires \usepgfplotslibrary{patchplots} 
% and compat=1.8 or newer
\begin{tikzpicture}
\begin{axis}[
	hide axis,
]
\addplot3[patch,
	patch type=biquadratic,
	shader=interp]
coordinates {
	(0,0,1) (6,1,0) (5,5,0) (-1,5,0)
	(3,1,0) (6,3,0) (2,6,0) (0,3,0)
	(3,3.75,0)
};
\end{axis}
\end{tikzpicture}% <- eliminate space
\end{codeexample}
	This can be used to embed a \PGFPlots\ path which needs an axis to a standard \tikzname\ picture. See also Section~\ref{pgfplots:tikz:interoperability} for details how to synchronize the alignment between a \PGFPlots\ figure (which typically rescales its coordinates) to that of a standard |tikzpicture|.

	Note that \PGFPlots\ uses the input coordinates to determine the bounding box of the picture. In this case, the bounding box is slightly smaller than the shading. A cure would be to increase the bounding box manually.

	You may want to disable the |clip| path using the option |clip=false|.
\end{pgfplotsxykeylist}

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

\begin{pgfplotskey}{colorbar=\mchoice{true,false} (initially false)}
	Activates or deactivates color bars.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar]
		\addplot[mesh,ultra thick] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar,colormap/greenyellow]
		\addplot[mesh,ultra thick] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar horizontal]
		\addplot[mesh,ultra thick] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	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
\begin{codeexample}[code only]
\axis[every colorbar,colorbar shift,colorbar=false]
	\addplot graphics {};
\endaxis
\end{codeexample}
	\noindent where the placement, alignment, appearance and other options are done by the two styles |every colorbar| and |colorbar shift|. These styles and the possible placement and alignment options are described below.

	\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. 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}
\end{pgfplotskey}

\begin{stylekey}{/pgfplots/colorbar right}
	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}[]
\begin{tikzpicture}
	\begin{axis}[colorbar right]
	\addplot[mesh,thick,samples=150,domain=0.1:3] 
		{1/x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	The style |colorbar right| is defined as
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar right/.style={
		/pgfplots/colorbar=true,
		/pgfplots/colorbar shift/.style={xshift=0.3cm},
		/pgfplots/every colorbar/.style={
			title=,
			xlabel=,
			ylabel=,
			zlabel=,
			legend entries=,
			axis on top,
			at={(parent axis.right of north east)},
			anchor=north west,
			xmin=0,
			xmax=1,
			ymin=\pgfkeysvalueof{/pgfplots/point meta min},
			ymax=\pgfkeysvalueof{/pgfplots/point meta max},
			plot graphics/xmin=0,
			plot graphics/xmax=1,
			plot graphics/ymin=\pgfkeysvalueof{/pgfplots/point meta min},
			plot graphics/ymax=\pgfkeysvalueof{/pgfplots/point meta max},
			enlargelimits=false,
			scale only axis,
			height=\pgfkeysvalueof{/pgfplots/parent axis height},
			x=\pgfkeysvalueof{/pgfplots/colorbar/width},
			yticklabel pos=right,
			xtick=\empty,
			colorbar vertical/lowlevel,
		}
	},
	/pgfplots/colorbar vertical/lowlevel/.style={
		plot graphics/lowlevel draw/.code 2 args={%
			\pgfuseshading{...} % some advanced basic level shading operations
		}
	},
}
\end{codeexample}
	\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>}]
% wrong, colorbar right resets the customization:
\begin{axis}[colorbar style={<some customization>}, colorbar right]
\end{codeexample}
\end{stylekey}

\begin{stylekey}{/pgfplots/colorbar left}
	A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed left of their parent axis.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar left]
	\addplot[mesh,thick,samples=150] 
		{x*sin(deg(4*x))};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	The style |colorbar left| is defined as
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar left/.style={
		/pgfplots/colorbar right,
		/pgfplots/colorbar shift/.style={xshift=-0.3cm},
		/pgfplots/every colorbar/.append style={
			at={(parent axis.left of north west)},
			anchor=north east,
			yticklabel pos=left,
		}
	}
}
\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|).
\end{stylekey}

\begin{stylekey}{/pgfplots/colorbar horizontal}
	A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed below their parent axis, with a horizontal bar.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar horizontal]
	\addplot[only marks,scatter,
		scatter src={mod(\coordindex,15)},samples=150] 
		{rand};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	This style is defined as
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar horizontal/.style={
		/pgfplots/colorbar=true,
		/pgfplots/colorbar shift/.style={yshift=-0.3cm},
		/pgfplots/every colorbar/.style={
			title=,
			xlabel=,
			ylabel=,
			zlabel=,
			legend entries=,
			axis on top,
			at={(parent axis.below south west)},
			anchor=north west,
			ymin=0,
			ymax=1,
			xmin=\pgfkeysvalueof{/pgfplots/point meta min},
			xmax=\pgfkeysvalueof{/pgfplots/point meta max},
			plot graphics/ymin=0,
			plot graphics/ymax=1,
			plot graphics/xmin=\pgfkeysvalueof{/pgfplots/point meta min},
			plot graphics/xmax=\pgfkeysvalueof{/pgfplots/point meta max},
			enlargelimits=false,
			scale only axis,
			width=\pgfkeysvalueof{/pgfplots/parent axis width},
			y=\pgfkeysvalueof{/pgfplots/colorbar/width},
			xticklabel pos=left,
			ytick=\empty,
			colorbar horizontal/lowlevel,
		}%
	},%
	/pgfplots/colorbar horizontal/lowlevel/.style={%
		plot graphics/lowlevel draw/.code 2 args={%
			\pgfuseshading{...} % some advanced basic level shading operations
		},%
	},%
}
\end{codeexample}
	\paragraph{Attention:} |colorbar horizontal| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar horizontal|:
\begin{codeexample}[code only]
% correct:
\begin{axis}[colorbar horizontal, colorbar style={<some customization>}]
% wrong, colorbar horizontal resets the customization:
\begin{axis}[colorbar style={<some customization>}, colorbar horizontal]
\end{codeexample}
\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.
\begin{predefinednode}{parent axis}
	A node for the parent axis of a color bar. It is only valid for color bars.
\end{predefinednode}

	Thus, 
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar style={
		at={(parent axis.right of north east)},
		anchor=north west,
	},
	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.

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

	These values are only valid inside of color bars.
\end{pgfplotskeylist}

	Besides these values, each color bar inherits a list of styles of its parent axis, namely

	\begin{itemize}
		\item |every tick|,
		\item |every minor tick|,
		\item |every major tick|,
		\item |every axis grid|,
		\item |every minor grid|,
		\item |every major grid|,
		\item |every tick label|.
	\end{itemize}
	This can be used to inherit line width and/or fonts.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	colorbar horizontal, 
	colorbar style={
	  at={(0.5,1.03)},anchor=south,
	  xticklabel pos=upper
	},
	title style={yshift=1cm},
	title=Customization: ``colorbar top'']

	\addplot[mesh,thick,samples=150,domain=0.1:3] 
		{x};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	colorbar horizontal, 
	colorbar style={
	  at={(1,1.03)},anchor=south east,
	  width=0.5*
	    \pgfkeysvalueof{/pgfplots/parent axis width},
	  xticklabel pos=upper,
	},
	title style={yshift=1cm},
	title=More Customization: ``colorbar top'']

	\addplot[mesh,thick,samples=150,domain=0.1:3] 
		{x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	Please take a look at the predefined styles |colorbar right|, |colorbar left| and |colorbar horizontal| for more details about configuration possibilities for |every colorbar|.

	\paragraph{Remark:} A color bar is just a normal axis. That means |every colorbar| can contain specifications where to place tick labels, extra ticks, scalings and most other features of a normal axis as well (except nested color bars).
\end{stylekey}

\begin{pgfplotskey}{colorbar style=\marg{key-value list}}
	A shortcut for |every colorbar/.append style=|\marg{key-value list}. It appends options to the colorbar style.
\end{pgfplotskey}

\begin{pgfplotskey}{colorbar/width=\marg{dimension} (initially 0.5cm)}
	Sets the width of a color bar.
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		view/az=45,
		colorbar,
		colorbar/width=2cm,
		colormap/blackwhite]

	\addplot3[surf,domain=0:1,y domain=-3:3] {x*(1-x)*tanh(y)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	For horizontal color bars, this sets the height.
\end{pgfplotskey}


\begin{stylekey}{/pgfplots/colorbar shift}
	This style is installed after |every colorbar|. It is intended to contain only shift transformations like |xshift| and/or |yshift|. The reason to provide two separate styles is to allow easier deactivation of shift transformations.

\begin{codeexample}[code only]
\pgfplotsset{
	colorbar shift/.style={xshift=1cm}
}
\end{codeexample}
\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 itself).
\end{predefinednode}

\begin{pgfplotscodekey}{colorbar/draw}
	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.
	
	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).

	The initial configuration is
\begin{codeexample}[code only]
\pgfplotsset{colorbar/draw/.code={%
	\axis[every colorbar,colorbar shift,colorbar=false]
	\addplot graphics {};
	\endaxis
	}
}
\end{codeexample}

	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}

	\paragraph{Attention:} this style merely changes the appearance of the |colorbar|. The way |colormap|s are used to determine plot colors is unrelated to this key. See also |colormap access=direct| for ways to affect the color selection.

	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}]
	\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 color bar.
\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}
	\paragraph{Attention:} this style merely changes the appearance of the |colorbar|. The way |colormap|s are used to determine plot colors is unrelated to this key. See also |colormap access=direct| for ways to affect the color selection.

	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 |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}

\begin{stylekey}{/pgfplots/colorbar as legend}
	A |colorbar| which uses the same place for each color. It is useful for |colormap|s with non-uniform positions where each item has to be documented in the |colorbar|, even if it is only relevant for a ``small'' portion of the data range.

	The following example shows a non-uniform |colormap| with the default (proportional) display: each color receives as much ``room'' as its interval occupies.
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colorbar style={
		ticklabel style={font=\tiny}},
	colormap access=const,
	colormap={CM}{
		of colormap={
			viridis, 
			target pos={0,200,300,350,375,
				400,700,800,850,1000},
			sample for=const,
		}
	}]
\end{codeexample}

	If we use the very same |colormap| but visualize it as |colorbar as legend|, we get the same ``room'' for each color, independent of the underlying position interval -- it is more like a legend than a normal |colorbar|:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colorbar as legend,
	colorbar style={ticklabel style={font=\tiny}},
	colormap access=const,
	colormap={CM}{
		of colormap={
			viridis, 
			target pos={0,200,300,350,375,
				400,700,800,850,1000},
			sample for=const,
		}
	}]
\end{codeexample}
	\noindent Clearly, such a |colorbar| looses the capability to interpolate positions; it becomes a lookup table (which, again, is more like a legend).

	\paragraph{Limitations:} This style has its best fit for |colormap access=const|, especially in conjunction with |sample for=const|\footnote{Note that \texttt{sample for=const} adds a dummy color. This dummy color is omitted when displaying \texttt{colorbar as legend}, assuming it is a dummy color for the last interval. This may produce unexpected effects when used with a continuous colormap.} It may produce unexpected results when used for continuous mappings.
\end{stylekey}

\subsection{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}

