HISTOGRAM command

Concept Information

Groups records based on values in a character or numeric field, counts the number of records in each group, and displays the groups and counts in a bar chart.

Syntax

HISTOGRAM {<ON> character_field|<ON> numeric_field MINIMUM value MAXIMUM value {<INTERVALS number>|FREE interval_value <...n> last_interval}} <TO {SCREEN|filename|GRAPH|PRINT}> <IF test> <WHILE test> <FIRST range|NEXT range> <HEADER header_text> <FOOTER footer_text> <KEY break_field> <SUPPRESS> <COLUMNS number> <APPEND> <OPEN>

Parameters

Name	Description
ON character_field	The character field or expression to use for the histogram.
ON numeric_field	The numeric field or expression to use for the histogram.
MINIMUM value	Applies to numeric fields only. The minimum value of the first numeric interval. MINIMUM is optional if you are using FREE, otherwise it is required.
MAXIMUM value	Applies to numeric fields only. The maximum value of the last numeric interval. MAXIMUM is optional if you are using FREE, otherwise it is required.
INTERVALS number optional	Applies to numeric fields only. The number of equal-sized intervals Analytics produces over the range specified by the MINIMUM and MAXIMUM values. If you do not specify a number of intervals, the default number is used. The default is specified by the Intervals number on the Command tab in the Options dialog box.
FREE interval_value <...n> last_interval optional	Applies to numeric fields only. Creates custom-sized intervals by specifying the start point of each interval and the end point of the last interval. If you specify MINIMUM and MAXIMUM values, those values are the start point of the first interval and the end point of the last interval, and each interval_value creates an additional interval within the range. The interval values you specify must be greater than the MINIMUM value, and equal to or less than the MAXIMUM value. Interval values must be in numeric sequence and cannot contain duplicate values: FREE -1000, 0, 1000, 2000, 3000 If you specify both FREE and INTERVALS, then INTERVALS is ignored.
TO SCREEN \| filename \| GRAPH \| PRINT	The location to send the results of the command to: SCREEN displays the results in the Analytics display area Tip You can click any linked result value in the display area to drill down to the associated record or records in the source table. filename saves the results to a file Specify filename as a quoted string with the appropriate file extension. For example: TO "Output.TXT" By default, the file is saved to the folder containing the Analytics project. Use either an absolute or relative file path to save the file to a different, existing folder: TO "C:\Output.TXT" TO "Results\Output.TXT" GRAPH displays the results in a graph in the Analytics display area PRINT sends the results to the default printer Note Histogram results output to a file appear as a textual representation of a bar chart.
IF test optional	A conditional expression that must be true in order to process each record. The command is executed on only those records that satisfy the condition. Note The IF parameter is evaluated against only the records remaining in a table after any scope parameters have been applied (WHILE, FIRST, NEXT).
WHILE test optional	A conditional expression that must be true in order to process each record. The command is executed until the condition evaluates as false, or the end of the table is reached. Note If you use WHILE in conjunction with FIRST or NEXT, record processing stops as soon as one limit is reached.
FIRST range \| NEXT range optional	The number of records to process: FIRST start processing from the first record until the specified number of records is reached NEXT start processing from the currently selected record until the specified number of records is reached Use range to specify the number of records to process. If you omit FIRST and NEXT, all records are processed by default.
HEADER header_text optional	The text to insert at the top of each page of a report. header_text must be specified as a quoted string. The value overrides the Analytics HEADER system variable.
FOOTER footer_text optional	The text to insert at the bottom of each page of a report. footer_text must be specified as a quoted string. The value overrides the Analytics FOOTER system variable.
KEY break_field optional	The field or expression that groups subtotal calculations. A subtotal is calculated each time the value of break_field changes. break_field must be a character field or expression. You can specify only one field, but you can use an expression that contains more than one field.
SUPPRESS optional	Values above the MAXIMUM value and below the MINIMUM value are excluded from the command output.
COLUMNS number optional	The length of the x-axis in the textual representation of the bar chart if you output histogram results to a text file. The number value is the number of character spaces (text columns) to use for the x-axis (and the y-axis labels). If you omit COLUMNS, the default of 78 character spaces is used.
APPEND optional	Appends the command output to the end of an existing file instead of overwriting it. Note You must ensure that the structure of the command output and the existing file are identical: the same fields the same field order matching fields are the same length matching fields are the same data type Analytics appends output to an existing file regardless of its structure. If the structure of the output and the existing file do not match, jumbled, missing, or inaccurate data can result.
OPEN optional	Opens the table created by the command after the command executes. Only valid if the command creates an output table.

Examples

Basic histogram for hourly salary

You use HISTOGRAM to create a graph showing the distribution of wages between 0 and 100 dollars per hour:

HISTOGRAM ON Rate MINIMUM 0 MAXIMUM 100 TO GRAPH

Histogram with defined intervals for hourly salary

Continuing from the previous example, you use HISTOGRAM to specify the ranges in the graph in a more meaningful way.

Most of the wages fall between 20 and 50 dollars per hour, so the graph includes the following number of intervals:

three in the 20 to 50 range
one for 0-20
one for 50-100
one for > 100

HISTOGRAM ON Rate MINIMUM 0 MAXIMUM 100 FREE 20,30,40,50,100 TO GRAPH

Remarks

For more information about how this command works, see Creating histograms.

Populating low and high values

You can run the STATISTICS or PROFILE commands on a numeric field before running the HISTOGRAM command to automatically populate the MINIMUM and MAXIMUM parameter values with the lowest and highest values in the field.

Related commands

Creating a histogram using a character field is similar to classifying. Creating a histogram using a numeric field is similar to stratifying.

Unlike the other grouping operations in Analytics, histograms do not support subtotaling numeric fields.