D3HISTOGRAM directive

Plots three-dimensional histograms.

Options

TITLE = text	General title; default *
WINDOW = scalar	Window number for the plots; default 1
KEYWINDOW = scalar	Window number for the key (zero for no key); default 2
ELEVATION = scalar	The elevation of the viewpoint relative to the surface; default 25 (degrees)
AZIMUTH = scalar	Rotation about the horizontal plane; the default of 225 degrees ensures that, with a square matrix M, the element M$[1;1] is nearest to the viewpoint
DISTANCE = scalar	Distance of the viewpoint from the centre of the grid on the base plane; default * gives a distance of 100 times the maximum of the x-range and the y-range
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; default *
ENDACTION = string token	Action to be taken after completing the plot (continue, pause); default * uses the setting from the last DEVICE statement

Parameters

GRID = identifier	Pointer (of variates representing the columns of a data matrix), matrix or two-way table specifying values on a regular grid
PEN = scalar	Pen number to be used for the plot; default 3
DESCRIPTION = texts	Annotation for key

Description

D3HISTOGRAM plots a surface as a three-dimensional (or bivariate) histogram. The surface is represented 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 position of the point from which the histogram is viewed is specified in polar coordinates, using the options ELEVATION, DISTANCE and AZIMUTH. These define the angle of elevation, in degrees, above the base plane of the surface, distance from the centre of this plane, and angular position relative to the vertical z-axis, respectively, similarly to the DSURFACE directive.

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.

The PEN parameter specifies the pen to be used to plot the histogram (by default, pen 3). The PEN directive can be used to modify the colour and the thickness of the pen, but the other attributes of the pen are ignored.

Simple axes are drawn to indicate the directions in which x and y increase. The TITLE parameter of the XAXIS and YAXIS directives can be used to add further annotation.

Options: TITLE, WINDOW, KEYWINDOW, ELEVATION, AZIMUTH, DISTANCE, SCREEN, KEYDESCRIPTION, ENDACTION.

Parameters: GRID, PEN, DESCRIPTION.

Action with RESTRICT

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

See also

Directives: DBITMAP, DCONTOUR, DSHADE, DSURFACE, D3GRAPH, BARCHART, DHISTOGRAM, DPIE, LPHISTOGRAM, FRAME, XAXIS, YAXIS, ZAXIS, PEN, MATRIX, POINTER, TABLE.

Procedures: TRELLIS, DBARCHART, DOTHISTOGRAM, DOTPLOT, DCIRCULAR, WINDROSE.

Commands for: Graphics.

Example

" Examples 1:4.11.4a, 1:4.11.4b, 1:4.11.4c, 1:6.4.4 and Figure 6.4.4 "
TEXT [VALUES= Aberdeen,Birmingham,Cardiff,Dundee,Edinburgh,\ 
  Liverpool,Manchester,Sheffield,Swansea] Townname
VARIATE [VALUES=1979,1980,1981,1982,1983,1984] Yearnum
FACTOR  [LABELS=Townname] Town
FACTOR  [LEVELS=Yearnum]  Year; DECIMALS=0
TABLE [CLASSIFICATION=Town,Year] Sales 
READ Sales
608 635 672 692 685 723
618 601 784 720 863 921     
757 743 785 816 783 737     
343 391 358 366 418 470     
714 751 710 763 788 830 
816 859 820 938 1007 1158   
662 632 758 721 893 837     
531 569 615 624 607 593 
416 461 478 462 497 520 :     
PRINT Sales; FIELDWIDTH=8; DECIMALS=0
FACTOR [LABELS=!T(England,Wales,Scotland)] Country
" Form a table Csales, classified by country instead of town."
COMBINE [OLDSTRUCTURE=Sales; NEWSTRUCTURE=Csales]\ 
  OLDDIMENSION=Town; NEWDIMENSION=Country;\ 
  OLDPOSITIONS=!(2,6,7,8,1,4,5,3,9);\ 
  NEWPOSITIONS=!T(4(England),3(Scotland),2(Wales)) 
PRINT Csales; FIELDWIDTH=8; DECIMALS=0
" Form a table classified by country and year,
  including biannual totals."
FACTOR [LABELS=!T('1981','1982','1981-2','1983','1984','1983-4')]\
  Yearsum
TABLE  [CLASSIFICATION=Yearsum,Country] Salesum
COMBINE [OLDSTRUCTURE=Sales; NEWSTRUCTURE=Salesum]\ 
  OLDDIMENSION=Town,Year; NEWDIMENSION=Country,Yearsum;\ 
  OLDPOSITIONS=!(2,6,7,8,1,4,5,3,9),!V((1981...1984)2);\ 
  NEWPOSITIONS=!T(4(England),3(Scotland),2(Wales)),\ 
  !T('1981','1982','1983','1984',2('1981-2','1983-4'))
PRINT Salesum; FIELDWIDTH=8; DECIMALS=0
COMBINE [OLDSTRUCTURE=Csales; NEWSTRUCTURE=Esales]\ 
  OLDDIMENSION=Country; NEWDIMENSION=0; OLDPOSITIONS='England'
PRINT Esales
" Plot 3-d histogram."
PEN   11; SIZE=2; COLOUR='black'
XAXIS 3; PENLABELS=11
YAXIS 3; MARKS=!(1...9); LABELS=Townname; PENLABELS=11
ZAXIS 3; LOWER=0; PENLABELS=11
D3HISTOGRAM [WINDOW=3; KEY=0; ELEVATION=40] Sales
" Restore pen and axis settings."
PEN    [RESET=yes] 11
XAXIS  [RESET=yes] 3
YAXIS  [RESET=yes] 3
ZAXIS  [RESET=yes] 3