GRAPH directive

Produces scatter and line graphs on the terminal or line printer (synonym of LPGRAPH).

Options

CHANNEL = scalar	Channel number of output file; default is current output file
TITLE = text	General title; default *
YTITLE = text	Title for y-axis; default *
XTITLE = text	Title for x-axis; default *
YLOWER = scalar	Lower bound for y-axis; default *
YUPPER = scalar	Upper bound for y-axis; default *
XLOWER = scalar	Lower bound for x-axis; default *
XUPPER = scalar	Upper bound for x-axis; default *
MULTIPLE = variate	Numbers of plots per frame; default * i.e. all plots are on a single frame
JOIN = string token	Order in which to join points (ascending, given); default asce
EQUAL = string tokens	Whether/how to make bounds equal (no, scale, lower, upper); default no
NROWS = scalar	Number of rows in the frame; default * i.e. determined automatically
NCOLUMNS = scalar	Number of columns in the frame; default * i.e. determined automatically
YINTEGER = string token	Whether y-labels integral (yes, no); default no
XINTEGER = string token	Whether x-labels integral (yes, no); default no

Parameters

Y = identifiers	Y-coordinates
X = identifiers	X-coordinates
METHOD = string tokens	Type of each graph (point, line, curve, text); if unspecified, poin is assumed
SYMBOLS = factors or texts	For factor SYMBOLS, the labels (if defined), or else the levels, define plotting symbols for each unit, whereas a text defines textual information to be placed within the frame for METHOD=text or the symbol to be used for each plot for other METHOD settings; if unspecified, * is used for points, with integers 1-9 to indicate coincident points, ' and . are used for lines and curves
DESCRIPTION = texts	Annotation for key

Description

The GRAPH directive has been replaced by the LPGRAPH directive, and may be removed in a future release or modified to produce high-resolution plots instead of character-based plots.

The simplest form of the GRAPH directive produces a point plot (or scatterplot as it is sometimes called). It can also be used to plot lines and curves, and text can be added for extra annotation. The data are supplied as y- and x-coordinates in separate parameter lists. For example

VARIATE [VALUES=-16,-7,9,16,7,-8,-12,-5,0,10,4,-4,-3,3,16] X

& [VALUES=0,-14,-12.5,0,14,0,12,0,-10,-9,5,6,-6,-1.5,16] Y

GRAPH Y; X

Here the identifiers Y and X are variates of equal length; Genstat uses their values in pairs to give the coordinates of the points to be plotted.

By default, if you specify several identifiers, Genstat plots them all in the same frame a pair at a time; for example

GRAPH Y[1...3]; X[1,2]

superimposes plots of Y[1] against X[1], Y[2] against X[2], and Y[3] against X[1]. The usual rules governing the parallel expansion of lists apply here: the length of the Y parameter list determines the number of plots within the frame, and the X parameter list is recycled if it is shorter. To generate several frames from one GRAPH statement you can use the MULTIPLE option, described below.

The identifiers supplied by the Y and X parameters need not be variates, but can be any numerical structures: scalars, variates, factors, tables or matrices. The only constraints are that the pairs of structures must have the same numbers of values, and that tables must not have margins.

There are four types of graph available, controlled by the METHOD parameter: point (the default), line, curve and text.

A line plot is one in which each point is joined to the next by a straight line. Alternatively, using the curve method, cubic splines are used to produce a smoothed curve through the data points. This does not represent any model fitted in the statistical sense, but as long as the data points are not too widely spaced (especially where the gradient changes quickly) the plotted curve should be a good representation of the underlying function.

By default, Genstat sorts the data so that the x-values are in ascending order before any line or curve is drawn through the points. However, if you set option JOIN=given, the points are joined in the order in which they occur in the data; if there are then any missing values there will be breaks in the line at each missing unit.

Plots produced with METHOD set to either line or curve do not include markings for the data points themselves; you should plot these separately if they are required. For example

VARIATE [VALUES=-0.1,0.1...0.9] V

& [VALUES=5.5,9.9,8.7,2.3,1.3,5.5] W

GRAPH W,W; V; METHOD=curve,point

Here W is plotted against V twice, first with the curve method and then with the point method. It is best to plot the line first, so that the symbols for individual points will overwrite those used for the line or curve.

The fourth plotting method is text. You can use this to place an item of text within a graph as extra annotation. For example:

SCALAR Xt,Yt; VALUE=20,10

TEXT [VALUES='Y=aX+b'] T

GRAPH Y,Yt; X,Xt; METHOD=line,text; SYMBOLS=*,T

This plots a line, defined by the variates Y and X, as described above. In addition, the text T is printed within the frame starting at the coordinates defined by the scalars Yt and Xt. As these statements show, the SYMBOLS parameter then specifies the text that is to be plotted. The text is truncated as necessary, if positioned too close to the edge of the graph.

With other methods SYMBOL defines the plotting symbol to be used to mark either points or lines on the graph. The default symbol for points is the asterisk, and for lines is a combination of dots and single quotes. If several points coincide, Genstat replaces the asterisk by a digit between 2 and 9, representing the number of coincidences, with 9 meaning nine or more. For point plots, the SYMBOLS parameter can be set to either a text or a factor. If you specify a text with a single string, the string is used to label every point; otherwise, the text must have one string for each point.

Normally, output goes to the current output channel, but you can use the CHANNEL option to direct it to another. For example, when you are working interactively, you might want to send a graph to a secondary output file so that you can print it later. Unlike some directives you cannot save the output in a text structure.

The TITLE option allows you to set an overall title for the graph. For example:

GRAPH [XTITLE='Nitrogen Applied (kg/ha)'] Yield; Nitrogen

You can also have individual axis titles, specified by the YTITLE and XTITLE options. Genstat prints the y-axis title as a column of characters down the left-hand side of the graph. New lines are ignored, so that strings within a text are concatenated. Genstat truncates the title if necessary: the maximum possible number of characters is the number of rows of the frame plus 4. The x-axis title is printed below the graph; the maximum number of characters is the number of columns of the frame plus four: long strings are truncated whereas short strings are centred.

If no titles are set, a simple key will be produced below the graph which lists the identifiers and plotting symbols for each pair of Y and X structures. You can obtain your own key by setting the DESCRIPTION parameter, which supplies a line of text for each plot.

By default, Genstat automatically calculates the extent of the axes from the data to be plotted, in such a way that all the data are contained within the frame. You can set one or more of the bounds for the axes by options YLOWER, YUPPER, XLOWER and XUPPER. By setting the upper bound of an axis to a value that is less than the lower bound, you can reverse the usual convention for plotting in which the y-values increase upwards and the x-values increase to the right. Setting the options YINTEGER and XINTEGER constrains the axis markings to be integral, if possible.

The EQUAL option allows you to place constraints on the bounds for the axes. The default setting no (meaning no constraint) uses the boundary values as set by the options or calculated from the data. The settings lower and upper constrain the lower or upper bounds of the two axes to be equal: for example, to plot the line y=x along with the data, setting EQUAL=lower will ensure that it will pass through the bottom left-hand corner of the frame. The scale setting adjusts the y-bounds and x-bounds so that the physical distance on one axis corresponds as closely as possible to physical distance on the other: for example, so that one centimetre will represent the same distance along each axis.

Normally each GRAPH statement produces one frame, and Genstat sets the size so that it will fill one screen or line-printer page, based on the settings of WIDTH and PAGE from OPEN or OUTPUT, or their defaults if these have not been specified. When output is to a file the graph will be placed on a new page, unless this has been disabled using OUTPUT, JOB or SET. The size of the graph is defined in terms of the number of characters in each row and the number of rows in the frame, a row being one line of output. You can adjust the size of the frame by using the NROWS and NCOLUMNS options; the minimum allowed is three rows and three columns, and the maximum number of columns is 17 characters less than the width of the output channel (to leave room for axis markings and titles). There is no maximum on the number of rows. By default, the number of columns is 101, subject to the maximum above, and the number of rows is the number of lines per page, less 8, to allow room for annotation. By defining the page size in advance you can avoid having to specify the numbers of rows and columns when you wish to plot many graphs.

The automatic axis scaling aims to find axis markings that are at reasonable values, but because the markings appear at fixed character positions this may not always be possible. If both upper and lower axis bounds are set, or EQUAL is set in conjunction with axis bounds, or you have requested integral axis markings, there may be conflicting constraints on the axis scaling. If the resultant axis markings then require several decimal places, you may be able to obtain better values by slight adjustments to the numbers of rows or columns.

The MULTIPLE option allows you to generate several frames (separate graphs) from one statement. If there is room, the graphs can be printed alongside each other, for example to produce a two-by-two array of plots on a line-printer page. The option should be set to a variate whose elements define the number of graphs to plot in each frame and the number of values in the variate determines the number of frames to be output. For example,

GRAPH [MULTIPLE=!(2,1,2)] A,B,C,D,E; X[1...3]

will produce three frames; the first containing A against X[1] and B against X[2], the second containing C against X[3] and the third containing D against X[1] and E against X[2]. The sum of the values in the MULTIPLE list gives the total number of structures required to form the plots, which must therefore be equal to the length of the Y parameter list. The X list will be recycled if necessary, as here.

By default, each graph will fit the page (as if it had been produced by an individual GRAPH statement). However, if you set the NCOLUMNS option to a suitably small value, Genstat may be able to fit more than one frame across the page. The MULTIPLE option will then produce the graphs side by side. Remember that 17 columns are automatically added to provide annotation, and five blank columns are used to separate multiple graphs in parallel. This means that, for example, setting NCOLUMNS=20 will produce two graphs in parallel on a screen of width 80, and three graphs when output to a file of width 121 or more.

Options: CHANNEL, TITLE, YTITLE, XTITLE, YLOWER, YUPPER, XLOWER, XUPPER, MULTIPLE, JOIN, EQUAL, NROWS, NCOLUMNS, YINTEGER, XINTEGER.

Parameters: Y, X, METHOD, SYMBOLS, DESCRIPTION.

Action with RESTRICT

You can arrange to plot only a subset of the points specified by a particular pair of Y and X vectors (i.e. variates and/or factors), by restricting either one of them. If both are restricted, then they must be restricted in exactly the same way.

See also

Directives: DGRAPH, D3GRAPH, LPGRAPH.

Commands for: Graphics.

Example

" Example GRAP-1: line-printer scatter-plot"

VARIATE [VALUES=-16,-7,9,16,7,-8,-12,-5,0,10,4,-4,-3,3,16] X
& [VALUES=0,-14,-12.5,0,14,0,12,0,-10,-9,5,6,-6,-1.5,16] Y
GRAPH Y; X

" Superimpose point and 'line' plot, and add text to the picture"
VARIATE [VALUES=-0.1,0.1...0.9] V
& [VALUES=5.5,9.9,8.7,2.3,1.3,5.5] W
GRAPH [TITLE='Point and curve plot'; NROWS=16; NCOLUMNS=61] W,W; V;\ 
  METHOD=curve,point; SYMBOLS=*,'X'; DESCRIPTION='Fitted curve   ...',*

" Series of Line graphs in the same picture"
VARIATE [NVALUES=4] Z[2...16]
& [VALUES=1,3,2,4] Z[1]
CALCULATE Z[2...16] = Z[1...15] + 1
& Ymax = MAX(VMAX(Z))
& Ymin = MIN(VMIN(Z))
VARIATE [NVALUES=4; VALUES=1...4] X
GRAPH [YLOWER=Ymin; YUPPER=Ymax] Z[1...16]; X; METHOD=line;\ 
  SYMBOL='1','2','3','4','5','6','7','8'