NAG Library Function Document

nag_frequency_table (g01aec)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

+− 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

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 <nag.h>

#include <nagg01.h>

void	nag_frequency_table (Integer n, const double x[], Integer num_class, Nag_ClassBoundary classb, 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

i = 1, 2, \dots, n

. Let

a = \min (x_{1}, \dots, x_{n})

and

b = \max (x_{1}, \dots, x_{n})

nag_frequency_table (g01aec) constructs a frequency distribution with

k (> 1)

classes denoted by

f_{i}

, for

i = 1, 2, \dots, k

The boundary values may be either user-supplied, or function-calculated, and are denoted by

y_{j}

, for

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} (a + b)$ .

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} =$ the number of $x$ values in the interval $(- \infty, y_{1})$
$f_{i} =$ the number of $x$ values in the interval $[y_{i - 1}, y_{i})$ , $i = 2, \dots, k - 1$
$f_{k} =$ the number of $x$ values in the interval $[y_{k - 1}, \infty)$ ,

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} < a

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.

4 References

None.

5 Arguments

1: n – IntegerInput: On entry: $n$ , the number of observations.

Constraint: $n \geq 1$ .
2: x[n] – const doubleInput: On entry: the sample of observations of the variable for which the frequency distribution is required, $x_{i}$ , for $i = 1, 2, \dots, n$ . The values may be in any order.
3: num_class – IntegerInput: 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 $\pm \infty$ .
Constraint: $num_class \geq 2$ .
4: classb – Nag_ClassBoundaryInput: On entry: indicates whether class boundary values are to be calculated within nag_frequency_table (g01aec), or are supplied by you.
If $classb = Nag_ClassBoundaryComp$ , then the class boundary values are to be calculated within the function.

If $classb = Nag_ClassBoundaryUser$ , they are user-supplied.

Constraint: $classb = Nag_ClassBoundaryComp$ or $Nag_ClassBoundaryUser$ .
5: cint[num_class] – doubleInput/Output: On entry: if $classb = Nag_ClassBoundaryComp$ , then the elements of cint need not be assigned values, as nag_frequency_table (g01aec) calculates $k - 1$ class boundary values.
If $classb = 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 $classb = Nag_ClassBoundaryUser$ , $cint [i - 1] < cint [i]$ , for $i = 1, 2, \dots, k - 2$ .
6: ifreq[num_class] – IntegerOutput: On exit: the elements of ifreq contain the frequencies in each class, $f_{i}$ , for $i = 1, 2, \dots, k$ . In particular $ifreq [0]$ contains the frequency of the class up to $cint [0]$ , $f_{1}$ , and $ifreq [k - 1]$ contains the frequency of the class greater than $cint [k - 2]$ , $f_{k}$ .
7: xmin – double *Output: On exit: the smallest value in the sample, $a$ .
8: xmax – double *Output: On exit: the largest value in the sample, $b$ .
9: fail – NagError *Input/Output: The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_BAD_PARAM: On entry, argument $⟨value⟩$ had an illegal value.
NE_INT_ARG_LT: On entry, $n = ⟨value⟩$ .
Constraint: $n \geq 1$ .
On entry, $num_class = ⟨value⟩$ .
Constraint: $num_class \geq 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, $cint [⟨value⟩] = ⟨value⟩$ and $cint [⟨value⟩] = ⟨value⟩$ .
Constraint: $cint [⟨value⟩] < cint [⟨value⟩]$ .

7 Accuracy

The method used is believed to be stable.

8 Parallelism and Performance

Not applicable.

9 Further Comments

The time taken by nag_frequency_table (g01aec) increases with num_class 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. nag_frequency_table (g01aec) is then called and the frequency distribution and largest and smallest observations printed.

NAG Library Function Documentnag_frequency_table (g01aec)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Document

nag_frequency_table (g01aec)