1. Home

Plots a shade diagram of 3-dimensional data.

### Options

`TITLE` = text General title; default `*` Window number for the graph; default 1 Window number for the key (0 for no key); default 2 Y-axis orientation of the plot (`reverse`, `normal`); default `reve` How to draw a grid around the elements of the matrix (`present`, `complete`); default `pres` Pen to use for the grid; default -7 Whether to clear the screen before plotting or to continue plotting on the old screen (`clear`, `keep`); default `clea` Overall description for the key 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 How to draw each shade Boundary values for changes in shade Number of groups to form from the data values (i.e. number of different shades) Interval between changes in shade 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.

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,\
X19,Contach,Delta,Thema,Y10,Spider)] 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'