Produces point and line graphs using character (i.e. line-printer) graphics.
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
LPGRAPH
plots graphs in “line-printer” format, that is, using the characters of ordinary output rather than a high-resolution graphics display. It was added in Release 10 as a synonym of the earlier GRAPH
directive, which may be modified to use high-resolution graphics in a future release.
The simplest form of the LPGRAPH
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
LPGRAPH 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
LPGRAPH 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 LPGRAPH
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
LPGRAPH 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
LPGRAPH 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:
LPGRAPH [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 lets you 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 LPGRAPH
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,
LPGRAPH [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 LPGRAPH
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
, LPCONTOUR
, LPHISTOGRAM
.
Commands for: Graphics.
Example
" Examples 1:6.10.1a-b " 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 LPGRAPH Y; X VARIATE [VALUES=-0.1,0.1...0.9] V & [VALUES=5.5,9.9,8.7,2.3,1.3,5.5] W LPGRAPH [TITLE='Point and curve plot'; NROWS=16; NCOLUMNS=61] W,W; V;\ METHOD=curve,point; SYMBOLS=*,'X'; DESCRIPTION='Fitted curve ...',*