CLINPLOT - Draws a spatial grid of line plots for an axis of a cube NDF

Description:

This application displays a three-dimensional NDF  as a series of line plots of array value against position, arranged on a uniform spatial grid and plotted on the current graphics device. The vertical axis of each line plot represents array value, and the horizontal axis represents position along a chosen axis (see parameter USEAXIS). All the line plots have the same axis limits.

This application will typically be used to display a grid of spectra taken from a cube in which the current WCS Frame  includes one spectral axis (e.g. frequency) and two spatial axes (e.g. RA and Dec). For this reason the following documentation refers to the `spectral axis' and the `spatial axes'. However, cubes containing other types of axes can also be displayed, and references to `spectral' and `spatial' axes should be interpreted appropriately.

A rectangular grid of $NX$ by $NY$ points (see parameters NX and NY) is defined over the spatial extent of the cube, and a spectrum is drawn at each such point. If $NX$ and $NY$ equal the spatial dimensions of the cube (which is the default for spatial axes of fewer than 31 pixels), then one spectrum is drawn for every spatial pixel in the cube. For speed, the spectrum will be binned up so that the number of elements in the spectrum does not exceed the horizontal number of device pixels available for the line plot.

Annotated axes for the spatial co-ordinates may be drawn around the grid of line plots (see parameter AXES). The appearance of these and the space they occupy may be controlled in detail (see parameters STYLE and MARGIN).

The data value at the top and bottom of each line plot can be specified using parameters YBOT and YTOP. The defaults can be selected in several ways including percentiles (see parameter LMODE).

The current picture is usually cleared before plotting the new picture, but parameter CLEAR can be used to prevent this, allowing the plot (say) to be drawn over the top of a previously displayed grey-scale image.

The range and nature of the vertical and horizontal axes in each line plot can be displayed in a key to the right of the main plot (see parameter KEY). Also, an option exists to add numerical labels to the first (i.e. bottom-left) line plot, see parameter REFLABEL. However, due to the nature of the plot, the text used may often be too small to read.

Usage:

clinplot ndf [useaxis] [device] [nx] [ny]

Parameters:

AXES = _LOGICAL (Read)

TRUE if labelled and annotated axes describing the spatial are to be drawn around the outer edges of the plot. The appearance of the axes can be controlled using the STYLE parameter. The dynamic default is to draw axes only if the CLEAR parameter indicates that the graphics device is not being cleared. []

BLANKEDGE = _LOGICAL (Read)

If TRUE then no tick marks or labels are placed on the edges of line plots that touch the outer spatial axes (other edges that do not touch the outer axes will still be annotated). This can avoid existing tick marks being over-written when drawing a grid of spectra over the top of a picture that includes annotated axes. The dynamic default is TRUE if and only if the graphics device is not being cleared (i.e. parameter CLEAR is FALSE) and no spatial axes are being drawn (i.e. parameter AXES is FALSE). []

CLEAR = _LOGICAL (Read)

If TRUE the current picture is cleared before the plot is drawn. If FALSE, then the display is left uncleared and an attempt is made to align the spatial axes of the new plot with any spatial axes of the existing plot. Thus, for instance, a while light image may be displayed using DISPLAY, and then spectra drawn over the top of the image using this application. [TRUE]

COMP = LITERAL (Read)

The NDF array component to be displayed. It may be "Data", "Quality", "Variance", or "Error" (where "Error" is an alternative to "Variance" and causes the square root of the variance values to be displayed). If "Quality" is specified, then the quality values are treated as numerical values (in the range 0 to 255). ["Data"]

DEVICE = DEVICE (Read)

The name of the graphics device used to display the cube. [Current graphics device]

FILL = _LOGICAL (Read)

If FILL is set to TRUE, then the display will be `stretched' to fill the current picture in both directions. This can be useful to elongate the spectra to reveal more detail by using more of the display surface at the cost of different spatial scales, and when the spatial axes have markedly different dimensions. The dynamic default is TRUE if either of the spatial dimensions is one. and FALSE otherwise. []

KEY = _LOGICAL (Read)

If TRUE, then a `key' will be drawn to the right of the plot. The key will include information about the vertical and horizontal axes of the line plots, including the maximum and minimum value covered by the axis and the quantity represented by the axis. The appearance of this key can be controlled using parameter KEYSTYLE, and its position can be controlled using parameter KEYPOS. [TRUE]

KEYPOS() = _REAL (Read)

Two values giving the position of the key. The first value gives the gap between the right-hand edge of the grid plot and the left-hand edge of the key (0.0 for no gap, 1.0 for the largest gap). The second value gives the vertical position of the top of the key (1.0 for the highest position, 0.0 for the lowest). If the second value is not given, the top of the key is placed level with the top of the grid plot. Both values should be in the range 0.0 to 1.0. If a key is produced, then the right-hand margin specified by parameter MARGIN is ignored. [current value]

KEYSTYLE = GROUP (Read)

A group of attribute settings describing the plotting style to use for the key (see parameter KEY).

A comma-separated list of strings should be given in which each string is either an attribute setting, or the name of a text file preceded by an up-arrow character "$\wedge$". Such text files should contain further comma-separated lists which will be read and interpreted in the same manner. Attribute settings are applied in the order in which they occur within the list, with later settings overriding any earlier settings given for the same attribute.

Each individual attribute setting should be of the form:

$<$name$>$=$<$value$>$

where $<$name$>$ is the name of a plotting attribute, and $<$value$>$ is the value to assign to the attribute. Default values will be used for any unspecified attributes. All attributes will be defaulted if a null value (!) is supplied. See Plotting Attributes for a description of the available attributes. Any unrecognised attributes are ignored (no error is reported).

The appearance of the text in the key can be changed by setting new values for the attributes Colour(Strings), Font(Strings)etc. [current value]

LMODE = LITERAL (Read)

LMODE specifies how the defaults for parameters YBOT and YTOP (the lower and upper limit of the vertical axis of each line plot) should be found. The supplied string should consist of up to three sub-strings, separated by commas. The first sub-string must specify the method to use. If supplied, the other two sub-strings should be numerical values as described below (default values will be used if these sub-strings are not provided). The following methods are available.

• "Range" -- The minimum and maximum data values in the supplied cube are used as the defaults for YBOT and YTOP. No other sub-strings are needed by this option.

• "Extended" -- The minimum and maximum data values in the cube are extended by percentages of the data range, specified by the second and third sub-strings. For instance, if the value "Ex,10,5" is supplied, then the default for YBOT is set to the minimum data value minus 10% of the data range, and the default for YTOP is set to the maximum data value plus 5% of the data range. If only one value is supplied, the second value defaults to the supplied value. If no values are supplied, both values default to "2.5".

• "Percentile" -- The default values for YBOT and YTOP are set to the specified percentiles of the data in the supplied cube. For instance, if the value "Per,10,99" is supplied, then the default for YBOT is set so that the lowest 10% of the plotted points are off the bottom of the plot, and the default for YTOP is set so that the highest 1% of the points are off the top of the plot. If only one value, $p1$, is supplied, the second value, $p2$, defaults to $(100 - p1)$. If no values are supplied, the values default to "5,95".

• "Sigma" -- The default values for YBOT and YTOP are set to the specified numbers of standard deviations below and above the mean of the data. For instance, if the value "sig,1.5,3.0" is supplied, then the default for YBOT is set to the mean of the data minus 1.5 standard deviations, and the default for YTOP is set to the mean plus 3 standard deviations. If only one value is supplied, the second value defaults to the supplied value. If no values are provided both default to "3.0".

The method name can be abbreviated to a single character, and is case insensitive. The initial value is "Range". [current value]

MARGIN( 4 ) = _REAL (Read)

The widths of the margins to leave around the outer spatial axes for axis annotations, given as fractions of the corresponding dimension of the current picture. The actual margins used may be increased to preserve the aspect ratio of the data. Four values may be given, in the order: bottom, right, top, left. If fewer than four values are given, extra values are used equal to the first supplied value. If these margins are too narrow any axis annotation may be clipped. If a null (!) value is supplied, the value used is (for all edges); 0.15 if annotated axes are being produced; and 0.0 otherwise. The initial default is null. [current value]

NDF = NDF (Read)

The input NDF structure containing the data to be displayed. It should have three significant axes, i.e. whose dimensions are greater than 1.

NX = _INTEGER (Read)

The number of spectra to draw in each row. The spectra will be equally spaced over the bounds of the $X$ pixel axis. The dynamic default is the number of pixels along the $X$ axis of the NDF, so long as this value is no more than 30. If the $X$ axis spans more than 30 pixels, then the dynamic default is 30 (meaning that some spatial pixels will be ignored). []

NY = _INTEGER (Read)

The number of spectra to draw in each column. The spectra will be equally spaced over the bounds of the $Y$ pixel axis. The dynamic default is the number of pixels along the $Y$ axis of the NDF, so long as this value is no more than 30. If the $Y$ axis spans more than 30 pixels, then the dynamic default is 30 (meaning that some spatial pixels will be ignored). []

REFLABEL = _LOGICAL (Read)

If TRUE then the first line plot (i.e. the lower-left spectrum) will be annotated with numerical and textual labels describing the two axes. Note, due to the small size of the line plot, such text may be too small to read on some graphics devices. [current value]

SPECSTYLE = LITERAL (Read)

A group of attribute settings describing the plotting style to use when drawing the axes and data values in the spectrum line plots.

A comma-separated list of strings should be given in which each string is either an attribute setting, or the name of a text file preceded by an up-arrow character "$\wedge$". Such text files should contain further comma-separated lists which will be read and interpreted in the same manner. Attribute settings are applied in the order in which they occur within the list, with later settings overriding any earlier settings given for the same attribute.

Each individual attribute setting should be of the form:

$<$name$>$=$<$value$>$

where $<$name$>$ is the name of a plotting attribute, and $<$value$>$ is the value to assign to the attribute. Default values will be used for any unspecified attributes. All attributes will be defaulted if a null value (!) is supplied. See Plotting Attributes for a description of the available attributes. Any unrecognised attributes are ignored (no error is reported).

By default the axes have interior tick marks, and are without labels and a title to avoid overprinting on adjacent plots.

The appearance of the data values is controlled by the attributes Colour(Curves), Width(Curves), etc. (the synonym Lines may be used in place of Curves). [current value]

STYLE = GROUP (Read)

A group of attribute settings describing the plotting style to use for the annotated outer spatial axes (see parameter AXES).

A comma-separated list of strings should be given in which each string is either an attribute setting, or the name of a text file preceded by an up-arrow character "$\wedge$". Such text files should contain further comma-separated lists which will be read and interpreted in the same manner. Attribute settings are applied in the order in which they occur within the list, with later settings overriding any earlier settings given for the same attribute.

Each individual attribute setting should be of the form:

$<$name$>$=$<$value$>$

where $<$name$>$ is the name of a plotting attribute, and $<$value$>$ is the value to assign to the attribute. Default values will be used for any unspecified attributes. All attributes will be defaulted if a null value (!) is supplied. See Plotting Attributes for a description of the available attributes. Any unrecognised attributes are ignored (no error is reported). [current value]

USEAXIS = LITERAL (Read)

The WCS axis that will appear along the horizontal axis of each line plot (the other two axes will be used as the spatial axes). The axis can be specified using one of the following options.

• Its integer index within the current Frame  of the NDF (in the range 1 to 3 in the current frame).

• Its Symbol  string such as "RA" or "VRAD".

• A generic option where "SPEC" requests the spectral axis, "TIME" selects the time axis, "SKYLON" and "SKYLAT" picks the sky longitude and latitude axes respectively. Only those axis domains present are available as options.

A list of acceptable values is displayed if an illegal value is supplied. The dynamic default is the index of any spectral axis found in the current Frame of the NDF. []

YBOT = _REAL (Read)

The data value for the bottom edge of each line plot. The dynamic default is chosen in a manner determined by parameter LMODE. []

YTOP = _REAL (Read)

The data value for the top edge of each line plot. The dynamic default is chosen in a manner determined by parameter LMODE. []

Examples:

clinplot cube useaxis=3

Plots a set of line plots of data values versus position along the third axis for the three-dimensional NDF called cube on the current graphics device. Axes are drawn around the grid of plots indicating the spatial positions in the current co-ordinate Frame. The third axis may not be spectral and the other two axes need not be spatial.

clinplot cube margin=0.1

As above, but if a search locates a spectral axis in the world co-ordinate system, this is plotted along the horizontal of the line plots, and the other axes are deemed to be spatial. Also the margin for the spatial axes is reduced to 0.1 to allow more room for the grid of line plots.

clinplot map($\sim$5,$\sim$5,) useaxis=3 noaxes

Plots data values versus position for the central 5-by-5 pixel region of the three-dimensional NDF called map on the current graphics device. No spatial axes are drawn.

clinplot map($\sim$5,$\sim$5,) useaxis=3 noaxes device=ps_l

As the previous example but now the output goes to a text file (pgplot.ps) which can be printed on a PostScript printer.

clinplot nearc v style="title=Ne Arc variance" useaxis=1 reflabel=f

Plots variance values versus position along axis 1, for each spatial position in dimensions two and three, for the three dimensional NDF called nearc on the current graphics device. The plot has a title of "Ne Arc variance". No labels are drawn around the lower-left line plot.

clinplot ndf=speccube noclear specstyle="colour(curves)=blue"

Plots data values versus pixel co-ordinate at each spatial position for the three-dimensional NDF called speccube on the current graphics device. The plot is drawn over any existing plot and inherits the spatial bounds of the previous plot. The data are drawn in blue, probably to distinguish it from the previous plot drawn in a different colour.

Notes:

• If no Title  is specified via the STYLE parameter, then the TITLE component in the NDF is used as the default title for the annotated axes. Should the NDF not have a TITLE component, then the default title is instead taken from current co-ordinate Frame in the NDF, unless this attribute has not been set explicitly, whereupon the name of the NDF is used as the default title.

• If all the data values at a spatial position are bad, no line plot is drawn at that location.

• The application stores a number of pictures in the graphics database  in the following order: a FRAME picture containing the annotated axes, data plots, and optional key; a KEY picture to store the key if present; and a DATA picture containing just the data plots. The world co-ordinates in the DATA picture will correspond to the offset along a spectrum on the horizontal axis, data value on the vertical axis, and the two spatial co-ordinates for that spectrum. On exit the current database picture for the chosen device reverts to the input picture.

Related Applications

KAPPA: DISPLAY, LINPLOT, MLINPLOT; FIGARO: SPECGRID; SPLAT.

Implementation Status:

• This routine correctly processes the AXIS, DATA, QUALITY, VARIANCE, LABEL, TITLE, WCS, and UNITS  components of the input NDF.

• Processing of bad pixels and automatic quality masking are supported.