Draws graphs on a plotter or graphics monitor.

### Options

`TITLE` = text |
General title; default `*` |
---|---|

`WINDOW` = scalar |
Window number for the graphs; default 1 |

`KEYWINDOW` = scalar |
Window number for the key (zero for no key); default 2 |

`SCREEN` = string token |
Whether to clear the screen before plotting or to continue plotting on the old screen (`clear` , `keep` , `resize` ); default `clea` |

`KEYDESCRIPTION` = text |
Overall description for the key; default `*` |

`ENDACTION` = string token |
Action to be taken after completing the plot (`continue` , `pause` ); default `*` uses the setting from the last `DEVICE` statement |

`HOTMENU` = matrices |
Defines sets of “hot” components for the user to select as shown or hidden by a menu in the Graphics Viewer |

`HOTCHOICE` = string token |
Whether one or several “hot” components can be displayed at a time (`one` , `several` ); default `seve` |

### Parameters

`Y` = identifiers |
Vertical coordinates |
---|---|

`X` = identifiers |
Horizontal coordinates |

`PEN` = scalars, variates or factors |
Pen number for each graph (use of a variate or factor allows different pens to be defined for different sets of units); default `*` uses pens 1, 2, and so on for the successive graphs |

`DESCRIPTION` = texts |
Annotation for key |

`YLOWER` = identifiers |
Lower values for vertical bars |

`YUPPER` = identifiers |
Upper values for vertical bars |

`XLOWER` = identifiers |
Lower values for horizontal bars |

`XUPPER` = identifiers |
Upper values for horizontal bars |

`YBARPEN` = scalars, variates or factors |
Pens to use to draw the vertical bars; default -11 |

`XBARPEN` = scalars, variates or factors |
Pens to use to draw the horizontal bars; default -11 |

`LAYER` = scalars |
“Layer” of the plot |

`UNITNUMBERS` = identifiers |
Specifies unit numbers to be used when points are selected in the graphics viewer; default `*` uses the actual unit numbers of the values in the `X` and `Y` structures |

`DISPLAY` = string tokens |
Whether to display each component initially in the graph (`show` , `hide` ); default `show` |

`HOTCOMPONENT` = scalars |
Allows components of the graph (specified by pairs of `Y` and `X` settings) to be defined as “hot” components that can be shown or hidden through their association with “hot” points or using a menu in the Graphics Viewer |

`HOTDEFINITION` = matrices |
Define how to use points defined by the Y and X parameters as “hot” points in the Graphics Viewer to allow the user to decide whether other components of the graph are shown or hidden |

### 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 ordinal number of 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 then define axis limits that enclose all the subsequent data. Alternatively, if you set `SCREEN=resize`

, the axes and their bounds will be adjusted, if necessary, to enclose the additional information. 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`

allows *error bars* to be included in 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 might 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`

(this would give a 95% confidence interval assuming that the y-values come from a Normal distribution). 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. Similarly, parameters `XLOWER`

and `XUPPER`

allow you to plot horizontal bars at each point.

The `YBARPEN`

and `XBARPEN`

parameters define the pens to be used for the vertical and horizontal bars, respectively, with the default to use pen -11. Similarly to the `PEN`

parameter, they can be set to either scalars, factors or variates. For each group of units defined by the setting of `PEN`

, `DGRAPH`

will use the first pen that it finds for that group in the setting supplied by `YBARPEN`

and `XBARPEN`

. (So `YBARPEN`

and `XBARPEN`

cannot define more detailed groupings of the points than those defined by `PEN`

.) For example:

`VARIATE [VALUES=1,1,2,2,3,3] Pvar`

`& [VALUES=4,4,5,5,6,6] Ybvar`

`& [VALUES=7,7,8,8,9,10] Xbvar`

`DGRAPH Y; X; PEN=Pvar; YLOWER=Ylow; YUPPER=Yupp;\`

` XLOWER=Xlow; XUPPER=Xupp;\`

` YBARPEN=Ybpen; XBARPEN=Xbpen`

The first two points here will be plotted in pen 1 with vertical bar in pen 4 and horizontal bar in pen 7. The third and fourth points will be plotted in pen 2 with vertical bar in pen 5 and horizontal bar in pen 8. The fifth and sixth points will be plotted in pen 3 with vertical bar in pen 6 and horizontal bar in pen 9. Notice, that the horizontal bar for the sixth point will be plotted in pen 9 *not* pen 10, as it is in the same `PEN`

group as the (earlier) fifth point which has pen 9 for the horizontal bar. However, if `PEN`

is not set to a factor or variate, the `YBARPEN`

and `XBARPEN`

settings define the groups.

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`

or `SCREEN=resize`

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; this is plotted using pen -5. 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.

The components of the graph defined by each pair of `Y`

and `X`

parameter settings are assumed to form separate, successive “layers” on the plot. So, if an area of the plot contains information (lines, symbols or labels) from several pairs of `Y`

and `X`

settings, the information from the later settings will overlay the information from earlier settings. You can control the orders of the layers by using the `LAYER`

parameter to assign an explicit layer number to each pair of `Y`

and `X`

settings. The pairs of `Y`

and `X`

settings are then plotted in ascending order of layer numbers. These layer numbers also work across `DGRAPH`

statements when you add to a plot by setting option `SCREEN=keep`

or `SCREEN=resize`

. So, for example, you can specify lower layer numbers to plot the new information “below” the layers formed by the earlier `DGRAPH`

statement(s).

Usually all these components of the graph are shown when the graph is plotted. In Genstat *for Windows*, the Graphics Editor (which can be opened from the Edit menu on the menu bar of the Graphics Viewer) allows you to show or hide components, and the `DISPLAY`

parameter of `DGRAPH`

allows you to define whether a component should be shown or hidden in the initial graph displayed by the Graphics Viewer.

Alternatively, the Graphics Viewer itself can allow components to be shown or hidden, either by using their association with some “hot” points that have been defined on the graph, or by using a menu on its menu bar. These “hot” components are identified by defining a unique integer number for each one, using the `HOTCOMPONENT`

parameter; if the component is not to be treated as “hot”, `HOTCOMPONENT`

should be left unset or given a missing value. Several pairs of `Y`

and `X`

parameter settings can be given the same number, so you can build up a “hot” component from more than one type of graphical item (e.g. from plotted points and shaded areas). “Hot” points are plotted within the graph using the `Y`

, `X`

and other parameters (e.g. `PEN`

) in the usual way, as described above. The extra information, to define them as “hot”, is supplied by setting the `HOTDEFINITION`

parameter to a matrix with a row for each “hot” point, and a column for each type of “hot” component. The elements of the matrix specify the “hot” components to be associated with each “hot” point, using the numbers defined by the `HOTCOMPONENT`

parameter. The menus in the Graphics Viewer can be made more informative, by defining textual labels for the rows and columns of the matrix (see the `MATRIX`

directive); these are then used as annotation in the menus. Alternatively, if you set the `HOTMENU`

option to a similar matrix, the Graphics Viewer will include a menu on its menu bar to allow users to choose whether “hot” components are shown or hidden. By default, users will be allowed to display several “hot” components at a time. However, you can set option `HOTCHOICE=one`

to indicate that only one can be shown at a time. (The `DISPLAY`

parameter should then be used to indicate which one, if any, should be shown on the initial graph.)

The Graphics Viewer also has a tool that allows you to select points, and copy their unit numbers onto the clipboard. Usually these numbers are simply the locations of the plotted values in the `X`

and `Y`

structures. However, you can use the `UNITNUMBERS`

parameter to supply other numbers. (This may be useful if, for example, you are plotting sorted values.)

Options: `TITLE`

, `WINDOW`

, `KEYWINDOW`

, `SCREEN`

, `KEYDESCRIPTION`

, `ENDACTION`

, `HOTMENU`

, `HOTCHOICE`

.

Parameters: `Y`

, `X`

, `PEN`

, `DESCRIPTION`

, `YLOWER`

, `YUPPER`

, `XLOWER`

, `XUPPER`

, `YBARPEN`

, `XBARPEN`

, `LAYER`

, `UNITNUMBERS`

, `DISPLAY`

, `HOTCOMPONENT`

, `HOTDEFINITION`

.

### 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.

### See also

Directives: `D3GRAPH`

, `BARCHART`

, `DHISTOGRAM`

, `LPGRAPH`

, `FRAME`

, `XAXIS`

, `YAXIS`

, `AXIS`

, `PEN`

.

Procedures: `DCIRCULAR`

, `DFUNCTION`

, `DMSCATTER`

, `DSCATTER`

, `DTEXT`

, `DFRTEXT`

, `DXYDENSITY`

, `TRELLIS`

.

Commands for: Graphics.

### Example

" Example DGRA-1: Draw a scatter plot" " File DGRA-1.DAT contains data on deaths from lung cancer and smoking rates in 11 countries in 1930, from a US report in 1964." " Read the data recorded in the file." FILEREAD [NAME='%gendir%/examples/DGRA-1.DAT'] country,deaths,cigarettes " Display the data in a high-resolution graph." TEXT cancer; VALUES='Lung cancer and smoking in 1930' DGRAPH [TITLE=cancer; WINDOW=3; KEYWINDOW=0] deaths; cigarettes " Add the axis titles and bounds, and a grid." XAXIS WINDOW=3; TITLE='Cigarettes per man per year'; LOWER=0 YAXIS WINDOW=3; TITLE='Deaths per million'; LOWER=0 FRAME [GRID=xy] WINDOW=3 DGRAPH [TITLE=cancer; WINDOW=3; KEYWINDOW=0] deaths; cigarettes " Specify the axis labelling precisely." XAXIS WINDOW=3; MARKS=!(0,300...1500) YAXIS WINDOW=3; MARKS=!(0,100...500); NSUBTICKS=3 DGRAPH [TITLE=cancer; WINDOW=3; KEYWINDOW=0] deaths; cigarettes " Label the points with the names of the countries." PEN 1; LABELS=country; SYMBOLS=0 DGRAPH [TITLE=cancer; WINDOW=3; KEYWINDOW=0] deaths; cigarettes; PEN=1 " Fit a linear regression line (assuming variance proportional to the square of the mean) to the relationship and add the fitted line to the graph." MODEL [DISTRIBUTION=gamma; LINK=identity] deaths FIT [PRINT=*] cigarettes RKEEP FITTEDVALUES=fit PEN 2; METHOD=line; SYMBOLS=0; CLINE=2 DGRAPH [SCREEN=keep; WINDOW=3; KEYWINDOW=0] fit; cigarettes; PEN=2