# NAG FL Interfaceg03daf (discrim)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

g03daf computes a test statistic for the equality of within-group covariance matrices and also computes matrices for use in discriminant analysis.

## 2Specification

Fortran Interface
 Subroutine g03daf ( n, m, x, ldx, isx, nvar, ing, ng, wt, nig, gmn, det, gc, stat, df, sig, wk, iwk,
 Integer, Intent (In) :: n, m, ldx, isx(m), nvar, ing(n), ng, ldgmn Integer, Intent (Inout) :: ifail Integer, Intent (Out) :: nig(ng), iwk(ng) Real (Kind=nag_wp), Intent (In) :: x(ldx,m), wt(*) Real (Kind=nag_wp), Intent (Inout) :: gmn(ldgmn,nvar) Real (Kind=nag_wp), Intent (Out) :: det(ng), gc((ng+1)*nvar*(nvar+1)/2), stat, df, sig, wk(n*(nvar+1)) Character (1), Intent (In) :: weight
#include <nag.h>
 void g03daf_ (const char *weight, const Integer *n, const Integer *m, const double x[], const Integer *ldx, const Integer isx[], const Integer *nvar, const Integer ing[], const Integer *ng, const double wt[], Integer nig[], double gmn[], const Integer *ldgmn, double det[], double gc[], double *stat, double *df, double *sig, double wk[], Integer iwk[], Integer *ifail, const Charlen length_weight)
The routine may be called by the names g03daf or nagf_mv_discrim.

## 3Description

Let a sample of $n$ observations on $p$ variables come from ${n}_{g}$ groups with ${n}_{j}$ observations in the $j$th group and $\sum {n}_{j}=n$. If the data is assumed to follow a multivariate Normal distribution with the variance-covariance matrix of the $j$th group ${\Sigma }_{j}$, then to test for equality of the variance-covariance matrices between groups, that is, ${\Sigma }_{1}={\Sigma }_{2}=\cdots ={\Sigma }_{{n}_{g}}=\Sigma$, the following likelihood-ratio test statistic, $G$, can be used;
 $G=C {(n-ng)log|S|-∑j=1ng(nj-1)log|Sj|} ,$
where
 $C= 1-2p2+3p- 1 6⁢(p+1)(ng-1) (∑j= 1ng1 (nj-1) -1 (n-ng) ) ,$
and ${S}_{j}$ are the within-group variance-covariance matrices and $S$ is the pooled variance-covariance matrix given by
 $S=∑j=1ng(nj-1)Sj (n-ng) .$
For large $n$, $G$ is approximately distributed as a ${\chi }^{2}$ variable with $\frac{1}{2}p\left(p+1\right)\left({n}_{g}-1\right)$ degrees of freedom, see Morrison (1967) for further comments. If weights are used, then $S$ and ${S}_{j}$ are the weighted pooled and within-group variance-covariance matrices and $n$ is the effective number of observations, that is, the sum of the weights.
Instead of calculating the within-group variance-covariance matrices and then computing their determinants in order to calculate the test statistic, g03daf uses a $QR$ decomposition. The group means are subtracted from the data and then for each group, a $QR$ decomposition is computed to give an upper triangular matrix ${R}_{j}^{*}$. This matrix can be scaled to give a matrix ${R}_{j}$ such that ${S}_{j}={R}_{j}^{\mathrm{T}}{R}_{j}$. The pooled $R$ matrix is then computed from the ${R}_{j}$ matrices. The values of $|S|$ and the $|{S}_{j}|$ can then be calculated from the diagonal elements of $R$ and the ${R}_{j}$.
This approach means that the Mahalanobis squared distances for a vector observation $x$ can be computed as ${z}^{\mathrm{T}}z$, where ${R}_{j}z=\left(x-{\overline{x}}_{j}\right)$, ${\overline{x}}_{j}$ being the vector of means of the $j$th group. These distances can be calculated by g03dbf. The distances are used in discriminant analysis and g03dcf uses the results of g03daf to perform several different types of discriminant analysis. The differences between the discriminant methods are, in part, due to whether or not the within-group variance-covariance matrices are equal.

## 4References

Aitchison J and Dunsmore I R (1975) Statistical Prediction Analysis Cambridge
Kendall M G and Stuart A (1976) The Advanced Theory of Statistics (Volume 3) (3rd Edition) Griffin
Krzanowski W J (1990) Principles of Multivariate Analysis Oxford University Press
Morrison D F (1967) Multivariate Statistical Methods McGraw–Hill

## 5Arguments

1: $\mathbf{weight}$Character(1) Input
On entry: indicates if weights are to be used.
${\mathbf{weight}}=\text{'U'}$
No weights are used.
${\mathbf{weight}}=\text{'W'}$
Weights are to be used and must be supplied in wt.
Constraint: ${\mathbf{weight}}=\text{'U'}$ or $\text{'W'}$.
2: $\mathbf{n}$Integer Input
On entry: $n$, the number of observations.
Constraint: ${\mathbf{n}}\ge 1$.
3: $\mathbf{m}$Integer Input
On entry: the number of variables in the data array x.
Constraint: ${\mathbf{m}}\ge {\mathbf{nvar}}$.
4: $\mathbf{x}\left({\mathbf{ldx}},{\mathbf{m}}\right)$Real (Kind=nag_wp) array Input
On entry: ${\mathbf{x}}\left(\mathit{k},\mathit{l}\right)$ must contain the $\mathit{k}$th observation for the $\mathit{l}$th variable, for $\mathit{k}=1,2,\dots ,n$ and $\mathit{l}=1,2,\dots ,{\mathbf{m}}$.
5: $\mathbf{ldx}$Integer Input
On entry: the first dimension of the array x as declared in the (sub)program from which g03daf is called.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
6: $\mathbf{isx}\left({\mathbf{m}}\right)$Integer array Input
On entry: ${\mathbf{isx}}\left(l\right)$ indicates whether or not the $l$th variable in x is to be included in the variance-covariance matrices.
If ${\mathbf{isx}}\left(\mathit{l}\right)>0$ the $\mathit{l}$th variable is included, for $\mathit{l}=1,2,\dots ,{\mathbf{m}}$; otherwise it is not referenced.
Constraint: ${\mathbf{isx}}\left(l\right)>0$ for nvar values of $l$.
7: $\mathbf{nvar}$Integer Input
On entry: $p$, the number of variables in the variance-covariance matrices.
Constraint: ${\mathbf{nvar}}\ge 1$.
8: $\mathbf{ing}\left({\mathbf{n}}\right)$Integer array Input
On entry: ${\mathbf{ing}}\left(\mathit{k}\right)$ indicates to which group the $\mathit{k}$th observation belongs, for $\mathit{k}=1,2,\dots ,n$.
Constraint: $1\le {\mathbf{ing}}\left(\mathit{k}\right)\le {\mathbf{ng}}$, for $\mathit{k}=1,2,\dots ,n$
The values of ing must be such that each group has at least nvar members.
9: $\mathbf{ng}$Integer Input
On entry: the number of groups, ${n}_{g}$.
Constraint: ${\mathbf{ng}}\ge 2$.
10: $\mathbf{wt}\left(*\right)$Real (Kind=nag_wp) array Input
Note: the dimension of the array wt must be at least ${\mathbf{n}}$ if ${\mathbf{weight}}=\text{'W'}$, and at least $1$ otherwise.
On entry: if ${\mathbf{weight}}=\text{'W'}$ the first $n$ elements of wt must contain the weights to be used in the analysis and the effective number of observations for a group is the sum of the weights of the observations in that group. If ${\mathbf{wt}}\left(k\right)=0.0$ the $k$th observation is excluded from the calculations.
If ${\mathbf{weight}}=\text{'U'}$, wt is not referenced and the effective number of observations for a group is the number of observations in that group.
Constraint: if ${\mathbf{weight}}=\text{'W'}$, ${\mathbf{wt}}\left(\mathit{k}\right)\ge 0.0$, for $\mathit{k}=1,2,\dots ,n$.
11: $\mathbf{nig}\left({\mathbf{ng}}\right)$Integer array Output
On exit: ${\mathbf{nig}}\left(\mathit{j}\right)$ contains the number of observations in the $\mathit{j}$th group, for $\mathit{j}=1,2,\dots ,{n}_{g}$.
12: $\mathbf{gmn}\left({\mathbf{ldgmn}},{\mathbf{nvar}}\right)$Real (Kind=nag_wp) array Output
On exit: the $\mathit{j}$th row of gmn contains the means of the $p$ selected variables for the $\mathit{j}$th group, for $\mathit{j}=1,2,\dots ,{n}_{g}$.
13: $\mathbf{ldgmn}$Integer Input
On entry: the first dimension of the array gmn as declared in the (sub)program from which g03daf is called.
Constraint: ${\mathbf{ldgmn}}\ge {\mathbf{ng}}$.
14: $\mathbf{det}\left({\mathbf{ng}}\right)$Real (Kind=nag_wp) array Output
On exit: the logarithm of the determinants of the within-group variance-covariance matrices.
15: $\mathbf{gc}\left(\left({\mathbf{ng}}+1\right)×{\mathbf{nvar}}×\left({\mathbf{nvar}}+1\right)/2\right)$Real (Kind=nag_wp) array Output
On exit: the first $p\left(p+1\right)/2$ elements of gc contain $R$ and the remaining ${n}_{g}$ blocks of $p\left(p+1\right)/2$ elements contain the ${R}_{j}$ matrices. All are stored in packed form by columns.
16: $\mathbf{stat}$Real (Kind=nag_wp) Output
On exit: the likelihood-ratio test statistic, $G$.
17: $\mathbf{df}$Real (Kind=nag_wp) Output
On exit: the degrees of freedom for the distribution of $G$.
18: $\mathbf{sig}$Real (Kind=nag_wp) Output
On exit: the significance level for $G$.
19: $\mathbf{wk}\left({\mathbf{n}}×\left({\mathbf{nvar}}+1\right)\right)$Real (Kind=nag_wp) array Workspace
20: $\mathbf{iwk}\left({\mathbf{ng}}\right)$Integer array Workspace
21: $\mathbf{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 $-\mathbf{1}$ 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).

## 6Error 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{ldgmn}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ng}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldgmn}}\ge {\mathbf{ng}}$.
On entry, ${\mathbf{ldx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{nvar}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m}}\ge {\mathbf{nvar}}$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{ng}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ng}}\ge 2$.
On entry, ${\mathbf{nvar}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nvar}}\ge 1$.
On entry, ${\mathbf{weight}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{weight}}=\text{'U'}$ or $\text{'W'}$.
${\mathbf{ifail}}=2$
On entry, $i=⟨\mathit{\text{value}}⟩$ and ${\mathbf{wt}}\left(i\right)<0.0$.
Constraint: ${\mathbf{wt}}\left(i\right)\ge 0.0$.
${\mathbf{ifail}}=3$
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{ing}}\left(i\right)=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ng}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{ing}}\left(i\right)\le {\mathbf{ng}}$.
On entry, ${\mathbf{nvar}}=⟨\mathit{\text{value}}⟩$ and $⟨\mathit{\text{value}}⟩$ values of ${\mathbf{isx}}>0$
Constraint: exactly nvar elements of ${\mathbf{isx}}>0$.
The effective number of observations for group $⟨\mathit{\text{value}}⟩$ is less than $1$.
The number of observations for group $⟨\mathit{\text{value}}⟩$ is less than nvar.
${\mathbf{ifail}}=4$
$R$ is not of full rank.
${R}_{j}$ is not of full rank for $j=⟨\mathit{\text{value}}⟩$.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{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.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

The accuracy is dependent on the accuracy of the computation of the $QR$ decomposition. See f08aef for further details.

## 8Parallelism and Performance

g03daf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g03daf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
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.

The time taken will be approximately proportional to $n{p}^{2}$.

## 10Example

The data, taken from Aitchison and Dunsmore (1975), is concerned with the diagnosis of three ‘types’ of Cushing's syndrome. The variables are the logarithms of the urinary excretion rates (mg/24hr) of two steroid metabolites. Observations for a total of $21$ patients are input and the statistics computed by g03daf. The printed results show that there is evidence that the within-group variance-covariance matrices are not equal.

### 10.1Program Text

Program Text (g03dafe.f90)

### 10.2Program Data

Program Data (g03dafe.d)

### 10.3Program Results

Program Results (g03dafe.r)