1. Home
  2. DOTHISTOGRAM procedure

DOTHISTOGRAM procedure

Plots dot histograms (L.H. Schmitt & A.R.G. McLachlan).

Options

TITLE = text Title for the plot; default * i.e. none
AXISTITLE = text Title for the axis representing the data values; default * uses the name of the DATA variate if there is only one, otherwise no title
WINDOW = scalar Window for the plot; default * uses window 1 when PEN is set, and window 3 when PEN is unset
ORIENTATION = string token Direction of the plot (horizontal, vertical); default vert
YORIENTATION = string token Direction of the y-axis for horizontal plots (reverse, normal); default reve
SCREEN = string token Whether to clear screen before displaying chart (keep, clear); default clea
JUSTIFICATION = string token How to position the dots; (right, left, centre, center, bottom, top, backtoback); default cent
CREATEMISSINGLEVEL = text Whether to create a level for missing GROUPS data (yes, no); default no
OMITEMPTYLEVELS = text Whether to omit levels of GROUPS for which there are no DATA values to plot (yes, no); default no
SIZE = scalar Size of the pen used to plot the dots; default 1
KEYWINDOW = scalar Window to use for a key when PEN is set; default 2
KEYDESCRIPTION = text Overall title for a key when PEN is set; default * uses name of PEN data structure

Parameters

DATA = variates or pointers Data to be plotted
GROUPS = factors Factor to divide values of a DATA variate into groups
COLOURS = scalars, variates, texts or factors Colours for the histograms in each plot, a scalar to use the same colour for all the histograms, or a variate or factor to plot each histogram in a different colour; default 'black'
NOBSERVATIONS = tables Save tables of count
PEN = variates, factors or pointers Pens to define colours for the individual dots; default uses those defined by the COLOURS parameter
DESCRIPTION = texts Annotation for key when PEN is set; default uses unique values of PEN

Description

Dot histograms display each observation in a set of values as a dot. The observations are allocated to bins of equal range, and all the observations in a bin are plotted in a row. The values are supplied by the DATA parameter. If this is a variate and the GROUPS parameter is set, then dot histograms are plotted side-by-side, one for each level of the grouping factor. If DATA is set to a pointer of variates, a dot histogram is plotted for each variate, side-by-side, and the GROUPS parameter is ignored.

You can control the colours of the dots, using either the COLOURS or the PEN parameter. The COLOURS parameter defines the colour of a whole histogram. You can specify a scalar or single-valued text to define the colour to be used for all the dot histogram in the plot, or you can supply a variate, text or factor, with a different value for each dot histogram in the plot. The PEN parameter specifies the colours by specifying a pen for every dot in the display, and over rides the COLOURS parameter if both are specified. (Each colour is taken from that defined for the pen concerned; other pen settings like the symbol are ignored.) So, PEN must be set to a variate or a factor if DATA is set to a variate. Alternatively, if DATA is set to a pointer, PEN too must be set to pointer, containing either a set of variates, or a set of factors (one for each variate in the DATA pointer).

The NOBSERVATIONS parameter can save a two-way table of the number of dots in each row for each dot histogram in the plot.

By default, the dot histograms are plotted vertically with a row for each bin arranged along the y-axis, but you can set option ORIENTATION=horizontal to plot the histograms horizontally and the dots are then in columns. When ORIENTATION=horizontal, the horizontal axis is taken to be the y-axis, so the same XAXIS and YAXIS settings can be used however the histograms are oriented. Rows of dots in each dot histogram are usually centred on the x-axis but the JUSTIFICATION option gives control over this. They can be either centred (the default), right justified, left justified, top justified, bottom justified, or back-to-back to plot adjacent dot histograms back to back. The left and right settings and the top and bottom settings are provided for vertical and horizontal dot histograms, respectively, but left and bottom are synonyms, as are right and top. The YORIENTATION option controls the orientation of the y-axis when the histograms are plotted horizontally. By default this is reversed, so that the first histogram is at the top of the screen.

The TITLE and the AXISTITLE options can supply titles for the graph and for the axis along which the values are displayed (i.e. the y-axis when ORIENTATION=vertical). The WINDOW option specifies the window to use for the plot. The default is to use window 3 if PEN has not been set. Alternatively, if PEN has been set, the default is to use window 1, and the KEYWINDOW option specifies the window to use for a key (default 2). The KEYDESCRIPTION option can supply an overall title for the key. The default is to use the name of PEN data structure. The DESCRIPTION parameter can specify the annotation for key. With PEN variates, the default annotation uses their the unique values. With PEN factors it uses their labels if available, or otherwise their levels. The SCREEN option controls whether or not the screen is cleared before plotting.

Usually any units with missing values in the GROUPS factor are ignored, but you can set option CREATEMISSINGLEVEL=yes to create a level for these units. Also, by default, a null (blank) dot histogram is included for levels of the GROUPS factor that are unrepresented in the DATA variate but you can set option OMITEMPTYLEVELS=yes to omit these. This will also omit null dot histograms for variates with no observations in a DATA pointer. Option SIZE can be used to make the dots smaller or larger. This can alter the number of bins into which the data set is divided. The value of SIZE is reduced if the supplied value would cause dots to overlap.

Options: TITLE, AXISTITLE, WINDOW, ORIENTATION, YORIENTATION, SCREEN, JUSTIFICATION, CREATEMISSINGLEVEL, OMITEMPTYLEVELS, SIZE, KEYWINDOW, KEYDESCRIPTION.
Parameters: DATA, GROUPS, COLOURS, NOBSERVATIONS, PEN, DESCRIPTION.

Method

The dot histograms are plotted by DGRAPH, using the solid dot symbol. The colours of the histograms are defined by using the settings from the COLOURS parameter of DOHISTOGRAM in the COLOUR parameter of the PEN directive. See PEN for details of how Genstat interprets strings (defined by a text setting) or numbers (defined by a scalar or variate, or by the levels of a factor setting) as colours.

Action with RESTRICT

DATA variates or the GROUPS factor can be restricted to exclude units from the plot. Restrictions on PEN are ignored.

See also

Directive: DHISTOGRAM.
Procedures: BOXPLOT, DOTPLOT, STEM.
Commands for: Graphics.

Example

CAPTION      'DOTHISTOGRAM example','Fisher''s Iris data'; STYLE=meta,plain
FACTOR       [NVALUES=150; LABELS=!t(Setosa,Versicolor,Virginica);\ 
             VALUES=50(1,2,3)] Species
VARIATE      [NVALUES=150] Sepal_L,Sepal_W,Petal_L,Petal_W
POINTER      [VALUES=Sepal_L,Sepal_W,Petal_L,Petal_W] Measures
READ         Measures[]
 5.1  3.5  1.4  0.2
 4.9  3.0  1.4  0.2
 4.7  3.2  1.3  0.2
 4.6  3.1  1.5  0.2
 5.0  3.6  1.4  0.2
 5.4  3.9  1.7  0.4
 4.6  3.4  1.4  0.3
 5.0  3.4  1.5  0.2
 4.4  2.9  1.4  0.2
 4.9  3.1  1.5  0.1
 5.4  3.7  1.5  0.2
 4.8  3.4  1.6  0.2
 4.8  3.0  1.4  0.1
 4.3  3.0  1.1  0.1
 5.8  4.0  1.2  0.2
 5.7  4.4  1.5  0.4
 5.4  3.9  1.3  0.4
 5.1  3.5  1.4  0.3
 5.7  3.8  1.7  0.3
 5.1  3.8  1.5  0.3
 5.4  3.4  1.7  0.2
 5.1  3.7  1.5  0.4
 4.6  3.6  1.0  0.2
 5.1  3.3  1.7  0.5
 4.8  3.4  1.9  0.2
 5.0  3.0  1.6  0.2
 5.0  3.4  1.6  0.4
 5.2  3.5  1.5  0.2
 5.2  3.4  1.4  0.2
 4.7  3.2  1.6  0.2
 4.8  3.1  1.6  0.2
 5.4  3.4  1.5  0.4
 5.2  4.1  1.5  0.1
 5.5  4.2  1.4  0.2
 4.9  3.1  1.5  0.2
 5.0  3.2  1.2  0.2
 5.5  3.5  1.3  0.2
 4.9  3.6  1.4  0.1
 4.4  3.0  1.3  0.2
 5.1  3.4  1.5  0.2
 5.0  3.5  1.3  0.3
 4.5  2.3  1.3  0.3
 4.4  3.2  1.3  0.2
 5.0  3.5  1.6  0.6
 5.1  3.8  1.9  0.4
 4.8  3.0  1.4  0.3
 5.1  3.8  1.6  0.2
 4.6  3.2  1.4  0.2
 5.3  3.7  1.5  0.2
 5.0  3.3  1.4  0.2
 7.0  3.2  4.7  1.4
 6.4  3.2  4.5  1.5
 6.9  3.1  4.9  1.5
 5.5  2.3  4.0  1.3
 6.5  2.8  4.6  1.5
 5.7  2.8  4.5  1.3
 6.3  3.3  4.7  1.6
 4.9  2.4  3.3  1.0
 6.6  2.9  4.6  1.3
 5.2  2.7  3.9  1.4
 5.0  2.0  3.5  1.0
 5.9  3.0  4.2  1.5
 6.0  2.2  4.0  1.0
 6.1  2.9  4.7  1.4
 5.6  2.9  3.6  1.3
 6.7  3.1  4.4  1.4
 5.6  3.0  4.5  1.5
 5.8  2.7  4.1  1.0
 6.2  2.2  4.5  1.5
 5.6  2.5  3.9  1.1
 5.9  3.2  4.8  1.8
 6.1  2.8  4.0  1.3
 6.3  2.5  4.9  1.5
 6.1  2.8  4.7  1.2
 6.4  2.9  4.3  1.3
 6.6  3.0  4.4  1.4
 6.8  2.8  4.8  1.4
 6.7  3.0  5.0  1.7
 6.0  2.9  4.5  1.5
 5.7  2.6  3.5  1.0
 5.5  2.4  3.8  1.1
 5.5  2.4  3.7  1.0
 5.8  2.7  3.9  1.2
 6.0  2.7  5.1  1.6
 5.4  3.0  4.5  1.5
 6.0  3.4  4.5  1.6
 6.7  3.1  4.7  1.5
 6.3  2.3  4.4  1.3
 5.6  3.0  4.1  1.3
 5.5  2.5  4.0  1.3
 5.5  2.6  4.4  1.2
 6.1  3.0  4.6  1.4
 5.8  2.6  4.0  1.2
 5.0  2.3  3.3  1.0
 5.6  2.7  4.2  1.3
 5.7  3.0  4.2  1.2
 5.7  2.9  4.2  1.3
 6.2  2.9  4.3  1.3
 5.1  2.5  3.0  1.1
 5.7  2.8  4.1  1.3
 6.3  3.3  6.0  2.5
 5.8  2.7  5.1  1.9
 7.1  3.0  5.9  2.1
 6.3  2.9  5.6  1.8
 6.5  3.0  5.8  2.2
 7.6  3.0  6.6  2.1
 4.9  2.5  4.5  1.7
 7.3  2.9  6.3  1.8
 6.7  2.5  5.8  1.8
 7.2  3.6  6.1  2.5
 6.5  3.2  5.1  2.0
 6.4  2.7  5.3  1.9
 6.8  3.0  5.5  2.1
 5.7  2.5  5.0  2.0
 5.8  2.8  5.1  2.4
 6.4  3.2  5.3  2.3
 6.5  3.0  5.5  1.8
 7.7  3.8  6.7  2.2
 7.7  2.6  6.9  2.3
 6.0  2.2  5.0  1.5
 6.9  3.2  5.7  2.3
 5.6  2.8  4.9  2.0
 7.7  2.8  6.7  2.0
 6.3  2.7  4.9  1.8
 6.7  3.3  5.7  2.1
 7.2  3.2  6.0  1.8
 6.2  2.8  4.8  1.8
 6.1  3.0  4.9  1.8
 6.4  2.8  5.6  2.1
 7.2  3.0  5.8  1.6
 7.4  2.8  6.1  1.9
 7.9  3.8  6.4  2.0
 6.4  2.8  5.6  2.2
 6.3  2.8  5.1  1.5
 6.1  2.6  5.6  1.4
 7.7  3.0  6.1  2.3
 6.3  3.4  5.6  2.4
 6.4  3.1  5.5  1.8
 6.0  3.0  4.8  1.8
 6.9  3.1  5.4  2.1
 6.7  3.1  5.6  2.4
 6.9  3.1  5.1  2.3
 5.8  2.7  5.1  1.9
 6.8  3.2  5.9  2.3
 6.7  3.3  5.7  2.5
 6.7  3.0  5.2  2.3
 6.3  2.5  5.0  1.9
 6.5  3.0  5.2  2.0
 6.2  3.4  5.4  2.3
 5.9  3.0  5.1  1.8  :
DOTHISTOGRAM Petal_L; GROUPS=Species
&            Measures; COLOURS=!t(Red,LimeGreen,Blue,Aqua)
Updated on September 5, 2019

Was this article helpful?