G01AFF (PDF version)
G01 Chapter Contents
G01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G01AFF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

G01AFF performs the analysis of a two-way r×c contingency table or classification. If r=c=2, and the total number of objects classified is 40 or fewer, then the probabilities for Fisher's exact test are computed. Otherwise, a test statistic is computed (with Yates' correction when r=c=2), which under the assumption of no association between the classifications has approximately a chi-square distribution with r-1×c-1 degrees of freedom.

2  Specification

SUBROUTINE G01AFF ( LDNOB, LDPRED, M, N, NOBS, NUM, PRED, CHIS, P, NPOS, NDF, M1, N1, IFAIL)
INTEGER  LDNOB, LDPRED, M, N, NOBS(LDNOB,N), NUM, NPOS, NDF, M1, N1, IFAIL
REAL (KIND=nag_wp)  PRED(LDPRED,N), CHIS, P(21)

3  Description

The data consist of the frequencies for the two-way classification, denoted by nij, for i=1,2,,m and j=1,2,,n with m,n>1.
A check is made to see whether any row or column of the matrix of frequencies consists entirely of zeros, and if so, the matrix of frequencies is reduced by omitting that row or column. Suppose the final size of the matrix is m1 by n1 (m1,n1>1), and let
There are two situations:
(i) If m1>2 and/or n1>2, or m1=n1=2 and T>40, then the matrix of expected frequencies, denoted by rij, for i=1,2,,m1 and j=1,2,,n1, and the test statistic, χ2, are computed, where
rij=RiCj/T,  i=1,2,,m1;j=1,2,,n1  
and
χ2=i= 1m1j= 1n1rij-nij-Y2/rij,  
where
Y= 12  if ​ m1=n1=2 0  otherwise  
is Yates' correction for continuity.
Under the assumption that there is no association between the two classifications, χ2 will have approximately a chi-square distribution with m1-1×n1-1 degrees of freedom.
An option exists which allows for further ‘shrinkage’ of the matrix of frequencies in the case where rij<1 for the (i,j)th cell. If this is the case, then row i or column j will be combined with the adjacent row or column with smaller total. Row i is selected for combination if Ri×m1Cj×n1. This ‘shrinking’ process is continued until rij1 for all cells (i,j).
(ii) If m1=n1=2 and T40, the probabilities to enable Fisher's exact test to be made are computed.
The matrix of frequencies may be rearranged so that R1 is the smallest marginal (i.e., column and row) total, and C2C1. Under the assumption of no association between the classifications, the probability of obtaining r entries in cell 1,1 is computed where
Pr+1=R1!R2!C1!C2! T!r!R1-r!C1-r!T-C1-R1+r! ,  r=0,1,,R1.  
The probability of obtaining the table of given frequencies is returned. A test of the assumption against some alternative may then be made by summing the relevant values of Pr.

4  References

None.

5  Parameters

1:     LDNOB – INTEGERInput
On entry: the first dimension of the array NOBS as declared in the (sub)program from which G01AFF is called.
Constraint: LDNOBM.
2:     LDPRED – INTEGERInput
On entry: the first dimension of the array PRED as declared in the (sub)program from which G01AFF is called.
Constraint: LDPREDM.
3:     M – INTEGERInput
On entry: m+1, one more than the number of rows of the frequency matrix.
Constraint: M>2.
4:     N – INTEGERInput
On entry: n+1, one more than the number of columns of the frequency matrix.
Constraint: N>2.
5:     NOBSLDNOBN – INTEGER arrayInput/Output
On entry: the elements NOBSij, for i=1,2,,m and j=1,2,,n, must contain the frequencies for the two-way classification. The m+1th row and the n+1th column of NOBS need not be set.
On exit: contains the following information:
  • NOBSij, for i=1,2,,m1 and j=1,2,,n1, contain the frequencies for the two-way classification after ‘shrinkage’ has taken place (see Section 3).
  • NOBSin+1, for i=1,2,,m1, contain the total frequencies in the remaining rows, Ri.
  • NOBSm+1j, for j=1,2,,n1, contain the total frequencies in the remaining columns, Cj.
  • NOBSm+1n+1, contains the total frequency, T.
If any ‘shrinkage’ has occurred, then all other cells contain no useful information.
Constraint: NOBSij0, for i=1,2,,M-1 and j=1,2,,N-1.
6:     NUM – INTEGERInput/Output
On entry: the value assigned to NUM must determine whether automatic ‘shrinkage’ is required when any rij<1, as outlined in Section 3(i).
If NUM=1, shrinkage is required, otherwise shrinkage is not required.
On exit: when Fisher's exact test for a 2×2 classification is used then NUM contains the number of elements used in the array P, otherwise NUM is set to zero.
7:     PREDLDPREDN – REAL (KIND=nag_wp) arrayOutput
On exit: the elements PREDij, where i=1,2,,M1 and j=1,2,,N1 contain the expected frequencies, rij corresponding to the observed frequencies NOBSij, except in the case when Fisher's exact test for a 2×2 classification is to be used, when PRED is not used. No other elements are utilized.
8:     CHIS – REAL (KIND=nag_wp)Output
On exit: the value of the test statistic, χ2, except when Fisher's exact test for a 2×2 classification is used in which case it is unspecified.
9:     P21 – REAL (KIND=nag_wp) arrayOutput
P is used only when Fisher's exact test for a 2×2 classification is to be used.
On exit: the first NUM elements contain the probabilities associated with the various possible frequency tables, Pr, for r=0,1,,R1, the remainder are unspecified.
10:   NPOS – INTEGEROutput
NPOS is used only when Fisher's exact test for a 2×2 classification is to be used.
On exit: PNPOS holds the probability associated with the given table of frequencies.
11:   NDF – INTEGEROutput
On exit: the value of NDF gives the number of degrees of freedom for the chi-square distribution, m1-1×n1-1; when Fisher's exact test is used NDF=1.
12:   M1 – INTEGEROutput
On exit: the number of rows of the two-way classification, after any ‘shrinkage’, m1.
13:   N1 – INTEGEROutput
On exit: the number of columns of the two-way classification, after any ‘shrinkage’, n1.
14:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ 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 parameter, the recommended value is 0. 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
The number of rows or columns of NOBS is less than 2, possibly after shrinkage.
IFAIL=2
At least one frequency is negative, or all frequencies are zero.
IFAIL=4
On entry,LDPRED<M,
orLDNOB<M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.8 in the Essential Introduction for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.7 in the Essential Introduction for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

The method used is believed to be stable.

8  Parallelism and Performance

Not applicable.

9  Further Comments

The time taken by G01AFF will increase with M and N, except when Fisher's exact test is to be used, in which case it increases with size of the marginal and total frequencies.
If, on exit, NUM>0, or alternatively NDF is 1 and NOBSMN40, the probabilities for use in Fisher's exact test for a 2×2 classification will be calculated, and not the test statistic with approximately a chi-square distribution.

10  Example

In the example program, NPROB determines the number of two-way classifications to be analysed. For each classification the frequencies are read, G01AFF called, and information given on how much ‘shrinkage’ has taken place. If Fisher's exact test is to be used, the given frequencies and the array of probabilities associated with the possible frequency tables are printed. Otherwise, if the chi-square test is to be used, the given and expected frequencies, and the test statistic with its degrees of freedom are printed. In the example, there is one 2×3 classification, with shrinkage not requested.

10.1  Program Text

Program Text (g01affe.f90)

10.2  Program Data

Program Data (g01affe.d)

10.3  Program Results

Program Results (g01affe.r)


G01AFF (PDF version)
G01 Chapter Contents
G01 Chapter Introduction
NAG Library Manual

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