Produces histograms using character (i.e. line-printer) graphics.

### Options

`CHANNEL` = scalar |
Channel number of output file; default is the current output file |
---|---|

`TITLE` = text |
General title; default `*` |

`LIMITS` = variate |
Variate of group limits for classifying variates into groups; default `*` |

`NGROUPS` = scalar |
When `LIMITS` is not specified, this defines the number of groups into which a data variate is to be classified; default is the integer value nearest to the square root of the number of values in the variate |

`LABELS` = text |
Group labels |

`SCALE` = scalar |
Number of units represented by each character; default 1 |

### 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 number of units in each group |
---|---|

`NOBSERVATIONS` = tables |
One-way table to save numbers in the groups |

`GROUPS` = factors |
Factor to save groups defined from a variate |

`SYMBOLS` = texts |
Characters to be used to represent the bars of each histogram |

`DESCRIPTION` = texts |
Annotation for key |

### Description

Histograms provide quick and simple visual summaries of data values. The data are divided into several groups, which are then displayed as a histogram consisting of a line of asterisks for each group. The number of asterisks in each line is proportional to the number of values assigned to that group; this figure is also printed at the beginning of each line. `LPHISTOGRAM`

plots histograms in “line-printer” format, that is, using the characters of ordinary output rather than a high-resolution graphics display. It was added in Release 10 as a synonym of the earlier `HISTOGRAM`

directive, which may become a command for high-resolution graphics in a future release.

The data for the histogram are specified using the `DATA`

parameter in either variates, factors or one-way tables. If a histogram is to be formed from a variate, Genstat sorts its values into groups as defined by upper and lower bounds. You can also specify a list of variates, to obtain a parallel histogram. For each group one row of asterisks is printed for each variate, labelled by the corresponding identifier. The variates are sorted according to the same intervals; there is no need for them all to have the same numbers of values.

With variates of data, you can use the `NGROUPS`

option to specify the number of groups in the histogram; Genstat will then work out appropriate limits, based on the range of the data, to form intervals of equal width. For example:

`LPHISTOGRAM [NGROUPS=5] Data`

Alternatively, you can define the groups explicitly, by setting the `LIMITS`

option to a variate containing the group limits. For example:

`VARIATE [VALUES=1,2,3,5,7,8,10] Glimits`

`LPHISTOGRAM [LIMITS=Glimits] Data`

`Glimits`

is a variate with seven values, producing a histogram in which the data are split into eight groups; ≤1, 1-2, 2-3, 3-5, 5-7, 7-8, 8-10, >10. The upper limit of each group is included within that group, so the group 3-5, for example, contains values that are greater than 3 and less than or equal to 5. The values of the limits variate are sorted into ascending order if necessary, but the variate itself is not changed.

You can use the `LABELS`

option to provide your own labelling for the groups of the histogram. It should be set to a text vector of length equal to the number of groups. If neither `NGROUPS`

nor `LIMITS`

has been set, the number of groups is determined from the number of values in the `LABELS`

structure. If `LABELS`

is also unset, the default number of groups is chosen as the integer value nearest to the square root of the number of values, up to a maximum of 10. Alternatively, procedure `AKAIKEHISTOGRAM`

provides a more sophisticated method of generating histograms, using Akaike’s Information Criterion (AIC) to generate an optimal grouping of the data.

The data for the histogram can also be specified as a factor (which defines the assignment of each unit to a group of the histogram). Genstat then counts the number of units that occur with each level of the factor; thus the number of groups of the histogram is the number of levels of the factor and the value for each group is the corresponding total. If the `LABELS`

option is unset, the labels of the factor (if present) are used to label the groups, otherwise Genstat uses the factor levels.

When Genstat plots the histogram of a one-way table, the number of groups is the number of levels of the factor classifying the table and the values of the table indicate the number of observations in each group. If the `LABELS`

option is unset, the labels or levels of the classifying factor are again used to label the histogram.

When producing a parallel histogram the data structures must all be of the same type: variate, factor or table. If parallel histograms are to be formed from several factors, they must all have the same number of levels, and the labels or levels of the first factor will be used to identify the groups. Likewise, if you are forming parallel histograms from several tables, they must all have the same number of values, and the classifying factor of the first table will define the labelling of the histogram.

The `SYMBOLS`

parameter can specify alternative plotting characters to be used instead of the asterisk. For example:

`LPHISTOGRAM Variate; SYMBOLS='+'`

You can specify a different string for each structure in a parallel histogram. If you specify strings of more than one character, Genstat uses the characters in order, recycled as necessary, until each histogram bar is of the correct length.

The `TITLE`

option lets you set an overall title for the output, and the `DESCRIPTION`

parameter can be used to provide a text for labelling the histogram instead of the identifiers of the `DATA `

structures.

Normally one asterisk will represent one unit. However, if there are many data values and the groups become large, Genstat may not be able to fit enough asterisks into one row. It will then alter the scaling so that one asterisk represents several units. You can set the scaling explicitly using the `SCALE`

option; the value specified is rounded to the nearest integer, and determines how many units should be represented by each asterisk.

`LPHISTOGRAM`

has two output parameters that allow you to save information that has been generated during formation of the histogram. The `NOBSERVATIONS`

parameter allows you to save a one-way table of counts that contains the number of observations that were assigned to each group; the missing-value cell of this table will contain a count of the number of units that were missing and that therefore remain unclassified. When producing a histogram from a variate, you can use the `GROUPS`

parameter to specify a factor to record the group to which each unit was allocated.

Normally, output goes to the current output channel, but you can use the `CHANNEL`

option to direct it to another. For example, when you are working interactively, you might want to send a graph to a secondary output file so that you can print it later. Unlike some directives (for example, `PRINT`

) you cannot save the output in a text structure.

Options: `CHANNEL`

, `TITLE`

, `LIMITS`

, `NGROUPS`

, `LABELS`

, `SCALE`

.

Parameters: `DATA`

, `NOBSERVATIONS`

, `GROUPS`

, `SYMBOLS`

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

, `DHISTOGRAM`

, `LPGRAPH`

, `LPCONTOUR`

.

Commands for: Graphics.

### Example

" Examples 1:6.10.2a-e " VARIATE Data READ Data 1 1 1 2 2 1 4 3 6 5 4 2 6 8 0 9 7 4 3 2 4 6 9 4 5: LPHISTOGRAM Data VARIATE Data2 READ Data2 1 1 1 2 2 2 3 3 3 3 4 4 4 4 4 4 5 5 5 6 6 6 6 2 2 2 2 3 1 4 1 7 8 0 1 3 3 1 0 5: LPHISTOGRAM Data,Data2 VARIATE [VALUES=1,2,3,5,7,8,10] Glimits LPHISTOGRAM [LIMITS=Glimits] Data TEXT [VALUES=apple,banana,peach,cherry,pear,orange] Name FACTOR [LEVELS=6; LABELS=Name; NVALUES=32] Fruit READ Fruit 4 6 3 4 1 6 3 3 6 4 3 5 3 5 1 5 1 6 3 4 4 5 5 5 6 3 6 2 2 5 5 3: LPHISTOGRAM Fruit LPHISTOGRAM Data; SYMBOLS='X-O-'