HISTOGRAM command

Used to group records based on values in a character or numeric field, count the number of records in each group, and display 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|NEXT range>
<HEADER header_text> <FOOTER footer_text> <KEY break_field> <SUPPRESS>
<COLUMNS number> <APPEND> <LOCAL> <OPEN>

Parameters

ON character_field

Specifies the character field or expression to use for the histogram. The ON parameter can be omitted.

ON numeric_field

Specifies the numeric field or expression to use for the histogram. The ON parameter can be omitted.

MINIMUM value

Applies to numeric fields only. Specifies the minimum value of the first numeric interval. MINIMUM is optional if you are using the FREE parameter, otherwise it is required.

MAXIMUM value

Applies to numeric fields only. Specifies the maximum value of the last numeric interval. MAXIMUM is optional if you are using the FREE parameter, otherwise it is required.

INTERVALS number

Optional. Applies to numeric fields only. Specifies the number of equal-sized intervals ACL 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. Allows you to create 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. For example, FREE -1000, 0, 1000, 2000, 3000

If you specify both the FREE parameter and the INTERVALS parameter, the INTERVALS parameter is ignored.

TO SCREEN | filename | GRAPH | PRINT
  • Specify TO SCREEN to display the results in the ACL display area. This is the default output if the TO parameter is not specified.

  • Specify TO filename to save the results to a file. You must specify the filename value as a quoted string with the appropriate file extension. For example, specify the .TXT file extension to create a text file.

    For example: TO "Output.TXT"

    You can also specify an absolute or relative file path to save the file to an existing folder.

    For example: TO "C:\Output.TXT" or TO "Results\Output.TXT"

  • Specify TO PRINT to send the results to the default printer.

  • Specify TO GRAPH to display the results in a graph in the ACL display area.

IF test

Optional. Specifies a condition that must be met. The command is executed on only those records that meet the condition.

WHILE test

Optional. Specifies that the command is executed only while a condition is true. The command processing terminates as soon as the specified condition evaluates as false, or the end of the table is reached.

FIRST | NEXT range

Optional. Specify FIRST to start processing at the first record or NEXT to start processing at the currently selected record. Use the range value to specify the number of records to process.

HEADER header_text

Optional. Specifies the text to insert at the top of each page of a report. The header_text value must be specified as a quoted string. The value overrides any value set for the ACL HEADER system variable.

FOOTER footer_text

Optional. Specifies the text to insert at the bottom of each page of a report. The footer_text value must be specified as a quoted string. The value overrides any value set for the ACL FOOTER system variable.

KEY break_field

Optional. Specifies that a subtotal is calculated each time the value of the specified field or expression changes. You can specify only one field, but you can create and specify an expression that contains more than one field. The break_field must be a character field or expression.

SUPPRESS

Optional. Specifies that values above the MAXIMUM value and below the MINIMUM value are excluded from the command output.

COLUMNS number

Optional. If you output histogram results to a text file, specifies the length of the x-axis in the textual representation of the bar chart. 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 the COLUMNS parameter, the default of 78 character spaces is used.

APPEND

Optional. Specifies that command output is appended to the end of an existing file instead of overwriting it. When using this parameter, you must ensure that the structure of the command output and the existing file is identical, if maintaining a consistent file structure is important (for example, when you are appending data to an existing ACL table), because ACL appends output to an existing file regardless of its structure.

LOCAL

Optional. Specifies that the output file is saved in the same location as the ACL project. This parameter only applies when the command is run on an ACL Server table and the output file is an ACL table.

OPEN

Optional. Specifies that the table created by the command is opened after the command executes. This parameter is only valid if the command creates an output table.

Remarks

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 ACL, histograms do not support subtotaling numeric fields.

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.

Histogram results output to a file appear as a textual representation of a bar chart.

Examples

a. Basic histogram for hourly salary

The following example uses the HISTOGRAM command 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

b.Histogram with defined intervals for hourly salary

The following example refines the HISTOGRAM command 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 three intervals in this range, and only one for 0-20, one for 50-100, and one for > 100.

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



(C) 2015 ACL Services Ltd. All Rights Reserved.