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 `BRUSH`

and `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 and brush style 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`

, `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