\input texinfo   @c -*-texinfo-*-@setfilename graph.info@settitle graph@ifinfoThis file documents graph, a utility for creating plot files.Copyright @copyright{} 1989 Free Software Foundation, Inc.@end ifinfo@titlepage@sp 10@center @titlefont{graph}@sp 2@center A utility for creating plot files@sp 2@vskip 0pt plus 1filllCopyright @copyright{} 1989 Free Software Foundation@end titlepage@node Top, Options, , (dir)@chapter The @code{graph} Utility@code{graph} is a utility for creating plots from data.  It reads asciidata and writes a plot with axes and labels.  You can specify labels andranges for the axes, and you can set the sizes and position of the ploton the page.  Each invocations of graph produces a single box with a setof axes and data draw within.  You can place an arbitrary number ofplots on the page by concatenating the plot output of eachinvocation.@refill@menu* Options::	     Command line options for graph.* Graph Examples::   How to use graph.* plot2ps::          A GNU plot to postscript conversion utility.@end menu@chapter Options at a glance@table @samp@item Option:Description:@item -Cprint copyright notice@item -Dbinary double precision data@item -Euse extended plot file format@item -H CHARACTER_HEIGHTfractional height of characters@item -Ibinary integer data@item -KChange symbol when each new line is stared.@item -LChange line style when each new line is stared.@item -M [x|y] MARGINamount of margin between data and x or y axes.@item -N TICKSnumber of tick marks on each axis@item -P SIZEplot file coordinate range@item -S SYMBOL_NUMBER SYMBOL_SIZEdraw symbols at each point@item -T TICK_SIZEfractional size of tick marks@item -W CHARACTER_WIDTHfractional width of characters@item -X X_LABELlabel printed below the x axis@item -Y Y_LABELlabel printed right of the y axis@item -a STEP_SIZE LOWER_LIMITgenerate abscissa, read only y values@item -bbreak lines whenever x decreases@item -c POINT_LABELdefault label printed at each point@item -dprint debugging information@item -g GRID_STYLEdraw a grid in the plot@item -h HEIGHTfractional height of the plot@item -l TOP_LABELlabel printed above the plot@item -m LINE_MODEsolid and dashed lines@item -r RIGHTmove plot right by fractional amount@item -ssave the screen - do not erase@item -ttranspose x and y axes@item -u UPmove plot up by fractional amount@item -w WIDTHfractional width of the plot@item -x [BTl] LOWER_LIMIT UPPER_LIMITlabels on bottom or top, log scale, axis limits@item -y [LRl] LOWER_LIMIT UPPER_LIMITlabels on left or right, log scale, axis limits @item -zdo not read data from standard input@end table@node Options, Graph Examples, Top, Top@chapter Command Line OptionsThe following table describes each of the command line arguments to graph.Each option which takes an argument is followed by the type and defaultvalues of the argument in parentheses.@table @samp@item -CPrint out the GNU copyright notice.@refill@item -DRead double precision binary data rather than ascii data.Since @code{graph} is generally I/O bound, this can decrease executiontime.@refill@item -EUse an extended plot file format. This provides automatic adjustment oflabels with respect to tick marks.  The @samp{-H} and @samp{-W} optionsare ignored if @samp{-E} is specified.  You will need the GNU plotutility @code{plot2ps} in oder to print the output.@refill@item -H(double, default .03) The fractional height of printed characters.  Thisvalue is used to adjust location of labels with respect to the tickmarks.@refill@item -IRead integer binary data rather than ascii data.@refill@item -KChange symbol when each new line is stared.  A new line is startedwhenever the abscissal (x) value decreases and the @samp{-b} option isspecified.  The symbol number is incremented through the values show inthe table below (see @samp{-S}).@refill@item -LChange line style when each new line is stared. As in @samp{-K}, theline style number is incremented through the values shown in the tablebelow (see @samp{-m}).@refill@item -M @samp{[x|y]} @var{margin}(double, default 0 for x and .05 for y) @var{margin} is the fractionalamount of margin between the data and the horizontal or vertical edgesof the box. A value of .05 for y produces a space which is 5% of theheight of the box, placed above and below the data.@refill@item -M  amount of margin between data and x or y axes.@item -N @var{ticks}(integer, default 5) @var{ticks} is the minimum number of tick marks foreach axis.  @code{graph} tries to pick as few digits as possible fortick mark labels and uses at least this many tick marks.@refill@item -P @var{size}(integer, default 4096) @var{size} is the upper limit on coordinatevalues in the plot file @code{graph} creates.  For devices with higherresolution, this value can be increased.  A value of 4096 is sufficientfor 300 dot per inch devices such as laser writers.  This limit on thevalues of coordinates (0 to @var{size}) output by @code{graph} isrigidly enforced to prevent unpredictable behaviors by device driverssuch as @code{plot}.@refill@item -S @var{symbol_number} @var{symbol_size}(integer and float, defaults -1 and 0.01) Draw a symbol at each point inthe data. @var{symbol_number} specifies the shape of the symbolaccording to the following table and @var{symbol_size} specifies thefractional size of the symbol with respect to the height and width ofthe plot.  Note that you can specify sybols to be drawn without any lineconnecting them by specifying the option @code{-m -1}.@refill@table @asis@item -1 no symbol at all@item 0 plus sign@item 1 cross@item 2 diamond@item 3 square@item 4 triangle@item 5 circle@item 6 circle with a line through it@end table@item -T @var{tick_size}(float, default .01) @var{tick_size} is the fractional size of the tickmarks on each axis.  A value of 1.0 produces tick marks on the x (y)axis whose length is equal to the width (height) of the plot.@refill@item -W(double, default .02) The fractional width of printed characters.  Likethe @samp{-H} option, this value is used to adjust location of labelswith respect to the tick marks.@refill@item -X @var{x_label}(string, default blank) @var{x_label} is a label printed below the xaxis.@refill@item -Y @var{y_label}(string, default blank) @var{y_label} is a label printed to the right ofthe y axis.@refill@item -a @var{step_size} @var{lower_limit}(floats, defaults 1 and 0) Automaticly generate abscissa (x) values.This option specifies that the data contains only ordinate (y) values.@var{step_size} specifies the interval between neighboring points and@var{lower_limit} specifies the first abscissa (x) value.@refill@item -bBreak the lines in the graph whenever the abscissa (x) valuesdecrease.  Several curves with monotonically increasing abscissavalues can be concatenated and fed to graph using this option.@refill@item -c @var{point_label}(string, default blank) @var{point_label} is the default label placed ateach point in the plot when none is read from the input for that point.That is, labels read from the input are printed instead of the defaultwhenever they are present.@refill@item -dDebugging information, including the data read in, is sent to thestandard error output.  This is useful for double checking binary datafiles.@refill@item -g @var{grid_style}(integer, default 1) @var{grid_style} specifies the type of box framingthe plot and whether grid lines are drawn inside the box.@refill@table @asis@item 0 no box around plot, no axes, no labels.@item 1 box around plot, axes with tick marks and labels.@item 2 box containing a grid and axes with tick marks and labels.@end table@item -h @var{height}(float, default 0.8) @var{height} specifies the fractional height of theplot with respect to the height of the plotting area.  A value of 1.0will produce a box which fills the available area.  Note that the tickmarks and labels are outside this area so that values less than 1.0 aregenerally used.@refill@item -l @var{top_label}(string, default blank) @var{top_label} is a label placed above theplot.@refill@item -m @var{line_mode}(integer, default 0) @var{line_mode} specifies the mode (or style) oflines drawn between data points.@refill@table @asis@item -1 no line at all@item 0 solid@item 1 longdashed@item 2 dotted@item 3 disconnected@item 4 dotdashed@item 5 shortdashed@end table@item -r @var{right}(float, default 0.1) Move the plot to the right by a fractional amount@var{right} with respect to the width of the plotting area.  Thisproduces a margin on the left hand side of the plot.  A value of 0.5will produce a margin half the width of the available area.  Note thatthe tick marks and labels are drawn in the margin.@refill@item -sSave the screen. This option prevent graph from erasing the previouscontents of the graphics window or device.@refill@item -tTranspose the axes and axis labels. This option flips the plot over byinterchanging x and y values and labels.@refill@item -u @var{up}(float, default 0.1) Move the plot up by a fractional amount @var{up}with respect to the height of the plotting area.  This produces a marginbelow the plot.  A value of 0.5 will produce a margin half the height ofthe available area.  Note that the tick marks and labels are drawn inthe margin.@refill@item -w @var{width}(float, default 0.8) @var{width} specifies the fractional width of theplot with respect to the width of the plotting area.  A value of 1.0will produce a box which fills the available area.  Note that the tickmarks and labels are outside this area, so values less than 1.0 aregenerally used.@refill@item -x @samp{[BTl]} @var{lower_limit} @var{upper_limit}(char, floats) Labels for the tick marks are placed on the top or bottomof the plot when @samp{B} or @samp{T} are specified respectively.  Thedefault position is the bottom.  @samp{l} is optional and specifies thata logarithmic scale be used for the x axis, by default a linear scale isused. Each of these option letters must be listed seperately, andseperated from the other letters or options by white space characters.The arguments @var{lower_limit} and @var{upper_limit} specify the limitsof the x axis. By default the upper and lower limits are taken from thedata.@refill@item -y @samp{[LRl]} @var{lower_limit} @var{upper_limit}Labels for the tick marks are placed on the left or right of the plotwhen @samp{L} or @samp{R} are specified respectively.  The defaultposition is the right.  The other arguments specify the scale and limitsof the y axis as those do for the x axis above.@refill@item -zDo not read data from the standard input.  You can specify input fileson the command line.  @code{graph} prints the file names and pointnumbers when it encounters error in ascii input files. If input files arenamed and contain one coordinate per line in the file axis whose lengthis equal to the width (height) of the plot you can use the emacs@code{next-error} function to locate the source of the error.@refill@end table@node Graph Examples, plot2ps, Options, Top@chapter @code{graph} Examples@section The format of input to @code{graph}@code{graph} reads in ascii data.  Most often, the data is in the formof pairs of x and y values:@refill@example0.0  0.01.0  0.22.0  0.03.0  0.44.0  0.25.0  0.6@end exampleYou can add labels to specific data points by appending a string afterthe  y coordinate.  The label ends at the end of the line:@refill@example3.0  0.4 this is a label for point (3.0, 0.4).@end exampleUsing the @samp{-b} option, you can put more than one data set in theinput as long as each is monotonic in x values and decreases from theend of one set to the start of the next:@refill@example0.0  0.0 first data set2.0  0.04.0  0.20.0  0.1 second data set2.0  0.24.0  0.3@end exampleIf your data contains only y values which are equally sampled along the xaxis, you can use the @samp{-a} option to specify the x axis valuesimplicitly.@refill@example0.00.10.2 label for point (2.0, 0.2)0.30.20.3@end example@section How to put multiple plots on one pageThe command@examplegraph -h .4 -w .4 -r .1 -u .1 < ascii_data_file_1 >  plot_file@end examplewill put a single box containing the plot in the lower left handquarter of the page.  You can add another plot to the upper left handcorner of the page using the command@examplegraph -h .4 -w .4 -r .1 -u .6 < ascii_data_file_2 >> plot_file@end exampleLikewise you can add plots to the right hand side of the page using@examplegraph -h .4 -w .4 -r .6 -u .1 < ascii_data_file_3 >> plot_filegraph -h .4 -w .4 -r .6 -u .6 < ascii_data_file_4 >> plot_file@end exampleThe tick marks can be moved inside the box and labels moved to theopposite sides using@examplegraph -T -.005 -x T -y L < ascii_data_file >> plot_file@end example@node plot2ps,, Graph Examples, Top@section The @code{plot2ps} Utility@code{plot2ps} is a utility for converting Unix plot files intopostscript.  The @code{plot2ps} utility reads plotting commands fromnamed files or the standard input and writes postscript to the standardoutput.  You can then print the postscript output on a printer, or editit using the @code{idraw} graphics editor.  You can also easily includethe output in LaTeX documents using the @code{dvi2ps} utility and theLaTeX command @code{psfig}.@refillThe source code and documentation for @code{plot2ps} and a more completedescription of this are available via anonymous ftp from qed.rice.edu(128.42.4.38) in the directory @file{/pub}.@contents@bye