PEN directive

Defines the properties of "pens" for high-resolution graphics.

Option

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 -10, 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 (see DHISTOGRAM) and pie charts (see DPIE). They cannot be used for any other purposes.

   The COLOUR, CSYMBOL, CLINE and CFILL parameters specify the colours to be used by the pen. COLOUR can be used to define the colour for anything plotted by the pen, while the other parameters define specific aspects (overiding any setting of COLOUR): CSYMBOL defines the colour to be used for drawing symbols, CLINE defines the colour for lines, and CFILL the colour for filling areas. The colour is an integer in the range 0 to 256. If fewer colours are available on the graphics device the colours are used in turn, and then recycled. Where possible, colour 0 is interpreted as the background colour, thus allowing points to be easily erased from a plot. The association of colour numbers with actual colours depends on the particular device. Using a colour graphics screen, the colours should be as defined by the COLOUR directive. However, for many plotters, the colour number relates only to the physical position in which the pen is mounted in the plotter, so the actual colours may vary between devices.

   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 is 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 specified as a factor; the factor labels are then used, if available, otherwise the levels. This provides another means of representing grouped data.

   The graphical symbols are drawn so that they are centred at the specified position. If LABELS are specified they are aligned to the left of the markers, unless you have set SYMBOLS=0 to suppress the markers, in which case the labels are drawn so that the bottom left point of the first character is at 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 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 option then specifies how many degrees of freedom to use in the spline (default 4). 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 FILLCOLOUR 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.

   The default size of characters and symbols is determined from the dimensions of the current window. The SIZE parameter can be used to modify the size, by specifying a value by which this default size is to be multiplied. 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. SIZE can 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 (6.8). If one of these is unavailable on your computer, the default font is used instead. The FONT parameter also works with the old-style (Version 4.1) graphics system, with the following allocations:

Some of the symbols produced by fonts 7, 8, 17 and 19 are of non-standard size. Device-specific fonts can also be used where available.

   The 4.1 graphics system does not support the standard GenStat typesetting commands (see PRINT), but has its own syntax of in-line commands. These allow you to change font or character size part-way through plotting text, when supplied for either a title or a label. You can also insert Greek characters in an equation, and use subscripts, superscripts and mathematical symbols. The escape character '!' is used to signal a change of font or character size, and must be followed immediately by a code indicating the required action. For a simple change of font the code is just the new font number, for example '!07' will switch to the mathematical symbols font. For fonts 1 up to 9 the leading zero may be omitted, so that '!7' may be used instead, but you should be careful of ambiguities; for example '!021' will plot the character '1' in font 2, whereas '!21' will just switch to font 21. The mnemonics 'G' for (Simplex) Greek, 'M' for mathematical and 'W' for simplex script can be used as well as the font numbers. The additional codes below specify other in-line commands.

In-line commands can be specified in upper or lower-case. To print the escape character, !, it should be entered twice; for example the string 'Outlier!!' could be used to label a point. If an invalid sequence of characters is specified the remainder of the string will not be plotted and a warning will be printed.

   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. For colour displays, by default symbol 1 is used for all pens but in different colours. On monochrome displays, the pens all use colour 1 and symbols 1 to 22 are used in turn: symbol 1 for pen 1, symbol 2 for pen 2, and so on. When solid fill and colour are available, the default brush style is -1, in different colours for each pen; otherwise software-generated brushes are used by default.

Option: RESET.

Parameters: NUMBER, COLOUR, LINESTYLE, METHOD, SYMBOLS, LABELS, ROTATION, JOIN, BRUSH, FONT, THICKNESS, SIZE, CSYMBOL, CLINE, CFILL, SAVE.

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.