NAG Library Routine Document
G01AEF
1 Purpose
G01AEF constructs a frequency distribution of a variable, according to either usersupplied, or routinecalculated class boundary values.
2 Specification
INTEGER 
N, K, ICLASS, IFREQ(K), IFAIL 
REAL (KIND=nag_wp) 
X(N), CB(K), XMIN, XMAX 

3 Description
The data consists of a sample of $n$ observations of a continuous variable, denoted by ${x}_{i}$, for $\mathit{i}=1,2,\dots ,n$. Let $a=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({x}_{1},\dots ,{x}_{n}\right)$ and $b=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({x}_{1},\dots ,{x}_{n}\right)$.
G01AEF constructs a frequency distribution with $k\left(>1\right)$ classes denoted by ${f}_{i}$, for $\mathit{i}=1,2,\dots ,k$.
The boundary values may be either usersupplied, or routinecalculated, and are denoted by ${y}_{j}$, for $\mathit{j}=1,2,\dots ,k1$.
If the boundary values of the classes are to be routinecalculated, then they are determined in one of the following ways:
(a) 
if $k>2$, the range of $x$ values is divided into $k2$ intervals of equal length, and two extreme intervals, defined by the class boundary values ${y}_{1},{y}_{2},\dots ,{y}_{k1}$; 
(b) 
if $k=2$, ${y}_{1}=\frac{1}{2}\left(a+b\right)$. 
However formed, the values
${y}_{1},\dots ,{y}_{k1}$ are assumed to be in ascending order. The class frequencies are formed with
 ${f}_{1}=\text{}$ the number of $x$ values in the interval $\left(\infty ,{y}_{1}\right)$
 ${f}_{i}=\text{}$ the number of $x$ values in the interval $\left[{y}_{i1},{y}_{i}\right)$, $\text{\hspace{1em}}i=2,\dots ,k1$
 ${f}_{k}=\text{}$ the number of $x$ values in the interval $\left[{y}_{k1},\infty \right)$,
where [ means inclusive, and ) means exclusive. If the class boundary values are routinecalculated and
$k>2$, then
${f}_{1}={f}_{k}=0$, and
${y}_{1}$ and
${y}_{k1}$ are chosen so that
${y}_{1}<a$ and
${y}_{k1}>b$.
If a frequency distribution is required for a discrete variable, then it is suggested that you supply the class boundary values; routinecalculated boundary values may be slightly imprecise (due to the adjustment of ${y}_{1}$ and ${y}_{k1}$ outlined above) and cause values very close to a class boundary to be assigned to the wrong class.
4 References
None.
5 Parameters
 1: $\mathrm{N}$ – INTEGERInput

On entry: $n$, the number of observations.
Constraint:
${\mathbf{N}}\ge 1$.
 2: $\mathrm{K}$ – INTEGERInput

On entry:
$k$, the number of classes desired in the frequency distribution. Whether or not class boundary values are usersupplied,
K must include the two extreme classes which stretch to
$\pm \infty $.
Constraint:
${\mathbf{K}}\ge 2$.
 3: $\mathrm{X}\left({\mathbf{N}}\right)$ – REAL (KIND=nag_wp) arrayInput

On entry: the sample of observations of the variable for which the frequency distribution is required,
${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$. The values may be in any order.
 4: $\mathrm{ICLASS}$ – INTEGERInput

On entry: indicates whether class boundary values are to be calculated within G01AEF, or are supplied by you.
If ${\mathbf{ICLASS}}=0$, then the class boundary values are to be calculated within the routine.
If ${\mathbf{ICLASS}}=1$, they are usersupplied.
Constraint:
${\mathbf{ICLASS}}=0$ or $1$.
 5: $\mathrm{CB}\left({\mathbf{K}}\right)$ – REAL (KIND=nag_wp) arrayInput/Output

On entry: if
${\mathbf{ICLASS}}=0$, then the elements of
CB need not be assigned values, as G01AEF calculates
$k1$ class boundary values.
If
${\mathbf{ICLASS}}=1$, the first
$k1$ elements of
CB must contain the class boundary values you supplied, in ascending order.
In both cases, the element ${\mathbf{CB}}\left(k\right)$ need not be assigned, as it is not used in the routine.
On exit: the first
$k1$ elements of
CB contain the class boundary values in ascending order.
Constraint:
if ${\mathbf{ICLASS}}=1$, ${\mathbf{CB}}\left(\mathit{i}\right)<{\mathbf{CB}}\left(\mathit{i}+1\right)$, for $\mathit{i}=1,2,\dots ,k2$.
 6: $\mathrm{IFREQ}\left({\mathbf{K}}\right)$ – INTEGER arrayOutput

On exit: the elements of
IFREQ contain the frequencies in each class,
${f}_{\mathit{i}}$, for
$\mathit{i}=1,2,\dots ,k$. In particular
${\mathbf{IFREQ}}\left(1\right)$ contains the frequency of the class up to
${\mathbf{CB}}\left(1\right)$,
${f}_{1}$, and
${\mathbf{IFREQ}}\left(k\right)$ contains the frequency of the class greater than
${\mathbf{CB}}\left(k1\right)$,
${f}_{k}$.
 7: $\mathrm{XMIN}$ – REAL (KIND=nag_wp)Output

On exit: the smallest value in the sample, $a$.
 8: $\mathrm{XMAX}$ – REAL (KIND=nag_wp)Output

On exit: the largest value in the sample, $b$.
 9: $\mathrm{IFAIL}$ – INTEGERInput/Output

On entry:
IFAIL must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{ or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is
$0$.
When the value $\mathbf{1}\text{ or}\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.
On exit:
${\mathbf{IFAIL}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6 Error Indicators and Warnings
If on entry
${\mathbf{IFAIL}}={\mathbf{0}}$ or
${{\mathbf{1}}}$, explanatory error messages are output on the current error message unit (as defined by
X04AAF).
Errors or warnings detected by the routine:
 ${\mathbf{IFAIL}}=1$

On entry,  ${\mathbf{K}}<2$. 
 ${\mathbf{IFAIL}}=2$

On entry,  ${\mathbf{N}}<1$. 
 ${\mathbf{IFAIL}}=3$

On entry,  the usersupplied class boundary values are not in ascending order. 
 ${\mathbf{IFAIL}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.8 in the Essential Introduction for further information.
 ${\mathbf{IFAIL}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.7 in the Essential Introduction for further information.
 ${\mathbf{IFAIL}}=999$
Dynamic memory allocation failed.
See
Section 3.6 in the Essential Introduction for further information.
7 Accuracy
The method used is believed to be stable.
8 Parallelism and Performance
Not applicable.
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)