g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_frequency_table (g01aec)

## 1  Purpose

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

## 2  Specification

 #include #include
 void nag_frequency_table (Integer n, const double x[], Integer num_class, Nag_ClassBoundary class, double cint[], Integer ifreq[], double *xmin, double *xmax, NagError *fail)

## 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)$.
nag_frequency_table (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:
 (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}$; (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},{i}_{k}\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.

## 5  Arguments

1:     nIntegerInput
On entry: $n$, the number of observations.
Constraint: ${\mathbf{n}}\ge 1$.
2:     x[n]const doubleInput
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:     num_classIntegerInput
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:     classNag_ClassBoundaryInput
On entry: indicates whether class boundary values are to be calculated within nag_frequency_table (g01aec), or are supplied by you.
If ${\mathbf{class}}=\mathrm{Nag_ClassBoundaryComp}$, then the class boundary values are to be calculated within the function.
If ${\mathbf{class}}=\mathrm{Nag_ClassBoundaryUser}$, they are user-supplied.
Constraint: ${\mathbf{class}}=\mathrm{Nag_ClassBoundaryComp}$ or $\mathrm{Nag_ClassBoundaryUser}$.
5:     cint[num_class]doubleInput/Output
On entry: if ${\mathbf{class}}=\mathrm{Nag_ClassBoundaryComp}$, then the elements of cint need not be assigned values, as nag_frequency_table (g01aec) calculates $k-1$ class boundary values.
If ${\mathbf{class}}=\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{class}}=\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:     ifreq[num_class]IntegerOutput
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:     xmindouble *Output
On exit: the smallest value in the sample, $a$.
8:     xmaxdouble *Output
On exit: the largest value in the sample, $b$.
9:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

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.
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]$.

## 7  Accuracy

The method used is believed to be stable.

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

## 9  Example

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

### 9.1  Program Text

Program Text (g01aece.c)

### 9.2  Program Data

Program Data (g01aece.d)

### 9.3  Program Results

Program Results (g01aece.r)