Forms multiple windows in a plot-matrix for high-resolution graphics (P.W. Goedhart).
Options
PRINT = string tokens |
Whether to display the layout and numbering of the plot-matrix in a table or in a high-resolution test-graph on the current device (table, testgraph); default * |
|---|---|
ARRANGEMENT = string token |
Type of plot-matrix (rectangle, square, lowersymmetric, uppersymmetric, diagonal); default rectangle |
ROWS = scalar |
Number of rows of plot-matrix; default 3 |
COLUMNS = scalar |
Number of columns of plot-matrix; default 3 |
DIAGONALWINDOWS = string token |
Whether to include or exclude the diagonal in symmetric plot-matrices (include, exclude); default include |
SQUARESHAPES = string token |
Whether to force the individual windows, excluding margins for annotation, to be square (yes, no); default no |
STARTWINDOW = scalar |
Specifies the number of the first window; default 1 |
TESTGRAPH = variate |
Specifies windows to be displayed in a test-graph (if this option is set, only a test-graph is produced and all other settings are ignored); default * |
NUMBERING = string token |
Controls the way in which the individual windows are numbered (rowwise, columnwise); default rowwise |
DEFINE = string token |
Whether to define the windows within the procedure (windows, nothing); default wind |
CLEARWINDOW = scalar or variate |
Defines the windows for which the screen should be cleared; i.e. specifies the elements of the SCREEN pointer which are set to the single-values text ‘clear’, other element of SCREEN are set to ‘keep’; default 1 |
RLOWER = scalar |
Lowest y device coordinate; default 0 |
RUPPER = scalar |
Highest y device coordinate; default 1 |
CLOWER = scalar |
Lowest x device coordinate; default 0 |
CUPPER = scalar |
Highest x device coordinate; default 1 |
RSKIP = scalar |
Space between windows along the y-axis; default 0 |
CSKIP = scalar |
Space between windows along the x-axis; default 0 |
MARGIN = string tokens |
Sets the size of the margins for labels and titles (xtitle, ytitle, none, small); default * |
YMLOWER = scalar |
Size of bottom margin (x-axis labelling) in each window; default * |
YMUPPER = scalar |
Size of upper margin (overall title) in each window; default * |
XMLOWER = scalar |
Size of left-hand margin (y-axis labelling) in each window; default * |
XMUPPER = scalar |
Size of right-hand margin in each window; default * |
RMLOWER = scalar |
Additional size of bottom margin (x-axis labelling) in windows at the bottom of the plot-matrix; default 0 |
RMUPPER = scalar |
Additional size of upper margin (overall title) in windows at the top of the plot-matrix; default 0 |
CMLOWER = scalar |
Additional size of left-hand margin (y-axis labelling) windows at the left of the plot-matrix; default 0 |
CMUPPER = scalar |
Additional size of right-hand margin in windows at the right of the plot-matrix; default 0 |
BACKGROUND = text or scalar |
Specifies the colour to be used for the background in each window (where allowed by the graphics device); default 'background' |
Parameters
NGRAPHS = scalar |
To save the number of windows in the plot-matrix |
|---|---|
SWINDOW = pointer |
Pointer to save scalars with window numbers |
SYLOWER = pointer |
Pointer to save scalars with lower y device coordinates for each window |
SYUPPER = pointer |
Pointer to save scalars with upper y device coordinates for each window |
SXLOWER = pointer |
Pointer to save scalars with lower x device coordinates for each window |
SXUPPER = pointer |
Pointer to save scalars with upper x device coordinates for each window |
SSCREEN = pointer |
Pointer to save single-valued texts with value 'clear' or 'keep'; this depends only on the setting of the CLEARWINDOW option |
SMYLOWER = pointer |
Pointer to save scalars with size of bottom margins for each window |
SMYUPPER = pointer |
Pointer to save scalars with size of upper margins for each window |
SMXLOWER = pointer |
Pointer to save scalars with size of left-hand margin for each window |
SMXUPPER = pointer |
Pointer to save scalars with size of right-hand margin for each window |
Description
Procedure FFRAME supplements the FRAME directive with automatic definition of windows in a so-called plot-matrix. The ARRANGEMENT option defines the arrangement of the plot-matrix which can be in either a rectangle, square, lowersymmetric, uppersymmetric or diagonal. The number of rows and columns of the plot-matrix can be specified by options ROWS and COLUMNS. The COLUMNS option is only relevant when ARRANGEMENT=rectangle. The DIAGONALWINDOWS option defines whether or not the diagonal windows should be included for symmetric plot-matrices. The option setting SQUARESHAPES=yes forces each window, excluding margins for annotation, to be square.
By default the positions of the windows in the plot-matrix are defined within the procedure by means of a FRAME statement using windows 1, 2 … Alternatively, you can use the STARTWINDOW option to start the window numbering at a different value. The windows are numbered by rows unless the NUMBERING option is set to columnwise. When the number of windows is larger than the maximum allowable number, the windows are not defined and a warning message is printed. In that case the parameters SYLOWER, SYUPPER, SXLOWER and SXUPPER can be used to save the y and x device coordinates of the windows for subsequent use in a FRAME statement. Likewise parameters SMYLOWER, SMYUPPER, SMXLOWER and SMXUPPER can be used to save the margins for each plot. Also, setting DEFINE=nothing does not define the windows. The NGRAPHS parameter saves the number of windows in the plot-matrix, and the SWINDOW parameter saves the window numbers.
Typically the screen should be cleared only for the first window in a plot-matrix. The SSCREEN parameter can be used to save the single-valued text 'clear' for the first window and 'keep' for all other windows. These texts can then be used to set the SCREEN option of the plot directives as is shown in the example. The CLEARWINDOW option can be employed in case the screen should be cleared for other windows.
By default the unit plot-square [0,1] x [0,1] is employed. Options RLOWER, RUPPER, CLOWER and CUPPER can be used to define a different plot-square. The RSKIP and CSKIP options can be used to increase the space between windows which is by default 0. The user must ensure that these options are set to sensible values.
The space used for labelling of axis and an overall title for each window can be controlled with options MARGIN, YMLOWER, YMUPPER, XMLOWER and XMUPPER options. Default values of these options ensure that an overall title and labels (not longer than 4 characters) along both axes are displayed when using the standard character size. However, the default values normally prohibit the display of titles along the axes. The settings xtitle and/or ytitle of the MARGIN option generate space for titles along the axes. The MARGIN option can have the following settings:
MARGIN=* |
YMLOW,YMUP,XMLOW,XMUP = 0.04, 0.04, 0.05, 0.01 |
|---|---|
MARGIN=xtit |
YMLOW,YMUP,XMLOW,XMUP = 0.09, 0.04, 0.05, 0.01 |
MARGIN=ytit |
YMLOW,YMUP,XMLOW,XMUP = 0.04, 0.04, 0.10, 0.01 |
MARGIN=xtit,ytit |
YMLOW,YMUP,XMLOW,XMUP = 0.09, 0.04, 0.10, 0.01 |
MARGIN=none |
YMLOW,YMUP,XMLOW,XMUP = 0 |
MARGIN=small |
YMLOW,YMUP,XMLOW,XMUP = 0.015 |
These values can be overridden by setting options YMLOWER, YMUPPER, XMLOWER, XMUPPER explicitly. The outer margins of the border plots in the plot-matrix
can be increased by specifying options RMLOWER, CMLOWER, RMUPPER and RMLOWER. For example, you could expand these, as needed for a trellis-style plot, by
FFRAME [ROWS=nwrows; COLUMNS=nwcols; MARGIN=none;\
CMLOWER=0.04; YMLOWER=0.09; RMUPPER=0.04]
The background colour for all windows may be modified by the BACKGROUND option.
The PRINT option can be used to display the layout and numbering of the plot-matrix in a table or in a high-resolution test-graph on the current device. A test-graph can also be requested by setting the TESTGRAPH option to a variate with the window numbers to be displayed; all other settings are then ignored.
Options: PRINT, ARRANGEMENT, ROWS, COLUMNS, DIAGONALWINDOWS, SQUARESHAPES, STARTWINDOW, TESTGRAPH, NUMBERING, DEFINE, CLEARWINDOW, RLOWER, RUPPER, CLOWER, CUPPER, RSKIP, CSKIP, MARGIN, YMLOWER, YMUPPER, XMLOWER, XMUPPER, RMLOWER, RMUPPER, CMLOWER, MUPPER, BACKGROUND.
Parameters: NGRAPHS, SWINDOW, SYLOWER, SYUPPER, SXLOWER, SXUPPER, SSCREEN SMYLOWER, SMYUPPER, SMXLOWER, SMXUPPER.
Method
The relevant part of the calculations for the lower and upper x device coordinates are
CALCULATE xrange = (CUPPER - CLOWER + CSKIP)/COLUMNS - CSKIP
CALCULATE XLOWER = CLOWER + (!(1...#COLUMNS) - 1)\
* (xrange + CSKIP)
CALCULATE XUPPER = XLOWER + xrange
The y device coordinates are calculated similarly.
Action with RESTRICT
Restrictions on CLEARWINDOW and TESTGRAPH are ignored.
See also
Directive: FRAME.
Commands for: Graphics.
Example
CAPTION 'FFRAME example',\
!t('Use the PRINT option to print the layout and numbering of',\
'the plot-matrix in a table and to display a test-graph on the',\
'current device.'); STYLE=meta,plain
FFRAME [PRINT=table,testgraph; ARRANGEMENT=rectangle; ROWS=3; COLUMNS=6;\
SQUARESHAPES=yes; RLOWER=0.1; RSKIP=0.1]
CAPTION !t('Examples of a spatial Poisson process. The screen must be',\
'cleared before displaying the first graph.')
FFRAME [ROWS=4; SQUARESHAPES=yes] NGRAPHS=ngraphs; SSCREEN=screen
XAXIS 1...#ngraphs; LOWER=0; UPPER=1; MARKS=!(10)
YAXIS 1...#ngraphs; LOWER=0; UPPER=1; MARKS=!(10)
PEN NUMBER=1; METHOD=point; SYMBOLS=2; SIZE=0.3
CALCULATE initialize = URAND(8412825; 1)
FOR [NTIMES=ngraphs; INDEX=ii]
CALCULATE yrandom, xrandom = URAND(0,0; 50)
DGRAPH [WINDOW=ii; KEYWINDOW=0; SCREEN=#screen[ii]] yrandom; xrandom
ENDFOR
CAPTION !t('Definition of multiple frames and display in a test-graph')
FFRAME [ROWS=1 ; COLUMNS=2 ; STARTWINDOW=1 ; RUPPER=1.0 ; RLOWER=0.8]
FFRAME [ROWS=3 ; COLUMNS=4 ; STARTWINDOW=3 ; RUPPER=0.8 ; RLOWER=0.2]
FFRAME [ROWS=1 ; COLUMNS=1 ; STARTWINDOW=15 ; RUPPER=0.2 ; RLOWER=0.0]
FFRAME [TESTGRAPH=!(1...15)]