# NAG CL Interfaceg01aec (frequency_​table)

Settings help

CL Name Style:

## 1Purpose

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

## 2Specification

 #include
 void g01aec (Integer n, const double x[], Integer num_class, Nag_ClassBoundary classb, double cint[], Integer ifreq[], double *xmin, double *xmax, NagError *fail)
The function may be called by the names: g01aec, nag_stat_frequency_table or nag_frequency_table.

## 3Description

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)$.
g01aec 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 user-supplied, or function-calculated, and are denoted by ${y}_{j}$, for $\mathit{j}=1,2,\dots ,k-1$.
If the boundary values of the classes are to be function-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 ${y}_{1},{y}_{2},\dots ,{y}_{k-1}$;
2. (b)if $k=2$, ${y}_{1}=\frac{1}{2}\left(a+b\right)$.
However formed, the values ${y}_{1},\dots ,{y}_{k-1}$ 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}_{i-1},{y}_{i}\right)$, $\text{ }i=2,\dots ,k-1$
• ${f}_{k}=\text{}$ the number of $x$ values in the interval $\left[{y}_{k-1},\infty \right)$,
where [ means inclusive, and ) means exclusive. If the class boundary values are function-calculated and $k>2$, then ${f}_{1}={f}_{k}=0$, and ${y}_{1}$ and ${y}_{k-1}$ are chosen so that ${y}_{1} and ${y}_{k-1}>b$.
If a frequency distribution is required for a discrete variable, then it is suggested that you supply the class boundary values; function-calculated boundary values may be slightly imprecise (due to the adjustment of ${y}_{1}$ and ${y}_{k-1}$ outlined above) and cause values very close to a class boundary to be assigned to the wrong class.
None.

## 5Arguments

1: $\mathbf{n}$Integer Input
On entry: $n$, the number of observations.
Constraint: ${\mathbf{n}}\ge 1$.
2: $\mathbf{x}\left[{\mathbf{n}}\right]$const double Input
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.
3: $\mathbf{num_class}$Integer Input
On entry: $k$, the number of classes desired in the frequency distribution. Whether or not class boundary values are user-supplied, num_class must include the two extreme classes which stretch to $±\infty$.
Constraint: ${\mathbf{num_class}}\ge 2$.
4: $\mathbf{classb}$Nag_ClassBoundary Input
On entry: indicates whether class boundary values are to be calculated within g01aec, or are supplied by you.
If ${\mathbf{classb}}=\mathrm{Nag_ClassBoundaryComp}$, the class boundary values are to be calculated within the function.
If ${\mathbf{classb}}=\mathrm{Nag_ClassBoundaryUser}$, they are user-supplied.
Constraint: ${\mathbf{classb}}=\mathrm{Nag_ClassBoundaryComp}$ or $\mathrm{Nag_ClassBoundaryUser}$.
5: $\mathbf{cint}\left[{\mathbf{num_class}}\right]$double Input/Output
On entry: if ${\mathbf{classb}}=\mathrm{Nag_ClassBoundaryComp}$, the elements of cint need not be assigned values, as g01aec calculates $k-1$ class boundary values.
If ${\mathbf{classb}}=\mathrm{Nag_ClassBoundaryUser}$, the first $k-1$ elements of cint must contain the class boundary values you supplied, in ascending order.
On exit: the first $k-1$ elements of cint contain the class boundary values in ascending order.
Constraint: if ${\mathbf{classb}}=\mathrm{Nag_ClassBoundaryUser}$, ${\mathbf{cint}}\left[\mathit{i}-1\right]<{\mathbf{cint}}\left[\mathit{i}\right]$, for $\mathit{i}=1,2,\dots ,k-2$.
6: $\mathbf{ifreq}\left[{\mathbf{num_class}}\right]$Integer Output
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[0\right]$ contains the frequency of the class up to ${\mathbf{cint}}\left[0\right]$, ${f}_{1}$, and ${\mathbf{ifreq}}\left[k-1\right]$ contains the frequency of the class greater than ${\mathbf{cint}}\left[k-2\right]$, ${f}_{k}$.
7: $\mathbf{xmin}$double * Output
On exit: the smallest value in the sample, $a$.
8: $\mathbf{xmax}$double * Output
On exit: the largest value in the sample, $b$.
9: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_INT_ARG_LT
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{num_class}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{num_class}}\ge 2$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_NOT_STRICTLY_INCREASING
On entry, ${\mathbf{cint}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{cint}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{cint}}\left[⟨\mathit{\text{value}}⟩\right]<{\mathbf{cint}}\left[⟨\mathit{\text{value}}⟩\right]$.

## 7Accuracy

The method used is believed to be stable.

## 8Parallelism and Performance

g01aec is not threaded in any implementation.

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

## 10Example

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

### 10.1Program Text

Program Text (g01aece.c)

### 10.2Program Data

Program Data (g01aece.d)

### 10.3Program Results

Program Results (g01aece.r)