NAG Library Function Document

1Purpose

nag_tabulate_percentile (g11bbc) computes a table from a set of classification factors using a given percentile or quantile, for example the median.

2Specification

 #include #include
 void 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)

3Description

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}_{\left(1\right)}$, ${y}_{\left(2\right)},\dots ,{y}_{\left(m\right)}$ be the values for that cell sorted into ascending order. Also, associated with each value there is a weight, ${w}_{\left(1\right)}$, ${w}_{\left(2\right)},\dots ,{w}_{\left(m\right)}$, which could represent the observed frequency for that value, with ${W}_{j}={\sum }_{i=1}^{j}{w}_{\left(i\right)}$ and ${W}_{j}^{\prime }={\sum }_{i=1}^{j}{w}_{\left(i\right)}-\frac{1}{2}{w}_{\left(j\right)}$. For the $p$ percentile let ${p}_{w}=\left(p/100\right){W}_{m}$ and ${p}_{w}^{\prime }=\left(p/100\right){W}_{m}^{\prime }$ 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:
 $y j if ​ W j-1 < p W < W j y j+1 + y j 2 if ​ p w = W j$
If the data is continuous then the quantiles are estimated by linear interpolation.
 $y 1 if ​ p w ′ ≤ W 1 ′ 1-f y j-1 + fy j if ​ W j-1 ′ < p w ′ ≤ W j ′ y m if ​ p w ′ > W m ′$
where $f=\left({p}_{w}^{\prime }-{W}_{j-1}^{\prime }\right)/\left({W}_{j}^{\prime }-{W}_{j-1}^{\prime }\right)$.
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

5Arguments

1:    $\mathbf{type}$Nag_TabulateVarInput
On entry: indicates whether the variable to be tabulated is discrete or continuous.
${\mathbf{type}}=\mathrm{Nag_TabulateVarDiscr}$
The percentiles are computed for a discrete variable.
${\mathbf{type}}=\mathrm{Nag_TabulateVarCont}$
The percentiles are computed for a continuous variable using linear interpolation.
Constraint: ${\mathbf{type}}=\mathrm{Nag_TabulateVarDiscr}$ or $\mathrm{Nag_TabulateVarCont}$.
2:    $\mathbf{n}$IntegerInput
On entry: the number of observations.
Constraint: ${\mathbf{n}}\ge 2$.
3:    $\mathbf{nfac}$IntegerInput
On entry: the number of classifying factors in factor.
Constraint: ${\mathbf{nfac}}\ge 1$.
4:    $\mathbf{sf}\left[{\mathbf{nfac}}\right]$const IntegerInput
On entry: indicates which factors in factor are to be used in the tabulation.
If ${\mathbf{sf}}\left[i-1\right]>0$ the $i$th factor in factor is included in the tabulation.
Note that if ${\mathbf{sf}}\left[\mathit{i}-1\right]\le 0$, for $\mathit{i}=1,2,\dots ,{\mathbf{nfac}}$ then the statistic for the whole sample is calculated and returned in a 1 by 1 table.
5:    $\mathbf{lfac}\left[{\mathbf{nfac}}\right]$const IntegerInput
On entry: the number of levels of the classifying factors in factor.
Constraint: if ${\mathbf{sf}}\left[i-1\right]>0$, ${\mathbf{lfac}}\left[\mathit{i}-1\right]\ge 2$, for $\mathit{i}=1,2,\dots ,{\mathbf{nfac}}$.
6:    $\mathbf{factor}\left[{\mathbf{n}}×{\mathbf{tdf}}\right]$const IntegerInput
On entry: the nfac coded classification factors for the n observations.
Constraint: if ${\mathbf{sf}}\left[\mathit{i}-1\right]>0$, $1\le {\mathbf{factor}}\left[\left(\mathit{i}-1\right)×{\mathbf{tdf}}+\mathit{j}-1\right]\le {\mathbf{lfac}}\left[\mathit{j}-1\right]$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$ and $\mathit{j}=1,2,\dots ,{\mathbf{nfac}}$.
7:    $\mathbf{tdf}$IntegerInput
On entry: the stride separating matrix column elements in the array factor.
Constraint: ${\mathbf{tdf}}\ge {\mathbf{nfac}}$.
8:    $\mathbf{percnt}$doubleInput
On entry: the percentile to be tabulated, $p$.
Constraint: $0.0<{\mathbf{percnt}}<100.0$.
9:    $\mathbf{y}\left[{\mathbf{n}}\right]$const doubleInput
On entry: the variable to be tabulated.
10:  $\mathbf{wt}\left[{\mathbf{n}}\right]$const doubleInput
On entry: wt must contain the n weights. Otherwise wt must be set to NULL.
Constraint: ${\mathbf{wt}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
11:  $\mathbf{table}\left[{\mathbf{maxt}}\right]$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:  $\mathbf{maxt}$IntegerInput
On entry: the maximum size of the table to be computed.
Constraint: ${\mathbf{maxt}}\ge$ product of the levels of the factors included in the tabulation.
13:  $\mathbf{ncells}$Integer *Output
On exit: the number of cells in the table.
14:  $\mathbf{ndim}$Integer *Output
On exit: the number of factors defining the table.
15:  $\mathbf{idim}\left[{\mathbf{nfac}}\right]$IntegerOutput
On exit: the first ndim elements contain the number of levels for the factors defining the table.
16:  $\mathbf{count}\left[{\mathbf{maxt}}\right]$IntegerOutput
On exit: a table containing the number of observations contributing to each cell of the table, stored identically to table.
17:  $\mathbf{fail}$NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, ${\mathbf{tdf}}=〈\mathit{\text{value}}〉$ while ${\mathbf{nfac}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{tdf}}\ge {\mathbf{nfac}}$.
NE_2_INT_ARRAY_CONS
On entry, ${\mathbf{sf}}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$ while ${\mathbf{lfac}}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{sf}}\left[i\right]>0$, ${\mathbf{lfac}}\left[\mathit{i}\right]\ge 2$, for $\mathit{i}=0,1,\dots ,{\mathbf{nfac}}-1$.
NE_2D_1D_INT_ARRAYS_CONS
On entry, ${\mathbf{factor}}\left[\left(〈\mathit{\text{value}}〉\right)×{\mathbf{tdf}}+〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$ while ${\mathbf{lfac}}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{factor}}\left[\left(\mathit{i}\right)×{\mathbf{tdf}}+\mathit{j}\right]\le {\mathbf{lfac}}\left[\mathit{j}\right]$, for $\mathit{i}=0,1,\dots ,n-1$ and $\mathit{j}=0,1,\dots ,{\mathbf{nfac}}-1$.
NE_2D_INT_ARRAY_CONS
On entry, ${\mathbf{factor}}\left[\left(〈\mathit{\text{value}}〉\right)×{\mathbf{tdf}}+〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{factor}}\left[\left(\mathit{i}\right)×{\mathbf{tdf}}+\mathit{j}\right]\ge 1$, for $\mathit{i}=0,1,\dots ,n-1$ and $\mathit{j}=0,1,\dots ,{\mathbf{nfac}}-1$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument type had an illegal value.
NE_CELL_EMPTY
At least one cell is empty.
NE_INT_ARG_LT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 2$.
On entry, ${\mathbf{nfac}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nfac}}\ge 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, ${\mathbf{percnt}}=〈\mathit{\text{value}}〉$.
Constraint: $0.0<{\mathbf{percnt}}<100.0$.
NE_REAL_ARRAY_CONS
On entry, ${\mathbf{wt}}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{wt}}\left[\mathit{i}\right]\ge 0$, for $\mathit{i}=0,1,\dots ,n-1$.

Not applicable.

8Parallelism and Performance

nag_tabulate_percentile (g11bbc) is not threaded in any implementation.

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 + ∑ k=1 n i k - 1 c k ,$
where ${c}_{\mathit{j}}={\prod }_{k=\mathit{j}+1}^{n}{l}_{k}$, for $\mathit{j}=1,2,\dots ,n-1$ and ${c}_{n}=1$.

10Example

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.

10.1Program Text

Program Text (g11bbce.c)

10.2Program Data

Program Data (g11bbce.d)

10.3Program Results

Program Results (g11bbce.r)

© The Numerical Algorithms Group Ltd, Oxford, UK. 2017