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 in the colours 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 block to illustrate colour (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