Draws histograms or bar charts on a plotter or graphics monitor.
||General title; default
||Window number for the histograms; default 1|
||Window number for the key (zero for no key); default 2|
||Variate of group limits for classifying
||Whether to plot the histogram with bars of equal width (
||What proportion of the space allocated along the x-axis each bar should occupy; default
||Width of bar for which one unit of bar length represents one unit of data; default
||Group labels; default
||Whether or not the bars of the histograms are appended together (
||Direction of the plot (
||Where to draw outlines (
||Pen to use for the outlines; default -8|
||Whether to clear the screen before plotting or to continue plotting on the old screen (
||Overall description for the key; default
||Action to be taken after completing the plot (
||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|
||One-way table to save numbers in the groups|
||Factor to save groups defined from a variate|
||Pen number(s) for each histogram; default
||Annotation for key|
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
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
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 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
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).
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.
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
KEYDESCRIPTION options respectively.
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.
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
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.
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
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
YAXIS directives to set the required attributes before the
DHISTOGRAM directive is used.
WINDOW parameter of
YAXIS should be set to the window in which the histogram is to be plotted (controlled by the
WINDOW option of
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
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.
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
" 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