Annotation of OpenXM_contrib/gnuplot/docs/latextut/tutorial.tex, Revision 1.1.1.1
1.1 maekawa 1: %
2: % Tutorial for GNUPLOT plotting program, for LaTeX users
3: % David Kotz
4: % Duke University Computer Science Department
5: %
6: % NOTE: If LaTeX runs out of memory processing plots,
7: % add ``with lines 4'' to each curve in eg*.plt and rerun make.
8: %
9:
10: % some header info
11: \input{header}
12:
13: \begin{document}
14:
15: \title{\LaTeX\ and the GNUPLOT Plotting
16: Program\thanks{This document describes GNUPLOT version 3.0. All plots
17: in this document were made with that version of GNUPLOT.} }
18: \author{David Kotz}
19: \date{July 3, 1991}
20:
21: \maketitle
22:
23: \pagestyle{myheadings}
24: \markright{GNUPLOT \LaTeX\ Tutorial Version 3.0}
25:
26: \currentspace % defined in header.tex
27:
28: \section{Introduction and History}
29:
30: GNUPLOT was originally developed by Colin Kelley and Thomas Williams
31: in 1986 to plot functions and data files on a variety of terminals.
32: In 1988 and 1989 I created an alternate version, known as Gnu\TeX,
33: that supported a new ``terminal type'' called {\tt latex}, so gnuplot
34: would output \LaTeX\ code. The plot could then be included in a
35: \LaTeX\ document. I added a number of embellishments, supported only
36: by the {\tt latex} terminal, allowing the user to produce
37: publication-quality plots.
38:
39: In late 1989 and early 1990 Gnu\TeX\ and a number of other GNUPLOT
40: variants were merged together into a new release of GNUPLOT, 2.0. This
41: includes, among many other improvements, a \LaTeX\ driver derived from
42: the one in Gnu\TeX. Former Gnu\TeX\ users are referred to
43: Section~\ref{oldusers} for information about adapting to GNUPLOT.
44: Anyone interested in using GNUPLOT with \LaTeX\ should read the next
45: section, a tutorial, and the primary GNUPLOT manual.
46:
47: The reader should note that the \LaTeX\ picture environments output by
48: GNUPLOT can be quite large and complicated, and can easily exceed the
49: memory capacity of \TeX. If an enlarged version of \TeX\ is available,
50: it is wise to use it. Otherwise, keep your plots simple and add
51: \verb+\clearpage+ to your document where necessary.
52:
53: There is also a new EEPIC driver ({\tt eepic}), intended for use with
54: the EEPIC macro package for \LaTeX. EEPIC allows for much more
55: efficient line-drawing, runs through \LaTeX\ faster, and uses less
56: memory. See Section~\ref{s:eepic} for more information.
57:
58: There is a small package of auxiliary files (makefiles and scripts)
59: that I find useful for making \LaTeX\ plots with GNUPLOT. This is
60: available for \verb+ftp+ as \verb+pub/gnuplot-latex.shar+ from
61: \verb+cs.duke.edu+. I can mail copies (see the end of this paper for
62: information).
63:
64: \section{Using GNUPLOT for \LaTeX: a Tutorial}
65:
66: GNUPLOT is by nature an interactive program. Users making plots for
67: \LaTeX\ will generally not use GNUPLOT interactively. Whenever hard
68: copy is desired from GNUPLOT, the program need not be run on a
69: graphics terminal. In this case the output is directed to a file or
70: pipe, then sent to the appropriate output device. For example, output
71: from the terminal type {\tt unixplot} may be sent to a program
72: interpreting the Unix plotting standard. The terminal types {\tt
73: imagen} and {\tt postscript} may be used for output to printers
74: understanding those languages. (A shell script ({\tt lasergnu}) is
75: supplied with the distribution that will accept a GNUPLOT command or
76: input file and send the output to an Imagen or Postscript laser
77: printer. This script may have been adapted to your site.) The terminal
78: type {\tt fig} outputs FIG code that can be read by the Fig graphics
79: program and translated into forms usable in both \TeX\ and
80: \LaTeX\ documents.
81:
82: We now ignore the interactive nature of GNUPLOT and provide the input
83: to GNUPLOT from a file, \ie,
84: \begin{verbatim}
85: gnuplot gnu.input
86: \end{verbatim}
87: In this example, all of the commands to GNUPLOT are contained in the
88: file {\tt gnu.input}. Multiple filenames may be supplied to GNUPLOT
89: this way, read in the order they are given. The output (one or more
90: plots) may be piped to another program or redirected to a file.
91: Usually, however, we direct the output explicitly with an instruction
92: to GNUPLOT (the {\tt set output} command). GNUPLOT continues to print
93: error messages to the terminal (stderr).
94:
95: \paragraph{Example 1:} Here is a first example, producing a plot for
96: this document. The GNUPLOT input file is given below, and the output
97: appears as Figure~\ref{eg1}. The input file defines the output to be
98: in \LaTeX, gives a file name for the output, and plots $y=sin(x)$ for
99: $x$ on $[-\pi,\pi]$. To produce the figure, I simply
100: \verb+\input{eg1}+ in a {\tt center} environment in a {\tt figure}
101: environment. In following examples, I will enclose the figure in a box
102: to make it look a little better.
103:
104: \singlespace
105: \begin{verbatim}
106: set terminal latex
107: set output "eg1.tex"
108: plot [-3.14:3.14] sin(x)
109: \end{verbatim}
110: \currentspace
111:
112: \begin{figure}[htbp]
113: \begin{center}
114: \input{eg1}
115: \end{center}
116: \caption{A first example: $y=sin(x)$}
117: \label{eg1}
118: \end{figure}
119:
120: Note that GNUPLOT has drawn in the axes, labeled the tic marks for us,
121: scaled the $y$ axis automatically, and added a key in the
122: upper-right-hand corner (this may be moved with the {\tt set key}
123: command, and removed with {\tt set nokey}).
124:
125: This is the default line style for the \LaTeX\ driver. Because of the
126: limited picture capabilities of \LaTeX, many dots are required to
127: approximate drawing a solid line. This may overload the memory of many
128: \TeX\ implementations. There are other line types available that draw
129: dotted lines and use much less memory. The EEPIC driver draws solid
130: lines with much less memory usage.
131:
132: \paragraph{Example 2:} Now we will embellish the plot a little with
133: some labels. This input file produces Figure~\ref{eg2}.
134:
135: \singlespace
136: \begin{verbatim}
137: set terminal latex
138: set output "eg2.tex"
139: set size 5/5., 4/3.
140: set format xy "$%g$"
141: set title "This is a plot of $y=sin(x)$"
142: set xlabel "This is the $x$ axis"
143: set ylabel "This is\\the\\$y$ axis"
144: plot [0:6.28] [0:1] sin(x)
145: \end{verbatim}
146: \currentspace
147:
148: \boxfigure{htbp}{\fullboxwidth}{
149: \begin{center}
150: \input{eg2}
151: \end{center}
152: \caption{A more fancy example.}
153: \label{eg2}
154: }
155:
156: We have specified the plot to be 5 inches wide and 4 inches tall with
157: the {\tt set size} command. This is the size of the area used by the
158: plot, {\em including} space for the labels. In the first example,
159: this size was the default 5 inches by 3 inches. By specifying the
160: scaling factors of 1 (or 5/5) and 1.3333 (or 4/3), we obtain the
161: desired plot size.
162:
163: We have requested that the format used by the $x$- and $y$-axis tic
164: mark labels be in \LaTeX\ math mode. This makes the labels look a
165: little better. The default is \verb+set format xy "%g"+. The \verb+%g+
166: represents the general-purpose floating point formatting specification
167: for the {\tt printf} function in C. Any valid floating-point
168: formatting specification, or \LaTeX\ command, is allowed in the
169: format.
170:
171: A title for the plot and labels for the axes were set up in the next
172: three commands. Note that they are processed by \LaTeX\ and so may
173: have math mode and other symbols in them. The ylabel may have multiple
174: lines, delineated with \verb+\\+. The ylabel can be moved around with
175: optional offset parameters (see {\tt set ylabel} in the GNUPLOT
176: manual). Typically, the ylabel needs to be moved to the left to avoid
177: interfering with the left-hand side of the plot. Once these labels
178: are set up, they will be used for all subsequent plot commands until
179: they are changed. These labels are also supported by the other
180: terminal types, but (of course) any \LaTeX\ code in the string will
181: not be interpreted. We have also defined the range of both $x$ (now
182: $[0,2\pi]$) and $y$ (here $[0,1]$).
183:
184: So far we have plotted one curve, $y=\sin(x)$, on one plot. In
185: GNUPLOT, each {\tt plot} command generates a new plot. If the output
186: is to a screen, the screen is cleared. If to a printer, a new page is
187: produced. In the {\tt latex} case, a new picture is started. It is not
188: likely that \LaTeX\ users will want this to happen, so generally each
189: plot has its own input file and is kept in a separate output ({\tt
190: .tex}) file for inclusion at different places in the document.
191:
192: \paragraph{Example 3:} To place more than one curve on a plot, use one
193: {\tt plot} statement and separate the description of each curve by a
194: comma. In our next example, we will plot both a function and a data
195: file on the same plot. This plot is shown in Figure~\ref{eg3}.
196:
197: \singlespace
198: \begin{verbatim}
199: set terminal latex
200: set output "eg3.tex"
201: set format xy "$%g$"
202: set title "This is another plot"
203: set xlabel "$x$ axis"
204: set ylabel "$y$ axis"
205: set key 15,-10
206: plot x with lines, "eg3.dat" with linespoints
207: \end{verbatim}
208: \currentspace
209:
210: \boxfigure{htbp}{\fullboxwidth}{
211: \begin{center}
212: \input{eg3}
213: \end{center}
214: \caption{An example with two curves on the same plot.}
215: \label{eg3}
216: }
217:
218: Here you will see that the $x$ range was not specified. The $x$ range
219: is determined automatically, unless specified by the user. In
220: this case, it is defined by the range of the data file
221: \verb+"eg3.dat"+. The function is plotted over the same range. If no
222: data files or $x$ range are supplied, the default range of $[-10:10]$
223: is used. We have also moved the key to a different position. The
224: function $y=x$ is plotted ``with lines'', which is the default plot
225: style for functions, and is shown here to illustrate the plot style
226: option. The data file {\tt eg3.dat} is plotted with style {\tt
227: linespoints}, a style like {\tt lines} that also plots a symbol at
228: each data point.
229:
230: There is a style called {\tt points} that only plots the symbols at
231: data points, and another called {\tt dots} that plots a tiny dot for
232: each data point. The {\tt points} and {\tt linespoints} styles
233: produce a different point symbol for each curve on the plot (for up to
234: twelve symbols, after which they are re-used; see
235: Figure~\ref{linepoint} for a complete list). The {\tt lines} and {\tt
236: linespoints} styles use a different line style for each curve on the
237: plot (in this example the dots have different spacing). The
238: style {\tt impulses} draws a perpendicular from each point to the
239: $x$-axis. Finally, the {\tt errorbars} style can draw error bars at
240: each data point (see the GNUPLOT manual).
241:
242: \paragraph{Example 4:} In the above plots of $\sin(x)$, it would make
243: more sense to label the axis in units of $\pi$. The position and
244: labels of the tic labels may be specified by the user, with the {\tt
245: set xtics} and {\tt set ytics} commands. This is demonstrated by
246: the following example, shown in Figure~\ref{eg4}.
247:
248: \singlespace
249: \begin{verbatim}
250: set terminal latex
251: set output "eg4.tex"
252: set format y "$%g$"
253: set format x "$%.2f$"
254: set title "This is $\sin(x)$"
255: set xlabel "This is the $x$ axis"
256: set ylabel "$\sin(x)$"
257: set nokey
258: set xtics -pi, pi/4
259: plot [-pi:pi] [-1:1] sin(x)
260: \end{verbatim}
261: \currentspace
262:
263: \boxfigure{htbp}{\fullboxwidth}{
264: \begin{center}
265: \input{eg4}
266: \end{center}
267: \caption{An example of the {\tt set xtics} command.}
268: \label{eg4}
269: }
270:
271: Since {\tt pi} is a predefined variable in GNUPLOT, we can use it
272: anywhere we may use an expression. The {\tt set xtics} command here
273: specifies that the tics on the $x$ axis start at $-\pi$ and increment
274: by $\pi/4$. Since no end point is given, the tics continue to the
275: right edge. We have also turned off the key, and changed the format to
276: restrict the $x$-axis tic labels to 2 decimal places.
277:
278: With a little more work, the plot can look even better. Another form
279: of this command allows us to specify the label and position of each
280: tic individually. Replacing the above {\tt set xtics} command with
281: the following gives us Figure~\ref{eg5}. We also make use of the line
282: continuation character, the backslash (\verb+\+), to spread out this
283: command for readability.
284:
285: \singlespace
286: \begin{verbatim}
287: set xtics ("$-\pi$" -pi,\
288: "$-\frac{\pi}{2}$" -pi/2,\
289: "0" 0,\
290: "$\frac{\pi}{2}$" pi/2,\
291: "$\pi$" pi)
292: \end{verbatim}
293: \currentspace
294:
295: \boxfigure{htbp}{\fullboxwidth}{
296: \begin{center}
297: \input{eg5}
298: \end{center}
299: \caption{A fancy example of the {\tt set xtics} command.}
300: \label{eg5}
301: }
302:
303: \paragraph{Going further:} You should now be able to make a variety of
304: plots for your \LaTeX\ document. We will present a final example
305: without explanation that showcases some of the capabilities of
306: GNUPLOT. You may find documentation for the various commands in the
307: GNUPLOT manual, though hopefully this example is somewhat
308: self-explanatory. This is shown in Figure~\ref{eg6}.
309:
310: \singlespace
311: \begin{verbatim}
312: set terminal latex
313: set output "eg6.tex"
314: set size 3.5/5, 3/3.
315: set format y "$%g$"
316: set format x "$%5.1f\mu$"
317: set title "This is a title"
318: set xlabel "This is the $x$ axis"
319: set ylabel "This is\\a longer\\version\\ of\\the $y$\\ axis"
320: set label "Data" at -5,-5 right
321: set arrow from -5,-5 to -3.3,-6.7
322: set key -4,8
323: set xtic -10,5,10
324: plot [-10:10] [-10:10] "eg3.dat" title "Data File" with linespoints 1 7,\
325: 3*exp(-x*x)+1 title "$3e^{-x^{2}}+1$" with lines 4
326: \end{verbatim}
327: \currentspace
328:
329: \boxfigure{htbp}{\fullboxwidth}{
330: \begin{center}
331: \input{eg6}
332: \end{center}
333: \caption{An example of many features.}
334: \label{eg6}
335: }
336:
337: \paragraph{Line and point types:} For reference, we show all of the
338: line and point types available in Figure~\ref{linepoint}.
339:
340: \boxfigure{htbp}{\fullboxwidth}{
341: \begin{center}
342: \input{linepoin}
343: \end{center}
344: \caption{All of the line and point types in the \LaTeX\ driver.}
345: \label{linepoint}
346: }
347:
348: \subsection{Summary --- Use with \LaTeX}
349: In summary, to use the \LaTeX\ facilities of GNUPLOT, the first
350: command to GNUPLOT should be
351: \begin{syntax}
352: set terminal latex
353: \end{syntax}
354: and the output of GNUPLOT should be directed to a file, for example,
355: \begin{verbatim}
356: set output "plot.tex"
357: \end{verbatim}
358: This may be anything you like but it should have a {\tt .tex} extension,
359: of course. Then the size of the plot should be given. For example, the
360: command
361: \begin{verbatim}
362: set size 1,2
363: \end{verbatim}
364: tells GNUPLOT to use a 5 inch wide by 6 inch high box for the plot.
365: The numbers given are {\em scale factors}, not the actual size. The
366: default is 5 inches by 3 inches. This is the size of the complete
367: plot, including all labels.
368:
369: When finished, the file will contain all of the plots you have
370: specified (you probably only want one plot per file). This file can
371: then be used in a \LaTeX\ document, \eg,
372:
373: \singlespace
374: \begin{verbatim}
375: \begin {figure}
376: \begin{center}
377: \input{plot}
378: \end{center}
379: \end {figure}
380: \end{verbatim}
381: \currentspace
382: This puts the plot into a figure.
383:
384: You will also want to read about the following commands: {\tt set
385: title, set xlabel, set ylabel, set key, set label, set xtics, set
386: ytics}, and {\tt set clip}. These are all described in the regular
387: GNUPLOT manual.
388:
389: \section{Use with EEPIC}
390: \label{s:eepic}
391: EEPIC is a macro package extending the picture environment of \LaTeX.
392: If you have the EPIC or EEPIC macros, and your {\tt dvi} translator
393: supports the {\em tpic\/} \verb+\special+s, then you can save \LaTeX\
394: memory. With EEPIC pictures, the {\tt plot.tex} file will be smaller,
395: \LaTeX\ will run much faster (and need much less memory), and the {\tt
396: dvi} file will be smaller. The quality of the output is about the
397: same. If you change the source, you can generate some more interesting
398: line styles.
399:
400: To use EEPIC, set GNUPLOT's terminal type to {\tt eepic} instead of
401: {\tt latex}, and use GNUPLOT as before. The line styles will change.
402: Include the file {\tt plot.tex} in your document as before, along with
403: the document style options {\tt [epic,eepic]}.
404:
405: \section{For Former Gnu\TeX\ Users}
406: \label{oldusers}
407:
408: Former Gnu\TeX\ users may be pleased with many of the new features
409: (many inspired by your suggestions!), but will also find many changes.
410: GNUPLOT will {\em not\/} run all Gnu\TeX\ input files unchanged.
411: Several Gnu\TeX\ features were not included in GNUPLOT because they
412: were specific to the \LaTeX\ driver. I encourage you to use the newer
413: GNUPLOT. A translator is available that attempts to translate your
414: old Gnu\TeX\ 1.6 input files into GNUPLOT 3.0 files. You can ftp it
415: from \verb+cs.duke.edu+ as \verb+dist/sources/gnuplot/gnut2p.tar.Z+.
416: This file also contains directions and a list of changes from Gnu\TeX\
417: to GNUPLOT.
418:
419: \section{Contact}
420: For general GNUPLOT questions, send mail to the GNUPLOT mailing list
421: (\verb+info-gnuplot@dartmouth.edu+) or post to the GNUPLOT newsgroup
422: (\verb+comp.graphics.apps.gnuplot+).
423:
424: \end{document}
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to tutorial.tex CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gnuplot / docs / latextut