DGRAPH directive

Draws graphs on a plotter or graphics monitor.

Options

Parameters

Description

The DGRAPH directive draws high-resolution graphs, containing points, lines or shaded polygons. The graph is produced on the current graphics device which can be selected using the DEVICE directive. The WINDOW option defines the window, within the plotting area, in which the graph is drawn; by default this is window 1.

   The Y and X parameters specify the coordinates of the points to be plotted; they must be numerical structures (scalars, variates, factors, matrices or tables) of equal length. If any of the variates or factors is restricted, only the subset of values specified by the restriction will be included in the graph. The restrictions are applied to the Y and X variates or factors in pairs, and do not carry over to all the variates or factors in a list. For example, suppose the variate Y1 is restricted but the variate Y2 is not. The statement

DGRAPH Y1,Y2; X

will plot the subset of values of Y1 against X, but all the values of Y2 against X. Conversely, if X were restricted the subset would be plotted for both Y1 and Y2. Any associated structures, like variates specified by the PEN parameter or factors used to provide labels for the points, must be of the same length as Y and X.

   Each pair of Y and X structures has an associated pen, specified by the PEN parameter. By default, pen 1 is used for the first pair, pen 2 for the second, and so on. The type of graph that is produced is determined by the METHOD setting of that pen. This can be point, to produce a point plot or scatterplot; line to join the points with straight lines; monotonic, open or closed to plot various types of curve through the points; or fill to produce shaded polygons. In the initial graphics environment, all the pens are defined to produce point plots. This can be modified using the METHOD option of the PEN directive. Other attributes of the pen can be used to control the colour, font, symbols and labels.

   With METHOD=fill, the points defined by the Y and X variates are joined by straight lines to form one or more polygons which are then filled using the brush style specified for the pen. The JOIN parameter of PEN determines the order in which the points are joined; with the default, ascending, the data are sorted into ascending order of x-values, while with JOIN=given they are left in their original order. There should be at least three points when using this method.

   A warning message is printed if the data contain missing values. The effect of these depends on the type of graph being produced, as follows. If the method is point there will be no indication on the graph itself that any points were missing (but obviously none of the points with missing values for either the y- or x-coordinate can be included in the plot). If a line or curve is plotted through the points there will be a break wherever a missing value is found; that is, line segments will be omitted between points that are separated by missing values. When using METHOD=fill missing values will, in effect, define subsets of points, each of which will be shaded separately. Note, however, that the position of the missing values within the data will differ according to whether or not the data values have been sorted; this is controlled by the JOIN parameter of PEN, as described above. If the data are sorted, units with missing x-values are all moved to the beginning (and are thus ignored).

   The PEN parameter can also be set to a variate or factor, to allow different pens to be used for different subsets of the units. With a factor, the units with each level are plotted separately, using the pen defined by the level concerned. If PEN is set to a variate, its values similarly define the pen for each unit. For example, if you fit separate regression lines to some grouped data, you can easily plot the fitted lines in just two statements, one to set up the pens and one to plot the data:

PEN 1...Ngroups; METHOD=line; SYMBOL=0

DGRAPH Fitted; X; PEN=Groups

   By default, GenStat calculates bounds on the axes that are wide enough to include all the data; the range of the data is extended by five percent at each end, and the axes are drawn on the left-hand side and bottom edge of the graph. This can all be changed by the XAXIS and YAXIS directives using the LOWER and UPPER parameters to set the bounds, and YORIGIN and XORIGIN to control the position of the axes. Other parameters allow you to control the axis labelling and style. If the axis bounds are too narrow, some points may be excluded from the graph, so that clipping occurs. If the plotting method is point, GenStat ignores points that are out of bounds. For other settings of METHOD, lines are drawn from points that are within bounds towards points that are out of bounds, terminating at the appropriate edge. Clipping may also occur if the method is monotonic, open or closed and you have left GenStat to set default axis bounds, because these methods fit curves that may extend beyond the boundaries. If this occurs you should use the XAXIS and YAXIS directives to provide increased axis bounds. When you use several DGRAPH statements with SCREEN=keep to build up a complex graph, the axes are drawn only the first time, and the same axes bounds are then used for the subsequent graphs. You should thus define axis limits that enclose all the subsequent data. Axes are drawn only if SCREEN=clear, or the specified window has not been used since the screen was last cleared, or the window has been redefined by a FRAME statement.

   DGRAPH can also be used to add error bars to the plot. You might want to use these, for example, to show confidence limits on points that have been fitted by a regression. Error bars are requested by setting the YLOWER and YUPPER parameters to variates defining the lower and upper values for the error bar to be drawn at each point. For example, if you know the standard error for each point, you could calculate and plot the bounds as follows:

CALCULATE Barlow = Y - 1.96 * Err

& Barhigh = Y + 1.96 * Err

DGRAPH Y; X; YLOWER=Barlow; YUPPER=Barhigh

The error bar is drawn from the lower point to the upper point at the associated x-position; the bar will be drawn even if the corresponding y-value (or y-variate) is missing. If the lower value is missing, or the YLOWER parameter is not set, only the upper section of the bar is drawn; likewise if the upper value is missing only the lower section is drawn. The same pen is used to draw the error bars as is used for the y- and x-values. If you want to use a different pen for the error bars you can plot them separately: for example

DGRAPH Y,Mv; X,X; YLOWER=*,Barlow; YUPPER=*,Barhigh; PEN=2,6

(where Mv is a variate of missing values of the same length as Y). Similarly, parameters XLOWER and XUPPER allow you to plot horizontal bars at each point.

   The KEYWINDOW option specifies the window in which the key appears; by default this is window 2. Alternatively, you can set KEYWINDOW=0 to suppress the key. The key contains a line of information for each pair of Y and X structures, written with the associated pen. This will indicate the symbol used, the line style (for a plotting method of line or curve) or a shaded block to illustrate the brush style (when METHOD=fill), the name of the structure (if any) defined by the LABELS parameter of PEN, and a description indicating the identifiers of the data plotted (for example Residuals v Fitted). Alternatively, you can supply your own key, using the DESCRIPTION parameter, and you can specify a title for the key using the KEYDESCRIPTION option. If you draw several graphs using SCREEN=keep and the same key window, each new set of information is appended to the existing key, until the window is full.

   If you have set the PEN parameter to a variate or factor in order to plot independent subsets of the data, the key will contain information for each subset. If the LABELS parameter of PEN has been used to specify labels for the points, each line of the key will contain the label corresponding to the first value of the subset, rather than the identifier of the labels structure itself.

   The TITLE option can be used to provide a title for the graph. You can also put titles on the axes by using the TITLE parameter of the XAXIS and YAXIS directives. The SCREEN option controls whether the graphical display is cleared before the graph is plotted and the ENDACTION option controls whether GenStat pauses at the end of the plot.

Options: TITLE, WINDOW, KEYWINDOW, SCREEN, KEYDESCRIPTION, ENDACTION.

Parameters: Y, X, PEN, DESCRIPTION, YLOWER, YUPPER, XLOWER, XUPPER.

Action with RESTRICT

You can arrange to plot only a subset of the points specified by a particular pair of Y and X vectors and associated PEN vector, by restricting any one of them. If more than one of these is restricted, then they must all be restricted in exactly the same way.