PGFPLOTS

PGFPLOTS works in combination with TikZ. It serves the purpose of adding plots. Mainly giving facilities to create very customized axis and read of data points inlined or in external files.

In general we think as a plot in a document as a separate part. It is regarded as a figure that we somehow include in the main document, and by tradition it has some arbitrary format independent of that in the document. Moreover due to usual limitations of plotting programs we don't dare to include complicated symbols or formulas in plots. They can't typeset formulas or text properly, but LaTeX could in principle.

PGFPLOT allow to add plots with an exquisite level of sophistication and at the same time keep all the typesetting capabilities. Let alone the capacity of giving the plot the same formatting as the rest of the document, including font type and bibliographical references.

In order to keep the tutorial short and simple I will concentrate in PGFPLOTS as a replacement for the good GNUplot.

Installation

PGFplots 1.12 comes with TeXLive 2009 and therefore also with Ubuntu 10.04-11.10. However that can be a pretty old version for some useful features. A possible fix is to install the latest version of PGFplots manually or in the user directory or update TeXLive manually to 2011. Another quick fix that works in Ubuntu is to install PGFplots 1.3 from this repository

 deb http://ppa.launchpad.net/johannes-reinhardt/ppa/ubuntu lucid main

The last version is 1.5.1, check that the manual you are using corresponds to the same version that you have installed. Some options change with version and the error messages derived are cryptic. To install 1.5.1 on top of TeXLive 2009 you need to upgrade PGF also:

mkdir -p ~/texmf
cd ~/texmf
wget http://downloads.sourceforge.net/project/pgf/pgf/version%202.10/pgf_2.10.tds.zip
unzip pgf_2.10.tds.zip
wget http://downloads.sourceforge.net/project/pgfplots/pgfplots/1.5.1/pgfplots_1.5.1.tds.zip
unzip pgfplots_1.5.1.tds.zip
texhash

This will make TeX ignore the system's old version of the libraries. Check the TeX output to ensure that this is the path of the library being used.

Basics

To start using the library, just add this line to the header of a LaTeX document:

\usepackage{pgfplots}

Every plot is part of a tikzpicture (this allows to combine TikZ and PGFPLOTS seamlessly). The main object in PGFPLOTS is the axis environment.

\begin{tikzpicture}  %every plot is part of a tikzpicture
  \begin{axis}
    ... plots are defined here ...
  \end{axis}
\begin{tikzpicture}

Plotting data from a file

PGFPLOTS has the ability to read data from a file, just as GNUPlot typically as

gnuplot> plot 'datafile.dat'

In PGFPLOTS we insert this command inside de axis environment.

\addplot table {datafile.dat};

Plotting columns

gnuplot> plot 'datafile.dat' using 3:4

translates to

\addplot table[x index=2, y index=3] {datafile.dat};

Note that indixing starts at 0 for numbering columns.

Expressions (transformation) from data [x expr=\thisrow...]

gnuplot> plot 'datafile.dat' using ($1*2.):($2+1.)

can be reproduced by

\addplot table[x expr=\thisrowno{0}*2., y expr=\thisrowno{1}+1.] {datafile.dat};

Restricted domain

In GNUPlot there are two ways to cutoff the plotted data/domain. The first is to add a domain for abscisas (or for abscisas and ordinates)

gnuplot> plot [1:9][2:5] 'datafile.dat'

This works and it is a property of the axis, not a property of the curve. That is, for example, if plotting two data sets it will be a restriction for both curves. The second way is per curve and it more complicated, it involves adding an expression that is undefined (1/0) for certain points.

gnuplot> plot 'datafile.dat' using ($1<1?1/0:($1>9?1/0:$1)):($1<2?1/0:($1>5?1/0:$1))

In PGFPLOTS the equivalent of the first is to

 \begin{axis}[width=\textwidth, restrict x to domain=0:50, restrict y to domain=0:10]
   \addplot ...
 \end{axis}

A 'per curve' equivalent is

 \addplot[restrict x to domain=0:50, restrict y to domain=0:10] table {datafile.dat};

Both methods are obviously different in the case where there is more that one curve, since the restriction domain can be different for each.

(PGFPLOTS has 'domain' and 'domain y' option that is very similar for expression plots, but has not effect in table plots.)

Independently of the above absolute axis limits can be defined with the keys:

\begin{axis}[xmin = x1, xmax = x2, ymin = y1, ymax = y2] ...

these absolute limits are relaxed by the key "enlargelimits".

Formatting

Colors

In gnuplot specifying that we are using colors is done implicitly when we determine the terminal (output type). Typically 'set terminal postscript enhanced color'.

In PGFPlots colors (and marks) are automatic for the most part. Unless we define some formatting for the lines, everything become black. We can restore colors plot by plot, but by far the most useful thing is to add the following option to the axis environment

\begin{axis}[cycle list name=color list]
...

This automatically assigns colors to the plots inside the axis. The color list cycle can be defined explicitly by replacing 'color list' with the colors we want. Or to have new default

\pgfplotscreateplotcyclelist{color list}{
 red,blue,black,yellow,brown,teal,orange,violet,cyan,green!70!black,magenta,gray
}

The color is also a property that the plot itself can overwrite (note that all properties --line type, symbol type, etc-- will be overwritten then):

\addplot[red] coordinates {...};

(See section 4.6.6 in the official manual).

To avoid overwritting the options set externally (to the plot) you can use the construction

\addplot+[red] coordinates {...};