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:

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.

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:

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):

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.⁵

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:

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:

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.⁶ So the above style could be given on the command line as follows:

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:

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:

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.

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.

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.

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:

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:

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:

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’.⁷ 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.⁸ 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.⁹ 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 "$10^{\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.