NAG Library Routine Document
g11bcf (tabulate_margin)
1
Purpose
g11bcf computes a marginal table from a table computed by
g11baf or
g11bbf using a selected statistic.
2
Specification
Fortran Interface
Subroutine g11bcf ( 
stat, table, ncells, ndim, idim, isdim, stable, maxst, mcells, mdim, mlevel, auxt, iwk, wk, ifail) 
Integer, Intent (In)  ::  ncells, ndim, idim(ndim), isdim(ndim), maxst  Integer, Intent (Inout)  ::  ifail  Integer, Intent (Out)  ::  mcells, mdim, mlevel(ndim), iwk(3*ndim)  Real (Kind=nag_wp), Intent (In)  ::  table(ncells)  Real (Kind=nag_wp), Intent (Inout)  ::  auxt(*)  Real (Kind=nag_wp), Intent (Out)  ::  stable(maxst), wk(ncells)  Character (1), Intent (In)  ::  stat 

C Header Interface
#include nagmk26.h
void 
g11bcf_ (const char *stat, const double table[], const Integer *ncells, const Integer *ndim, const Integer idim[], const Integer isdim[], double stable[], const Integer *maxst, Integer *mcells, Integer *mdim, Integer mlevel[], double auxt[], Integer iwk[], double wk[], Integer *ifail, const Charlen length_stat) 

3
Description
For a dataset containing classification variables (known as factors) the routines
g11baf and
g11bbf 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\times 2\times 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
g11baf or
g11bbf,
g11bcf computes a subtable defined by a subset of the factors used to define the table such that each cell of the subtable 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.
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
West D H D (1979) Updating mean and variance estimates: An improved method Comm. ACM 22 532–555
5
Arguments
 1: $\mathbf{stat}$ – Character(1)Input

On entry: indicates which statistic is to be used to compute the marginal table.
 ${\mathbf{stat}}=\text{'T'}$
 The total.
 ${\mathbf{stat}}=\text{'A'}$
 The average or mean.
 ${\mathbf{stat}}=\text{'M'}$
 The median.
 ${\mathbf{stat}}=\text{'V'}$
 The variance.
 ${\mathbf{stat}}=\text{'L'}$
 The largest value.
 ${\mathbf{stat}}=\text{'S'}$
 The smallest value.
Constraint:
${\mathbf{stat}}=\text{'T'}$, $\text{'A'}$, $\text{'M'}$, $\text{'V'}$, $\text{'L'}$ or $\text{'S'}$.
 2: $\mathbf{table}\left({\mathbf{ncells}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the table as computed by
g11baf or
g11bbf.
 3: $\mathbf{ncells}$ – IntegerInput

On entry: the number of cells in
table as returned by
g11baf or
g11bbf.
 4: $\mathbf{ndim}$ – IntegerInput

On entry: the number of dimensions for
table as returned by
g11baf or
g11bbf.
Constraint:
${\mathbf{ndim}}\ge 2$.
 5: $\mathbf{idim}\left({\mathbf{ndim}}\right)$ – Integer arrayInput

On entry: the number of levels for each dimension of
table as returned by
g11baf or
g11bbf.
Constraint:
${\mathbf{idim}}\left(\mathit{i}\right)\ge 2$, for $\mathit{i}=1,2,\dots ,{\mathbf{ndim}}$.
 6: $\mathbf{isdim}\left({\mathbf{ndim}}\right)$ – Integer arrayInput

On entry: indicates which dimensions of
table are to be included in the subtable. If
${\mathbf{isdim}}\left(i\right)>0$ the dimension or factor indicated by
${\mathbf{idim}}\left(i\right)$ is to be included in the subtable, otherwise it is excluded.
 7: $\mathbf{stable}\left({\mathbf{maxst}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the first
mcells elements contain the subtable 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 subtable to be computed.
Constraint:
${\mathbf{maxst}}\ge \text{}$ the product of the levels of the dimensions of
table included in the subtable,
stable.
 9: $\mathbf{mcells}$ – IntegerOutput

On exit: the number of cells in the subtable in
stable.
 10: $\mathbf{mdim}$ – IntegerOutput

On exit: the number of dimensions to the subtable in
stable.
 11: $\mathbf{mlevel}\left({\mathbf{ndim}}\right)$ – Integer arrayOutput

On exit: the first
mdim elements contain the number of levels for the dimensions of the subtable in
stable. The remaining elements are not referenced.
 12: $\mathbf{auxt}\left(*\right)$ – Real (Kind=nag_wp) arrayOutput

Note: the dimension of the array
auxt
must be at least
${\mathbf{maxst}}$ if
${\mathbf{stat}}=\text{'V'}$, and at least
$1$ otherwise.
On exit: if
${\mathbf{stat}}=\text{'V'}$ auxt contains the subtable of means corresponding to the subtable of variances in
stable. Otherwise
auxt is not referenced.
 13: $\mathbf{iwk}\left(3\times {\mathbf{ndim}}\right)$ – Integer arrayWorkspace

 14: $\mathbf{wk}\left({\mathbf{ncells}}\right)$ – Real (Kind=nag_wp) arrayWorkspace

 15: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{ or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{ or}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry,  ${\mathbf{ndim}}<2$, 
or  ${\mathbf{stat}}\ne \text{'T'}$, $\text{'A'}$, $\text{'M'}$, $\text{'V'}$, $\text{'L'}$ or $\text{'S'}$. 
 ${\mathbf{ifail}}=2$

On entry,  ${\mathbf{idim}}\left(i\right)\le 1$, for some $i=1,2,\dots ,{\mathbf{ndim}}$, 
or  ncells is incompatible with idim, 
or  the requested subtable is of dimension $0$, 
or  the requested subtable is the full table, 
or  maxst is too small, the minimum value is returned in mdim. 
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
Only applicable when
${\mathbf{stat}}=\text{'V'}$. In this case a one pass algorithm is used as describe in
West (1979).
8
Parallelism and Performance
g11bcf 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 routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
The subtables created by
g11bcf and stored in
stable and, depending on
stat, also in
auxt 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
where
10
Example
The data, given by
John and Quenouille (1977), is for 3 blocks of a
$3\times 6$ factorial experiment. The data can be considered as a
$3\times 6\times 3$ table (i.e., blocks
$\times $ treatment with
$6$ levels
$\times $ treatment with
$3$ levels). This table is input and the
$6\times 3$ table of treatment means for over blocks is computed and printed.
10.1
Program Text
Program Text (g11bcfe.f90)
10.2
Program Data
Program Data (g11bcfe.d)
10.3
Program Results
Program Results (g11bcfe.r)