DSHADE directive

Plots a shade diagram of 3-dimensional data.

Options

TITLE = text	General title; default *
WINDOW = scalar	Window number for the graph; default 1
KEYWINDOW = scalar	Window number for the key (0 for no key); default 2
YORIENTATION = string token	Y-axis orientation of the plot (reverse, normal); default reve
GRIDMETHOD = string token	How to draw a grid around the elements of the matrix (present, complete); default pres
PENGRID = scalar	Pen to use for the grid; default -7
SCREEN = string token	Whether to clear the screen before plotting or to continue plotting on the old screen (clear, keep); default clea
KEYDESCRIPTION = text	Overall description for the key
ENDACTION = string token	Action to be taken after completing the plot (continue, pause); default * uses the setting from the last DEVICE statement

Parameters

GRID = symmetric matrix, matrix, table or pointer to variates	Data to be plotted
PEN = scalar or variate	How to draw each shade
LIMITS = variate	Boundary values for changes in shade
NGROUPS = scalar	Number of groups to form from the data values (i.e. number of different shades)
INTERVAL = scalar	Interval between changes in shade
DESCRIPTION = text	Annotation for key

Description

DSHADE produces a shaded representation of a rectangular or symmetric matrix using high-resolution graphics. Each element of the data matrix is represented by a shaded rectangle indicating the value at that location, using its colour. This type of display is often used in a cluster analysis to display a similarity matrix, but it is also useful for the graphical display of spatial data.

The data are specified by the GRID parameter, in either a matrix, a symmetric matrix (e.g. of similarities), a 2-way table or a pointer to a set of variates.

The range of data values corresponding to each shade are determined using the NGROUPS, the LIMITS or the INTERVAL parameter. The first possibility is to set LIMITS to a variate defining the boundaries on the data values where the shades change. Alternatively, if LIMITS is unset, NGROUPS can be used to define the required number of shades; Genstat then partitions the range of data values into that number of equal intervals (and shades each interval in a different way). Or, if both NGROUPS and LIMITS are unset, INTERVAL can set the interval between each change in shade. Finally, if none of these parameters is set, Genstat uses a different shade for each distinct data value. Missing values are ignored, thus leaving blank areas in the plot.

By default, the shades are drawn using pens 1, 2 onwards, with pen 1 being used for the lowest data values. Alternatively, you can specify the pen or pens explicitly, using the PEN parameter. If PEN is set to a scalar, the shades are defined in increasing intensities of the colour of the specified pen. Alternatively, if PEN is set to a variate of length two, the pens are taken to define the shades of the minimum and maximum data values, and the other shades are interpolated between them. Finally, you can set PEN to a variate with more than two values, and the shades use the pens in the order in which they are given in the variate (recycling if insufficient pens are defined for the total number of shades).

The shades are controlled by the current COLOUR settings of the pens. If the default settings do not produce a suitable display, these attributes should be set by a PEN statement before using DSHADE.

The GRIDMETHOD option specifies whether an outline should be drawn around each element of the matrix. The default setting, present, produces an outline for all values that are present; i.e. it ignores missing values. This is suitable where data have been sampled over an irregularly shaped area. Alternatively, with the complete setting, an outline is drawn around every element. Setting GRIDMETHOD=* stops the grid being drawn, which may be preferable if there are a large number of elements in the input data. The PENGRID option specifies which pen to use to draw the grid. The default is to use pen -7.

The YORIENTATION option controls the orientation of the y-axis. By default this is reversed, so that the data are in the same order as they would take if the data matrix were printed.

The TITLE, WINDOW, SCREEN and ENDACTION options are used to specify a title, the plotting window, whether the screen should be cleared first, and whether there should be a pause once the plotting is finished; as in other graphics directives (see, for example, DGRAPH). Similarly, the KEYWINDOW and KEYDESCRIPTION options and the DESCRIPTION parameters allow a key to be defined, if feasible for these plots with the current graphics device.

Options: TITLE, WINDOW , KEYWINDOW , YORIENTATION, GRIDMETHOD, PENGRID, SCREEN, KEYDESCRIPTION, ENDACTION.

Parameters: GRID, PEN, LIMITS, NGROUPS, INTERVAL, DESCRIPTION.

Action with RESTRICT

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

See also

Directives: DBITMAP, DCONTOUR, DSURFACE, D3HISTOGRAM, FRAME, XAXIS, YAXIS, PEN, MATRIX, POINTER, SYMMETRICMATRIX, TABLE.

Procedure: DXYDENSITY.

Commands for: Graphics.

Example

" Example 1:6.4.2 and Figure 1:6.4.2 "
SYMMETRIC [ROWS=!t(Estate,'Arna1.5','Alfa2.5',Mondialqc,\
          Testarossa,Croma,Panda,Regatta,Regattad,Uno,\
          X19,Contach,Delta,Thema,Y10,Spider)] Carsim
READ      Carsim
 1.000
 0.976 1.000
 0.815 0.800 1.000
 0.576 0.546 0.762 1.000
 0.389 0.355 0.561 0.827 1.000
 0.794 0.776 0.762 0.768 0.567 1.000
 0.820 0.855 0.618 0.296 0.103 0.546 1.000
 0.981 0.969 0.823 0.589 0.394 0.820 0.801 1.000
 0.839 0.822 0.675 0.525 0.329 0.756 0.756 0.844 1.000
 0.884 0.909 0.693 0.409 0.211 0.650 0.960 0.866 0.815
 1.000
 0.870 0.858 0.828 0.578 0.425 0.602 0.758 0.836 0.700
 0.787 1.000
 0.462 0.432 0.618 0.709 0.885 0.440 0.215 0.458 0.309
 0.302 0.531 1.000
 0.959 0.951 0.837 0.585 0.393 0.814 0.813 0.959 0.806
 0.871 0.826 0.471 1.000
 0.785 0.765 0.754 0.774 0.571 0.987 0.529 0.811 0.748
 0.637 0.591 0.440 0.802 1.000
 0.895 0.924 0.692 0.377 0.190 0.621 0.929 0.875 0.740
 0.925 0.830 0.305 0.884 0.605 1.000
 0.778 0.761 0.823 0.746 0.583 0.782 0.629 0.772 0.706
 0.673 0.860 0.506 0.788 0.772 0.704 1.000 :
FRAME  1; BOX=omit
PEN    9,10; COLOUR='white','blue'
DSHADE Carsim; INTERVAL=0.1; PEN=!(9,10)