2 % $Id: tutorial.tex,v 1.6 2006/08/05 18:17:57 sfeam Exp $
4 % Tutorial for gnuplot plotting program, for LaTeX users
6 % Duke University Computer Science Department
8 % Slightly updated by the gnuplot team in 2004, for gnuplot 4.0.
9 % Updated for gnuplot 4.2 to include epslatex example by Ethan A Merritt
11 % NOTE: If LaTeX runs out of memory processing plots,
12 % add ``with lines 4'' to each curve in eg*.plt and rerun make.
25 {\Large \bf \LaTeX\ and the Gnuplot Plotting Program}
29 {\bf David Kotz} \\[0.4cm]
30 Principal author of this tutorial for gnuplot 3.0, July 3, 1991 \\[1.0cm]
32 {\bf current gnuplot team} \\[0.4cm]
33 Updates of this tutorial for gnuplot 4.0, March 2004 \\
34 Updates of this tutorial for gnuplot 4.2, August 2006
38 % All plots in this document were made with the version of gnuplot.
50 \pagestyle{myheadings}
51 \markright{Gnuplot \LaTeX\ Tutorial Version 4.2}
53 \currentspace % defined in header.tex
55 \section{Introduction and History}
57 Gnuplot was originally developed by Colin Kelley and Thomas Williams
58 in 1986 to plot functions and data files on a variety of terminals.
59 In 1988 and 1989 I created an alternate version, known as Gnu\TeX,
60 that supported a new ``terminal type'' called {\tt latex}, so gnuplot
61 would output \LaTeX\ code. The plot could then be included in a
62 \LaTeX\ document. I added a number of embellishments, supported only
63 by the {\tt latex} terminal, allowing the user to produce
64 publication-quality plots.
66 In late 1989 and early 1990 Gnu\TeX\ and a number of other gnuplot
67 variants were merged together into a new release of gnuplot, 2.0. This
68 includes, among many other improvements, a \LaTeX\ driver derived from
69 the one in Gnu\TeX. Former Gnu\TeX\ users are referred to
70 Section~\ref{oldusers} for information about adapting to gnuplot.
71 Anyone interested in using gnuplot with \LaTeX\ should read the next
72 section, a tutorial, and the primary gnuplot manual.
74 The reader should note that the \LaTeX\ picture environments output by
75 gnuplot can be quite large and complicated, and can easily exceed the
76 memory capacity of \TeX. If an enlarged version of \TeX\ is available,
77 it is wise to use it. Otherwise, keep your plots simple and add
78 \verb+\clearpage+ to your document where necessary.
80 There is also a new EEPIC driver ({\tt eepic}), intended for use with
81 the EEPIC macro package for \LaTeX. EEPIC allows for much more
82 efficient line-drawing, runs through \LaTeX\ faster, and uses less
83 memory. See Section~\ref{s:eepic} for more information.
85 There is a small package of auxiliary files (makefiles and scripts)
86 that I find useful for making \LaTeX\ plots with gnuplot. This is
87 available for \verb+ftp+ as \verb+pub/gnuplot-latex.shar+ from
88 \verb+cs.duke.edu+. I can mail copies (see the end of this paper for
91 \section{Using gnuplot for \LaTeX: a Tutorial}
93 Gnuplot is by nature an interactive program. Users making plots for
94 \LaTeX\ will generally not use gnuplot interactively. Whenever hard
95 copy is desired from gnuplot, the program need not be run on a
96 graphics terminal. In this case the output is directed to a file or
97 pipe, then sent to the appropriate output device. For example, output
98 from the terminal type {\tt unixplot} may be sent to a program
99 interpreting the Unix plotting standard. The terminal types {\tt
100 imagen} and {\tt postscript} may be used for output to printers
101 understanding those languages. (A shell script ({\tt lasergnu}) is
102 supplied with the distribution that will accept a gnuplot command or
103 input file and send the output to an Imagen or Postscript laser
104 printer. This script may have been adapted to your site.) The terminal
105 type {\tt fig} outputs FIG code that can be read by the Fig graphics
106 program and translated into forms usable in both \TeX\ and
109 We now ignore the interactive nature of gnuplot and provide the input
110 to gnuplot from a file, \ie,
112 gnuplot plotcommands.gp
114 In this example, all of the commands to gnuplot are contained in the
115 file {\tt plotcommands.gp}. Multiple filenames may be supplied to gnuplot
116 this way, read in the order they are given. The output (one or more
117 plots) may be piped to another program or redirected to a file.
118 Usually, however, we direct the output explicitly with an instruction
119 to gnuplot (the {\tt set output "outfile.tex"} command). Gnuplot continues to
120 print error messages to the terminal (stderr). After printing, the output file
121 has to be closed by {\tt set output}, \ie{} without the file name specification.
123 \paragraph{Example 1:} Here is a first example, producing a plot for
124 this document. The gnuplot input file is given below, and the output
125 appears as Figure~\ref{eg1}. The input file defines the output to be
126 in \LaTeX, gives a file name for the output, and plots $y=\sin(x)$ for
127 $x$ on $[-\pi,\pi]$. To produce the figure, I simply
128 \verb+\input{eg1}+ in a {\tt center} environment in a {\tt figure}
129 environment. In following examples, I will enclose the figure in a box
130 to make it look a little better.
136 plot [-3.14:3.14] sin(x)
144 \caption{A first example: $y=\sin(x)$.}
148 Note that gnuplot has drawn in the axes, labeled the tic marks for us,
149 scaled the $y$ axis automatically, and added a key in the
150 upper-right-hand corner (this may be moved with the {\tt set key}
151 command, and removed with {\tt unset key}%
152 \footnote{In gnuplot version 4.0, the syntax {\tt set noXXX} changed to
155 This is the default line style for the \LaTeX\ driver. Because of the
156 limited picture capabilities of \LaTeX, many dots are required to
157 approximate drawing a solid line. This may overload the memory of many
158 \TeX\ implementations. There are other line types available that draw
159 dotted lines and use much less memory. The EEPIC driver draws solid
160 lines with much less memory usage.
162 \paragraph{Example 2:} Now we will embellish the plot a little with
163 some labels. This input file produces Figure~\ref{eg2}.
171 set title "This is a plot of $y=\\sin(x)$"
172 set xlabel "This is the $x$ axis"
173 set ylabel "This is\\the\\$y$ axis"
174 plot [0:6.28] [0:1] sin(x)
178 \boxfigure{htbp}{\fullboxwidth}{
182 \caption{A more fancy example.}
186 We have specified the plot to be 5 inches wide and 4 inches tall with
187 the {\tt set size} command. This is the size of the area used by the
188 plot, {\em including} space for the labels. In the first example,
189 this size was the default 5 inches by 3 inches. By specifying the
190 scaling factors of 1 (or 5/5) and 1.3333 (or 4/3), we obtain the
193 We have requested that the format used by the $x$- and $y$-axis tic
194 mark labels be in \LaTeX\ math mode. This makes the labels look a
195 little better. The default is \verb+set format xy "%g"+. The \verb+%g+
196 represents the general-purpose floating point formatting specification
197 for the {\tt printf} function in C. Any valid floating-point
198 formatting specification, or \LaTeX\ command, is allowed in the
201 A title for the plot and labels for the axes were set up in the next
202 three commands. Note that they are processed by \LaTeX\ and so may
203 have math mode and other symbols in them. The ylabel may have multiple
204 lines, delineated with \verb+\\+. The ylabel can be moved around with
205 optional offset parameters (see {\tt set ylabel} in the gnuplot
206 manual). Typically, the ylabel needs to be moved to the left to avoid
207 interfering with the left-hand side of the plot. Once these labels
208 are set up, they will be used for all subsequent plot commands until
209 they are changed. These labels are also supported by the other
210 terminal types, but (of course) any \LaTeX\ code in the string will
211 not be interpreted. We have also defined the range of both $x$ (now
212 $[0,2\pi]$) and $y$ (here $[0,1]$).
214 So far we have plotted one curve, $y=\sin(x)$, on one plot. In
215 gnuplot, each {\tt plot} command generates a new plot. If the output
216 is to a screen, the screen is cleared. If to a printer, a new page is
217 produced. In the {\tt latex} case, a new picture is started. It is not
218 likely that \LaTeX\ users will want this to happen, so generally each
219 plot has its own input file and is kept in a separate output ({\tt
220 .tex}) file for inclusion at different places in the document.
222 \paragraph{Example 3:} To place more than one curve on a plot, use one
223 {\tt plot} statement and separate the description of each curve by a
224 comma. In our next example, we will plot both a function and a data
225 file on the same plot. This plot is shown in Figure~\ref{eg3}.
232 set title "This is another plot"
233 set xlabel "$x$ axis"
234 set ylabel "$y$ axis"
236 plot x with lines, "eg3.dat" with linespoints
240 \boxfigure{htbp}{\fullboxwidth}{
244 \caption{An example with two curves on the same plot.}
248 Here you will see that the $x$ range was not specified. The $x$ range
249 is determined automatically, unless specified by the user. In
250 this case, it is defined by the range of the data file
251 \verb+"eg3.dat"+. The function is plotted over the same range. If no
252 data files or $x$ range are supplied, the default range of $[-10:10]$
253 is used. We have also moved the key to a different position. The
254 function $y=x$ is plotted ``with lines'', which is the default plot
255 style for functions, and is shown here to illustrate the plot style
256 option. The data file {\tt eg3.dat} is plotted with style {\tt
257 linespoints}, a style like {\tt lines} that also plots a symbol at
260 There is a style called {\tt points} that only plots the symbols at
261 data points, and another called {\tt dots} that plots a tiny dot for
262 each data point. The {\tt points} and {\tt linespoints} styles
263 produce a different point symbol for each curve on the plot (for up to
264 twelve symbols, after which they are re-used; see
265 Figure~\ref{test} for a complete list). The {\tt lines} and {\tt
266 linespoints} styles use a different line style for each curve on the
267 plot (in this example the dots have different spacing). The
268 style {\tt impulses} draws a perpendicular from each point to the
269 $x$-axis. Finally, the {\tt errorbars} style can draw error bars at
270 each data point (see the gnuplot manual).
272 \paragraph{Example 4:} In the above plots of $\sin(x)$, it would make
273 more sense to label the axis in units of $\pi$. The position and
274 labels of the tic labels may be specified by the user, with the {\tt
275 set xtics} and {\tt set ytics} commands. This is demonstrated by
276 the following example, shown in Figure~\ref{eg4}.
283 set format x "$%.2f$"
284 set title "This is $\sin(x)$"
285 set xlabel "This is the $x$ axis"
286 set ylabel "$\sin(x)$"
289 plot [-pi:pi] [-1:1] sin(x)
293 \boxfigure{htbp}{\fullboxwidth}{
297 \caption{An example of the {\tt set xtics} command.}
301 Since {\tt pi} is a predefined variable in gnuplot, we can use it
302 anywhere we may use an expression. The {\tt set xtics} command here
303 specifies that the tics on the $x$ axis start at $-\pi$ and increment
304 by $\pi/4$. Since no end point is given, the tics continue to the
305 right edge. We have also turned off the key, and changed the format to
306 restrict the $x$-axis tic labels to 2 decimal places.
308 With a little more work, the plot can look even better. Another form
309 of this command allows us to specify the label and position of each
310 tic individually. Replacing the above {\tt set xtics} command with
311 the following gives us Figure~\ref{eg5}. We also make use of the line
312 continuation character, the backslash (\verb+\+), to spread out this
313 command for readability.
317 set xtics ("$-\pi$" -pi,\
318 "$-\frac{\pi}{2}$" -pi/2,\
320 "$\frac{\pi}{2}$" pi/2,\
325 \boxfigure{htbp}{\fullboxwidth}{
329 \caption{A fancy example of the {\tt set xtics} command.}
333 \paragraph{Going further:} You should now be able to make a variety of
334 plots for your \LaTeX\ document. We will present a final example
335 without explanation that showcases some of the capabilities of
336 gnuplot. You may find documentation for the various commands in the
337 gnuplot manual, though hopefully this example is somewhat
338 self-explanatory. This is shown in Figure~\ref{eg6}.
346 set format x "$%5.1f\mu$"
347 set title "This is a title"
348 set xlabel "This is the $x$ axis"
349 set ylabel "This is\\a longer\\version\\ of\\the $y$\\ axis"
350 set label "Data" at -5,-5 right
351 set arrow from -5,-5 to -3.3,-6.7
354 plot [-10:10] [-10:10] "eg3.dat" title "Data File" with linespoints 1 7,\
355 3*exp(-x*x)+1 title "$3e^{-x^{2}}+1$" with lines 4
359 \boxfigure{htbp}{\fullboxwidth}{
363 \caption{An example of many features.}
367 \paragraph{Line and point types:} For reference, we show all of the
368 line and point types available in Figure~\ref{test}.
370 \boxfigure{htbp}{\fullboxwidth}{
374 \caption{All of the line and point types in the \LaTeX\ driver.}
378 \subsection{Summary --- Use with \LaTeX}
379 In summary, to use the \LaTeX\ facilities of gnuplot, the first
380 command to gnuplot should be
384 and the output of gnuplot should be directed to a file, for example,
386 set output "plot.tex"
388 This may be anything you like but it should have a {\tt .tex} extension,
389 of course. Then the size of the plot should be given. For example, the
394 tells gnuplot to use a 5 inch wide by 6 inch high box for the plot.
395 The numbers given are {\em scale factors}, not the actual size. The
396 default is 5 inches by 3 inches. This is the size of the complete
397 plot, including all labels.
399 Then you do the (s)plot, and finally issue commands to close the file and
400 switch the terminal back to the default by
406 Finally, the file will contain all of the plots you have
407 specified (you probably only want one plot per file). This file can
408 then be used in a \LaTeX\ document, \eg,
419 This puts the plot into a figure.
421 You will also want to read about the following commands: {\tt set
422 title, set xlabel, set ylabel, set key, set label, set xtics, set
423 ytics}, and {\tt set clip}. These are all described in the regular
426 \section{Use with EEPIC}
428 EEPIC is a macro package extending the picture environment of \LaTeX.
429 If you have the EPIC or EEPIC macros, and your {\tt dvi} translator
430 supports the {\em tpic\/} \verb+\special+s, then you can save \LaTeX\
431 memory. With EEPIC pictures, the {\tt plot.tex} file will be smaller,
432 \LaTeX\ will run much faster (and need much less memory), and the {\tt
433 dvi} file will be smaller. The quality of the output is about the
434 same. If you change the source, you can generate some more interesting
437 To use EEPIC, set gnuplot's terminal type to {\tt eepic} instead of
438 {\tt latex}, and use gnuplot as before. The line styles will change.
439 Include the file {\tt plot.tex} in your document as before, along with
440 the document style options {\tt [epic,eepic]}.
442 \section{For Former Gnu\TeX\ Users}
445 Former Gnu\TeX\ users may be pleased with many of the new features
446 (many inspired by your suggestions!), but will also find many changes.
447 gnuplot will \emph{not} run all Gnu\TeX\ input files unchanged.
448 Several Gnu\TeX\ features were not included in gnuplot because they
449 were specific to the \LaTeX\ driver. I encourage you to use the newer
450 gnuplot. A translator is available that attempts to translate your
451 old Gnu\TeX\ 1.6 input files into gnuplot 3.0 files. You can ftp it
452 from \verb+cs.duke.edu+ as \verb+dist/sources/gnuplot/gnut2p.tar.Z+.
453 This file also contains directions and a list of changes from Gnu\TeX\
456 \section{What is new for \TeX{} and \LaTeX{} terminals in gnuplot 4.0}
458 In addition to the \texttt{latex} terminal, the following \LaTeX-friendly
459 terminals are available:
462 \item \texttt{emtex}: Like the \texttt{latex} terminal, but supports emtex
463 specials: any line slopes contrary to a very limited set of \LaTeX{} slopes.
465 \item \texttt{epslatex}: Combined \LaTeX{} and postscript parts for text and
466 lines, respectively, with the postscript part included by
467 \verb+\includegraphics{...}+ command.
469 \item \texttt{pstex} and \texttt{pslatex}: Combined \TeX{} / \LaTeX{} and
470 postscript parts for text and lines, respectively, included by
471 \verb+\special{psfile=...}+ command.
473 \item \texttt{mf} and \texttt{mp}: Produces metafont and metapost outputs.
477 See helps of these terminals for more details about their usage.
479 In addition, the \texttt{postscript eps enhanced} is the most useful for \TeX{}
480 and \LaTeX{} if you don't insist of using \TeX{} fonts for the graph labels, and
481 \texttt{pdf enhanced} and \texttt{png enhanced} for pdf\LaTeX{}.
483 \section{Sample of epslatex terminal driver}
486 The epslatex terminal driver allows you to mix the best features of \TeX\
487 and PostScript. Text elements are typeset by \TeX\, while the graphic
488 elements are created and positioned in parallel by gnuplot's PostScript
489 driver. The plot can use either color or grayscale.
490 The driver produces two different files, one for the eps part of the figure
491 and one for the \LaTeX{} part. The name of the \LaTeX{} file is taken from the
492 `set output` command. The name of the eps file is derived by replacing
493 the file extension (normally `.tex`) with `.eps` instead.
495 \boxfigure{htbp}{\fullboxwidth}{
499 \caption{Interlocking tori demo, drawn using the epslatex driver.}
500 \label{epslatex_test}
504 \section{Contact for help}
506 For general gnuplot questions, the gnuplot mailing list
507 \url{info-gnuplot@lists.sourceforge.net} is where you can send your e-mail, or
508 you can use gnuplot newsgroup \url{comp.graphics.apps.gnuplot}. Addional sources
509 of information are available on gnuplot homepage \url{www.gnuplot.info}.