IMSL_FREQTABLE

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

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

Syntax

Result = IMSL_FREQTABLE(x, nxbins[, y, nybins] [, CUTPOINTS=array] [, 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

(Use this keyword if two positional arguments are used) Specifies 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.

CUTPOINTS

(Use this keyword if four positional arguments are used.) Specifies 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

If two positional arguments are used, this keyword specifies 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, this keyword specifies 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

If present and nonzero, double precision is used.

LOWER_BOUND

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 Discussion below for details.

UPPER_BOUND

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 Discussion below for details.

Discussion

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 (nybins–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 nybins 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) 
    
    
    
   Bin Number  Count 
   ----------  ----- 
    1      4.00000 
    2      8.00000 
    3      5.00000 
    4      5.00000 
    5      3.00000 
    6      1.00000 
    7      3.00000 
    8      0.00000 
    9      0.00000 
    10     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

Version History


6.4	Introduced