NAG Library Function Document

nag_tabulate_percentile (g11bbc)

nag_tabulate_percentile (Nag_TabulateVar type, Integer n, Integer nfac, const Integer sf[], const Integer lfac[], const Integer factor[], Integer tdf, double percnt, const double y[], const double wt[], double table[], Integer maxt, Integer *ncells, Integer *ndim, Integer idim[], Integer count[], NagError *fail)

3 Description

A dataset may include both classification variables and general variables. The classification variables, known as factors, take a small number of values known as levels. For example, the factor sex would have the levels male and female. These can be coded as 1 and 2 respectively. Given several factors, a multi-way table can be constructed such that each cell of the table represents one level from each factor. For example, the two factors sex and habitat, habitat having three levels: inner-city, suburban and rural, define the 2 by 3 contingency table:

Sex	Habitat
	Inner-city	Suburban	Rural
Male
Female

For each cell statistics can be computed. If a third variable in the dataset was age then for each cell the median age could be computed:

Sex	Habitat
	Inner-city	Suburban	Rural
Male	24	31	37
Female	21.5	28.5	33

That is the median age for all observations for males living in rural areas is 37. The median being the 50% quantile. Other quantiles can also be computed: the

p

percent quantile or percentile,

q_{p}

, is the estimate of the value such that

p

percent of observations are less than

q_{p}

. This is calculated in two different ways depending on whether the tabulated variable is continuous or discrete. Let there be

m

values in a cell and let

y_{(1)}

y_{(2)}, \dots, y_{(m)}

be the values for that cell sorted into ascending order. Also, associated with each value there is a weight,

w_{(1)}

w_{(2)}, \dots, w_{(m)}

, which could represent the observed frequency for that value, with

W_{j} = \sum_{i = 1}^{j} w_{(i)}

and

W_{j}^{'} = \sum_{i = 1}^{j} w_{(i)} - \frac{1}{2} w_{(j)}

. For the

p

percentile let

p_{w} = (p / 100) W_{m}

and

p_{w}^{'} = (p / 100) W_{m}^{'}

then the percentiles for the two cases are as given below.

If the variable is discrete, that is takes only a limited number of (usually integer) values then the percentile is defined as:

\begin{array}{l} y_{(j)} & if ​ W_{j - 1} < p_{W} < W_{j} \\ \frac{y_{(j + 1)} + y_{(j)}}{2} & if ​ p_{w} = W_{j} \end{array}

If the data is continuous then the quantiles are estimated by linear interpolation.

\begin{array}{l} y_{(1)} & if ​ p_{w}^{'} \leq W_{1}^{'} \\ (1 - f) y_{(j - 1)} + {f y}_{(j)} & if ​ W_{j - 1}^{'} < p_{w}^{'} \leq W_{j}^{'} \\ y_{(m)} & if ​ p_{w}^{'} > W_{m}^{'} \end{array}

where

f = (p_{w}^{'} - W_{j - 1}^{'}) / (W_{j}^{'} - W_{j - 1}^{'})

4 References

John J A and Quenouille M H (1977) Experiments: Design and Analysis Griffin

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin

5 Arguments

1: type – Nag_TabulateVarInput

On entry: indicates whether the variable to be tabulated is discrete or continuous.

$type = Nag_TabulateVarDiscr$: The percentiles are computed for a discrete variable.
$type = Nag_TabulateVarCont$: The percentiles are computed for a continuous variable using linear interpolation.

Constraint:

type = Nag_TabulateVarDiscr

Nag_TabulateVarCont

2: n – IntegerInput

On entry: the number of observations.

Constraint:

n \geq 2

3: nfac – IntegerInput

On entry: the number of classifying factors in factor.

Constraint:

nfac \geq 1

4: sf[nfac] – const IntegerInput

On entry: indicates which factors in factor are to be used in the tabulation.

sf [i - 1] > 0

the

i

th factor in factor is included in the tabulation.

Note that if

sf [i - 1] \leq 0

, for

i = 1, 2, \dots, nfac

then the statistic for the whole sample is calculated and returned in a 1 by 1 table.

5: lfac[nfac] – const IntegerInput

On entry: the number of levels of the classifying factors in factor.

Constraint: if

sf [i - 1] > 0

lfac [i - 1] \geq 2

, for

i = 1, 2, \dots, nfac

6: factor[ $n \times tdf$ ] – const IntegerInput

On entry: the nfac coded classification factors for the n observations.

Constraint: if

sf [i - 1] > 0

1 \leq factor [(i - 1) \times tdf + j - 1] \leq lfac [j - 1]

, for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, nfac

7: tdf – IntegerInput

On entry: the stride separating matrix column elements in the array factor.

Constraint:

tdf \geq nfac

8: percnt – doubleInput

On entry: the percentile to be tabulated,

p

Constraint:

0.0 < percnt < 100.0

9: y[n] – const doubleInput

On entry: the variable to be tabulated.

10: wt[n] – const doubleInput

On entry: wt must contain the n weights. Otherwise wt must be set to NULL.

Constraint:

wt [i - 1] \geq 0.0

, for

i = 1, 2, \dots, n

11: table[maxt] – doubleOutput

On exit: the computed table. The ncells cells of the table are stored so that for any two factors the index relating to the factor occurring later in lfac and factor changes faster. For further details see Section 9.

12: maxt – IntegerInput

On entry: the maximum size of the table to be computed.

Constraint:

maxt \geq

product of the levels of the factors included in the tabulation.

13: ncells – Integer *Output

On exit: the number of cells in the table.

14: ndim – Integer *Output

On exit: the number of factors defining the table.

15: idim[nfac] – IntegerOutput

On exit: the first ndim elements contain the number of levels for the factors defining the table.

16: count[maxt] – IntegerOutput

On exit: a table containing the number of observations contributing to each cell of the table, stored identically to table.

17: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_2_INT_ARG_LT: On entry, $tdf = ⟨value⟩$ while $nfac = ⟨value⟩$ . These arguments must satisfy $tdf \geq nfac$ .
NE_2_INT_ARRAY_CONS: On entry, $sf [⟨value⟩] = ⟨value⟩$ while $lfac [⟨value⟩] = ⟨value⟩$ .
Constraint: if $sf [i] > 0$ , $lfac [i] \geq 2$ , for $i = 0, 1, \dots, nfac - 1$ .
NE_2D_1D_INT_ARRAYS_CONS: On entry, $factor [(⟨value⟩) \times tdf + ⟨value⟩] = ⟨value⟩$ while $lfac [⟨value⟩] = ⟨value⟩$ .
Constraint: $factor [(i) \times tdf + j] \leq lfac [j]$ , for $i = 0, 1, \dots, n - 1$ and $j = 0, 1, \dots, nfac - 1$ .
NE_2D_INT_ARRAY_CONS: On entry, $factor [(⟨value⟩) \times tdf + ⟨value⟩] = ⟨value⟩$ .
Constraint: $factor [(i) \times tdf + j] \geq 1$ , for $i = 0, 1, \dots, n - 1$ and $j = 0, 1, \dots, nfac - 1$ .
NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument type had an illegal value.
NE_CELL_EMPTY: At least one cell is empty.
NE_INT_ARG_LT: On entry, $n = ⟨value⟩$ .
Constraint: $n \geq 2$ .
On entry, $nfac = ⟨value⟩$ .
Constraint: $nfac \geq 1$ .
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_MAXT: The maximum size of the table to be computed, maxt is too small.
NE_REAL: On entry, $percnt = ⟨value⟩$ .
Constraint: $0.0 < percnt < 100.0$ .
NE_REAL_ARRAY_CONS: On entry, $wt [⟨value⟩] = ⟨value⟩$ .
Constraint: $wt [i] \geq 0$ , for $i = 0, 1, \dots, n - 1$ .

7 Accuracy

Not applicable.

8 Parallelism and Performance

Not applicable.

9 Further Comments

The tables created by nag_tabulate_percentile (g11bbc) and stored in table and count are stored in the following way. Let there be

n

factors defining the table with factor

k

having

l_{k}

levels, then the cell defined by the levels

i_{1}, i_{2}, \dots, i_{n}

of the factors is stored in

m

th cell given by:

m = 1 + \sum_{k = 1}^{n} \{(i_{k} - 1) c_{k}\},

where

c_{j} = \prod_{k = j + 1}^{n} l_{k}

, for

j = 1, 2, \dots, n - 1

and

c_{n} = 1

10 Example

The data, given by John and Quenouille (1977), are for a 3 by 6 factorial experiment in 3 blocks of 18 units. The data is input in the order: blocks, factor with 3 levels, factor with 6 levels, yield, and the 3 by 6 table of treatment medians for yield over blocks is computed and printed.

NAG Library Function Documentnag_tabulate_percentile (g11bbc)

+− 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_tabulate_percentile (g11bbc)