NAGGraph

DESCRIPTION

-- Introduction --

NAGGraph generates a line and/or marker plot from two-dimensional data values. Optionally, a pair of axes may be drawn; a centred title at the top, axis titles below and to the left, and a legend may be used to annotate the plot. The curve fitting method, as well as the color, line style and markers associated with the curves may be specified. Hardcopy output may be sent directly to a printer; Encapsulated PostScript (EPS) files may be generated for later processing.

NAGGraph is implemented using the NAG Graphics Library (discontinued). As such it uses the Adobe PostScript NAG Graphical Interface to generate hardcopy output. Color PostScript files are generated; when sent to a monochrome printer lines of different color are distinguishable through shades of grey.

-- Curve drawing --

Data points may be connected by straight lines or curves generated using the osculatory or cubic Bessel, piecewise monotonic, Butland or McConalogue methods.

The Bessel and piecewise monotonic method are suitable when the data points are observations of some underlying single-valued function. For data points that are observations of two independent variables, the Butland or McConalogue method should be used instead.

The cubic Bessel method will produce a fairly free-flowing curve and is recommended for general applications; if the precise shape of the data is to be preserved, with maxima and minima occurring at data points and with no unnecessary oscillations, the piecewise monotonic method should be used.

McConalogue's method generates a curve which is invariant under rotation but not under scaling of the axes. It is recommended for general applications. In cases where the precise shape of the data is to be preserved, with the turning points of the curve occurring at data points and with no unnecessary fluctuations, Butland's method should be selected. It generates a curve invariant under linear scaling, but not invariant under rotation.

Straight lines are implemented using NAG Graphics Library routine J06BAF; curve fits using the piecewise monotonic or Bessel method are implemented using NAG Graphics Library routine J06CAF; curve fits using Butland's or McConalogue's method are implemented using NAG Graphics Library routine J06CCF.

-- Default Settings --

Lines and markers for a data channel will be drawn in the same color. By default the colors black, red, green, blue, cyan, magenta, and yellow will be used for data channels one to seven. If more than seven data channels are to be depicted, then these colors will be used cyclically.

By default the markers cross, circle, plus, star, square, lozenge, triangle pointing upwards, triangle pointing downwards, and cross overlayed by plus will be used for data channels one to nine. If more than nine data channels are to be depicted, then these markers will be used cyclically.

The default text used in the legend to the data channels is "Curve1", "Curve2", etc.

By default all lines will be drawn solid; no axes, legend or titles will be used on the plot, until they are requested by the user.

The default line (color, style), marker (symbol) and legend (text) attributes for a data channel will be used until they are reset by the user; they will again come into force when reset has been specified on the pull-down menu and a new lattice has been attached.

The default is not to have any annotation in the form of a plot title, and x and y-axis titles. If titles have been specified, they will remain in force until new titles have been defined, or if reset has been specified on the pull-down menu and a new lattice has been attached.

-- Actions Performed upon Receiving new Lattice Data --

If the number of data channels of the new lattice is less than was the case forthe previous lattice and the value of the last selected channel is now out of range, then this value will be reduced to the maximum data channel for the new lattice.

-- Text --

A maximum string length of 255 characters is imposed on all text strings used.

All text has been implemented using the NAG Graphics Library. As such you may use all in-string keyword facilities available to users of this library. A short description of the most important features is given in this section.

Keywords are available to support such actions as changing the current text font (perhaps to a Greek font), modifying the size and relative position of characters within the string (perhaps to draw subscripts, superscripts or mathematical expressions), etc.

Keywords may be specified as an integral part of any text string supplied to NAG Graphics. Their presence will automatically be detected and the appropriate actions taken; they will not appear on the output plot. Each keyword consists of a delimiter symbol, followed by a one or two- character keyword mnemonic, which may be in upper or lower case. The keyword delimiter is an exclamation mark ("!");

As a simple example, let us take the string "E = mc!u2!N" which may be used to plot the expression E=mc2. This string contains two keywords:

  • Keyword !u indicates that all of the following characters up to the next delimiter should be interpreted as a superscript.
  • Keyword !N is added to ensure that the current point is returned to the base line ready to plot any subsequent text.
The range of in-string keywords is summarised in Table 1. Where appropriate, the relative movement of the current point (up or down, in units of the current character height) and scale factor (relating to character size and spacing), are indicated.
Table 1: In-string keywords, excluding those for font changes

Mnemonic Description                      Movement  Scale Factor
----------------------------------------------------------------

A        Shift above the fraction line        1.0       1.0
B        Shift below the fraction line       -1.0       1.0
U        Move up to superscript level         0.6       0.62
D        Move down to subscript level        -0.35      0.62
E        Move to exponent level               0.94      0.44
I        Move to index level                 -0.94      0.44
L        Move to lower subscript level       -1.125     0.62
N        Move to normal or base line level    1.0

S        Save current point and character size on stack
R        Restore previous current point and character size from stack
!        Display the current symbol

Note: either upper or lower case characters may be used for the mnemonic.

In order to make effective use of the in-string keyword facility you should bear the following points in mind:

  • The maximum number of keyword delimiters permissible in a single string is 30.
  • The NAG Graphics Library utilises a stack to keep track of the current point and character size during the plotting of any given string. Up to ten levels can be stored.
  • The Hershey fonts supplied as part of the NAG Graphics Library offer a wide range of symbols, including mathematical symbols, and as such it is possible to plot quite complex formulae.
  • Fraction lines can be plotted by selecting the Hershey Meteorological Symbol font (see Table 2) and plotting the character "X". The length of the fraction line is determined by the number of "X"s plotted.
  • The keyword delimiter symbol can be plotted by duplicating the delimiter symbol within the input string.
  • The "save" command can be used to temporarily set the "normal" line level for subsequent plotting. The new base line position is added to the stack until such time as a "restore" command is issued.
As well as giving you the opportunity to modify character positions and size, in-string keywords allow you to change the current font. This allows you, for example, to plot Greek characters as an integral part of your output text string.

The form of the in-string keyword used to select a specific font is the same as previously defined, except that the character mnemonic is replaced by a numeric value ranging from 1 to 25.

You have a choice of 25 different fonts; these can be accessed by issuing the mnemonics (with a preceding delimiter) detailed in Table 2. For ease of use, some fonts have been given a one-character mnemonic which can be used in place of the associated numeric value.

Table 2: In-string keywords for font changing

Mnemonic Description                 Mnemonic Description
---------------------------------------------------------

01       Simplex Roman               14       Cyrillic
02       Duplex  Roman               15       Triplex Roman
03       Complex Roman               16       Triplex  Italic
04 or g  Simplex Greek               17       Map  Symbols
05       Complex Greek               18       Astronomical Symbols
06       Complex Italic              19       Music Symbols
07 or m  Mathematical Symbols        20       Monospace Typewriter
08       Meteorological Symbols      21       Typewriter
09       Gothic English              22       Simplex
10 or w  Simplex Script              23       Italic
11       Complex Script              24       Complex
12       Gothic Italian              25       Complex Cyrillic
13       Gothic German

Note: either upper or lower case characters may be used for the mnemonics.

It may be useful to bear the following points in mind when using in-string keywords to change fonts:

  • The leading zero may be omitted for fonts 01 through 09. However, to avoid potential ambiguity, especially if numeric values follow the supplied in-string keyword, it is recommended that the leading 0 is retained. For example, the string "!11 is a number" will be plotted as " is a number" using font style 11, whereas "!011 is a number" will give "1 is a number" plotted using font 1.
  • The NAG Graphics Library offers you a choice of two Greek Hershey fonts: simplex and complex. Issuing the in-string keyword mnemonic G will give you the default simplex Greek font. To select the complex font you will need to explicitly request font number 05.
References
  • A method for usage of a large calligraphy set under RSX-11M. Grandle, R.E. and Nystrom, P.A. Proceedings of the Digital Equipment Computer Users Society, November 1980, 391-395.
-- Use of NAGGraph in conjunction with skm --

When manipulating widgets to set input values, some widgets are unavailable for editing (hidden from view) some of the time. For example, it is possible to edit the line color for a single data channel which forms part of a set of data channels, only when this data channel is being displayed as a single channel. This establishes which of the data channels is to be associated with the new line color.

When using skm to set input values, every widget may be set, regardless of its visibility or otherwise at the time of editing. Additional rules are therefore required to associate widget values with a particular data channel. This is done by using the previously selected data channel if no single data channel is selected.

Note: if a new lattice is used, which has fewer data channels than the previous lattice, the value of the last selected channel may have been reduced to the maximum data channel for the new lattice.

INPUTS

Port: InLat
Type: Lattice
Constraints: 1-D
Data points (x,y) are extracted from the lattice, which must be one-dimensional. Any data type, number of data channels, and number of coordinate values may be supplied. The x values are extracted from the coordinate values; the y values from the data channels. One or all data channels may be plotted.

All values are converted to double precision before being processed by the NAG Graphics Library.

WIDGETS

Port: Channel Flag
Type: Radio Box
Menu Item: All Channels
Menu Item: One Channel
When the input lattice consists of more than one data channel, you may select which channels are to be displayed by choosing the option "All Channels" or "One Channel".

Port: Channel Selector
Type: Slider
When the input lattice consists of more than one data channel, and you have selected to display only one channel, then you may select the channel using the slider marked "Channel Selector".

Port: Legend Flag
Type: Radio Box
Menu Item: No Legend
Menu Item: Legend
The annotation option for a legend may be set by choosing the option "No Legend" or "Legend". If a legend is selected a key to lines and markers used will be displayed in the position specified in the pull-down menu "Legends". The default position is the top right hand corner of the plot. The annotation used in the key may be set by the user (see Legend Text); default text labels are "Curve1", "Curve2", etc.

Port: Legend Text
Type: Text
When a legend has been selected (see Legend Flag), and the input lattice consists of one data channel, or the input lattice consists of more than one data channel and the "One Channel" option has been selected, then the text for the key to the selected channel may be specified in the text slot marked "Legend Text".

This text will be used as the key to the specified data channel until new text is entered in the text slot, or if reset is specified on the pull-down menu and a new lattice has been selected. In the latter case all annotation for the key is reverted to the default values "Curve1", "Curve2". etc.

A maximum of 256 characters may be entered in the text slot. Incorrect strings will be rejected, and an indication will be given of the nature of the error.

You are recommended to use short input strings; if strings are too long to fit in the allocated space they will be clipped to the size of the legend box.

Port: Legend Position
Type: Option Menu
Menu Item: Legend Auto Placing
Menu Item: Legend Top Right
Menu Item: Legend Top Left
Menu Item: Legend Bottom Right
Menu Item: Legend Bottom Left
The position of the legend, when drawn, is determined by the setting of the widget "Legend Position", which may be controlled through the pull-down menu "Legends". The default position is such that a minimum number of data points and line segments is hidden by the legend.

If the legend is placed in one of the corners, the actual position depends on the presence of titles and/or axes. The legend will never be plotted on top of any title or axis.

Port: Line Color
Type: Option Menu
Menu Item: White
Menu Item: Red
Menu Item: Green
Menu Item: Blue
Menu Item: Cyan
Menu Item: Magenta
Menu Item: Yellow
When the input lattice consists of one data channel, or the input lattice consists of more than one data channel and the "One Channel" option has been selected, then the color for the selected channel may be specified using the option menu marked "Line Color". A selection of 7 colors is available; both lines and markers for a curve will be drawn in the selected color.

This color will be used to depict the specified data channel until a new color is requested, or reset is specified from the pull-down menu and a new lattice has been selected. In the latter case the color for the data channel is reverted to the default values, i.e. black for the first channel, red for the second, etc. If more than 7 data channels are present the colors will be used cyclically.

Port: Line Style
Type: Option Menu
Menu Item: Solid
Menu Item: Long Dash
Menu Item: Small Dash
Menu Item: Dot
When the input lattice consists of one data channel, or the input lattice consists of more than one data channel and the "One Channel" option has been selected, then the line style for the selected channel may be specified using the option menu marked "Line Style". A selection of solid, dashed and dotted line styles is available.

This line style will be used to depict the specified data channel until a new line style is requested, or reset is specified from the pull-down menu and a new lattice has been selected. In the latter case the line style for the data channel is reverted to the default value of solid lines for each channel.

Port: Marker Style
Type: Option Menu
Menu Item: Cross
Menu Item: Circle
Menu Item: Plus
Menu Item: Star
Menu Item: Square
Menu Item: Lozenge
Menu Item: Triangle Top
Menu Item: Triangle Bot
Menu Item: Cross And Plus
When the input lattice consists of one data channel, or the input lattice consists of more than one data channel and the "One Channel" option has been selected, then the marker for the selected channel may be specified using the option menu marked "Marker Style". A selection of nine markers is available.

This marker will be used to depict the points of the specified data channel until a new marker is requested, or reset is specified from the pull-down menu and a new lattice has been selected. In the latter case the marker for the data channel is reverted to the default values, i.e. a cross for the first channel, a circle for the second, etc. If more than nine data channels are present the markers will be used cyclically.

Port: Plot Style
Type: Option Menu
Menu Item: Lines
Menu Item: Markers
Menu Item: Both
You may select the style of the plot using the option menu marked "Plot Style". Data points may be connected by lines, indicated by markers, or both lines and markers may be used on the plot.

The selected plot style will be used for all data channels displayed on the plot.

Port: Curve Style
Type: Option Menu
Menu Item: Straight Lines
Menu Item: Cubic Bessel
Menu Item: Piecewise Monotonic
Menu Item: Butland
You may select the style of the lines using the option menu marked "Curve Style". Data points may be connected by straight lines, or a curve may be fitted to go through the points. The cubic Bessel (oscillatory) or McConalogue (piecewise monotonic) method may be selected.

The cubic Bessel method will produce a fairly free- flowing curve and is recommended for general applications; if the precise shape of the data is to be preserved, with maxima and minima occurring at data points and with no unnecessary oscillations, the piecewise monotonic method should be used.

The selected curve style will be used for all data channels displayed on the plot.

Port: Plot Title
Type: Text
The text to be used as the main title to be displayed at the top of the plot may be specified in the text slot marked "Plot Title".

A maximum of 256 characters may be entered in the text slot. Incorrect strings will be rejected, and an indication will be given of the nature of the error.

You are recommended to use input strings of reasonable length; if strings are too long to fit in the allocated space they will be clipped to the size of the plot.

Port: X Axis Title
Type: Text
The text to be used as the x axis title to be displayed at the bottom of the plot may be specified in the text slot marked "X Axis Title".

A maximum of 256 characters may be entered in the text slot. Incorrect strings will be rejected, and an indication will be given of the nature of the error.

You are recommended to use input strings of reasonable length; if strings are too long to fit in the allocated space they will be clipped to the size of the plot.

Port: Y Axis Title
Type: Text
The text to be used as the y axis title to be displayed on the left-hand side of the plot may be specified in the text slot marked "Y Axis Title".

A maximum of 256 characters may be entered in the text slot. Incorrect strings will be rejected, and an indication will be given of the nature of the error.

You are recommended to use input strings of reasonable length; if strings are too long to fit in the allocated space they will be clipped to the size of the plot.

Port: Axes Flag
Type: Radio Box
Menu Item: No Axes
Menu Item: Axes
The annotation option for a pair of axes may be set by choosing the option "No Axes" or "Axes". If a pair of axes is selected they will be displayed on the left- hand side and bottom of the plot. The (numerical) annotation is automatically generated.

Port: Hardcopy
Type: Radio Box
Menu Item: Print
Menu Item: Save
Menu Item: Save As...
Menu Item: Set Printer Command
Hardcopy output (sent directly to a printer or generated as an EPS file for later processing) may be obtained through the selection of the pull-down menu marked "File" on the menu bar of NAGGraph.

By selecting "Print" hardcopy output will be sent directly to the printer; the printout uses an intermediary PostScript file, and no permanent print files will be generated. The current print command will be used.

By selecting "Set Printer Command" you may change the printer command, for example to specify the destination printer.

By selecting "Save" a PostScript file will be generated; its default file name will be "NAGGraph.ps" in the directory from which IRIS Explorer was launched. A different file name may be selected through the "Save as..." option.

By selecting "Save as..." you may change the file name to which any EPS files will be written (see Filename).

Port: Filename
Type: File Browser
If the "Filename" option is selected from the "File" menu on the menu bar of NAGGraph, then you may select the file name to which any EPS files will be written. Selection is through the IRIS Explorer File Browser.

Port: Annotation
Type: Radio Box
Menu Item: No Annotation
Menu Item: Annotation
If annotation is selected, a number of text slots will appear in which plot titles may be typed. Titles may be plotted above, to the left and below the plot.

Port: Data Region
Type: Radio Box
Menu Item: Automatic Region
Menu Item: User-Defined
The type of data region to be used for the display of the curves may be specified. Automatic data regions have their extent in the x direction determined by the coordinates of the lattice that is to be depicted; their extent in the y direction is equal to the extent of the data values to be depicted, with an additional margin of 5 percent added on both sides to ensure that most curves will fit inside the data region, even if smoothing is applied.

When a user-defined data region is specified, then 4 sliders are made visible, which may be set to the minimum and maximum values for the data extent in x and y direction. (See below for a description of the widgets "X Min", "X Max", "Y Min", and "Y Max".)

Port: X Min
Type: Text
When a user-defined data region is in force, the value set on this widget determines the minimum value of the x coordinates to be depicted.

Port: X Max
Type: Text
When a user-defined data region is in force, the value set on this widget determines the maximum value of the x coordinates to be depicted.

Port: Y Min
Type: Text
When a user-defined data region is in force, the value set on this widget determines the minimum value of the y coordinates to be depicted.

Port: Y Max
Type: Text
When a user-defined data region is in force, the value set on this widget determines the maximum value of the y coordinates to be depicted.

Port: Fonts
Type: Radio Box
Menu Item: Hardware Only
Menu Item: Hardware/Hershey
Menu Item: Hershey Only
By default, and by selecting "Hardware Only", all text will be plotted using hardware fonts. However, you may prefer to select Hershey fonts, for example if some mathematical expression is to be used in the title of the plot.

By selecting "Hardware/Hershey", all text will be plotted using hardware fonts, unless keywords are detected in the input string for the plot title, in which case all text will be plotted using Hershey fonts.

By selecting "Hershey Only", all text will be plotted using Hershey fonts.

Port: Reset
Type: Radio Box
Menu Item: Reuse All Attributes
Menu Item: Reset All Attributes
By default any attributes that have been set (line color, line style, marker color, titles, legends), remain in force until a different selection has been made.

However, if "Reset All Attributes" has been selected from the pull-down menu, and a new lattice is connected to the module, then all attributes will revert to the default attributes.

Port: Redraw
Type: Radio Box
Menu Item: No Redraw
Menu Item: Redraw
Under normal circumstances, the picture in the drawing area will always be updated whenever a widget value or the window size of the module control panel has changed. If, however, a redraw is required more frequently, you may specify this through the pull-down menu "Redraw" on the menu bar of NAGGraph.

Port: Legend State
Type: Text
When a legend is requested, "Legend State" indicates where the current position of the legend is. The legend position may be changed through the pull-down menu "Legends" on the menu bar of NAGGraph.

Port: Set Printer Command
Type: Text
You may change the printer command from the current setting, for example to specify the destination printer.

OUTPUTS

Port: Picture
Type: Geometry

Port: Key
Type: Geometry
Geometry output from this module.

KNOWN PROBLEMS

When a long title is entered into the text slot for either the main or the axis titles (widgets "Plot Title", "X Axis Title" and "Y Axis Title"), then text will be truncated at both ends of the text string.

SEE ALSO

DisplayImg, Graph, Render.

The underlying graphics routines in this module are taken from the NAG Graphics Library, Chapters J06B and J06C.

References

  • NAG Graphics Library Reference Manual, Mark 4, Volume 1.

[Documentation Home]