Produces scatter and line graphs on the terminal or line printer.
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 against X, Y against X, and Y against X. 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 lets you 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 lets you 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 and B against X, the second containing C against X and the third containing D against X and E against X. 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.
Directives: DGRAPH, D3GRAPH, LPGRAPH.