DCONTOUR directive

Draws contour plots on a plotter or graphics monitor.

Options

Parameters

Description

The contours to be plotted are defined by a grid of z-values or heights. The grid can be a rectangular matrix, a two-way table or a pointer to a set of variates; the y-dimension is represented by the rows of the structure and the x-dimension by the columns. In each case there must be at least three rows and three columns of data (after allowing for any restrictions on a set of variates). Missing values are not permitted; that is, only complete grids can be displayed. If the grid is supplied as a table with margins, these will be ignored when plotting the surface. The YORIENTATION option controls the orientation of the y-axis. By default this is reversed, so that the grid is in the same order as it would be if it were printed.

   The WINDOW option defines the window where the contours are plotted, and the KEYWINDOW option similarly specifies where the key should appear. The grid axes are scaled so that the y- and x-dimensions (rows and columns respectively) will match the dimensions of the specified window: if you wish to preserve the "shape" of the grid you should use the FRAME directive to define a window whose y- and x-dimensions are in the same proportions as the grid dimensions. Titles can be added to these windows using the TITLE and KEYDESCRIPTION options. The SCREEN option controls whether the graphical display is cleared before the histogram is plotted and the ENDACTION option controls whether GenStat pauses at the end of the plot.

   The heights of the contour lines are determined using the NCONTOURS, CONTOURS or INTERVAL parameters. The first possibility is to define the contours explicitly using the CONTOURS parameter. Alternatively, if CONTOURS is unset, INTERVAL can set the required interval between each contour. Or, if both CONTOURS and INTERVAL are unset, NCONTOURS defines the required number of lines. GenStat then partitions the range of data values accordingly to give NCONTOURS evenly-spaced contours (or fewer contours if there are insufficient distinct grid values).

   The ANNOTATION option controls how the contours are labelled. The default is to label them by integers (ordinals) if there is a key, and by the actual heights (levels) if there is no key. Contour lines that are very short will not be labelled but their height can be determined from adjacent contours. Each line of the key occupies a space of height 0.02 (in normalized device coordinates), and the key window by default has room for a heading and nine contour levels. If necessary, the size of the window can be redefined using the FRAME directive.

   The way in which the contour lines are drawn is determined by the pen that has been defined by the PENCONTOUR parameter of DCONTOUR; the default is to use pen 1. The relevant aspects of the pen should be set in advance, if required, using the METHOD, COLOUR, LINESTYLE and THICKNESS parameters of the PEN directive.

   If the PENCONTOUR parameter is not used, the plotting method will be line, so that individual contours are made up of straight line segments. If curves are required, METHOD should be set to monotonic to use the method of Butland (1980), or open (or closed) to use the method of McConalogue (1970). Both these methods produce curves that are fitted to independent sets of interpolated points and can thus produce contour lines that cross, particularly if the supplied grid of data is coarse or in a region where the contour height is changing rapidly. If METHOD is set to other values, straight lines will be used to draw the contours.

   The PENHIGHLIGHT parameter can specify a pen to use to highlight particular contours. The frequency of the highlighting is then determined by the HIGHLIGHTFREQUENCY parameter; by default every tenth contour is highlighted.

   The PENFILL parameter defines how to shade the areas between the contours. If this is set to a scalar, the shades are defined in increasing intensities of the colour of the specified pen. Alternatively, if PENFILL is set to a variate of length two, the pens are taken to define the shades at the minimum and maximum heights, and the other shades are interpolated between them. Finally, you can set PENFILL to a variate with more than two values, and the shading uses the pens in the order in which they are given in the variate (recycling if insufficient pens are defined for the total number of contours). By default, there is no shading, that is, the areas between the contours are in the background colour.

   By default, the axis bounds are determined from the grid. Normally the lower bound for each axis will be 1.0 and the upper bound will be the number of rows of the grid for the y-axis, and the number of columns for the x-axis. If a matrix is used to specify the grid, its row and column labels can be set to variates whose values will then be used to determine the axis bounds. The XAXIS and YAXIS directives can be used to control how the axes are drawn or, by setting ACTION=hide, to suppress them altogether.

Options: TITLE, WINDOW, KEYWINDOW, YORIENTATION, ANNOTATION, SCREEN, KEYDESCRIPTION, ENDACTION.

Parameters: GRID, PENCONTOUR, PENFILL, PENHIGHLIGHT, HIGHLIGHTFREQUENCY, NCONTOURS, CONTOURS, INTERVAL, DESCRIPTION.

Action with RESTRICT

DCONTOUR takes account of restrictions on any of the variates in a GRID pointer.

References

Butland, J. (1980). A method of interpolating reasonably-shaped curves through any data. Proceedings of Computer Graphics, 80, 409-422.

McConalogue, D.J. (1970). A quasi-intrinsic scheme for passing a smooth curve through a discrete set of points. Computer Journal, 13, 392-396.