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.

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.