NAG FL Interface
g01aef (frequency_​table)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

g01aef constructs a frequency distribution of a variable, according to either user-supplied, or routine-calculated class boundary values.

2 Specification

Fortran Interface
Subroutine g01aef ( n, k, x, iclass, cb, ifreq, xmin, xmax, ifail)
Integer, Intent (In) :: n, k, iclass
Integer, Intent (Inout) :: ifail
Integer, Intent (Out) :: ifreq(k)
Real (Kind=nag_wp), Intent (In) :: x(n)
Real (Kind=nag_wp), Intent (Inout) :: cb(k)
Real (Kind=nag_wp), Intent (Out) :: xmin, xmax
C Header Interface
#include <nag.h>
void  g01aef_ (const Integer *n, const Integer *k, const double x[], const Integer *iclass, double cb[], Integer ifreq[], double *xmin, double *xmax, Integer *ifail)
The routine may be called by the names g01aef or nagf_stat_frequency_table.

3 Description

The data consists of a sample of n observations of a continuous variable, denoted by xi, for i=1,2,,n. Let a = min(x1,,xn) and b = max(x1,,xn) .
g01aef constructs a frequency distribution with k(>1) classes denoted by fi, for i=1,2,,k.
The boundary values may be either user-supplied, or routine-calculated, and are denoted by yj, for j=1,2,,k-1.
If the boundary values of the classes are to be routine-calculated, then they are determined in one of the following ways:
  1. (a)if k>2, the range of x values is divided into k-2 intervals of equal length, and two extreme intervals, defined by the class boundary values y1,y2,,yk-1;
  2. (b)if k=2, y1=12(a+b).
However formed, the values y1,,yk-1 are assumed to be in ascending order. The class frequencies are formed with where [ means inclusive, and ) means exclusive. If the class boundary values are routine-calculated and k>2, then f1=fk=0, and y1 and yk-1 are chosen so that y1<a and yk-1>b.
If a frequency distribution is required for a discrete variable, then it is suggested that you supply the class boundary values; routine-calculated boundary values may be slightly imprecise (due to the adjustment of y1 and yk-1 outlined above) and cause values very close to a class boundary to be assigned to the wrong class.

4 References

None.

5 Arguments

1: n Integer Input
On entry: n, the number of observations.
Constraint: n1.
2: k Integer Input
On entry: k, the number of classes desired in the frequency distribution. Whether or not class boundary values are user-supplied, k must include the two extreme classes which stretch to ±.
Constraint: k2.
3: x(n) Real (Kind=nag_wp) array Input
On entry: the sample of observations of the variable for which the frequency distribution is required, xi, for i=1,2,,n. The values may be in any order.
4: iclass Integer Input
On entry: indicates whether class boundary values are to be calculated within g01aef, or are supplied by you.
If iclass=0, the class boundary values are to be calculated within the routine.
If iclass=1, they are user-supplied.
Constraint: iclass=0 or 1.
5: cb(k) Real (Kind=nag_wp) array Input/Output
On entry: if iclass=0, the elements of cb need not be assigned values, as g01aef calculates k-1 class boundary values.
If iclass=1, the first k-1 elements of cb must contain the class boundary values you supplied, in ascending order.
In both cases, the element cb(k) need not be assigned, as it is not used in the routine.
On exit: the first k-1 elements of cb contain the class boundary values in ascending order.
Constraint: if iclass=1, cb(i)<cb(i+1), for i=1,2,,k-2.
6: ifreq(k) Integer array Output
On exit: the elements of ifreq contain the frequencies in each class, fi, for i=1,2,,k. In particular ifreq(1) contains the frequency of the class up to cb(1), f1, and ifreq(k) contains the frequency of the class greater than cb(k-1), fk.
7: xmin Real (Kind=nag_wp) Output
On exit: the smallest value in the sample, a.
8: xmax Real (Kind=nag_wp) Output
On exit: the largest value in the sample, b.
9: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or −1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
On entry, k=value.
Constraint: k2.
ifail=2
On entry, n=value.
Constraint: n1.
ifail=3
On entry, cb(value)=value and cb(value)=value.
Constraint: cb(value)<cb(value).
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The method used is believed to be stable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
g01aef is not threaded in any implementation.

9 Further Comments

The time taken by g01aef increases with k and n. It also depends on the distribution of the sample observations.

10 Example

This example summarises a number of datasets. For each dataset the sample observations and optionally class boundary values are read. g01aef is then called and the frequency distribution and largest and smallest observations printed.

10.1 Program Text

Program Text (g01aefe.f90)

10.2 Program Data

Program Data (g01aefe.d)

10.3 Program Results

Program Results (g01aefe.r)