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'