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 + (xmaxxmin)/nxbins, and the y value less than or equal to ymin + (ymaxymin)/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)

  • If two positional arguments are used, use this keyword to specify a one-dimensional array of length Nxbins containing the cutpoints to use. 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 CUTPOINTS is used, no other keywords should be specified.
  • If four positional arguments are used, use this keyword to specify a one-dimensional array of cutpoints (boundaries). 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 (Nybins –1) elements.

CLASS_MARKS (optional)

  • If two positional arguments are used, use this keyword to specify a one-dimensional array containing equally spaced class marks in ascending order. The class marks are the midpoints of each of the nxbins, and each interval is taken to have length (CLASS_MARKS(1) – CLASS_MARKS(0)). The argument Nxbins must be greater than or equal to 2 for this option. If CLASS_MARKS is used, then no other keywords should be specified.
  • If four positional arguments are used, use this keyword to specify a one-dimensional array containing equally spaced class marks in ascending order. 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 Nybins elements.

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