Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_contab_tabulate_margin (g11bc)

## Purpose

nag_contab_tabulate_margin (g11bc) computes a marginal table from a table computed by nag_contab_tabulate_stat (g11ba) or nag_contab_tabulate_percentile (g11bb) using a selected statistic.

## Syntax

[stable, mcells, mdim, mlevel, auxt, ifail] = g11bc(stat, table, idim, isdim, maxst, 'ncells', ncells, 'ndim', ndim)
[stable, mcells, mdim, mlevel, auxt, ifail] = nag_contab_tabulate_margin(stat, table, idim, isdim, maxst, 'ncells', ncells, 'ndim', ndim)

## Description

For a dataset containing classification variables (known as factors) the functions nag_contab_tabulate_stat (g11ba) and nag_contab_tabulate_percentile (g11bb) 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$3$, 2$2$ and 4$4$ levels respectively and the mean was to be tabulated the resulting table would be 3 × 2 × 4$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_contab_tabulate_stat (g11ba) or nag_contab_tabulate_percentile (g11bb), nag_contab_tabulate_margin (g11bc) 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.

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

## Parameters

### Compulsory Input Parameters

1:     stat – string (length ≥ 1)
Indicates which statistic is to be used to compute the marginal table.
stat = 'T'${\mathbf{stat}}=\text{'T'}$
The total.
stat = 'A'${\mathbf{stat}}=\text{'A'}$
The average or mean.
stat = 'M'${\mathbf{stat}}=\text{'M'}$
The median.
stat = 'V'${\mathbf{stat}}=\text{'V'}$
The variance.
stat = 'L'${\mathbf{stat}}=\text{'L'}$
The largest value.
stat = 'S'${\mathbf{stat}}=\text{'S'}$
The smallest value.
Constraint: stat = 'T'${\mathbf{stat}}=\text{'T'}$, 'A'$\text{'A'}$, 'M'$\text{'M'}$, 'V'$\text{'V'}$, 'L'$\text{'L'}$ or 'S'$\text{'S'}$.
2:     table(ncells) – double array
3:     idim(ndim) – int64int32nag_int array
ndim, the dimension of the array, must satisfy the constraint ndim2${\mathbf{ndim}}\ge 2$.
The number of levels for each dimension of table as returned by nag_contab_tabulate_stat (g11ba) or nag_contab_tabulate_percentile (g11bb).
Constraint: idim(i)2${\mathbf{idim}}\left(\mathit{i}\right)\ge 2$, for i = 1,2,,ndim$\mathit{i}=1,2,\dots ,{\mathbf{ndim}}$.
4:     isdim(ndim) – int64int32nag_int array
ndim, the dimension of the array, must satisfy the constraint ndim2${\mathbf{ndim}}\ge 2$.
Indicates which dimensions of table are to be included in the sub-table. If isdim(i) > 0${\mathbf{isdim}}\left(i\right)>0$ the dimension or factor indicated by idim(i)${\mathbf{idim}}\left(i\right)$ is to be included in the sub-table, otherwise it is excluded.
5:     maxst – int64int32nag_int scalar
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, stable.

### Optional Input Parameters

1:     ncells – int64int32nag_int scalar
Default: The dimension of the array table.
2:     ndim – int64int32nag_int scalar
Default: The dimension of the arrays idim, isdim. (An error is raised if these dimensions are not equal.)
The number of dimensions for table as returned by nag_contab_tabulate_stat (g11ba) or nag_contab_tabulate_percentile (g11bb).
Constraint: ndim2${\mathbf{ndim}}\ge 2$.

iwk wk

### Output Parameters

1:     stable(maxst) – double array
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 [Further Comments].
2:     mcells – int64int32nag_int scalar
The number of cells in the sub-table in stable.
3:     mdim – int64int32nag_int scalar
The number of dimensions to the sub-table in stable.
4:     mlevel(ndim) – int64int32nag_int array
The first mdim elements contain the number of levels for the dimensions of the sub-table in stable. The remaining elements are not referenced.
5:     auxt( : $:$) – double array
Note: the dimension of the array auxt must be at least maxst${\mathbf{maxst}}$ if stat = 'V'${\mathbf{stat}}=\text{'V'}$, and at least 1$1$ otherwise.
If stat = 'V'${\mathbf{stat}}=\text{'V'}$ auxt contains the sub-table of means corresponding to the sub-table of variances in stable. Otherwise auxt is not referenced.
6:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
 On entry, ndim < 2${\mathbf{ndim}}<2$, or stat ≠ 'T'${\mathbf{stat}}\ne \text{'T'}$, 'A'$\text{'A'}$, 'M'$\text{'M'}$, 'V'$\text{'V'}$, 'L'$\text{'L'}$ or 'S'$\text{'S'}$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, idim(i) ≤ 1${\mathbf{idim}}\left(i\right)\le 1$, for some i = 1,2, … ,ndim$i=1,2,\dots ,{\mathbf{ndim}}$, or ncells is incompatible with idim, or the requested sub-table is of dimension 0$0$, or the requested sub-table is the full table, or maxst is too small, the minimum value is returned in mdim.

## Accuracy

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

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

## Example

```function nag_contab_tabulate_margin_example
stat = 'A';
table = [274;
361;
253;
325;
317;
339;
326;
402;
336;
379;
345;
361;
352;
334;
318;
339;
393;
358;
350;
340;
203;
397;
356;
298;
382;
376;
355;
418;
387;
379;
432;
339;
293;
322;
417;
342;
82;
297;
133;
306;
352;
361;
220;
333;
270;
388;
379;
274;
336;
307;
266;
389;
333;
353];
idim = [int64(3);6;3];
isdim = [int64(0);1;1];
maxst = int64(54);
[stable, mcells, mdim, mlevel, auxt, ifail] = ...
nag_contab_tabulate_margin(stat, table, idim, isdim, maxst)
```
```

stable =

235.3333
332.6667
196.3333
342.6667
341.6667
332.6667
309.3333
370.3333
320.3333
395.0000
370.3333
338.0000
373.3333
326.6667
292.3333
350.0000
381.0000
351.0000
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

mcells =

18

mdim =

2

mlevel =

6
3
0

auxt =

0

ifail =

0

```
```function g11bc_example
stat = 'A';
table = [274;
361;
253;
325;
317;
339;
326;
402;
336;
379;
345;
361;
352;
334;
318;
339;
393;
358;
350;
340;
203;
397;
356;
298;
382;
376;
355;
418;
387;
379;
432;
339;
293;
322;
417;
342;
82;
297;
133;
306;
352;
361;
220;
333;
270;
388;
379;
274;
336;
307;
266;
389;
333;
353];
idim = [int64(3);6;3];
isdim = [int64(0);1;1];
maxst = int64(54);
[stable, mcells, mdim, mlevel, auxt, ifail] = g11bc(stat, table, idim, isdim, maxst)
```
```

stable =

235.3333
332.6667
196.3333
342.6667
341.6667
332.6667
309.3333
370.3333
320.3333
395.0000
370.3333
338.0000
373.3333
326.6667
292.3333
350.0000
381.0000
351.0000
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

mcells =

18

mdim =

2

mlevel =

6
3
0

auxt =

0

ifail =

0

```