NAG Library Function Document

1Purpose

nag_tabulate_margin (g11bcc) computes a marginal table from a table computed by nag_tabulate_stats (g11bac) or nag_tabulate_percentile (g11bbc) using a selected statistic.

2Specification

 #include #include
 void nag_tabulate_margin (Nag_TableStats stat, const double table[], Integer ncells, Integer ndim, const Integer idim[], const Integer isdim[], double sub_table[], Integer maxst, Integer *mcells, Integer *mdim, Integer mlevel[], double comm_ar[], NagError *fail)

3Description

For a dataset containing classification variables (known as factors) the functions nag_tabulate_stats (g11bac) and nag_tabulate_percentile (g11bbc) compute a table using selected statistics, for example the mean or the median. The table is indexed by the levels of the selected factors, for example if there were three factors A, B and C with $3$, $2$ and $4$ levels respectively and the mean was to be tabulated the resulting table would be $3×2×4$ with each cell being the mean of all observations with the appropriate combination of levels of the three factors. In further analysis the table of means averaged over C for A and B may be required; this can be computed from the full table by taking the mean over the third dimension of the table, C.
In general, given a table computed by nag_tabulate_stats (g11bac) or nag_tabulate_percentile (g11bbc), nag_tabulate_margin (g11bcc) computes a sub-table defined by a subset of the factors used to define the table such that each cell of the sub-table is the selected statistic computed over the remaining factors. The statistics that can be used are the total, the mean, the median, the variance, the smallest and the largest value.
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
West D H D (1979) Updating mean and variance estimates: An improved method Comm. ACM 22 532–555

5Arguments

1:    $\mathbf{stat}$Nag_TableStatsInput
On entry: indicates which statistic is to be used to compute the marginal table.
${\mathbf{stat}}=\mathrm{Nag_TableStatsNObs}$
The total.
${\mathbf{stat}}=\mathrm{Nag_TableStatsAv}$
The average or mean.
${\mathbf{stat}}=\mathrm{Nag_TableStatsMedian}$
The median.
${\mathbf{stat}}=\mathrm{Nag_TableStatsVar}$
The variance.
${\mathbf{stat}}=\mathrm{Nag_TableStatsLarge}$
The largest value.
${\mathbf{stat}}=\mathrm{Nag_TableStatsSmall}$
The smallest value.
Constraint: ${\mathbf{stat}}=\mathrm{Nag_TableStatsNObs}$, $\mathrm{Nag_TableStatsAv}$, $\mathrm{Nag_TableStatsMedian}$, $\mathrm{Nag_TableStatsVar}$, $\mathrm{Nag_TableStatsLarge}$ or $\mathrm{Nag_TableStatsSmall}$.
2:    $\mathbf{table}\left[{\mathbf{ncells}}\right]$const doubleInput
3:    $\mathbf{ncells}$IntegerInput
On entry: the number of cells in table as returned by nag_tabulate_stats (g11bac) or nag_tabulate_percentile (g11bbc).
4:    $\mathbf{ndim}$IntegerInput
On entry: the number of dimensions for table as returned by nag_tabulate_stats (g11bac) or nag_tabulate_percentile (g11bbc).
Constraint: ${\mathbf{ndim}}\ge 2$.
5:    $\mathbf{idim}\left[{\mathbf{ndim}}\right]$const IntegerInput
On entry: the number of levels for each dimension of table as returned by nag_tabulate_stats (g11bac) or nag_tabulate_percentile (g11bbc).
Constraint: ${\mathbf{idim}}\left[\mathit{i}\right]\ge 2$, for $\mathit{i}=0,1,\dots ,{\mathbf{ndim}}-1$.
6:    $\mathbf{isdim}\left[{\mathbf{ndim}}\right]$const IntegerInput
On entry: indicates which dimensions of table are to be included in the sub-table. If ${\mathbf{isdim}}\left[i-1\right]>0$ the dimension or factor indicated by ${\mathbf{idim}}\left[i-1\right]$ is to be included in the sub-table, otherwise it is excluded.
7:    $\mathbf{sub_table}\left[{\mathbf{maxst}}\right]$doubleOutput
On exit: the first mcells elements contain the sub-table computed using the statistic indicated by stat. The table is stored in a similar way to table with the mcells cells stored so that for any two dimensions the index relating to the dimension given later in idim changes faster. For further details see Section 9.
8:    $\mathbf{maxst}$IntegerInput
On entry: the maximum size of sub-table to be computed.
Constraint: ${\mathbf{maxst}}\ge \text{}$ the product of the levels of the dimensions of table included in the sub-table, sub_table.
9:    $\mathbf{mcells}$Integer *Output
On exit: the number of cells in the sub-table in sub_table.
10:  $\mathbf{mdim}$Integer *Output
On exit: the number of dimensions to the sub-table in sub_table.
11:  $\mathbf{mlevel}\left[{\mathbf{ndim}}\right]$IntegerOutput
On exit: the first mdim elements contain the number of levels for the dimensions of the sub-table in sub_table. The remaining elements are not referenced.
12:  $\mathbf{comm_ar}\left[\mathit{dim}\right]$doubleOutput
Note: the dimension, dim, of the array comm_ar must be at least
• ${\mathbf{maxst}}$ when ${\mathbf{stat}}=\mathrm{Nag_TableStatsVar}$;
• $1$ otherwise.
On exit: if ${\mathbf{stat}}=\mathrm{Nag_TableStatsVar}$ comm_ar contains the sub-table of means corresponding to the sub-table of variances in sub_table. Otherwise comm_ar is not referenced.
13:  $\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_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.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT
On entry, element $〈\mathit{\text{value}}〉$ of ${\mathbf{idim}}\le 1$.
On entry, ${\mathbf{ndim}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ndim}}\ge 2$.
NE_INT_2
On entry, maxst ($\text{}=〈\mathit{\text{value}}〉$) is too small, $\text{min value}=〈\mathit{\text{value}}〉$.
On entry, ncells is incompatible with idim.
NE_INT_ARRAY_ELEM_CONS
On entry, all elements of ${\mathbf{isdim}}>0$.
On entry, no elements of ${\mathbf{isdim}}>0$.
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.

7Accuracy

Only applicable when ${\mathbf{stat}}=\mathrm{Nag_TableStatsVar}$. In this case a one pass algorithm is used as describe in West (1979).

8Parallelism and Performance

nag_tabulate_margin (g11bcc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the x06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

The sub-tables created by nag_tabulate_margin (g11bcc) and stored in sub_table and, depending on stat, also in comm_ar are stored in the following way. Let there be $m$ dimensions defining the table with dimension $k$ having ${l}_{k}$ levels, then the cell defined by the levels ${i}_{1},{i}_{2},\dots ,{i}_{m}$ of the factors is stored in $s$th cell given by
 $s=1+∑k=1mik-1ck,$
where
 $cj=∏k=j+ 1m lk for ​ j= 1, 2,…, n- 1 and cm=1.$

10Example

The data, given by John and Quenouille (1977), is for 3 blocks of a $3×6$ factorial experiment. The data can be considered as a $3×6×3$ table (i.e., blocks $×$ treatment with $6$ levels $×$ treatment with $3$ levels). This table is input and the $6×3$ table of treatment means for over blocks is computed and printed.

10.1Program Text

Program Text (g11bcce.c)

10.2Program Data

Program Data (g11bcce.d)

10.3Program Results

Program Results (g11bcce.r)

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