NAG Library ManualKeyword Search:

NAG Library Function Document

nag_mv_discrim_mahaldist (g03dbc)

▸▿ 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

1 Purpose

nag_mv_discrim_mahaldist (g03dbc) computes Mahalanobis squared distances for group or pooled variance-covariance matrices. It is intended for use after nag_mv_discrim (g03dac).

2 Specification

#include <nag.h>

#include <nagg03.h>

void	nag_mv_discrim_mahaldist (Nag_GroupCovars equal, Nag_MahalDist mode, Integer nvar, Integer ng, const double gmean[], Integer tdg, const double gc[], Integer nobs, Integer m, const Integer isx[], const double x[], Integer tdx, double d[], Integer tdd, NagError *fail)

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}^{2}

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}

, nag_mv_discrim_mahaldist (g03dbc) uses the upper triangular matrices

R

and

R_{j}

supplied by nag_mv_discrim (g03dac) 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 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$ – Nag_GroupCovarsInput

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 = Nag_EqualCovar$: 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 = Nag_NotEqualCovar$: 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 = Nag_EqualCovar

Nag_NotEqualCovar

2: $mode$ – Nag_MahalDistInput

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

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

Constraint:

mode = Nag_SamplePoints

Nag_GroupMeans

3: $nvar$ – IntegerInput

On entry: the number of variables,

p

, in the variance-covariance matrices as specified to nag_mv_discrim (g03dac).

Constraint:

nvar \geq 1

4: $ng$ – IntegerInput

On entry: the number of groups,

n_{g}

Constraint:

ng \geq 2

5: $gmean [ng \times tdg]$ – const doubleInput

Note: the

(i, j)

th element of the matrix is stored in

gmean [(i - 1) \times tdg + j - 1]

On entry: the

j

th row of gmean contains the means of the

p

selected variables for the

j

th group, for

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

. These are returned by nag_mv_discrim (g03dac).

6: $tdg$ – IntegerInput

On entry: the stride separating matrix column elements in the array gmean.

Constraint:

tdg \geq nvar

7: $gc [\dim]$ – const doubleInput

Note: the dimension, dim, of the array gc must be at least

(ng + 1) \times nvar \times (nvar + 1) / 2

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 nag_mv_discrim (g03dac).

equal = Nag_EqualCovar

only the first

p (p + 1) / 2

elements are referenced.

equal = Nag_NotEqualCovar

only the elements

p (p + 1) / 2

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

are referenced.

Constraints:

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

8: $nobs$ – IntegerInput

On entry: if

mode = Nag_SamplePoints

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

mode = Nag_GroupMeans

, nobs is not referenced.

Constraint: if

mode = Nag_SamplePoints

nobs \geq 1

9: $m$ – IntegerInput

On entry: if

mode = Nag_SamplePoints

the number of variables in the data array x.

mode = Nag_GroupMeans

, then m is not referenced.

Constraint: if

mode = Nag_SamplePoints

m \geq nvar

10: $isx [m]$ – const IntegerInput

On entry: if

mode = Nag_SamplePoints

isx [l - 1]

indicates if the

l

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

isx [l - 1] > 0

, the

l

th variable is included, for

l = 1, 2, \dots, m

; otherwise the

l

th variable is not referenced.

mode = Nag_GroupMeans

, then isx is not referenced and may be set to the NULL pointer (Integer *)0.

Constraint: if

mode = Nag_SamplePoints

isx [l - 1] > 0

for nvar values of

l

11: $x [nobs \times tdx]$ – const doubleInput

On entry: if

mode = Nag_SamplePoints

, the

k

th row of x must contain

x_{k}

. That is,

x [(k - 1) \times tdx + l - 1]

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 and may be set to the NULL pointer (double *)0.

12: $tdx$ – IntegerInput

On entry: the stride separating matrix column elements in the array x.

Constraint:

tdx \geq \max (1, m)

13: $d [dim1 \times tdd]$ – doubleOutput

On exit: the squared distances.

mode = Nag_SamplePoints

d [(k - 1) \times tdd + j - 1]

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 = Nag_GroupMeans

and

equal = Nag_NotEqualCovar

d [(i - 1) \times tdd + j - 1]

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 - 1) \times tdd + i - 1]

are not referenced, for

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

mode = Nag_GroupMeans

and

equal = Nag_EqualCovar

d [(i - 1) \times tdd + j - 1]

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 - 1) \times tdd + j - 1]

are not referenced, for

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

and

j = i, \dots, n_{g}

14: $tdd$ – IntegerInput

On entry: the stride separating matrix column elements in the array d.

Constraint:

tdd \geq ng

15: $fail$ – NagError *Input/Output

The NAG error argument (see Section 2.7 in How to Use the NAG Library and its Documentation).

6 Error Indicators and Warnings

NE_2_INT_ARG_ENUM_CONS: On entry, $m = 〈value〉$ while $nvar = 〈value〉$ and $mode = Nag_SamplePoints$ . These arguments must satisfy $m \geq nvar$ when $mode = Nag_SamplePoints$ .

On entry, $tdx = 〈value〉$ while $m = 〈value〉$ and $mode = Nag_SamplePoints$ . These arguments must satisfy $tdx \geq \max$ (1,m) when $mode = Nag_SamplePoints$ .
NE_2_INT_ARG_LT: On entry, $tdd = 〈value〉$ while $ng = 〈value〉$ . These arguments must satisfy $tdd \geq ng$ .

On entry, $tdg = 〈value〉$ while $nvar = 〈value〉$ . These arguments must satisfy $tdg \geq nvar$ .
NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument equal had an illegal value.

On entry, argument mode had an illegal value.
NE_DIAG_0_COND: A diagonal element of $R$ is zero when $equal = Nag_EqualCovar$ .
NE_DIAG_0_J_COND: A diagonal element of $R$ is zero for some $j$ , when $equal = Nag_NotEqualCovar$ .
NE_INT_ARG_ENUM_CONS: On entry, $nobs = 〈value〉$ while $mode = Nag_SamplePoints$ . These arguments must satisfy $nobs \geq 1$ when $mode = Nag_SamplePoints$ .
NE_INT_ARG_LT: On entry, $ng = 〈value〉$ .
Constraint: $ng \geq 2$ .

On entry, $nvar = 〈value〉$ .
Constraint: $nvar \geq 1$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_VAR_INCL_COND: The number of variables, nvar in the analysis $= 〈value〉$ , while number of variables included in the analysis via array $isx = 〈value〉$ .
Constraint: These two numbers must be the same when $mode = Nag_SamplePoints$ .

7 Accuracy

The accuracy will depend upon the accuracy of the input

R

R_{j}

matrices.

8 Parallelism and Performance

nag_mv_discrim_mahaldist (g03dbc) is not threaded in any implementation.

9 Further Comments

If the distances are to be used for discrimination, see also nag_mv_discrim_group (g03dcc).

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 nag_mv_discrim (g03dac). 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.

NAG Library Function Documentnag_mv_discrim_mahaldist (g03dbc)

▸▿ 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 Library Function Document

nag_mv_discrim_mahaldist (g03dbc)