NAG FL Interface
g11bcf (tabulate_​margin)

Settings help

FL Name Style:


FL Specification Language:


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 <nag.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)
The routine may be called by the names g11bcf or nagf_contab_tabulate_margin.

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×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 g11baf or g11bbf, g11bcf 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.

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: stat Character(1) Input
On entry: indicates which statistic is to be used to compute the marginal table.
stat='T'
The total.
stat='A'
The average or mean.
stat='M'
The median.
stat='V'
The variance.
stat='L'
The largest value.
stat='S'
The smallest value.
Constraint: stat='T', 'A', 'M', 'V', 'L' or 'S'.
2: table(ncells) Real (Kind=nag_wp) array Input
On entry: the table as computed by g11baf or g11bbf.
3: ncells Integer Input
On entry: the number of cells in table as returned by g11baf or g11bbf.
4: ndim Integer Input
On entry: the number of dimensions for table as returned by g11baf or g11bbf.
Constraint: ndim2.
5: idim(ndim) Integer array Input
On entry: the number of levels for each dimension of table as returned by g11baf or g11bbf.
Constraint: idim(i)2, for i=1,2,,ndim.
6: isdim(ndim) Integer array Input
On entry: indicates which dimensions of table are to be included in the sub-table. If isdim(i)>0 the dimension or factor indicated by idim(i) is to be included in the sub-table, otherwise it is excluded.
7: stable(maxst) Real (Kind=nag_wp) array Output
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: maxst Integer Input
On entry: the maximum size of sub-table to be computed.
Constraint: maxst the product of the levels of the dimensions of table included in the sub-table, stable.
9: mcells Integer Output
On exit: the number of cells in the sub-table in stable.
10: mdim Integer Output
On exit: the number of dimensions to the sub-table in stable.
11: mlevel(ndim) Integer array Output
On exit: the first mdim elements contain the number of levels for the dimensions of the sub-table in stable. The remaining elements are not referenced.
12: auxt(*) Real (Kind=nag_wp) array Output
Note: the dimension of the array auxt must be at least maxst if stat='V', and at least 1 otherwise.
On exit: if stat='V' auxt contains the sub-table of means corresponding to the sub-table of variances in stable. Otherwise auxt is not referenced.
13: iwk(3×ndim) Integer array Workspace
14: wk(ncells) Real (Kind=nag_wp) array Workspace
15: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry 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:
ifail=1
On entry, ndim=value.
Constraint: ndim2.
On entry, stat=value.
Constraint: stat='T', 'A', 'M', 'V', 'L' or 'S'.
ifail=2
On entry, all elements of isdim>0.
On entry, i=value and idim(i)=value.
Constraint: idim2.
On entry, maxst=value and minimum value for maxst=value.
Constraint: maxstproduct of the levels of the dimensions of the table included in the sub-table, stable.
On entry, ncells is incompatible with idim.
On entry, no elements of isdim>0.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

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

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
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 implementation-specific information.

9 Further Comments

The sub-tables 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 lk levels, then the cell defined by the levels i1,i2,,im of the factors is stored in sth cell given by
s=1+k=1m[(ik-1)ck],  
where
cj=k=j+ 1m lk   for ​ j= 1, 2,, n- 1   and   cm=1.  

10 Example

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.1 Program Text

Program Text (g11bcfe.f90)

10.2 Program Data

Program Data (g11bcfe.d)

10.3 Program Results

Program Results (g11bcfe.r)