PEN directive
Defines the properties of "pens" for high-resolution graphics.
Options
Parameters
Description
Graphical displays are drawn using graphical pens. Certain pens are used by default, or you can specify other pens, as described in the preceding sections. The attributes of each pen, such as colour, font and symbol-type, determine how they are used to generate output. The PEN directive can be used to change these attributes of the pens so that you can modify the resulting display. Different attributes are relevant for different types of output, for example symbols and labels are used only within DGRAPH.
The NUMBER parameter lists the numbers of the pens, in the range 1 to 256 or -1 to -12, that you wish to redefine. By default, any aspects of these pens that are not set explicitly retain the values that they had immediately before the PEN statement. Alternatively, you can specify option RESET=yes to reset their definitions to the default values defined by GenStat at the start of each job.
Pens 1 to 256 are used for the information that is plotted in a graph (points, lines, and so on). In most of the graphics commands, the default is to use these pens in succession for the different structures that are plotted, so that the various data sets can easily be distinguished. The negatively numbered pens are used as the initial defaults for the axes and their associated marks and labels (see XAXIS), and for gridlines, the overall title and the key (see FRAME), or for default gridlines in shade plots (see DSHADE), or for default outlines in histograms, bar charts and pie charts (see DHISTOGRAM, BARCHART and DPIE), or for error bars (see BARCHART), or for the overall title (see DSTART). They cannot be used for any other purposes.
The COLOUR, CSYMBOL, CLINE, CFILL and CAREA parameters specify the colours to be used by the pen. The COLOUR parameter can be used to define the colour for anything plotted by the pen, while the other parameters define specific aspects (overriding any setting of COLOUR): CSYMBOL defines the colour to be used for drawing symbols, CLINE defines the colour for lines, CFILL defines the colour for filling areas inside "hollow" symbols like circles, and CAREA defines the colour for filling areas inside polygons and bars of histograms. 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, or to a hexadecimal digit defined in a string of the form '#abc', '0xabc' or '0Xabc' where abc is the hexadecimal digit. You can use the RGB function to construct these colour numbers from their red, green and blue components: for example
CALCULATE xgold = RGB(255; 215; 0)
PEN 2; CSYMBOL=xgold
sets xgold to the colour gold (which has red, green and blue values 255, 215 and 0 respectively) and uses this as the colour for symbols drawn by pen 2. The numbers give you access to the complete spectrum supported by most colour graphics devices. (Note, though, that they will automatically be mapped onto a grey scale if the device is defined with a grey-scale palette; see DEVICE). Alternatively, the pre-defined colours define the standard colours used by many web browsers, and mainly use the same names. The names, and their corresponding red, green and blue values, are listed in Methods section. They can be given in either upper- or lower-case, or in any mixture, but they must not be abbreviated.
The SYMBOLS parameter determines what symbol is drawn at each point by DGRAPH. The numbers 1 to 22 provide a range of differently shaped symbols. You can also use any standard character to mark the points (for example you could set SYMBOLS='+' to use the plus character), or you can request device-specific symbols. If you do not want to plot symbols at the data points, for example when drawing a line through the points, you can set SYMBOLS=0. You can also set SYMBOLS to a pointer containing a pair of variates, to define your own symbol. The variates contain the coordinates of a set of points to be joined by straight line segments; these points should be within a notional square with bounds -1.0 to 1.0 in each direction. The square is centred on the data point and scaled to the same size as the standard symbols. Missing values can be included in the definition so that separate pen strokes are used draw line segments. You can mark different points with different symbols (for example to indicate groupings in the data) by setting the PEN parameter of DGRAPH to a variate or factor specifying a pen with the appropriate symbol for each point.
You can also label each point with a string or number. The LABELS parameter can be set to a text structure specifying the strings to be plotted at each point. You can specify a single string to be plotted at every point, otherwise the text must have the same number of values as the Y and X variates that are being plotted. LABELS can also be set to a factor; the factor labels are then used, if available, otherwise the levels. This provides another means of representing grouped data. The positioning of the labels with respect to the points is controlled by the YLPOSITION and XLPOSITION parameters. The initial default is to determine the positions automatically according to their type (e.g. labels for points, or for tick marks on the y-axis, or on the x-axis, and so on). The labels are plotted into text boxes whose widths in the x- and y-directions can be defined by the YLSIZE and XLSIZE parameters; if these are not set, the boxes are defined to plot the labels as a single line of characters. The amounts by which the boxes are offset in the the x- and y-directions can be defined by the YLOFFSET and XLOFFSET parameters; if these are not set, the positions of the boxes are defined automatically as appropriate for the positions defined by the YLPOSITION and XLPOSITION parameters. The BOXUNITS option defines what units to use when defining the sizes and positions of the text boxes. The initial default is to measure these in numbers of characters of an average width in the defined font and size (see parameters FONT and SMLABEL), but you can set option BOXUNITS=distance to use the distances as defined by the axes of the graph.
The graphical symbols are drawn so that they are centred at the specified position. If LABELS are specified they are aligned alongside the markers, unless you have set SYMBOLS=0 to suppress the markers, in which case the labels start from the specified (x,y) position. For compatibility with previous releases of GenStat you can also set SYMBOLS to a factor or text, which has the same effect as setting LABELS with SYMBOLS=0.
The GenStat Graphics Viewer with GenStat for Windows has a "Data Information" tool that allows you to display information about each point when you place the cursor over the point. If you want to replace the default information, you can set the DESCRIPTION parameter to a text (with one line for each point) containing your own information.
The METHOD parameter specifies the type of graph to be plotted: points, lines or filled polygons. The initial default for every pen, METHOD=point, will result in points being plotted using the corresponding symbols, labels, colours and fonts. Various types of line can be drawn through the plotted points; either straight lines (line) or smooth curves (monotonic, open, closed and spline). The monotonic setting specifies that a smooth single-valued curve is to be drawn through the data points. The name is derived from the requirement that the x-values (rather than the fitted curve) must be strictly monotonic, so that there is only one y-value for each distinct x-value. To ensure this, a copy of the data is made and sorted before the curve is fitted. This setting is recommended for plotting curves fitted to data, for example with FITCURVE. You should ensure that the points are close enough for the plotted line to be a reasonable approximation. When you know the functional form of the curve, it may be advantageous to calculate extra points. The open and closed settings specify that a smooth, possibly multi-valued, curve is to be drawn through the data points, using the method of McConalogue (1970); the resulting curve is rotationally invariant, although it is not invariant under scaling. The closed setting connects the last point to the first. McConalogue's method (open or closed) is more suited to the situation where the plotted curve is intended to represent the shape of an object. Alternatively, the spline setting plots a smoothing spline fitted through the points. The DFSPLINE parameter specifies how many degrees of freedom to use in the spline (initial default 4). The YMISSING parameter controls whether to break the spline at a missing y-value or to interpolate y-value, and the XMISSING parameter controls whether to break the spline at a missing x-value or to ignore the point; the initial default for both parameters is to break the spline. The setting METHOD=fill joins the data points by straight lines to produce one or more polygons. Each polygon is then shaded in the style specified by BRUSH (see below). The plotting method also determines how contours will be drawn. Also, the combination of SYMBOLS=0 and METHOD=point will produce no plotting at all (and no warning) within DGRAPH.
If the requested plotting method produces a line through the points, the LINESTYLE parameter will specify what sort of line is drawn (for example a solid, dotted or dashed line). The type of line style is denoted by a number in the range 1 up to 10. The exact appearance of the different line styles is device-specific, and there are not necessarily 10 different line styles available on a particular device, but line style 1 should always produce a solid line.
The JOIN parameter controls the order in which points are connected when lines are to be drawn or the points define a polygon to be shaded. Given requests that the data are to be plotted in the order in which they are stored, whereas ascending implies that the data are copied and sorted so that the x-values are in ascending order before plotting. This parameter is ignored when METHOD=monotonic, as this requires that the data must always be sorted.
The BRUSH parameter controls how areas are shaded when METHOD is set to fill, or when plotting histograms and pie charts. There are 16 available patterns indicated by the integers 1 to 16. In general, the higher the number, the denser the hatching, and the longer such areas take to plot. The device-specific brush styles are generally faster, and produce smaller output files; however results are not guaranteed to be the same on every type of device. The CFILL parameter defines which colour is used by the pen to fill the areas.
The THICKNESS parameter allows you to specify an amount by which the standard thickness of plotted lines is to be multiplied. This allows you to increase the thickness of lines, perhaps to highlight some feature of a plot. You can also use thickness to emphasize the axes, by redefining the appropriate pen. For some devices, it is not possible to control the thickness of plotted lines; the THICKNESS parameter is then ignored. Similarly, the BARTHICKNESS parameter can provide a multiplier for the line thickness when the pen is used to draw an error bar, and the BARCAPWIDTH parameter can give a multiplier to adjust the standard width of the lines at the top and bottom of error bars.
The default sizes of symbols and the characters in labels are determined from the dimensions of the current window. The SIZEMULTIPLIER parameter can be used to modify the sizes of both of these, by specifying a value by which this default size is to be multiplied. Alternatively, you can use the SMSYMBOL parameter to modify just the symbol size, or the SMLABEL parameter to modify just the size of characters in labels. For example when plotting a graph in a small window you may wish to increase the size of annotation in order to make it legible. They can each be set to a scalar, or to a variate to allow the different points to be scaled in different ways.
The ROTATION parameter controls the angle (in degrees) at which to plot text or user-defined symbols. The initial setting of zero will produce text "conventionally" orientated. You can set ROTATION to a scalar value that will apply to all points, or to a variate that allows a different angle to be used at each point.
In most implementations, including GenStat for Windows, the FONT parameter can be set to an integer between 1 and 25 to select different fonts for text appearing as titles, axis annotation, plotting symbols and key information. The initial default for each pen is font 1, which is the default font (set on the Fonts tab of the Options menu of the Graphics viewer). You can list the other fonts allocations using the DHELP procedure. If one of these is unavailable on your computer, the default font is used instead.
The current settings of each pen can be saved in a pointer supplied by the SAVE parameter. The elements of the pointer are labelled to identify the components. Initial default settings are represented by missing values; the actual values used for these attributes when plotting will depend on the output device.
The standard text fonts, graphical symbols and brush styles are software generated. However, you can set negative values for these parameters of the PEN directive to select device-specific alternatives. For each parameter, the device-specific settings have the same range as the standard settings; thus you can select symbols -1 to -9, fonts -1 to -25, and brush styles -1 to -16. If fewer device-specific settings are actually available, the settings are taken in turn, and then recycled. Where a feature has no device-specific settings on a particular device, the standard form is used instead (for example, font -3 appearing as font 3). Device-specific font numbers cannot be used within the in-line typesetting system; GenStat will use either the standard fonts or the corresponding device-specific fonts depending on the base font originally specified by the PEN directive. In some cases, device-specific symbols or fonts may be of fixed size; the SIZE parameter will then have no effect, and some of the typesetting commands may not function correctly. Although the device-specific settings are likely to be different from device to device, they are arranged to be consistent where possible, so that for example brush style -1 will select solid fill, if available.
By default, GenStat uses software generated symbols and fonts. You can discover the initial defaults for the colours using the GETRGB procedure. On a grey-scale device, the colours are mapped automatically to shades of grey, while on a monochrome device all colours except white are plotted as black. By default, on colour and grey-scale devices, symbol 1 is used for all pens. On monochrome displays, the default is to use symbols 1 to 22 in turn: symbol 1 for pen 1, symbol 2 for pen 2, and so on. When solid fill and colour (or grey-scale) are available, the default brush style is -1, in different colours for each pen. Otherwise, by default, the pens use different software-generated brushes.
Options: RESET, BOXUNITS.
Parameters: NUMBER, COLOUR, LINESTYLE, METHOD, SYMBOLS, LABELS, ROTATION, JOIN, BRUSH, FONT, THICKNESS, SIZE, CSYMBOL, CLINE, CFILL, CAREA, SMSYMBOL, SMLABEL, DFSPLINE, YMISSING, XMISSING, YLPOSITION, XLPOSITION, YLSIZE, XLSIZE, YLOFFSET, XLOFFSET, BARTHICKNESS, BARCAPWIDTH, DESCRIPTION, SAVE.
Method
The names of the standard pre-defined colours are listed below with their corresponding red, green and blue values for use e.g. in the RGB function.
Red colors
Pink colors
Orange colors
Yellow colors
Purple colors
Green colors
Blue colors
Brown colors
White colors
Grey colors
In addition, the string Background can be used to refer to the background colour that has been defined (e.g. by FRAME) for the particular part of the screen where the pen is being used, and the string Transparent can be used for example to define a colour that will not obscure anything that is plotted below it (e.g. in another window). Alternatively, you can define the colour intensity by three hexadecimal digits (0-F), by using a string starting containing first the character #, and then containing the three digits.
Reference
McConalogue, D.J. (1970). A quasi-intrinsic scheme for passing a smooth curve through a discrete set of points. Computer Journal, 13, 392-396.
See also