% main=pgfplots.tex

\section{User's Guide: Drawing Axes and Plots}

The user interface of \PGFPlots\ consists of three components: a |tikzpicture| environment, an |axis| and the |\addplot| command.

Each axis is generated as part of a picture environment (which can be used to annotate plots afterwards, for example). The axis environment encapsulates one or more |\addplot| commands and controls axis-wide settings (like limits, legends, and descriptions). The |\addplot| command supports several coordinate input methods (like table input or mathematical expressions) and allows various sorts of visualization options with straight lines as initial configuration. 

The rest of \PGFPlots\ is a huge set of key--value options to modify the initial configuration or to select plot types. The reference manual has been optimized for electronical display: a lot of examples illustrate the features, and reference documentation can be found by clicking into the sourcecode text fields. Note that most pdf viewers also support to jump back from a hyperlink: for Acrobat Reader, open the menu View$\gg$Toolbars$\gg$More Tools and activate the ``Previous View'' and ``Next View'' buttons (which are under ``Page Navigation Toolbar''). Thus, knowledge of all keys is unnecessary; you can learn them when it is necessary.

To learn \PGFPlots, you should learn about the |\addplot| command and its coordinate input methods. The most important input methods are \verbpdfref{\addplot table} and \verbpdfref{\addplot expression}.

The following sections explain the basics of \PGFPlots, namely how to work with the |\addplot| commands and |axis| environments and how line styles are assigned automatically.

\subsection{\TeX-dialects: \LaTeX, Con{\TeX}t, plain \TeX }
\label{sec:tex:dialects}%
The starting point for \PGFPlots\ is an |axis| enviroment like |axis| or the logarithmic variants |semilogxaxis|, |semilogyaxis| or |loglogaxis|.

Each environment is available for \LaTeX, Con{\TeX}t and plain \TeX:
\begin{description}
\def\HEAD{%
	\small
	%\lstset{boxpos=b,breaklines=false,aboveskip=3pt,belowskip=3pt}%
	%\hspace{-1cm}%
	\begin{tabular}{*{2}{p{4cm}}}%
}%
\item[\LaTeX:] |\usepackage{pgfplots}| and

{\HEAD
\begin{codeexample}[code only]
\begin{tikzpicture}
\begin{axis}
...
\end{axis}
\end{tikzpicture}
\end{codeexample}
&
\begin{codeexample}[code only]
\begin{tikzpicture}
\begin{semilogxaxis}
...
\end{semilogxaxis}
\end{tikzpicture}
\end{codeexample}
\\
\end{tabular}%
}

\begin{codeexample}[code only]
\documentclass[a4paper]{article}

% for dvipdfm:
%\def\pgfsysdriver{pgfsys-dvipdfm.def}
\usepackage{pgfplots}
\pgfplotsset{compat=1.3}% <-- moves axis labels near ticklabels (respects tick label widths)

\begin{document}
\begin{figure}
	\centering
	\begin{tikzpicture}
		\begin{loglogaxis}[xlabel=Cost,ylabel=Error]
		\addplot coordinates {
			(5,     8.31160034e-02)
			(17,    2.54685628e-02)
			(49,    7.40715288e-03)
			(129,   2.10192154e-03)
			(321,   5.87352989e-04)
			(769,   1.62269942e-04)
			(1793,  4.44248889e-05)
			(4097,  1.20714122e-05)
			(9217,  3.26101452e-06)
		};
		\addplot coordinates {
			(7,     8.47178381e-02)
			(31,    3.04409349e-02)
			(111,   1.02214539e-02)
			(351,   3.30346265e-03)
			(1023,  1.03886535e-03)
			(2815,  3.19646457e-04)
			(7423,  9.65789766e-05)
			(18943, 2.87339125e-05)
			(47103, 8.43749881e-06)
		};
		\legend{Case 1,Case 2}
		\end{loglogaxis}
	\end{tikzpicture}
	\caption{A larger example}
\end{figure}
\end{document}
\end{codeexample}

\item[Con{\TeX}t:] |\usemodule[pgfplots]| and

{\HEAD
\begin{codeexample}[code only]
\starttikzpicture
\startaxis
...
\stopaxis
\stoptikzpicture
\end{codeexample}
&
\begin{codeexample}[code only]
\starttikzpicture
\startsemilogxaxis
...
\stopsemilogxaxis
\stoptikzpicture
\end{codeexample}
\\
\end{tabular}%
}

A complete Con{\TeX}t--example file can be found in
\begin{codeexample}[code only]
doc/context/pgfplots/pgfplotsexample.tex.
\end{codeexample}

\item[plain \TeX:] |\input pgfplots.tex| and

{\HEAD
\begin{codeexample}[code only]
\tikzpicture
\axis
...
\endaxis
\endtikzpicture
\end{codeexample}
&
\begin{codeexample}[code only]
\tikzpicture
\semilogxaxis
...
\endsemilogxaxis
\endtikzpicture
\end{codeexample}
\\
\end{tabular}%
}

A complete plain--\TeX--example file can be found in
\begin{codeexample}[code only]
doc/plain/pgfplots/pgfplotsexample.tex.
\end{codeexample}
\end{description}

If you use |latex| / |dvips| or |pdflatex|, no further modifications are necessary. For |dvipdfm|, you should use the |\def\pgfsysdriver| line as indicated above in the examples (see also Section~\ref{sec:drivers}).


\subsection{A First Plot}
Plotting is done using |\begin{axis} ... \addplot ...; \end{axis}|, where |\addplot| is the main interface to perform plotting operations.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		xlabel=Cost,
		ylabel=Error]
	\addplot[color=red,mark=x] coordinates {
		(2,-2.8559703)
		(3,-3.5301677)
		(4,-4.3050655)
		(5,-5.1413136)
		(6,-6.0322865)
		(7,-6.9675052)
		(8,-7.9377747)
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}


\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		xlabel=$x$,
		ylabel={$f(x) = x^2 - x +4$}
	]
	% use TeX as calculator:
	\addplot {x^2 - x +4};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		xlabel=$x$,
		ylabel=$\sin(x)$
	]
	% invoke external gnuplot as
	% calculator:
	\addplot gnuplot[id=sin]{sin(x)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

The |plot coordinates|, |plot expression| and |plot gnuplot| commands are three of the several supported ways to create plots, see Section~\ref{sec:addplot} for more details\footnote{Please note that you need \lstinline{gnuplot} installed to use \lstinline{plot gnuplot}.} and the remaining ones (|plot file|, |plot shell|, |plot table| and |plot graphics|). The options `|xlabel|' and `|ylabel|' define axis descriptions.

\subsection{Two Plots in the Same Axis}
Multiple |\addplot|-commands can be placed into the same axis, and a |cycle list| is used to automatically select different line styles:
	% generated with this statement:
	%\addplot plot[id=filesuffix_noise,domain=-6:5,samples=10] gnuplot{(-x**5 - 242 + (-300 + 600*rand(0)))};
\begin{codeexample}[leave comments]
\begin{tikzpicture}
	\begin{axis}[
		height=9cm,
		width=9cm,
		grid=major,
	]
		
	\addplot {-x^5 - 242};
	\addlegendentry{model}

	\addplot coordinates {
		(-4.77778,2027.60977)
		(-3.55556,347.84069)
		(-2.33333,22.58953)
		(-1.11111,-493.50066)
		(0.11111,46.66082)
		(1.33333,-205.56286)
		(2.55556,-341.40638)
		(3.77778,-1169.24780)
		(5.00000,-3269.56775)
	};
	\addlegendentry{estimate}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
A legend entry is generated if there are |\addlegendentry| commands (or one |\legend| command).

\subsection{Logarithmic Plots}
Logarithmic plots show $\log x$ versus $\log y$  (or just one logarithmic axis). \PGFPlots\ normally uses the natural logarithm, i.e. basis $e\approx2.718$ (see the key |log basis x|). Now, the axis description also contains minor ticks and the labels are placed at $10^i$.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}[xlabel=Cost,ylabel=Gain]
\addplot[color=red,mark=x] coordinates {
	(10,100)
	(20,150)
	(40,225)
	(80,340)
	(160,510)
	(320,765)
	(640,1150)
};
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
A common application is to visualise scientific data. This is often provided in the format $1.42\cdot10^4$, usually written as 1.42e+04. Suppose we have a numeric table named |pgfplots.testtable|, containing
\begin{codeexample}[code only,tabsize=6]
Level Cost  Error
1     7     8.471e-02
2     31    3.044e-02
3     111   1.022e-02
4     351   3.303e-03
5     1023  1.038e-03
6     2815  3.196e-04
7     7423  9.657e-05
8     18943 2.873e-05
9     47103 8.437e-06
\end{codeexample}
\noindent then we can plot |Cost| versus |Error| using
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}[
	xlabel=Cost,
	ylabel=Error]
\addplot[color=red,mark=x] coordinates {
	(5,    8.31160034e-02)
	(17,   2.54685628e-02)
	(49,   7.40715288e-03)
	(129,  2.10192154e-03)
	(321,  5.87352989e-04)
	(769,  1.62269942e-04)
	(1793, 4.44248889e-05)
	(4097, 1.20714122e-05)
	(9217, 3.26101452e-06)
};

\addplot[color=blue,mark=*] 
	table[x=Cost,y=Error] {pgfplots.testtable};

\legend{Case 1,Case 2}
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
The first plot employs inline coordinates; the second one reads numerical data from file and plots column `|Cost|' versus `|Error|'.

\noindent
Besides the environment ``|loglogaxis|'' you can use
\begin{itemize}
	\item |\begin{axis}...\end{axis}| for normal plots,
	\item |\begin{semilogxaxis}...\end{semilogxaxis}| for plots which have a normal~$y$ axis and a logarithmic~$x$ axis,
	\item |\begin{semilogyaxis}...\end{semilogyaxis}| the same with $x$~and~$y$ switched,
	\item |\begin{loglogaxis}...\end{loglogaxis}| for double--logarithmic plots.
\end{itemize}
You can also use
\begin{codeexample}[code only]
\begin{axis}[xmode=normal,ymode=log]
...
\end{axis}
\end{codeexample}
which is the same as |\begin{semilogyaxis}...\end{semilogyaxis}|.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{semilogyaxis}[
		xlabel=Index,ylabel=Value]

	\addplot[color=blue,mark=*] coordinates {
		(1,8)
		(2,16)
		(3,32)
		(4,64)
		(5,128)
		(6,256)
		(7,512)
	};
	\end{semilogyaxis}%
\end{tikzpicture}%
\end{codeexample}

\subsection{Cycling Line Styles}
You can skip the style arguments for |\addplot[...]| to determine plot specifications from a predefined list:
\label{page:plotcoords:src}%
\pgfmanualpdflabel{\textbackslash plotcoords}{}%
\begin{codeexample}[width=4cm]
\begin{tikzpicture}
\begin{loglogaxis}[
	xlabel={Degrees of freedom},
	ylabel={$L_2$ Error}
]
\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)
};

\addplot 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)
};

\addplot coordinates{
	(9,7.881e-02)     (49,3.243e-02)    (209,1.232e-02)
	(769,4.454e-03)   (2561,1.551e-03)  (7937,5.236e-04)
	(23297,1.723e-04) (65537,5.545e-05) (178177,1.751e-05)
};

\addplot coordinates{
	(11,6.887e-02)    (71,3.177e-02)     (351,1.341e-02)
	(1471,5.334e-03)  (5503,2.027e-03)   (18943,7.415e-04)
	(61183,2.628e-04) (187903,9.063e-05) (553983,3.053e-05)
};

\addplot coordinates{
	(13,5.755e-02)     (97,2.925e-02)     (545,1.351e-02)
	(2561,5.842e-03)   (10625,2.397e-03)  (40193,9.414e-04)
	(141569,3.564e-04) (471041,1.308e-04) (1496065,4.670e-05)
};
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
\noindent
The |cycle list| can be modified, see the reference below.

\subsection{Scaling Plots}
You can use any of the \Tikz\ options to modify the appearance. For example, the ``|scale|'' transformation takes the picture as such and scales it (just like |\includegraphics|):

\begin{codeexample}[]
\begin{tikzpicture}[scale=0.5]
	\begin{loglogaxis}[
		xlabel={Degrees of freedom},
		ylabel={$L_2$ Error}
	]
	\plotcoords
	\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
	\end{loglogaxis}
\end{tikzpicture}

\begin{tikzpicture}[scale=1.1]
	\begin{loglogaxis}[
		xlabel={Degrees of freedom},
		ylabel={$L_2$ Error}
	]
	\plotcoords
	\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
	\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
However, you can also scale plots by assigning a |width=5cm| and/or |height=3cm| argument. This only affects the distance of point coordinates, no font sizes or axis descriptions:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{loglogaxis}[
		width=6cm,
		xlabel={Degrees of freedom},
		ylabel={$L_2$ Error}
	]
	\plotcoords
	\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
	\end{loglogaxis}
\end{tikzpicture}

\begin{tikzpicture}
	\begin{loglogaxis}[
		width=8cm,
		xlabel={Degrees of freedom},
		ylabel={$L_2$ Error}
	]
	\plotcoords
	\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
	\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}

Use the predefined styles |normalsize|, |small|, |footnotesize| to adopt font sizes and ticks automatically. Use the |/pgfplots/scale| key to rescale the axis without affecting fonts.

\endinput