Adds a key to a graph (D.B. Baird & V.M. Cave).
Options
WINDOW = scalar |
Window in which to draw the key; default 2 |
|---|---|
NCOLUMNS = scalar |
Number of columns forming the grid in which the key is displayed; default * (i.e. set automatically) |
NROWS = scalar |
Number of rows forming the grid in which the key is displayed; default * (i.e. set automatically) |
TITLE = text |
Title for the key |
PENTITLE = scalar |
Pen used to write the title of the key; default is that set for the window in which the key is plotted |
PENLABELS = variate |
Pens to use to plot the labels; default is to plot the labels using the settings of LFONT, LSIZE and LCOLOUR |
TPOSITION = string |
Position of the title (inside, outside, left, centre, center, right); default cent, outs |
ORDER = string |
Order in which to fill the key’s row by column grid (rows, columns); default rows |
LSIZE = scalar |
Relative size of the labels; default 1 |
LFONT = scalar or text |
Font to use for the labels; default 1 |
LCOLOUR = scalar or text |
Colour used to write the labels; default 'black' |
XLOFFSET = scalar or variate |
Offset in the x-direction between the items (i.e. symbols/lines) and labels in the key; default 0 |
COLSPACING = string |
Column spacing (equal, unequal); default equa |
ROWGAP = scalar |
Multiplier for gaps between rows; default 1 |
COLGAP = scalar |
Multiplier for gaps between columns; default 1 |
BORDER = string |
Border around the key (fit, given, none); default fit |
CBORDER = string |
Colour for the border around the key; default 'black' |
Parameters
DESCRIPTIONS = texts |
Labels for the key |
|---|---|
PEN = variates |
Pens to use for the items in the key; default uses the integers 1, 2 … |
METHOD = texts |
Method for plotting the items in the key (fill, point, line, both, none); default is to use the method defined for the corresponding PEN |
SYMBOL = variates, scalars, factors or texts |
Symbols to be drawn in the key; default is to use those specified by PEN |
COLOUR = variates, scalars, factors or texts |
Colours of lines, or of filled areas when METHOD='fill'; default is to use those specified by PEN |
CSYMBOL = variates, scalars, factors or texts |
Colours of symbols; default is to use those specified by PEN |
CFILL = variates, scalars, factors or texts |
Colours used to fill hollow symbols; default is to use those specified by PEN |
SIZEMULTIPLIER = variates, scalars or factors |
Relative sizes of symbols and filled area; default is to use those specified by PEN |
LINESTYLE = variates, scalars or factors |
Numbers or names of the linestyles to use; default is to use those specified by PEN |
THICKNESS = variates, scalars or factors |
Thicknesses of the lines; default is to use those specified by PEN |
TRANSPARENCY = variates, scalars or factors |
Transparencies of the filled areas when METHOD='fill'; default is to use those specified by PEN |
Description
The DKEY procedure provides a more flexible way of providing a key for a plot, than the standard facilities provided by the ordinary plotting commands. The standard keys can be suppressed by setting the option KEYWINDOW in those commands to zero.
The labels to appear in the key must be supplied as a text structure by the DESCRIPTIONS parameter. The number of labels defines the number of items n to appear in the key. The appearance of the labels (size, font and colour) can be controlled either by the PENLABELS option by or the LSIZE, LFONT and LCOLOUR options. PENLABELS can supply a variate, with n values, to define the pens to use for the labels.
If PENLABELS is not set, the labels are all written in the same style, using the settings of the LSIZE, LFONT and LCOLOUR options. The LSIZE option modifies the size of the labels, by specifying a value by which the default size is to be multiplied; default 1. The LFONT option specifies the font to use for the labels. This can be set either to a text containing the name of a font family, or to a scalar containing an integer between 1 and 25. The default is to use the default graphics font (i.e. the default font set on the Fonts tab of the Options menu in the Graphics Viewer). The LCOLOUR option specifies the colour for the labels. This 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. The default is 'black'.
The METHOD parameter supplies a text defining the types of item to be plotted in the key. The text can contain a single string if all the items are to be displayed in the same way, or a string for each item if they are to be displayed differently. The possible strings are
'point' |
for points, |
|---|---|
'line' |
for lines, |
'both' |
for points and lines, |
'fill' |
for filled rectangles, and |
'none' |
to prevent an item from being plotted. |
The default is to use the method defined for the corresponding PEN.
The appearance of the items (symbol type, colour, size, linestyle, line thickness and transparency) can be controlled by specifying the pens to be used to plot them by the PEN parameter. The default is to use pens 1 … n.
Alternatively, you can set the appearance of the items explicitly, by using the parameters SYMBOL, COLOUR, CSYMBOL, CFILL, SIZEMULTIPLIER, LINESTYLE, THICKNESS and TRANSPARENCY. (These override the settings from PEN.) For each of these parameters, you can supply either a single value or a structure with n values (one for each item).
The SYMBOL parameter defines the symbols for items that are displayed as points (or as both points and lines). It can be set either to a text containing names of Genstat’s pre-defined symbols (see PEN for details), or to a scalar or variate containing integers between -4 and 22, or to factor with at most 22 levels.
The COLOUR, CSYMBOL and CFILL parameters specify the colours to be used for the items. The COLOUR parameter defines the colours of lines and filled areas. The CSYMBOL parameter defines the colours used for symbols. The CFILL parameter defines the colours used for filling areas inside hollow symbols. They can be set either to a text containing the name of one of Genstat’s pre-defined colours (see PEN for details), or to a scalar or variate containing numbers defining colours using the RGB system, or to a factor. The transparency of a filled area can be set using the TRANSPARENCY parameter. This can be set either to a scalar or variate containing values between 0 (opaque) and 255 (completely transparent), or to factor with at most 255 levels.
The SIZEMULTIPLIER parameter can modify the size of symbols and filled areas, by specifying a value by which the default size is to be multiplied. Either a scalar, variate or factor can be supplied. The LINESTYLE parameter defines what sort of line is drawn (for example a solid, dotted or dashed line). This can be set either to a text containing the names of Genstat’s pre-defined linestyles (see PEN for details), or to a scalar or variate containing integers between 1 and 11, or to factor with at most 11 levels. The THICKNESS parameter can modify the thickness of lines, by specifying a value by which the standard thickness is to be multiplied. Either a scalar, variate or factor may be supplied.
The WINDOW, NCOLUMNS, NROWS, ORDER, XLOFFSET, COLSPACING, ROWGAP, COLGAP, BORDER and CBORDER options control the layout of the key. The WINDOW option specifies the window in which the key is drawn; default 2. The number of rows and columns, forming the grid in which the key is arranged, can be set by the NROWS and NCOLUMNS options, respectively. If these are not set, an appropriate grid is constructed automatically. The order in which the items fill the grid is determined by the ORDER option. The default, ORDER=rows, fills the grid row by row. Alternatively ORDER=columns fills the grid column by column. The COLSPACING option specifies whether or not the columns of the grid are equally spaced (equal and unequal, respectively); default equal. The ROWGAP and COLGAP options control the sizes of the gaps between rows and columns, respectively. The distance between the items and labels can be adjusted by the XLOFFSET option. Each label in the grid can be individually offset by suppling a variate with n values. When a single value is supplied, a common offset is applied to all labels in the grid. The BORDER option controls the border drawn around the key. The default, BORDER=fit, draws a border fitted to the key. When BORDER=given, the border frames the window (and the key is drawn so that it occupies the entire window). Finally, if BORDER=none, no border is drawn. The CBORDER option specifies the colour for the border, when one is drawn around the key; default 'black'.
The TITLE option can provide a title for the key. The pen for the title can be set by the PENTITLE option. The default is to use the pen defined for the window in which the key is plotted. The TPOSITION parameter specifies the position of the title: either inside or outside the border with left, right or centre justification. The default is to centre the title outside the border of the key.
Options: WINDOW, NCOLUMNS, NROWS, TITLE, PENTITLE, PENLABELS, TPOSITION, ORDER, LSIZE, LFONT, LCOLOUR, XLOFFSET, COLSPACING, ROWGAP, COLGAP, BORDER, CBORDER.
Parameters: DESCRIPTIONS, PEN, METHOD, SYMBOL, COLOUR, CSYMBOL, CFILL, SIZEMULTIPLIER, LINESTYLE, THICKNESS, TRANSPARENCY.
Action with RESTRICT
DKEY takes account of restrictions on DESCRIPTIONS, PEN, PENLABELS and XLOFFSET. However, the parameters METHOD, SYMBOL, COLOUR, CSYMBOL, CFILL, SIZEMULTIPLIER, LINESTYLE, THICKNESS and TRANSPARENCY must not be restricted.
See also
Directive: PEN
Procedures: DTEXT, DFRTEXT.
Commands for: Graphics.
Example
CAPTION 'DKEY examples'; STYLE=meta
SPLOAD [PRINT=*] '%GENDIR%/Data/Iris.gsh'
XAXIS [RESET=yes] WINDOW=1; Title='Sepal Width (mm)'
YAXIS [RESET=yes] WINDOW=1; Title='Sepal Length (mm)'
PEN [RESET=yes] 1...6; COLOUR=('red','blue','darkgreen')2;\
SYMBOL=(1,2,3)2; SIZE=3(1,1.2)
DGRAPH [KEYWINDOW=0] Y=Sepal_Length; X=Sepal_Width; PEN=Species
"Define a key using factor labels"
GETATTRIBUTE [ATTRIBUTE=labels] Species; SAVE=SpeciesLabels
DKEY [NCOLUMNS=1; TITLE='Iris species'; TPOSITION=left,inside]\
PEN=!(4...6); DESCRIPTIONS=#SpeciesLabels
"Plot key in a bespoke window"
FRAME WINDOW=6; XLOWER=0.72
DGRAPH [KEYWINDOW=0] Y=Sepal_Length; X=Sepal_Width; PEN=Species
DKEY [WINDOW=6; NCOLUMNS=1; BORDER=none; LSIZE=1.2] PEN=!(4...6);\
DESCRIPTIONS=#SpeciesLabels
"Use coloured labels to define the key"
PEN 1...6; SYMBOL='circle'; CFILL=('red','blue','darkgreen')2
DGRAPH [KEYWINDOW=0] Y=Sepal_Length; X=Sepal_Width; PEN=Species
DKEY [WINDOW=6; NCOLUMNS=1; PENLABELS=!(4...6); BORDER=none; XLOFFSET=-6]\
!T('~i{Iris setosa}','~i{Iris versicolour}','~i{Iris virginica}');\
METHOD='none'
PEN [RESET=yes] 1...6
FRAME [RESET=yes] WINDOW=6