The GNU graphics utilities are a set of programs for plotting scientific
data. The program graph reads data files and writes a stream of
plotting commands in a device independent format referred to below as a
GNU plot file. The remaining programs provide support for displaying GNU
plot files on Tektronix 4010, PostScript (TM)*, and X window system
compatible output devices.
graph reads both ascii and binary data files and writes a plot
file with or without axes and labels. You can specify labels and ranges
for the axes, and you can set the sizes and position of the plot on the
page. Each invocation of graph produces a plot with single set of axes
and data. You can place an arbitrary number of plots on the page by
concatenating the plot output of several invocations.
plot2ps is a utility for converting plot files into PostScript.
The plot2ps utility reads plotting commands from named files or
the standard input and writes PostScript to the standard output. You
can then print the PostScript output on a printer, or edit it using the
idraw graphics editor. You can also easily include
the output in LaTeX documents using dvips and the LaTeX command
psfig.
Why is this useful? The plot file format is a common standard on un*x
systems. To produces figures for publication, you might need to take
data sets, and produce labeled figures from them. This can be done using
graph, plot2ps and the idraw editor. You can also
include these figures in LaTeX documents using the dvips utility.
All of these utilities, as well as the plot file format and plot
library, are discussed in the following sections.
This documentation is under revision. Any comments, suggestions, or additions would greatly benefit GNU users. Please mail them to either `bug-gnu-utils@prep.ai.mit.edu' or `Rich@Rice.edu'.
* PostScript is a trademark of Adobe Systems Incorporated.
graph Examples
Each invocation of graph plots data read from stdin or named
files together in a single plot with or without axes and labels. The
following sections show common usage of graph.
By default, graph reads ascii data from the standard input or
files specified on the command line. graph reads pairs of
values, x and y coordinates:
0.0 0.0 1.0 0.2 2.0 0.0 3.0 0.4 4.0 0.2 5.0 0.6
To plot this data, you might use
graph < ascii_data_file |plot
where ascii_data_file could contain data similar to the above example.
You can replace the command plot with plot2tek if you have
a Tektronix 4010 compatible graphics terminal, plot2ps if you
have a postscript compatible printer or previewer, or xplot if
you have an X window system display.
To reduce the change the size of the plot and position it in the middle of the display, you could use
graph -h .4 -w .4 -r .2 -u .2 < ascii_data_file |plot
where h and w are the height and width of the plot and
r and u indicate how far up and to the right the plot is
positioned.
You can put symbols at each data point using
graph -S 2 .01 < ascii_data_file |plot
where 2 indicates which symbol to plot, and .01 indicates it's size.
You can choose the type of line draw on each curve:
graph -m 2 < ascii_data_file |plot
where 2 indicates what kind of line connects the data points.
graph
As mentioned above, by default graph reads ascii pairs of values,
x and y coordinates, from the standard input or files specified on the
command line. Optional labels may be placed after each coordinate in
the data file. The label ends at the end of the line:
3.0 0.4 this is a label for point (3.0, 0.4).
The label must be enclosed in double quotes if it would otherwise be appear to be a coordinate:
3.0 0.4 "5.0 looks like a value."
You can use the `-b' to break lines after each label in the input. Use a pair of empty double quotes if you need to break a line, but do not need a label.
0.0 0.0 2.0 0.0 1.0 0.2 "" 0.0 0.1 2.0 0.2 4.0 0.3
You can also break cuves using `-M' option to break lines whenever the abscissal values between successive pairs of points decrease. When using `-M', each continuous curve has monotonically increasing abscissal values.
0.0 0.0 first data set 2.0 0.0 4.0 0.2 0.0 0.1 second data set 2.0 0.2 4.0 0.3
graph will automatically generate abscissal values for you if you
specify the `-a' option. Only ordinate values are given in the
data, and the data is then assumed to be equally sampled along the
abscissa. The values following `-a' on the command line specify
the sampling interval and the abscissal value of the first data
point.
0.0 0.1 0.2 label for point (2.0, 0.2) 0.3 0.2 0.3
There are cases where you will want to superimpose several data sets or
several plots on top of each other. If for example, the data sets are
in separate files, you can specify each by it's name on the command
line. Since graph reads the standard input only if no files are
named on the command line, you must add the name -- if you want
graph to read the standard input as well.
graph data-file-one data-file-two data-file-three |plot
For comparison sake, you might wish to distinguish the data in one set from another either by using different symbols at each point or by distinguishing the type of line draw. You can do this by preceding each file name with options affecting the synbol or line style used to plot that data.
graph -S 1 data-file-one -S 3 data-file-two -S 4 data-file-three |plot or graph -m 1 data-file-one -m 3 data-file-two -S 4 data-file-three |plot
If you need to superimpose several data sets, but must invoke graph separately for each, you will have to specify the limits of the axes.
graph -x 0 100 -y -3 3 -S 3 -m -1 < ascii_data_file_1 >> plot_file
where -x 0 100 specifies the limits on the x axis, -y -3 3
specifies the limits on the y axis, -S 2 specifies a box to be
drawn at each point, and -m -1 specifies that no line is to be
draw connecting the points. You can overlay a second data set on the first
by using:
graph -s -g 0 -x 0 100 -y -3 3 -m 0 < ascii_data_file_1 >> plot_file
where -s avoids erasing the page, -g 0 avoids drawing the
axis, tick marks and labels which were drawn previously, and -m 0
specifies that solid lines are draw connecting the points.
The command
graph -h .4 -w .4 -r .1 -u .1 < ascii_data_file_1 > plot_file
will put a single box containing the plot in the lower left hand quarter of the page. You can add another plot to the upper left hand corner of the page using the command
graph -s -h .4 -w .4 -r .1 -u .6 < ascii_data_file_2 >> plot_file
Be sure you use the -s option so the first plot isn't erased.
Likewise you can add plots to the right hand side of the page using
graph -s -h .4 -w .4 -r .6 -u .1 < ascii_data_file_3 >> plot_file graph -s -h .4 -w .4 -r .6 -u .6 < ascii_data_file_4 >> plot_file
The tick marks can be moved inside the box and labels moved to the opposite sides using
graph -T -.005 < ascii_data_file >> plot_file
graph will read binary data in integer, short integer, float, and
double float format when you use the -d option followed by
f, or d, respectively. There are two advantage to using
binary data: 1) graph runs significantly faster because the
computational overhead for converting data from ascii to binary is
eliminated, and 2) the input files can be significantly smaller than the
ascii format would be. Double float is the fastest format to read,
while short integer is the most space conservative. If you have very
large data sets, using a binary format can reduce storage and runtime
costs.
For example, you can create double float data as output from C language programs:
#include <stdio.h>
void write_point (x, y)
double x, y;
{
fwrite(&x, sizeof (double), 1, stdout);
fwrite(&y, sizeof (double), 1, stdout);
}
You can then plot data written this way using:
graph -d d <datafile >plotfile
The following table describes each of the command line arguments to graph. Each option which takes an argument is followed by the type and default values of the argument in parentheses.
-b.-m -1.plot2psTo produce a plot of data arranged in ordered pairs of x and y coordinates in an ASCII file, you can use:
graph <asciiDataFile | plot2ps | lpr -Plw
To create a simple PostScript figure you can use:
echo 0 0 1 1 2 0 | spline | graph | plot2ps > test.ps
To edit the plot:
idraw test.ps
To use the previewer to look at the plot:
gs test.ps
plot2ps is a relatively simple utility in that there are few
command line options to choose from. The plot file format does
not contain methods for specifying font or font size, so you must
specify these things with options. There are no other options for
controlling the picture.
The plot file format is machine dependent on the byte order of
unformatted, signed, two byte integer coordinates contained in plot
commands. The `-high-byte-first' or `-low-byte-first'
option specifies this order explicitly. plot2ps attempts to
determine the byte order from commands early in the plot file, but the
method is heuristic and is not foolproof. Several standard plot sizes
specified by the open command are used to recognize byte order
by plot2ps. If these sizes are recognized in byte reversed
order, plot2ps adjusts accordingly. These sizes include
504x504, 2048x2048 (Versatec plotters), 2100x2100,
3120x3120 (Tektronix 4010 terminals) and 4096x4096 (GSI 300
terminals).
The remaining command line options may be used specify an alternate PostScript prologue and to print the licensing information.
Input plot files names may be specified anywhere on the command line. If no file names are specified, or the name `-' is specified, the standard input is read for plotting instructions. Only the font or font size options which precede a file name will affect the text for that file.
plot2ps, a list of the font names (the standard builtin
PostScript fonts), and version, copyright and warranty information.
Specifying this options causes plot2ps to ignore files on the standard
input. You can specify a file on the standard input explicitly with
the option `-' if you want it to read the standard input as
well.idraw editor. Other font sizes will print correctly on a
PostScript device such as the laserwriter, but may not appear at the
correct size in the idraw editor.idraw prologue. The prologue declares procedures used to draw
each graphic object. The default prologue was generously provided by
John Interante and is a part of the InterViews distribution, version
2.5.plot2ps and information on the lack of any
warranty.
These conditions do not cover the output of plot2ps. The only
conditions imposed on the output are those which come from the
prologue that you are using.
xplot is a plot file previewer for the X window system. It reads
GNU plot commands from its standard input and draws the resulting
graphics in an X window.
After xplot reaches the end-of-file on the input, it puts itself in the background (forks). Control returns to the calling program, while xplot continues, remaining on screen.
To exit, click the left mouse button in the xplot window. Note that xplot ignores SIGHUP signals, so you must use another signal to kill xplot if necessary.
xplot accepts all of the standard X toolkit command line options,
and the initial geometry specification determines the resolution, with a
default geometry of 500x500 pixels.
The following standard X Toolkit command line arguments may be used with
xplot:
xplot uses the athena Command widget in the X Toolkit. So, it
understands all of the core resource names and classes as well
as:
The resources:
Xplot.font: 6x9 Xplot.geometry: 300x300
will set the font used in the plot window to `6x9' and the size of the window to 300 by 300 pixels.
To create a simple plot file one can use:
echo 0 0 1 1 2 0 | spline | graph | plot2fig > test.fig
To edit the plot:
fig test.fig
To convert the fig file into dvi code, create a latex file containing a document which includes the figure:
\\documentstyle\[\]{article}
\\begin{document}
\\input{test}
\\end{document}
Then, run transfig on the figure and latex on the document:
% transfig -L latex test.fig % make test.tex % latex t.tex
To edit a plot of data arranged in ordered pairs of x and y coordinates in an ascii file, one can use:
% graph <asciiDataFile | plot2fig >file.fig % fig file.fig
plot2fig reads plotting instructions from the specified input
files and/or the standard input and produces Fig compatible code
on it's standard output. This output file can be edited with the fig
(Facility for Interactive Generation of figures) graphics editor. The
output can subsequently be converted to pictex, PostScript, latex, epic,
eepic, and tpic languages using the transfig translator.
Any unrecognized options on the command line are assumed to be input files. The standard input is read by default only if no other files specified on the command line are successfully opened. A single dash (-) on the command line indicates the standard input is to be read. Each option is set and each file read in the order they are specified on the command line.
For compatibility with pic2fig, plot2fig ignores leading white space in labels. Labels containing all white space are ignored.
idraw prologue. The prologue declares procedures used to draw
each graphic object. The default prologue was generously provided by
John Interante and is a part of the InterViews distribution, version
2.5.plot and information on the lack of any
warranty.This is an example of LaTeX code which places the figure generated in the previous example in a page of text.
\documentstyle[]{article}
\input{psfig}
\begin{document}
\title{Title of the article.}
\author{The Author's name}
\maketitle
This is an example of how to include PostScript figures in LaTeX documents.
\begin{figure}[h]
\centerline{\psfig{figure=test.ps,height=3in}}
\caption{Here is a description of the figure which will appear below it.}
\end{figure}
Note that the above figure was included using dvips.
\end{document}
If the above LaTeX code is contained in a file called `mytext.tex' you can use the commands
latex mytext dvips mytext.dvi >mytext.ps lpr -Plw mytext.ps
to format and print the example text.
psfig for Including Figures
psfig is a LaTeX command used to insert a PostScript figure
into a document.
psfig can be used to insert plot2ps generated PostScript
into a LaTeX document. The placement of the psfig command
tells LaTeX where in the document to place the PostScript, and
arguments to the command give the name of the file containing the
PostScript, and the desired size of the figure. Arguments are
separated by commas or blanks, and are of the form
`keyword=value'. The following is a list of valid
arguments for the psfig command:
file=name
height=size
width=size
bbllx=coordinate
plot2ps output conforms to the version 2.0
conventions so that you should not need to use any of the bounding box
options.bblly=coordinate
bburx=coordinate
bbury=coordinate
rheight=size
rwidth=size
clip=
clip= is a switch and takes no value, but the
`=' must be present. This option is useful for including
PostScript figures which use the size of the clipping path to size
themselves.
atend.pl is a perl script which moves the bounding box comment
from the trailer to the header. Although either is legal, most document
preparation software, such as psfig, will only accept bounding
box comments in the header. If you use psfig and the
-bbox option together, run atend.pl on the output of
plot2ps before importing the graphics using psfig.
atend.pl can be used as a filter:
echo 0 0 1 1 2 0 | spline | graph >spline.pl plot2ps -bbox |atend.pl - >spline.ps
Or, atend.pl can be used to fix the output file in place:
echo 0 0 1 1 2 0 | spline | graph |plot2ps -bbox >spline.ps atend.pl spline.ps
dvips
The dvips utility mentioned previously is used convert dvi files
generated by LaTeX into post-script. It also has support for inclusion
of PostScript figures into LaTeX documents. It is available via
anonymous ftp from `labrea.stanford.edu' (36.8.0.47). Look for
`pub/dvips.tar.Z'.
idraw
The idraw utility mentioned previously is an interactive
graphics editor which is distributed with InterViews. InterViews is
available via anonymous ftp from `interviews.stanford.edu'
(36.22.0.175) in the file `InterViews/2.5.tar.Z'.
ghostscriptGhostscript is a previewer which is intended to be compatible with the PostScript language. It supports several output devices including the X window system and ega displays. Version 2.0 is suitable for previewing LaTeX documents with embedded encapsulated PostScript figures, the type of PostScript figures generated by plot2ps and idraw. It is available via anonymous ftp from `prep.ai.mit.edu' (18.71.0.38) - Look for `pub/gnu/ghostscript.tar.Z'.
libps, a Library of Plot Functions
Libps is a library of plot functions for drawing graphic object
using PostScript. Before drawing any objects or using any of the
other functions, a program should call openpl. Before exiting
and after all other libps calls a program should call
closepl.
alabel
int alabel (char x_justify, char y_justify, char *label);
alabel takes three arguments x_justify, y_justify,
and label and places the label according to the x and y axis
adjustments specified in x_justify and y_justify
respectively. x_justify is a character containing either
`l', `c', or `r' for left, center or right justified
with respect to the current x coordinate. y_justify is a
character containing either `b', `c', or `t' for
placing the bottom center or top of the label even with the current y
coordinate. *label is a string containing the label. The
current point is moved to follow the end of the text.
See section fontname on how to change the default font.
See section fontsize on how to change the font size.
arc
int arc (int x, int y, int x0, int y0, int x1, int y1)
arc takes six integer arguments specifying the coordinates of
the center (x, y), beginning (x0, y0), and
ending (x1, y1) of a circular arc. The current point
becomes (x, y).
circle
int circle (int x, int y, int r)
circle takes three integer arguments specifying the center
(x, y) of the circle and its radius (r). The
current point becomes (x, y).
closepl
int closepl ()
closepl takes no arguments. It merely outputs the PostScript
trailer containing a showpage command.
color
int color (int red, int green, int blue);
color sets the foreground color of all the following objects.
The arguments red, green and blue indicate the
intensity of red, green and blue components of the foreground color
respectively. Each is a unsigned integer specifying an intensity in
the range from 0 to 0xFFFF. A value of (0, 0, 0) represents black and
a value of (0xFFFF, 0xFFFF, 0xFFFF) indicates white.
cont
int cont (int x, int y)
cont takes two integer arguments specifying the coordinate
(x, y) for the continuation of a line. This draws a line
segment from the current point to the point (x, y). The
current point then becomes (x, y).
erase
int erase ()
erase normally erases all the graphics from the display before
a plot is viewed. Since we start off with a blank page in PostScript
and idraw this function does nothing.
fill
int fill (int level);
fill sets the intensity of the filler for closed paths. The
argument level indicates the grey level of the fill pattern.
It's value ranges from 1 to 0xFFFF. A value of 1 represents black and
a value of 0xFFFF indicates white. A value of 0 represents no fill,
or transparent.
fontname
int fontname (char *font_name);
fontname takes a single string argument, font_name,
specifying the name of the font to be used for following text. The
laser writer builtin fonts are supported:
courier-bold
courier-boldoblique
courier-oblique
courier
helvetica-bold
helvetica-boldoblique
helvetica-oblique
helvetica
symbol
times-bold
times-bolditalic
times-italic
times-roman
fontsize
int fontsize (int size);
fontsize takes a single integer argument size in
printer's points (1/72 inch) and sets the font size
accordingly.
label
int label (char *s)
label takes a single string argument s and draws the text
contained in s at the most recently used coordinate in the
current font. By default the text is left justified and centered
vertically with respect to the current coordinate.
line
int line (int x1, int y1, int x2, int y2)
line takes four integer arguments specifying the beginning
(x1, y1) and ending (x2, y2) points of a line.
The current point becomes (x2, y2).
See section linemod for how to specify the style or pattern of line.
linemod
int linemod (char *s)
linemod takes a single string argument s containing the
name of the line style desired. The names supported are longdashed,
disconnected, dotdashed, dotted, solid and shortdashed. These
correspond to the following sixteen bit patterns:
solid -------------------------------- longdashed ------- ------- disconnected - - dotdashed ----------- - ----------- - dotted - - - - - - - - - - - - - - - - shortdashed -- --
move
int move (int x, int y)
move takes two integer arguments specifying the coordinate
(x, y) for the beginning of a new line. This is
equivalent to lifting the pen on a plotter and moving it to a new
position without drawing any line. The current point becomes
(x, y).
openpl
int openpl ()
openpl normally opens the device. For PostScript we just print
out the PostScript prologue. The following global variables defined
in openpl specify what prologue is written to the
output.
user_has_prologue is a flag. If it is non-zero then the open routine should output the user specified prologue contained in the file specified in the string users_prologue.
users_prologue is a string containing the file name for any user specified PostScript prologue. This file is a substitute for the default prologue.
point
int point (int x, int y)
point takes a pair of integer arguments specifying the
coordinate (x, y) for a single point. The current point
then becomes (x, y).
rotate
int rotate (int angle);
rotate takes three integer arguments. The last argument,
angle, specifies the angle in degrees counter-clockwise from the
x (horizontal) axis following text.
space
int space (int x0, int y0, int x1, int y1)
space takes two pair of integers arguments specifying the
lower, left-hand and upper, right-hand limits of the range of plot
coordinates. The scaling of input to output coordinate conversion is
adjusted to fit these ranges into the page. Note however that if the
ranges of x and y coordinates are different the smallest scaling of
the two is used to avoid affecting the aspect ratio of the plot. This
means that although the plot is scaled to fit on the page, the axes
are not stretched with respect to each other.
The plot file is a set of plotting commands and data. Each command is
a single ascii character indicating which operation is to be
performed. The data following a command is either a newline
terminated ascii string or several signed, two byte integers in
binary format. For example, the command to move the current point
to the coordinate (3,5) would be m\000\003\000\005.
Note that the byte order of the binary representation of the signed,
two byte integers is machine dependent, so on some machines, this
command might appear as m\003\000\005\000. plot2ps
tries to guess the byte order from the arguments to the openpl
command and adjust the order accordingly.
The following table lists each single character commands followed by the name of the corresponding libps function called to handle the data and a description of the command and data.
arc function (see section arc).circle function
(see section circle).color function
(see section color).idraw and PostScript we start off with a blank
page. For this reason the erase command does not actually output any
PostScript. This is equivalent to the erase function
(see section erase).linemod function
(see section linemod) which describes the line styles and their names.fontname function (see section fontname).line
function (see section line).fill function (see section fill).c) which draws a
line. This is equivalent to the move function (see section move).
cont function (see section cont).point function
(see section point).rotate function (see section rotate).plot2ps uses the third
signed, two byte integer (the right-hand limit) to try to determine the
byte order. This is equivalent to the space function
(see section space) which describes the recognized sizes.fontsize function (see section fontsize).label function (see section label).alabel function (see section alabel)
which describes how to specify justification.Rich Murphey <Rich@Rice.edu> wrote the first version of the graph, tek 4010 and PostScript support and documentation and Richard Stallman <Rms@ai.mit.edu> further directed development of the program and editorial support for the documentation. John Interrante generously provided the PostScript prologue and helpful comments on the program.
Arthur Smith (Lassp, Cornell University) <arthur@helios.tn.cornell.edu> has generously provided his code for the xplot utility.
Ray Toy <toy@dino.ecse.rpi.edu> provided code for graph and tek 4011 and rewrote the tick mark spacing code, incorporated gnu getopt and provided the statistics package.
David B. Rosen <rosen@bu.edu>, jeffrey templon <templon@copper.ucs.indiana.edu> and David W. Forslund <dwf%hope.ACL@lanl.gov> alpha tested early versions.