7 Plotting Styles and Attributes

7.1 Plotting Styles and Attributes

Many different aspects of the appearance of line graphics produced by Kappa applications can be controlled by specifying a plotting style when running the application. This includes things like the colour, line width, line style, character size, and fount, each of which can be specified individually for different components of a plot (e.g. the tick marks, numerical labels, border, textual labels, etc.).

Each aspect of a plot is controlled by a plotting attribute. A plotting attribute has a name and a value.

Strings that assign new values to particular plotting attributes are called attribute setting strings. For instance:

Border=1
Title=This is my plot title

are two attribute setting strings. The first assigns the value 1 to the attribute called Border, and the second assigns the string "This is my plot title" to the attribute with name Title (attribute names are case insensitive but cannot be abbreviated).

Here is a list of the available attributes, with a brief description of each. Full descriptions are included in Appendix E.

 Border Draw a border around valid regions of a plot? Colour for a plot element Draw axes? Annotate both sidebands in a dual sideband spectrum? Draw a title? Which edges to label Include the NDF name as a second line in the title? Character fount for a plot element Interval between major axis values Draw grid lines? Where to place numerical labels Include unit descriptions in axis labels? Draw numerical axis labels upright? Label and tick placement option Length of major tick marks Length of minor tick marks Density of minor tick marks Draw numerical axis labels? Spacing of numerical axis labels Character size for a plot element Line style for a plot element Background colour to use when drawing text Draw descriptive axis labels? Spacing of descriptive axis labels Width of margin to clear when drawing text Draw tick marks on all edges? Vertical spacing for the title Plotting tolerance Line width for a plot element

Some attribute names can be qualified so that they refer to a particular component of the plot. This is done by putting the qualifier in parentheses after the attribute name. For instance:

Colour(border)=2
Edge(2)=left

assigns the value 2 to the Colour attribute for the plot border, and assigns the value left to the Edge attribute for the second axis. The full description of each attribute describes what happens if you omit the qualifier. Attribute names that end in "(axis)" in the above list can be qualified by an integer axis index to refer to a particular plot axis. Attribute names that end in "(element)" in the above list can be qualified by any of the following strings to refer to a particular component of the plot (the qualifiers are case-insensitive and unambiguous abbreviations may be used):

 Axes Axis lines drawn through tick marks within the plotting area, drawn if attribute DrawAxes is given a non-zero value. Values set using Axes are only only used if axis-specific values have not been set using Axis1 or Axis2. Thus, Axes provides default values for Axis1 and Axis2. An axis line drawn through tick marks on Axis 1 within the plotting area, drawn if attribute DrawAxes is given a non-zero value. Values specified using Axis1 override any supplied using Axes. An axis line drawn through tick marks on Axis 2 within the plotting area, drawn if attribute DrawAxes is given a non-zero value. Values specified using Axis2 override any supplied using Axes. The plot border, drawn if attribute Border is given a non-zero value. Curves drawn over the top of a plot (e.g. contours, data curves). The grid lines, drawn if attribute Grid is given a non-zero value. Values set using Grid are only only used if axis-specific values have not been set using Grid1 or Grid2. Thus, Grid provides default values for Grid1 and Grid2. Grid lines that cross Axis 1, drawn if attribute Grid is given a non-zero value. Values specified using Grid1 override any supplied using Grid. Grid lines that cross Axis 2, drawn if attribute Grid is given a non-zero value. Values specified using Grid2 override any supplied using Grid. Graphical markers (symbols) drawn over a plot. Numerical axis labels drawn around annotated axes. Values set using NumLab are only only used if axis-specific values have not been set using NumLab1 or NumLab2. Thus, NumLab provides default values for NumLab1 and NumLab2. Numerical labels drawn along Axis 1. Values specified using NumLab1 override any supplied using NumLab. Numerical labels drawn along Axis 2. Values specified usingNumLab2 override any supplied using NumLab. Text strings drawn over a plot (except for axis labels and plot title). Descriptive axis labels drawn around annotated axes. Values set using TextLab are only only used if axis-specific values have not been set using TextLab1 or TextLab2. Thus, TextLab provides default values for TextLab1 and TextLab2. Descriptive label for Axis 1. Values specified using TextLab1 override any supplied using TextLab. Descriptive label for Axis 2. Values specified using TextLab2 override any supplied using TextLab. Tick marks (both major and minor) drawn along annotated axes. Values set using Ticks are only only used if axis-specific values have not been set using Ticks1 or Ticks2. Thus, Ticks provides default values for Ticks1 and Ticks2. Tick marks (both major and minor) drawn along Axis 1. Values specified using Ticks1 override any supplied using Ticks. Tick marks (both major and minor) drawn along Axis 2. Values specified using Ticks2 override any supplied using Ticks. The title drawn at the top of a plot.

A collection of attribute settings is called a plotting style. Attributes that are not specified in a plotting style take on default values as described later. An example of a plotting style is contained in the file $KAPPA_DIR/kappa_style.def. This file defines the default style used by Kappa. In general each graphical application will determine the plotting style to be used when drawing line graphics by accessing a parameter called STYLE. Some applications have more than one style parameter. For instance, applications such as CONTOUR and LINPLOT that produce keys to the content of the plot have a parameter called KEYSTYLE, in addition to the normal STYLE parameter. KEYSTYLE is used to specify the plotting style for the key, whereas STYLE is used to specify the plotting style for the main plot. 7.2 Specifying a Plotting Style 7.2.1 Group Expressions The application parameters that are used to access plotting styles (STYLE, KEYSTYLE, etc.) expect a group of attribute setting strings to be supplied for the parameter. These should be supplied in the form of a group expression.5 A group expression is a character string containing a list of one or more sub-strings separated by some specified delimiter. The usual delimiter used when accessing plotting style parameters is a comma (although other parameters that require group expressions for other purposes may use a different delimiter). Each sub-string is known as a group element. Each group element must be either: • an attribute setting string (e.g. "Border=1"), or • the name of a text file, preceded by an up-arrow character ("^"”). If a group element starts with an up-arrow character, then the rest of the element is interpreted as a file name, and an attempt is made to read further group elements from the specified file. Each line in the file is interpreted as a group expression in its own right, using exactly the same rules as described above. In particular, references to text files can be nested (i.e. a text file can include a group element that refers to another text file). Blank lines and lines in which the first non-blank character is a hash ("#") are ignored and can be used to add textual comments to a text file. Attribute settings are used in the order in which they occur in the group expression. If a group expression includes more than one setting string for a given attribute, then the value that occurs nearest to the end of the group expression will overwrite any earlier values. All this means that there are several ways in which plotting styles can be supplied. The simplest method is probably to store all your attribute setting strings in a text file, one per line, and then just give the name of this text file (preceded by an up-arrow) as the value for the STYLE parameter. For instance, the file style.dat may contain: # A test plotting style width=2 edge(2)=right title=This is my title The first line and the following blank line are ignored. The remaining three lines specify three attribute values to use. When running an application such as DISPLAY, this style file would be specified on the command line as follows: % display style=^style.dat Alternatively, you can specify the setting strings explicitly on the command line. This can get a bit messy because you need to protect special characters (commas, parentheses, spaces, equals signs, and so on) both from the UNIX shell and from the parameter system. One safe way to do this is to enclose the whole group expression in single quotes, and then enclose the whole thing again in double quotes.6 So the above style could be given on the command line as follows: % display style="’width=2,edge(2)=right,title=This is my title’" A bit messy as I said! However, it can be useful to combine this method with the previous method. If you have a long, complicated style file, and you want to change one or two attribute settings, one method would be to take a copy of the style file and edit it. This would probably be the best thing to do if you intend to re-use the edited style file several times. But if you just want to try a quick experiment, just to see what the results look like, you can avoid the trouble of editing the style file by giving both the original style file and the new attribute settings on the command line. For instance: % display style="’^style.dat,width=3’" This reads the contents of our test style file style.dat, which includes the attribute setting width=2. It then also applies the attribute setting width=3, over-writing the effect of the Width value included in the style file. If you wanted to try temporarily changing the value of several attributes at once, you could put the new attribute settings into a second file, say style2.dat, and then run the application as follows: % display style="’^style.dat,^style2.dat’" Again, the contents of style.dat would be read, followed by the contents of style2.dat, over-writing any settings for the same attributes included in style.dat. 7.2.2 Temporary Attributes Sometimes you need to effect a change of style that only lasts for a single invocation of a task. For example, plotting data from different NDFs or NDF sections in different colours. This is available at the cost of a little further syntax to learn. The temporary attributes should be preceded by a plus sign. In the following example, three histograms are plotted on a single graphic. % histogram ndf1 \\ % histogram ndf2 style="+colour(curve)=yellow" noclear noaxes \\ % histogram ndf3 style="+width(curve)=4" noclear noaxes \\ The first uses the current attributes including line colour to plot the histogram for NDF ndf1. (Recall \\ is a synonym for the accept keyword, so other defaults are used for the likes of the data range and number of bins omitted for clarity.) The second NDF’s histogram is plotted in yellow. For the third NDF the locus is again in the colour of the first plot (since the yellow was only temporary) but has thickness four times normal. If you ran HISTOGRAM again, the line thickness would return to its original value used in the first graph. You are not limited to just one temporary attribute. You can supply a list that can include indirection to text files. % linplot spectrum style="’+style(curve)=2,grid,^temp.sty,colour(textlab)=green’" Here LINPLOT uses three temporary attributes plus whatever is defined in the text file file temp.sty. Note for a list the string requires an extra set of enclosing quotes to protect these from being misinterpreted by the UNIX shell. The experimental method that used a second parameter called TEMPSTYLE will be withdrawn. It is also possible to combine persistent and temporary attributes. Persistent style attributes must be supplied first, then after a plus sign comes the list of temporary attributes. % linplot spectrum style="’colour(line)=red,width=3+style(curve)=2’" Literal plus signs should be avoided if using both temporary and persistent attributes in a group expression. 7.2.3 Synonyms for Attribute Names The available plotting attributes and their names are defined by the AST subroutine library (see SUN/210) upon which Kappa graphics are based (together with PGPLOT). However, Kappa provides synonyms for certain plotting attributes where this would provide a clearer indication of the purpose of the attribute within the context of a particular application. These synonyms are listed in the description of the STYLE parameter for the particular applications concerned. For instance, the CONTOUR applications draws contours as ‘curves’, that is, it uses the attributes Colour(Curves), Width(Curves) and Style(Curves) to determine the appearance of the contours. However, the synonym Contours (minimum abbreviation Cont) may be used in place of Curves, so the appearance of the contours can also be specified using the ‘pseudo-’ attributes Colour(Cont), Width(Cont) and Style(Cont). You should remember that a synonym is simply an alternative way of specifying a particular attribute. So if you are running CONTOUR and you give the two setting strings: Colour(cont)=red Colour(curve)=blue the contours will appear blue, not red, because the second attribute setting overrides the first one. Any particular synonym will only be recognised by certain applications. Thus, Contours is only recognised as a synonym for Curves when running CONTOUR. Applications ignore attributes (or synonyms) that they do not recognise without reporting an error. Thus if the file containing your default plotting style (used by all applications—see later) contains the two lines: Colour(curve)=blue Colour(cont)=red then CONTOUR will draw contours in red, but other applications will draw their curves in blue since they ignore the Colour(cont)=red line. Note, if these two lines were the other way round: Colour(cont)=red Colour(curve)=blue then all curves, including contours drawn by CONTOUR, would be blue. This is because CONTOUR will process both lines in the order supplied, ending up with blue contours. 7.2.4 Colour Attributes The Colour attribute can be used to specify the colours of various components of a plot. The value assigned to the attribute can be one of the following options. • An integer colour index. Colour indices can be thought of as ‘pen numbers’. For instance, the string "Colour(border)=3" says “Draw the border using pen number 3”. The resulting colour depends on the colour of Pen 3, which can be set using PALENTRY. • A standard X colour name, e.g. "Colour(border)=red". • A triple of floating-point red, green and blue intensity values in the range zero to one, separated by spaces, e.g. Colour(border)=1.0 0.0 0.0. • An HTML colour code. This is a hash followed by three pairs of hexadecimal digits giving red, green, and blue intensity in the range 0 to 255, e.g. "Colour(border)=#ffa700". Within style files, the "#" character is used to introduce a comment, and so the colour code would be ignored. To avoid this, the "@" character can be used in place of "#". If no pen is currently available in the palette with the requested colour, then the ‘nearest’ colour will be used instead—sometimes this may not be very near at all! If you specifically want the requested colour, then you should use PALENTRY first to set one of the available pens to the required colour. Note, if you produce a plot on an X-window and then change the representation of pens using PALENTRY, then any components of the existing plot that were drawn with the modified pens will change colour immediately if and only if your X window is set to 256 colours (i.e. if you have an 8 bit pseudo-colour visual). If you are in the more usual situation of having a 16- or 24-bit display, then changes to pen colours will only affect subsequently drawn graphics. 7.3 Establishing Defaults for Plotting Attributes When an application needs a plotting style, it uses a style parameter to get a group of attribute settings. But what values are used for attributes that are not included in this group? Obviously, if an attribute has been assigned an explicit value using the parameter then that value is used, but you should note that most styles are ‘sticky’.7 That is, once a group of attribute settings has been specified for a style parameter, that group continues to be used by subsequent invocations of the application until a new group is supplied for the parameter. If the group is supplied within a text file, then the ‘current value’ stored for the parameter is the list of attribute settings read from the file, not the name of the file. Thus, changing the contents of the file at a later time will have no effect on the value used for the parameter unless you re-specify the parameter on the command line. If an attribute is not specified in the supplied group, then a default value is used for the attribute, determined as follows: (1) If the plot is being overlayed on another existing plot, then the value that was used for the attribute when the existing plot was created is used (but only if it was set to an explicit value). (2) Otherwise, the attribute value specified in a defaults file is used. The defaults file is found as follows: • If the environment variable KAPPA_<APP>_<PARAM> is defined (where <APP> is the name of the application e.g. DISPLAY, and <PARAM> is the name of the parameter, e.g. STYLE, both in upper-case), its value is taken to be the full path to the defaults file. • If KAPPA_<APP>_<PARAM> is not defined, the file $HOME/kappa_<app>_<param>.def is used (where <app> and <param> are in lower case this time).
• If the file $HOME/kappa_<app>_<param>.def cannot be accessed, the file $KAPPA_DIR/kappa_<app>_<param>.def is used.
• If the file $KAPPA_DIR/kappa_<app>_<param>.def cannot be accessed, then the value of the environment variable KAPPA_<PARAM> is used as the full path to the defaults file. • If KAPPA_<PARAM> is not defined, the file $HOME/kappa_<param>.def is used.
• If the file $HOME/kappa_<param>.def cannot be accessed, the file $KAPPA_DIR/kappa_<param>.def is used.
(3)
If the above process failed to produce a value for the attribute (either because no file was found, or the file did not contain a setting for the attribute), then the default value supplied by the AST library is used. These defaults are included in the full description of the relevant attributes in Appendix E.

From the above, you can see that defaults can be specified either for individual applications, or for all applications (any application-specific defaults file will be used in preference to the general defaults file).

It should be remembered that settings for unknown attributes are ignored, and do not cause the application to abort.8 So if you set a value for an attribute and it seems to have no effect, it may be worth checking that you have used the correct spelling for the attribute name.

7.4 Graphical Escape Sequences

Strings used for axis labels, plot titles, etc., can include special escape sequences which control the appearance of subsequent text when the string is drawn as part of a plot.9 Escape sequences are introduced using a percent character. For instance, if the string "10%^50+%^s50+Z" was used as an axis label in a plot, it would produce a string similar to "$1{0}^{\mathrm{\text{Z}}}$"—that is, the character "Z" would be displayed as a small superscript character. Any unrecognised, illegal or incomplete escape sequences are printed literally. The following escape sequences are currently recognised ("..." represents a string of one or more decimal digits):

• %% : Print a literal "%" character.
• %^...+ : Draw subsequent characters as superscripts. The digits "..." give the distance from the base-line of ‘normal’ text to the base-line of the superscript text, scaled so that a value of "100" corresponds to the height of ‘normal’ text.
• %^+ : Draw subsequent characters with the normal base-line.
• %v...+ : Draw subsequent characters as subscripts. The digits "..." give the distance from the base-line of ‘normal’ text to the base-line of the subscript text, scaled so that a value of "100" corresponds to the height of ‘normal’ text.
• %v+ : Draw subsequent characters with the normal base-line (equivalent to %^+).
• %>...+ : Leave a gap before drawing subsequent characters. The digits "..." give the size of the gap, scaled so that a value of "100" corresponds to the height of ‘normal’ text.
• %<...+ : Move backwards before drawing subsequent characters. The digits "..." give the size of the movement, scaled so that a value of "100" corresponds to the height of ‘normal’ text.
• %s...+ : Change the Size attribute for subsequent characters. The digits "..." give the new Size as a fraction of the ‘normal’ Size, scaled so that a value of "100" corresponds to 1.0;
• %s+ : Reset the Size attribute to its ‘normal’ value.
• %w...+ : Change the Width attribute for subsequent characters. The digits "..." give the new width as a fraction of the ‘normal’ Width, scaled so that a value of "100" corresponds to 1.0;
• %w+ : Reset the Width attribute to its ‘normal’ value.
• %f...+ : Change the Font attribute for subsequent characters. The digits "..." give the new Font value.
• %f+ : Reset the Font attribute to its ‘normal’ value.
• %c...+ : Change the Colour attribute for subsequent characters. The digits "..." give the new Colour value.
• %c+ : Reset the Colour attribute to its ‘normal’ value.
• %t...+ : Change the Style attribute for subsequent characters. The digits "..." give the new Style value.
• %t+ : Reset the Style attribute to its ‘normal’ value.
• %- : Push the current graphics attribute values on to the top of the stack (see %+).
• %+ : Pop attributes values of the top the stack (see %-). If the stack is empty, ‘normal’ attribute values are restored.

PGPLOT escape sequences may also be included in strings that are to be drawn.

5The complete group expression syntax is described in SUN/150. This is the documentation for the GRP subroutine library, which provides a programming interface for obtaining groups of strings.

6The up-arrow character is not one of these special characters, and so a simple reference to a single text file does not need to be enclosed in quotes.

7The exceptions are the TEMPSTYLE parameters. These parameters are used to make temporary style changes and always forget any previous values assigned to them.

8This is because they may be synonyms recognised by other other applications.

9When displayed in a non-graphical environment (for instance, on an alpha-numeric terminal) the characters forming an escape sequence are stripped out of the string before the string is displayed.