Defines the positions and appearance of the plotting windows within the frame of a high-resolution graph.
Options
GRID = string tokens |
Specifies grid lines (xy, xz, yx, yz, zx, zy) |
|---|---|
BOXFRAME = string tokens |
Whether to include a box enclosing the entire frame (include, omit) |
BACKGROUND = scalars or texts |
Specifies the colour to be used for the background of the whole frame (where allowed by the graphics device) |
RESET = string token |
Whether to reset the window definition to the default values (yes, no); default no |
Parameters
WINDOW = scalars |
Window numbers |
|---|---|
YLOWER = scalars |
Lower y device coordinate for each window |
YUPPER = scalars |
Upper y device coordinate for each window |
XLOWER = scalars |
Lower x device coordinate for each window |
XUPPER = scalars |
Upper x device coordinate for each window |
YMLOWER = scalars |
Size of bottom margin (for x-axis labels) |
YMUPPER = scalars |
Size of upper margin (for overall title) |
XMLOWER = scalars |
Size of left-hand margin (for y-axis labels) |
XMUPPER = scalars |
Size of right-hand margin |
BACKGROUND = scalars or texts |
Specifies the colour to be used for the background in each window (where allowed by the graphics device) |
BOX = string tokens |
Whether to include a box enclosing the plotted graphic (include, omit) |
BOXSURFACE = string tokens |
Box to include in a surface plot (full, bounded, omit) |
BOXKEY = string tokens |
Box to draw around key (full, bounded, omit) |
PENTITLE = scalars |
Pen to use to write the overall title |
PENKEY = scalars |
Pen to use for the key |
PENGRID = scalars |
Pen to use to draw the grid lines |
SCALING = string tokens |
How to scale the axis in each window (xyequal, xzequal, yzequal, xyzequal) |
TPOSITION = string tokens |
Position of title (right, left, center, centre) |
CINTERIOR = scalars or texts |
Specifies the colour to be used for the interior of each window (where allowed by the graphics device) |
CFRAME = scalars or texts |
Specifies the colour to be used for the frame of each window (where allowed by the graphics device) |
CTITLE = scalars or texts |
Specifies the colour to be used for the title bar of each window (where allowed by the graphics device) |
AXES = identifiers or pointers |
Additional oblique axes to include in each window |
SAVE = pointers |
Saves details of the current settings for the window concerned |
Description
You can define up to 256 different windows in which to plot graphics. Each window is a rectangular area of the screen which is defined using normalized device coordinates (NDC). These can have a range from 0.0 to 1.4 in both Y and X directions, but the usable area depends on the orientation of the device (as defined by the DEVICE directive). With a landscape device, your should use only the range 0.0 to 1.0 for Y, while for a portrait device you should use only 0.0 to 1.0 in the X direction. The mapping from NDC to physical coordinates on the current output device is performed internally, so the window definitions are independent of the choice of device. The actual size of a particular window on different devices will vary according to their relative physical sizes. The NDC system used for window definition is also completely independent of the values of the data that are to be plotted.
When you use FRAME, any aspects of the windows that you do not specify explicitly retain the values that they had immediately before the FRAME statement. Alternatively, you can specify option RESET=yes to reset all these aspects to the default values, defined by Genstat at the start of each job.
To define a window, the upper and lower bounds are required in both y- and x-directions; thus defining both the position and the size of the window. For example
FRAME WINDOW=1; YLOWER=0.25; YUPPER=0.75;\
XLOWER=0; XUPPER=0.5
defines window 1 to be a square of size 0.5, whose bottom left corner is at the point (0.0,0.25) and whose top right corner is (0.5,0.75). This does not define the exact size of a graph plotted in this window, as margins may be required for the annotation and titles (see below).
If you do not specify all four values in the FRAME statement, the existing values are retained. A check is then made on the validity of the window bounds. The settings of YLOWER and XLOWER must be strictly less than those of YUPPER and XUPPER respectively; also, none of the bounds can be outside the permitted range, which is [0.0,1.0] on most graphics devices. You cannot use * to reset a bound to the default value; if you try to do so, Genstat will produce an error diagnostic. (Instead you can specify option RESET=yes, as explained above.)
All the windows have a default size defined when you start Genstat. Window 1 is the default window used for plots by DGRAPH, DCONTOUR, and so on, and is set up to be a square of size 0.75. The default key window is window 2, which is a rectangle of height 0.25 and width 0.75 located immediately below window 1. Windows 3 and 4 are the unit square [0,1]×[0,1] and windows 5, 6, 7 and 8 are the top-left, top-right, bottom-left, and bottom-right quarters respectively of the unit square. Windows 9, 10, 11 and 12 also divide the frame into quarters, but they have the full width (0 to 1) in the x-direction and quarter of the width in the y-direction, working from the top (i.e. 0.75 to 1 for window 9) to the bottom (i.e. 0 to 0.25 for window 12) of the frame. The remaining windows, from 13 to 32, also default to the unit square. You can use FRAME to modify the size or position of any of these windows.
Usually, a margin is provided around each plot so that there is room for the axes to be drawn, along with labelling and titles as specified by the XAXIS or YAXIS directives. By default, the margin size is designed to allow sufficient room for annotation to be added using the standard character size, as defined by the SIZEMULTIPLIER or SMLABEL parameters of PEN. If you use XAXIS or YAXIS to control the plotting of axes explicitly you may wish to alter the size of the margins, either to increase the space used for the axes or, alternatively, to maximize the space available for the graph itself. For example, if you alter the size of the labelling, by explicitly defining the relevant axis pens, more space may be required for the axes; otherwise the labels may be clipped at the window bounds. The parameters YMLOWER, YMUPPER, XMLOWER and XMUPPER can be used to set the space (in NDC) for the bottom, top, left-hand and right-hand margins respectively, and have initial default settings of 0.10, 0.07, 0.12 and 0.05.
On most devices the background colours of the window may be modified by setting the BACKGROUND, CINTERIOR, CFRAME and CTITLE parameters. The BACKGROUND parameter can be used to define the colour for the whole background, while the other parameters define specific aspects (overriding any setting of BACKGROUND): CINTERIOR defines the colour of the interior of the plot (where the points are plotted), CFRAME defines the colour of the outer frame (outside the interior), and CTITLE is the colour of the title bar. The parameters can be set either to a text containing the name of one of Genstat’s pre-defined colours, or to a scalar containing a number defining a colour using the RGB system; see the PEN directive and the RGB function for details. Similarly, the BACKGROUND option can define the background colour for the whole frame (which may include areas outside any of the windows). The special colour setting 'match' can be used to apply the colour from the preceding parameter to the next one: CFRAME would inherit the colour from CINTERIOR , and CTITLE would inherit from from CFRAME . For example,
FRAME 1; CINTERIOR='white'; CFRAME='ivory'; CTITLE='match'
will specify colour white for the inside of the plot, and ivory to all the area outside this.
The PENTITLE and PENKEY options allow you to define the pens to be used to write the overall title and the key in each window; the initial default is to use pen -5 and -6 respectively. The TPOSITION parameter can be used to specify the position of the title in each window: either left-justified, right-justified or centred. The initial default is that it is centred.
The GRID option allows you to request grid lines to be drawn in particular directions and planes (for all the windows listed by the WINDOW parameter). For example the setting xy requests lines in the xy plane running from the x-axis (that is, parallel to the y-axis), and the setting yx requests lines in the xy plane running from the y-axis (that is, parallel to the x-axis); so you can set both of these to obtain box markings in the xy plane. The PENGRID parameter specifies the pen to be used for the grid lines in each window; the initial default is to use pen -4. You must use the RESET option if you want to restore these pen numbers to the initial defaults. (Genstat does not allow you to set negative pen numbers explicitly.) The BOX parameter allows you to put a box around the window in plots other than surface plots; the initial default is to include this. The box for a surface plot is controlled by the BOXSURFACE option, and can either be a full box enclosing the whole graph, or a bounded box enclosing just the surface; the initial default is that no box is drawn. The BOXKEY parameter can request that either a full or a bounded box be drawn around each key; the initial default is to omit the box. Finally, the BOXFRAME option controls whether or not a box is drawn around the entire frame; the initial default is to omit the box.
The SCALING parameter enables you to request that scaling of the x-, y- or z-axes should be equal in each window. For example, the xyequal setting ensures that the x- and y-axes are scaled identically, the setting xyzequal ensures that all the axes have the same scaling, and so on.
The AXES parameter allows you to specify the identifier of an oblique axis (defined by the AXIS directive) that should be included in a window. If you want to include several axes, you can specify a pointer containing the identifiers of the required axes.
The current FRAME settings for a particular window can be saved in a pointer supplied by the SAVE parameter. The elements of the pointer are labelled to identify the components.
Options: GRID, BOXFRAME, RESET.
Parameters: WINDOW, YLOWER, YUPPER, XLOWER, XUPPER, YMLOWER, YMUPPER, XMLOWER, XMUPPER, BACKGROUND, BOX, BOXSURFACE, BOXKEY, PENTITLE, PENKEY, PENGRID, TPOSITION, SCALING, CINTERIOR, CFRAME, CTITLE, AXES, SAVE.
See also
Directives: AXIS, XAXIS, YAXIS, ZAXIS.
Procedures: BANK, DHELP, FFRAME.
Commands for: Graphics.
Example
" Example FRAM-1: Drawing pictures in separate graphical windows
Demonstrates four graphical entities -
graph, contour, pie and histogram -
within a single picture
"
" Define the position of four windows in [0,1] coordinates"
FRAME 1; YLOWER=0.0; YUPPER=0.4; XLOWER=0.4; XUPPER=0.8
FRAME 2; YLOWER=0.4; YUPPER=0.8; XLOWER=0.0; XUPPER=0.4
FRAME 3; YLOWER=0.4; YUPPER=0.8; XLOWER=0.4; XUPPER=0.8
FRAME 4; YLOWER=0.0; YUPPER=0.4; XLOWER=0.0; XUPPER=0.4
" Draw some annotated lines with DGRAPH in window 1"
AXES 1; YLOWER=0; YUPPER=10; XLOWER=0; XUPPER=8
VARIATE Y[1...7]; !(1,2,3,7,9), !(1,2,3,5,8), !(1,2,3,5,7),\
!(1,2,3,5,6), !(1,2,6,5.5,5), !(1,2,7,5,4), !(1,2,8,4,3)
VARIATE X; !(1...5)
SCALAR [VALUE=7] N
VARIATE [NVALUES=N] XX,YY
TEXT [VALUES='G','E','N','S','T','A','T'] TXT
CALC NUM = NVAL(Y[1])
CALC XX$[1...N] = X$[NUM]+0.5
CALC YY$[1...N] = Y[1...N]$[NUM]
PEN 2; LINESTYLE=1; METHOD=monotonic; SYMBOL=0
PEN 3; SYMBOL=0; LABEL=TXT; METHOD=point
DGRAPH [TITLE='Graph';WINDOW=1;KEYWINDOW=0] Y[],YY; (X)7,XX; PEN=(2)7,3
" Draw a contour plot in window 2"
MATRIX [ROW=16; COLUMNS=18] M
OPEN '%gendir%/examples/DCON-1.DAT'; CHANNEL=data1; WIDTH=200
READ [CHANNEL=data1] M
CLOSE data1
DCONTOUR [TITLE='Contour'; WINDOW=2; KEYWINDOW=0; SCREEN=keep] M
" Draw a pie chart in window 3"
VARIATE [VALUES=1,1.1,1.2,1.3] Amount
PEN 1...4; BRUSH=12,13,9,8
" DPIE requires a series of numbers rathger than a variate,
so substitute the contents of the variate with the # symbol.
By default, DPIE will use pens 1...4 for the 4 sectors of the pie chart"
DPIE [TITLE='Pie Chart'; WINDOW=3; KEYWINDOW=0; SCREEN=keep] #Amount
" Draw a histogram in window 4"
FILEREAD [NAME='%gendir%/examples/DHIS-1.DAT'] X1,X2,X3,X4,X5
VARIATE FRED; !(1,2,4,8,16)
TEXT NAME; !T(A,BB,CCC,DDDD)
PEN 1...5; BRUSH=1,12,3,7,11
" By default, DHISTOGRAM will use pen 1 for the first variate,
pen 2 for the second, and so on."
DHISTOGRAM [WINDOW=4; KEYWINDOW=0; SCREEN=keep; TITLE='Histogram';\
LABELS=NAME] X1,X2,X3,X4,X5