Draws histograms or bar charts on a plotter or graphics monitor.
Options
TITLE = text |
General title; default * |
|---|---|
WINDOW = scalar |
Window number for the histograms; default 1 |
KEYWINDOW = scalar |
Window number for the key (zero for no key); default 2 |
LIMITS = variate |
Variate of group limits for classifying DATA variates into groups; default * |
LOWER = scalar |
For a DATA variate, this specifies the lower limit of the first bar; default * takes the minimum value of the variate |
UPPER = scalar |
For a DATA variate, this specifies the upper limit of the last bar; default * takes the maximum value of the variate |
NGROUPS = scalar |
When LIMITS and BINWIDTH are not specified, this defines the number of groups into which a DATA variate is to be classified; default is then 10, or the integer value nearest to the square root of the number of values in the variate if that is smaller |
BINWIDTH = scalar |
When LIMITS is unset the range of a DATA variate is split into equal intervals known as “bins” to form the groups, this option can set the bin widths (alternative is to set the number of groups using NGROUPS) |
FIXEDBARWIDTH = string token |
Whether to plot the histogram with bars of equal width (yes, no); default no |
BARCOVERING = scalar |
What proportion of the space allocated along the x-axis each bar should occupy; default * gives proportion 1 for a DATA variate, and 0.8 for a factor or table (thus giving a gap between each bar) |
BARSCALE = scalar |
Width of bar for which one unit of bar length represents one unit of data; default * uses the width of the narrowest bar |
LABELS = text |
Group labels; default * |
APPEND = string token |
Whether or not the bars of the histograms are appended together (yes, no); default no |
ORIENTATION = string token |
Direction of the plot (horizontal, vertical); default vert |
OUTLINE = string token |
Where to draw outlines (bars, perimeter); default bars |
PENOUTLINE = scalar |
Pen to use for the outlines; default -8 |
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
DATA = identifiers |
Data for the histograms; these can be either a factor indicating the group to which each unit belongs, a variate whose values are to be grouped, or a one-way table giving the height of each bar |
|---|---|
NOBSERVATIONS = tables |
One-way table to save numbers in the groups |
GROUPS = factors |
Factor to save groups defined from a variate |
PEN = scalars or variates |
Pen number(s) for each histogram; default * uses pens 2, 3, and so on for the successive structures specified by DATA |
DESCRIPTION = texts |
Annotation for key |
Description
DHISTOGRAM plots high-resolution histograms or bar charts, depending on the input supplied by the DATA parameter: either a list of variates, a list of factors or a list of one-way tables. For a DATA variate, a histogram is produced. This summarizes the distribution of the variate by counting the number of values within a set of intervals defined by the LIMITS, NGROUPS or BINWIDTH options. The histogram contains a “bar” for each interval, with area proportional to the number of values found there. You can define the boundaries between each interval using the LIMITS option. Alternatively, instead of setting LIMITS, you can specify the width of each interval using the BINWIDTH option. Or, instead of setting LIMITS or BINWIDTH, you can specify the number of groups using the NGROUPS option. Finally, if none of these options is set, Genstat defines the number of groups to be 10, or the integer value nearest to the square root of the number of values in the first DATA variate if that is smaller. The range of the histogram is specified by the LOWER and UPPER options. LOWER defines the lower limit of the first interval; by default this is set by making the width of the first bar equal to the width of the second bar, or it is the minimum value of the variates if that would otherwise be below the first bar. UPPER defines the upper limit of the last interval; by default this is set by making the width of the final bar equal to the width of the last-but-one bar, or it is the maximum value of the variates if that would otherwise be above the final bar. The bars are perpendicular to the x-axis, and this is labelled with the positions of the interval boundaries.
If you set DATA to factors or tables, bar charts are produced. However, these can be plotted more conveniently by the BARCHART directive. Bar charts differ from histograms in that there is no longer the concept of dividing the x-axis into a set of contiguous intervals. Instead we have a set of bars located at various positions along the x-axis. The bars are spaced equally along the x-axis. If DATA is set to a list of factors, the bars are labelled by the labels, if available, or otherwise the levels of the first factor. If DATA is set to a list of tables, the labelling is given by the levels/labels of the factor classifying the first table. A DATA table defines the heights of each bars directly (from the value in the corresponding cell of the table). With a factor, Genstat first constructs a table giving the replications of the factor levels. So the height of each bar is equal to the number of units of the factor with the corresponding level of the factor.
The bars in a bar chart always have equal widths. With a histogram, the default is for the bar widths to be equal to the widths of the underlying intervals. However, you can request equal bar widths by setting option FIXEDBARWIDTH=yes. The BARCOVERING option indicates what proportion of the space allocated along the x-axis each bar should occupy. For a histogram the default is 1, while for bar charts it is 0.8 (thus giving a gap between each bar).
The BARSCALE option controls how the lengths of the bars correspond to units of data. The length of each bar is calculated as (data-value × BARSCALE)/bar-width. By default, BARSCALE is set to the width of the narrowest bar. So for that bar, the length will correspond directly to the data units.
The WINDOW option defines the window where the histogram is plotted, and the KEYWINDOW option similarly specifies where the key should appear. You can set either of these to zero if you want to suppress the corresponding output. Titles can be added to the histogram and key using the TITLE and KEYDESCRIPTION options respectively.
The APPEND option controls the form of display to be used when the DATA parameter specifies a list of structures. These parallel histograms can be produced in one of two styles. By default (APPEND=no), the histogram contains a set of bars for each structure, drawn in parallel groups. Alternatively, if you set APPEND=yes, the bars for the structures are concatenated into a single bar for each group. The bottom portion of each bar then corresponds to the first structure, and the top to the last structure.
The ORIENTATION option controls whether the bars of the histogram are plotted vertically (the default) or horizontally. 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 histogram is oriented.
The bars for each structure are all shaded according to the pen or pens that have been specified for that structure, using the PEN parameter. You can set PEN to a scalar to define a single pen to be used for all the bars, or to a variate to define a different pen for each bar. If PEN is not set, Genstat uses the pens in turn, pen 2 for the first structure, pen 3 for the second structure, and so on, so that a different shading is used for each structure. The relevant aspects of the pens should be set in advance, if required, using the COLOUR parameters of the PEN directive. Generally, however, the default attributes of the pens will be satisfactory.
The OUTLINE option controls whether lines are drawn around the bars or around the perimeter of the histogram. These are drawn using the pen specified by the PENOUTLINE option (default -8). You can suppress all the outlines by setting OUTLINE=*.
The axes of the histogram are formed automatically from the data. By default, the upper bound of the y-axis is set to be five percent greater than the height of the longest bar. If any of the bars has a negative height the lower bound is adjusted in a similar way, otherwise it is set to zero. As already mentioned, when the histogram is formed from a variate, the x-axis markings are set to indicate the limits of each bar or set of bars; when the data are provided in a factor the factor labels or levels are used to label the histogram bars, and when the bar heights are provided directly in a table the classifying factor of the table is used. You can control the form of the axes by using the XAXIS and YAXIS directives to set the required attributes before the DHISTOGRAM directive is used.
The WINDOW parameter of XAXIS and YAXIS should be set to the window in which the histogram is to be plotted (controlled by the WINDOW option of DHISTOGRAM). The TITLE, LOWER, UPPER, MARKS and LABELS parameters control annotation. The UPPER parameter of YAXIS is particularly useful when you are plotting a series of histograms; by setting UPPER to a value larger than any of the bars in any of the histograms, you can ensure that they are all plotted on the same scale.
The histogram key consists of the title, if set by KEYDESCRIPTION, followed by a legend for each structure plotted. This consists of a small rectangle that is drawn in the same colour as that used in the histogram, followed by the identifier name or the piece of text specified by the DESCRIPTION parameter.
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.
Options: TITLE, WINDOW, KEYWINDOW, LIMITS, LOWER, UPPER, NGROUPS, BINWIDTH, FIXEDBARWIDTH, BARCOVERING, BARSCALE, LABELS, APPEND, ORIENTATION, OUTLINE, PENOUTLINE, SCREEN, KEYDESCRIPTION, ENDACTION.
Parameters: DATA, NOBSERVATIONS, GROUPS, PEN, DESCRIPTION.
Action with RESTRICT
You can restrict a DATA variate or factor to form a histogram for only a subset of the units. However, the restriction does not carry over to any other variates or factors listed by the DATA parameter.
See also
Directives: BARCHART, D3HISTOGRAM, DPIE, LPHISTOGRAM, FRAME, XAXIS, YAXIS, PEN.
Procedures: TRELLIS, DMOSAIC, DOTHISTOGRAM, DOTPLOT, DCIRCULAR, WINDROSE.
Commands for: Graphics.
Example
" Example DHIS-1: A histogram of five variates in parallel" FILEREAD [NAME='%gendir%/examples/DHIS-1.DAT'] X1,X2,X3,X4,X5 " By default, DHISTOGRAM will use pen 1 for the first variate, pen 2 for the second, and so on." PEN 2...6; TAREA=100 DHISTOGRAM [TITLE='Parallel Histogram';NGROUP=4] X1,X2,X3,X4,X5