Integer, Intent (In)	::	nvar, ng, ldgmn, nobs, m, isx(*), ldx, ldd
Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	gmn(ldgmn,nvar), gc((ng+1)nvar(nvar+1)/2), x(ldx,*)
Real (Kind=nag_wp), Intent (Inout)	::	d(ldd,ng)
Real (Kind=nag_wp), Intent (Out)	::	wk(2*nvar)
Character (1), Intent (In)	::	equal, mode

C Header Interface

#include <nag.h>

void

g03dbf_ (const char *equal, const char *mode, const Integer *nvar, const Integer *ng, const double gmn[], const Integer *ldgmn, const double gc[], const Integer *nobs, const Integer *m, const Integer isx[], const double x[], const Integer *ldx, double d[], const Integer *ldd, double wk[], Integer *ifail, const Charlen length_equal, const Charlen length_mode)

The routine may be called by the names g03dbf or nagf_mv_discrim_mahal.

3 Description

Consider

p

variables observed on

n_{g}

populations or groups. Let

{\bar{x}}_{j}

be the sample mean and

S_{j}

the within-group variance-covariance matrix for the

j

th group and let

x_{k}

be the

k

th sample point in a dataset. A measure of the distance of the point from the

j

th population or group is given by the Mahalanobis distance,

D_{k j}

D_{k j}^{2} = {(x_{k} - {\bar{x}}_{j})}^{T} S_{j}^{- 1} (x_{k} - {\bar{x}}_{j}) .

If the pooled estimated of the variance-covariance matrix

S

is used rather than the within-group variance-covariance matrices, then the distance is:

D_{k j}^{2} = {(x_{k} - {\bar{x}}_{j})}^{T} S^{- 1} (x_{k} - {\bar{x}}_{j}) .

Instead of using the variance-covariance matrices

S

and

S_{j}

, g03dbf uses the upper triangular matrices

R

and

R_{j}

supplied by g03daf such that

S = R^{T} R

and

S_{j} = R_{j}^{T} R_{j}

D_{k j}^{2}

can then be calculated as

z^{T} z

where

R_{j} z = (x_{k} - {\bar{x}}_{j})

R z = (x_{k} - {\bar{x}}_{j})

as appropriate.

A particular case is when the distance between the group or population means is to be estimated. The Mahalanobis squared distance between the

i

th and

j

th groups is:

D_{i j}^{2} = {({\bar{x}}_{i} - {\bar{x}}_{j})}^{T} S_{j}^{- 1} ({\bar{x}}_{i} - {\bar{x}}_{j})

D_{i j}^{2} = {({\bar{x}}_{i} - {\bar{x}}_{j})}^{T} S^{- 1} ({\bar{x}}_{i} - {\bar{x}}_{j}) .

Note:

D_{j j}^{2} = 0

and that in the case when the pooled variance-covariance matrix is used

D_{i j}^{2} = D_{j i}^{2}

so in this case only the lower triangular values of

D_{i j}^{2}

i > j

, are computed.

4 References

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

5 Arguments

1: $equal$ – Character(1) Input

On entry: indicates whether or not the within-group variance-covariance matrices are assumed to be equal and the pooled variance-covariance matrix used.

$equal ='E'$: The within-group variance-covariance matrices are assumed equal and the matrix $R$ stored in the first $p (p + 1) / 2$ elements of gc is used.
$equal ='U'$: The within-group variance-covariance matrices are assumed to be unequal and the matrices $R_{j}$ , for $j = 1, 2, \dots, n_{g}$ , stored in the remainder of gc are used.

Constraint:

equal ='E'

'U'

2: $mode$ – Character(1) Input

On entry: indicates whether distances from sample points are to be calculated or distances between the group means.

$mode ='S'$: The distances between the sample points given in x and the group means are calculated.
$mode ='M'$: The distances between the group means will be calculated.

Constraint:

mode ='M'

'S'

3: $nvar$ – Integer Input

On entry:

p

, the number of variables in the variance-covariance matrices as specified to g03daf.

Constraint:

nvar \geq 1

4: $ng$ – Integer Input

On entry: the number of groups,

n_{g}

Constraint:

ng \geq 2

5: $gmn (ldgmn, nvar)$ – Real (Kind=nag_wp) array Input

On entry: the

j

th row of gmn contains the means of the

p

selected variables for the

j

th group, for

j = 1, 2, \dots, n_{g}

. These are returned by g03daf.

6: $ldgmn$ – Integer Input

On entry: the first dimension of the array gmn as declared in the (sub)program from which g03dbf is called.

Constraint:

ldgmn \geq ng

7: $gc ((ng + 1) \times nvar \times (nvar + 1) / 2)$ – Real (Kind=nag_wp) array Input

On entry: the first

p (p + 1) / 2

elements of gc should contain the upper triangular matrix

R

and the next

n_{g}

blocks of

p (p + 1) / 2

elements should contain the upper triangular matrices

R_{j}

. All matrices must be stored packed by column. These matrices are returned by g03daf. If

equal ='E'

only the first

p (p + 1) / 2

elements are referenced, if

equal ='U'

only the elements

p (p + 1) / 2 + 1

(n_{g} + 1) p (p + 1) / 2

are referenced.

Constraints:

if $equal ='E'$ , $R \neq 0.0$ ;
if $equal ='U'$ , the diagonal elements of the $R_{j} \neq 0.0$ , for $j = 1, 2, \dots, ng$ .

8: $nobs$ – Integer Input

On entry: if

mode ='S'

, the number of sample points in x for which distances are to be calculated.

mode ='M'

, nobs is not referenced.

Constraint: if

nobs \geq 1

mode ='S'

9: $m$ – Integer Input

On entry: if

mode ='S'

, the number of variables in the data array x.

mode ='M'

, m is not referenced.

Constraint: if

m \geq nvar

mode ='S'

10: $isx (*)$ – Integer array Input

Note: the dimension of the array isx must be at least

\max (1, m)

On entry: if

mode ='S'

isx (l)

indicates if the

l

th variable in x is to be included in the distance calculations. If

isx (l) > 0

the

l

th variable is included, for

l = 1, 2, \dots, m

; otherwise the

l

th variable is not referenced.

mode ='M'

, isx is not referenced.

Constraint: if

mode ='S'

isx (l) > 0

for nvar values of

l

11: $x (ldx, *)$ – Real (Kind=nag_wp) array Input

Note: the second dimension of the array x must be at least

\max (1, m)

On entry: if

mode ='S'

the

k

th row of x must contain

x_{k}

. That is

x (k, l)

must contain the

k

th sample value for the

l

th variable, for

k = 1, 2, \dots, nobs

and

l = 1, 2, \dots, m

. Otherwise x is not referenced.

12: $ldx$ – Integer Input

On entry: the first dimension of the array x as declared in the (sub)program from which g03dbf is called.

Constraints:

if $mode ='S'$ , $ldx \geq nobs$ ;
otherwise $ldx \geq 1$ .

13: $d (ldd, ng)$ – Real (Kind=nag_wp) array Output

On exit: the squared distances.

mode ='S'

d (k, j)

contains the squared distance of the

k

th sample point from the

j

th group mean,

D_{k j}^{2}

, for

k = 1, 2, \dots, nobs

and

j = 1, 2, \dots, n_{g}

mode ='M'

and

equal ='U'

d (i, j)

contains the squared distance between the

i

th mean and the

j

th mean,

D_{i j}^{2}

, for

i = 1, 2, \dots, n_{g}

and

j = 1, 2, \dots, i - 1, i + 1, \dots, n_{g}

. The elements

d (i, i)

are not referenced, for

i = 1, 2, \dots, n_{g}

mode ='M'

and

equal ='E'

d (i, j)

contains the squared distance between the

i

th mean and the

j

th mean,

D_{i j}^{2}

, for

i = 1, 2, \dots, n_{g}

and

j = 1, 2, \dots, i - 1

. Since

D_{i j} = D_{j i}

the elements

d (i, j)

are not referenced, for

i = 1, 2, \dots, n_{g}

and

j = i + 1, \dots, n_{g}

14: $ldd$ – Integer Input

On entry: the first dimension of the array d as declared in the (sub)program from which g03dbf is called.

Constraints:

if $mode ='S'$ , $ldd \geq nobs$ ;
if $mode ='M'$ , $ldd \geq ng$ .

15: $wk (2 \times nvar)$ – Real (Kind=nag_wp) array Workspace

16: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

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

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

−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, $equal = ⟨ value ⟩$ .
Constraint: $equal ='E'$ or $'U'$ .

On entry, $ldd = ⟨ value ⟩$ and $ng = ⟨ value ⟩$ .
Constraint: $ldd \geq ng$ .

On entry, $ldd = ⟨ value ⟩$ and $nobs = ⟨ value ⟩$ .
Constraint: $ldd \geq nobs$ .

On entry, $ldgmn = ⟨ value ⟩$ and $ng = ⟨ value ⟩$ .
Constraint: $ldgmn \geq ng$ .

On entry, $ldx = ⟨ value ⟩$ and $nobs = ⟨ value ⟩$ .
Constraint: $ldx \geq nobs$ .

On entry, $m = ⟨ value ⟩$ and $nvar = ⟨ value ⟩$ .
Constraint: $m \geq nvar$ .

On entry, $mode = ⟨ value ⟩$ .
Constraint: $mode ='M'$ or $'S'$ .

On entry, $ng = ⟨ value ⟩$ .
Constraint: $ng \geq 2$ .

On entry, $nobs = ⟨ value ⟩$ .
Constraint: $nobs \geq 1$ .

On entry, $nvar = ⟨ value ⟩$ .
Constraint: $nvar \geq 1$ .

$ifail = 2$: On entry, diagonal element $⟨ value ⟩$ of $R = 0$ .

On entry, diagonal element $⟨ value ⟩$ of $R_{j} = 0$ for $j = ⟨ value ⟩$ .

On entry, $nvar = ⟨ value ⟩$ and $⟨ value ⟩$ values of $isx > 0$ .
Constraint: exactly nvar elements of $isx > 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

The accuracy will depend upon the accuracy of the input

R

R_{j}

matrices.

8 Parallelism and Performance

g03dbf 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.

9 Further Comments

If the distances are to be used for discrimination, see also g03dcf.

10 Example

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 group means and

R

matrices are computed by g03daf. A further six observations of unknown type are input, and the distances from the group means of the

21

patients of known type are computed under the assumption that the within-group variance-covariance matrices are not equal. These results are printed and indicate that the first four are close to one of the groups while observations

5

and

6

are some distance from any group.

g03db: FL CL CPP AD

NAG FL Interfaceg03dbf (discrim_​mahal)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
g03dbf (discrim_mahal)