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.
|Border||Draw a border around valid regions of a plot?|
|Colour(element)||Colour for a plot element|
|DrawDSB||Annotate both sidebands in a dual sideband spectrum?|
|DrawTitle||Draw a title?|
|Edge(axis)||Which edges to label|
|FileInTitle||Include the NDF name as a second line in the title?|
|Font(element)||Character fount for a plot element|
|Gap(axis)||Interval between major axis values|
|Grid||Draw grid lines?|
|LabelAt(axis)||Where to place numerical labels|
|LabelUnits(axis)||Include unit descriptions in axis labels?|
|LabelUp(axis)||Draw numerical axis labels upright?|
|Labelling||Label and tick placement option|
|MajTickLen||Length of major tick marks|
|MinTickLen||Length of minor tick marks|
|MinTick(axis)||Density of minor tick marks|
|NumLab(axis)||Draw numerical axis labels?|
|NumLabGap(axis)||Spacing of numerical axis labels|
|Size(element)||Character size for a plot element|
|Style(element)||Line style for a plot element|
|TextBackColour||Background colour to use when drawing text|
|TextLab(axis)||Draw descriptive axis labels?|
|TextLabGap(axis)||Spacing of descriptive axis labels|
|TextMargin||Width of margin to clear when drawing text|
|TickAll||Draw tick marks on all edges?|
|TitleGap||Vertical spacing for the title|
|Width(element)||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:
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
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
|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.|
|Axis1||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.|
|Axis2||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.|
|Border||The plot border, drawn if attribute Border is given a non-zero value.|
|Curves||Curves drawn over the top of a plot (e.g. contours, data curves).|
|Grid||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.|
|Grid1||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.|
|Grid2||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.|
|Markers||Graphical markers (symbols) drawn over a plot.|
|NumLab||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.|
|NumLab1||Numerical labels drawn along Axis 1. Values specified using NumLab1 override any supplied using NumLab.|
|NumLab2||Numerical labels drawn along Axis 2. Values specified usingNumLab2 override any supplied using NumLab.|
|Strings||Text strings drawn over a plot (except for axis labels and plot title).|
|TextLab||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.|
|TextLab1||Descriptive label for Axis 1. Values specified using TextLab1 override any supplied using TextLab.|
|TextLab2||Descriptive label for Axis 2. Values specified using TextLab2 override any supplied using TextLab.|
|Ticks||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.|
|Ticks1||Tick marks (both major and minor) drawn along Axis 1. Values specified using Ticks1 override any supplied using Ticks.|
|Ticks2||Tick marks (both major and minor) drawn along Axis 2. Values specified using Ticks2 override any supplied using Ticks.|
|Title||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
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.
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:
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.6 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
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
Again, the contents of
style.dat would be read, followed by the contents of
any settings for the same attributes included in
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
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.
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
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.
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.
"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.
Colour(border)=1.0 0.0 0.0.
"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.
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:
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.
KAPPA_<APP>_<PARAM>is not defined, the file
$HOME/kappa_<app>_<param>.defis used (where
<param>are in lower case this time).
$HOME/kappa_<app>_<param>.defcannot be accessed, the file
$KAPPA_DIR/kappa_<app>_<param>.defcannot be accessed, then the value of the environment variable
KAPPA_<PARAM>is used as the full path to the defaults file.
KAPPA_<PARAM>is not defined, the file
$HOME/kappa_<param>.defcannot be accessed, the file
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.
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
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
"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
"..." represents a string of one or more decimal 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.
"..."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.
"..."give the size of the gap, scaled so that a value of
"100"corresponds to the height of ‘normal’ text.
"..."give the size of the movement, scaled so that a value of
"100"corresponds to the height of ‘normal’ text.
"..."give the new Size as a fraction of the ‘normal’ Size, scaled so that a value of
"100"corresponds to 1.0;
"..."give the new width as a fraction of the ‘normal’ Width, scaled so that a value of
"100"corresponds to 1.0;
"..."give the new Font value.
"..."give the new Colour value.
"..."give the new Style value.
PGPLOT escape sequences may also be included in strings that are to be drawn.
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.