NAG C Library Function Document

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$ , 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$ , 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.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
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.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_NO_LICENCE: Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
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

nag_frequency_table (g01aec) is not threaded in any implementation.

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 C 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

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