IMSL_FREQTABLE

The IMSL_FREQTABLE function tallies observations into a one-way or two-way frequency table.

This routine requires an IDL Advanced Math and Stats license. For more information, contact your sales or technical support representative.

If Two Positional Arguments are Used

The default action of IMSL_FREQTABLE is to group data into nxbins categories of size (max (x) – min (x))/nxbins. The initial interval is closed on the left and open on the right. The remaining intervals are open on the left and closed on the right. Using keywords, the types of intervals used may be changed.

If UPPER_BOUND and LOWER_BOUND are specified, two semi-infinite intervals are used as the initial and last interval. The initial interval is closed on the right and includes LOWER_BOUND as its right endpoint. The last interval is open on the left and includes all values greater than UPPER_BOUND. The remaining Nxbins – 2 intervals are of length (UPPER_BOUND – LOWER_BOUND)/(Nxbins – 2) and are open on the left and closed on the right. The argument Nxbins must be greater than or equal to 3 for this option.

If the keyword CLASS_MARKS is used, equally spaced class marks in ascending order must be provided in an array of length Nxbins. The class marks are the midpoints of each of the Nxbins, and each interval is taken to have the following length:

(CLASS_MARKS(1) – CLASS_MARKS(0))

The argument Nxbins must be greater than or equal to 2 for this option.

If the keyword CUTPOINTS is used, cutpoints (bounders) must be provided in an array of length Nxbins. This option allows unequal intervals. The initial interval is closed on the right and contains the initial cutpoint as its right endpoint. The last interval is open on the left and includes all values greater than the last cutpoint. The remaining Nxbins - 2 intervals are open on the left and closed on the right. The argument Nxbins must be greater than 3 for this option.

If Four Positional Arguments are Used

By default, Nxbins intervals of equal length are used. Let xmin and xmax be the minimum and maximum values in x, respectively, with similar meanings for ymin and ymax. Then, table(0, 0) is the tally of observations with the x value less than or equal to xmin + (xmax – xmin)/nxbins, and the y value less than or equal to ymin + (ymax–ymin)/ny.

If UPPER_BOUND and LOWER_BOUND are specified, intervals of equal lengths are used just as in the default case, except the upper and lower bounds are taken as supplied keywords xmin = LOWER_BOUND(0), xmax = UPPER_BOUND(0), ymin = LOWER_BOUND(1), and ymax = UPPER_BOUND(1), instead of the actual minima and maxima in the data. Therefore, the first and last intervals for both variables are semi-infinite in length.

If CUTPOINTS is specified, cutpoints (boundaries) must be provided. The keyword CUTPOINTS must be a one-dimensional array of length (Nxbins – 1) + (Nybins– 1) containing the cutpoints for x in the first (Nxbins –1) elements followed by the cutpoints for y in the final (Nxbins –1) elements.

If CLASS_MARKS is specified, equally spaced class marks in ascending order must be provided. The class marks are the midpoints of each interval. The keyword CLASS_MARKS must be a one-dimensional array of length (Nxbins + Nybins) containing the class marks for x in the first Nxbins elements followed by the class marks for y in the final Nxbins elements.

Examples

Example 1: One-way Frequency Table

The data for this example is from Hinkley (1977) and Velleman and Hoaglin (1981). Data includes measurements (in inches) of precipitation in Minneapolis/St. Paul during the month of March for 30 consecutive years.

x = [0.77, 1.74, 0.81, 1.20, 1.95, 1.20, 0.47, 1.43, 3.37, 2.20, $

3.00, 3.09, 1.51, 2.10, 0.52, 1.62, 1.31, 0.32, 0.59, 0.81, $

2.81, 1.87, 1.18, 1.35, 4.75, 2.48, 0.96, 1.89, 0.90, 2.05]

; Define the data set.

table = IMSL_FREQTABLE(x, 10)

; Call IMSL_FREQTABLE with nxbins = 10.

PRINT, ' Bin Number Count' &$

PRINT, ' ---------- -----' &$

FOR i = 0, 9 DO PRINT, i + 1, table(i)

IDL prints:

Bin Number  Count

----------  -----

1           4.00000

21          8.00000

31          5.00000

41          5.00000

51          3.00000

61          1.00000

71          3.00000

81          0.00000

91          0.00000

101         1.00000

Example 2: Two-way Frequency Table

The data for X in this example is the same as in the example above. The data for y were created by adding small integers to x.

nxbins = 5

nybins = 6

; Define the data set.

x = [0.77, 1.74, 0.81, 1.20, 1.95, 1.20, 0.47, 1.43, 3.37, $

2.20, 3.00, 3.09, 1.51, 2.10, 0.52, 1.62, 1.31, 0.32, $

0.59, 0.81, 2.81, 1.87, 1.18, 1.35, 4.75, 2.48, 0.96, $

1.89, 0.90, 2.05]

y = [1.77, 3.74, 3.81, 2.20, 3.95, 4.20, 1.47, 3.43, 6.37, $

3.20, 5.00, 6.09, 2.51, 4.10, 3.52, 2.62, 3.31, 3.32, $

1.59, 2.81, 5.81, 2.87, 3.18, 4.35, 5.75, 4.48, 3.96, $

2.89, 2.90, 5.05]

; Default usage of IMSL_FREQTABLE

table = IMSL_FREQTABLE(x, nxbins, y, nybins)

PM, table, FORMAT = '(6(F8.5, 2X))', $

Title = ' counts'

                    counts

4.00000  2.00000  4.00000  2.00000  0.00000  0.00000

0.00000  4.00000  3.00000  2.00000  1.00000  0.00000

0.00000  0.00000  1.00000  2.00000  0.00000  1.00000

0.00000  0.00000  0.00000  0.00000  1.00000  2.00000

0.00000  0.00000  0.00000  0.00000  0.00000  1.00000

lb = [1, 2]

up = [4, 6]

; Using user-defined bounds

table = IMSL_FREQTABLE(x, nxbins, y, nybins, Upper_Bound = up, $

Lower_Bound = lb)

PM, table, FORMAT = '(6(F8.5, 2X))', $

Title = ' counts'

                    counts

3.00000  2.00000  4.00000  0.00000  0.00000  0.00000

0.00000  5.00000  5.00000  2.00000  0.00000  0.00000

0.00000  0.00000  1.00000  3.00000  2.00000  0.00000

0.00000  0.00000  0.00000  0.00000  0.00000  2.00000

0.00000  0.00000  0.00000  0.00000  1.00000  0.00000

cm = [0.5, 1.5, 2.5, 3.5, 4.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5]

; Using class-marks

table = IMSL_FREQTABLE(x, nxbins, y, nybins, Class_Marks = cm)

PM, table, FORMAT = '(6(F8.5, 2X))', $

Title = ' counts'

                    counts

3.00000  2.00000  4.00000  0.00000  0.00000  0.00000

0.00000  5.00000  5.00000  2.00000  0.00000  0.00000

0.00000  0.00000  1.00000  3.00000  2.00000  0.00000

0.00000  0.00000  0.00000  0.00000  0.00000  2.00000

0.00000  0.00000  0.00000  0.00000  1.00000  0.00000

cp = [1, 2, 3, 4, 2, 3, 4, 5, 6]

; Using cutpoints

table = IMSL_FREQTABLE(x, nxbins, y, nybins, Cutpoints = cp)

PM, table, FORMAT = '(6(F8.5, 2X))', $

Title = ' counts'

                    counts

3.00000  2.00000  4.00000  0.00000  0.00000  0.00000

0.00000  5.00000  5.00000  2.00000  0.00000  0.00000

0.00000  0.00000  1.00000  3.00000  2.00000  0.00000

0.00000  0.00000  0.00000  0.00000  0.00000  2.00000

0.00000  0.00000  0.00000  0.00000  1.00000  0.00000

Syntax

Result = IMSL_FREQTABLE(X, Nxbins[, Y, Nybins] [, CUTPOINTS=array] [, CLASS_MARKS=array] [, /DOUBLE] [, LOWER_BOUND=value] [, UPPER_BOUND=value])

Return Value

One-dimensional or two-dimensional array containing the counts.

Arguments

Nxbins

Number of intervals (bins) for x.

Nybins (optional)

Number of intervals (bins) for y.

X

One-dimensional array containing the observations for the first variable.

Y (optional)

One-dimensional array containing the observations for the second variable.

Keywords

CUTPOINTS (optional)

CLASS_MARKS (optional)

DOUBLE (optional)

If present and nonzero, double precision is used.

LOWER_BOUND (optional)

If two positional arguments are used, use this keyword and the UPPER_BOUND keyword together to specify two semi-infinite intervals that are used as the initial and last interval. The LOWER_BOUND and UPPER_BOUND keywords must be used together. The initial interval is closed on the right and includes LOWER_BOUND as its right endpoint. The last interval is open on the left and includes all values greater than UPPER_BOUND. The remaining Nxbins − 2 intervals are of length. (UPPER_BOUND – LOWER_BOUND)/(Nxbins – 2) and are open on the left and closed on the right. The argument Nxbins must be greater than or equal to 3 for this option.

If four positional arguments are used, use this keyword with the UPPER_BOUND keyword to specify intervals of equal lengths. The LOWER_BOUND and UPPER_BOUND keywords must be used together. See the description above for details.

UPPER_BOUND (optional)

If two positional arguments are used, use this keyword along with the LOWER_BOUND keyword to specify two semi-infinite intervals that are used as the initial and last interval. The UPPER_BOUND and LOWER_BOUND keywords must be used together. The initial interval is closed on the right and includes LOWER_BOUND as its right endpoint. The last interval is open on the left and includes all values greater than UPPER_BOUND. The remaining Nxbins − 2 intervals are of length (UPPER_BOUND – LOWER_BOUND)/(Nxbins – 2)and are open on the left and closed on the right. LOWER_BOUND must also be specified with this keyword. The argument Nxbins must be greater than or equal to 3 for this option.

If four positional arguments are used, use this keyword with the LOWER_BOUND keyword to specify intervals of equal lengths. The UPPER_BOUND and LOWER_BOUND keywords must be used together. See the description above for details.

Version History

6.4

Introduced