Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_mv_multidimscal_metric (g03fa)

## Purpose

nag_mv_multidimscal_metric (g03fa) performs a principal coordinate analysis also known as classical metric scaling.

## Syntax

[x, eval, ifail] = g03fa(roots, n, d, ndim)
[x, eval, ifail] = nag_mv_multidimscal_metric(roots, n, d, ndim)

## Description

For a set of n$n$ objects a distance matrix D$D$ can be calculated such that dij${d}_{ij}$ is a measure of how ‘far apart’ are objects i$i$ and j$j$ (see nag_mv_distance_mat (g03ea) for example). Principal coordinate analysis or metric scaling starts with a distance matrix and finds points X$X$ in Euclidean space such that those points have the same distance matrix. The aim is to find a small number of dimensions, k(n1)$k\ll \left(n-1\right)$, that provide an adequate representation of the distances.
The principal coordinates of the points are computed from the eigenvectors of the matrix E$E$ where eij = 1 / 2 (dij2di . 2d . j2 + d . . 2) ${e}_{ij}=-1/2\left({d}_{ij}^{2}-{d}_{i.}^{2}-{d}_{.j}^{2}+{d}_{..}^{2}\right)$ with di . 2${d}_{i.}^{2}$ denoting the average of dij2${d}_{ij}^{2}$ over the suffix j$j$, etc.. The eigenvectors are then scaled by multiplying by the square root of the value of the corresponding eigenvalue.
Provided that the ordered eigenvalues, λi${\lambda }_{i}$, of the matrix E$E$ are all positive, i = 1k λi / i = 1n1 λi $\sum _{i=1}^{k}{\lambda }_{i}/\sum _{i=1}^{n-1}{\lambda }_{i}$ shows how well the data is represented in k$k$ dimensions. The eigenvalues will be non-negative if E$E$ is positive semidefinite. This will be true provided dij${d}_{ij}$ satisfies the inequality: dij dik + djk ${d}_{ij}\le {d}_{ik}+{d}_{jk}$ for all i,j,k$i,j,k$. If this is not the case the size of the negative eigenvalue reflects the amount of deviation from this condition and the results should be treated cautiously in the presence of large negative eigenvalues. See Krzanowski (1990) for further discussion. nag_mv_multidimscal_metric (g03fa) provides the option for all eigenvalues to be computed so that the smallest eigenvalues can be checked.

## References

Chatfield C and Collins A J (1980) Introduction to Multivariate Analysis Chapman and Hall
Gower J C (1966) Some distance properties of latent root and vector methods used in multivariate analysis Biometrika 53 325–338
Krzanowski W J (1990) Principles of Multivariate Analysis Oxford University Press

## Parameters

### Compulsory Input Parameters

1:     roots – string (length ≥ 1)
Indicates if all the eigenvalues are to be computed or just the ndim largest.
roots = 'A'${\mathbf{roots}}=\text{'A'}$
All the eigenvalues are computed.
roots = 'L'${\mathbf{roots}}=\text{'L'}$
Only the largest ndim eigenvalues are computed.
Constraint: roots = 'A'${\mathbf{roots}}=\text{'A'}$ or 'L'$\text{'L'}$.
2:     n – int64int32nag_int scalar
n$n$, the number of objects in the distance matrix.
Constraint: ${\mathbf{n}}>{\mathbf{ndim}}$.
3:     d(n × (n1) / 2${\mathbf{n}}×\left({\mathbf{n}}-1\right)/2$) – double array
The lower triangle of the distance matrix D$D$ stored packed by rows. That is d((i1) × (i2) / 2 + j)${\mathbf{d}}\left(\left(i-1\right)×\left(i-2\right)/2+j\right)$ must contain dij${d}_{ij}$ for i = 2,3,,n;j = 1,2,,i1$i=2,3,\dots ,n\text{;}j=1,2,\dots ,i-1$.
Constraint: d(i)0.0${\mathbf{d}}\left(\mathit{i}\right)\ge 0.0$, for i = 1,2,,n(n1) / 2$\mathit{i}=1,2,\dots ,n\left(n-1\right)/2$.
4:     ndim – int64int32nag_int scalar
k$k$, the number of dimensions used to represent the data.
Constraint: ndim1${\mathbf{ndim}}\ge 1$.

None.

ldx wk iwk

### Output Parameters

1:     x(ldx,ndim) – double array
ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
The i$i$th row contains k$k$ coordinates for the i$i$th point, i = 1,2,,n$i=1,2,\dots ,n$.
2:     eval(n) – double array
If roots = 'A'${\mathbf{roots}}=\text{'A'}$, eval contains the n$n$ scaled eigenvalues of the matrix E$E$.
If roots = 'L'${\mathbf{roots}}=\text{'L'}$, eval contains the largest k$k$ scaled eigenvalues of the matrix E$E$.
In both cases the eigenvalues are divided by the sum of the eigenvalues (that is, the trace of E$E$).
3:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
 On entry, ndim < 1${\mathbf{ndim}}<1$, or ${\mathbf{n}}<{\mathbf{ndim}}$, or roots ≠ 'A'${\mathbf{roots}}\ne \text{'A'}$ or 'L'$\text{'L'}$, or ldx < n$\mathit{ldx}<{\mathbf{n}}$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, d(i) < 0.0${\mathbf{d}}\left(i\right)<0.0$ for some i$i$, i = 1,2, … ,n(n − 1) / 2$i=1,2,\dots ,n\left(n-1\right)/2$, or all elements of d = 0.0${\mathbf{d}}=0.0$.
ifail = 3${\mathbf{ifail}}=3$
There are less than ndim eigenvalues greater than zero. Try a smaller number of dimensions (ndim) or use non-metric scaling (nag_mv_multidimscal_ordinal (g03fc)).
ifail = 4${\mathbf{ifail}}=4$
The computation of the eigenvalues or eigenvectors has failed. Seek expert help.

## Accuracy

nag_mv_multidimscal_metric (g03fa) uses nag_lapack_dsterf (f08jf) or nag_lapack_dstebz (f08jj) to compute the eigenvalues and nag_lapack_dstein (f08jk) to compute the eigenvectors. These functions should be consulted for a discussion of the accuracy of the computations involved.

Alternative, non-metric, methods of scaling are provided by nag_mv_multidimscal_ordinal (g03fc).
The relationship between principal coordinates and principal components, see nag_mv_multidimscal_ordinal (g03fc), is discussed in Krzanowski (1990) and Gower (1966).

## Example

```function nag_mv_multidimscal_metric_example
roots = 'l';
n = int64(14);
d = [0.099;
0.033;
0.022;
0.183;
0.114;
0.042;
0.148;
0.224;
0.059;
0.068;
0.198;
0.039;
0.053;
0.085;
0.051;
0.462;
0.266;
0.322;
0.435;
0.268;
0.025;
0.628;
0.442;
0.444;
0.406;
0.24;
0.129;
0.014;
0.113;
0.07;
0.046;
0.047;
0.034;
0.002;
0.106;
0.129;
0.173;
0.119;
0.162;
0.331;
0.177;
0.039;
0.089;
0.237;
0.071;
0.434;
0.419;
0.339;
0.505;
0.469;
0.39;
0.315;
0.349;
0.151;
0.43;
0.762;
0.633;
0.781;
0.7;
0.758;
0.625;
0.469;
0.618;
0.44;
0.538;
0.607;
0.53;
0.389;
0.482;
0.579;
0.597;
0.498;
0.374;
0.562;
0.247;
0.383;
0.387;
0.084;
0.586;
0.435;
0.55;
0.53;
0.552;
0.509;
0.369;
0.471;
0.234;
0.346;
0.456;
0.09;
0.038];
ndim = int64(2);
[x, eval, ifail] = nag_mv_multidimscal_metric(roots, n, d, ndim)
```
```

x =

0.2408    0.2337
0.1137    0.1168
0.2394    0.0760
0.2129    0.0605
0.2495   -0.0693
0.1487   -0.0778
-0.0514   -0.1623
0.0115   -0.3446
-0.0039    0.0059
0.0386   -0.0089
-0.0421   -0.0566
-0.5158    0.0291
-0.3180    0.1501
-0.3238    0.0475

eval =

0.7871
0.2808
0
0
0
0
0
0
0
0
0
0
0
0

ifail =

0

```
```function g03fa_example
roots = 'l';
n = int64(14);
d = [0.099;
0.033;
0.022;
0.183;
0.114;
0.042;
0.148;
0.224;
0.059;
0.068;
0.198;
0.039;
0.053;
0.085;
0.051;
0.462;
0.266;
0.322;
0.435;
0.268;
0.025;
0.628;
0.442;
0.444;
0.406;
0.24;
0.129;
0.014;
0.113;
0.07;
0.046;
0.047;
0.034;
0.002;
0.106;
0.129;
0.173;
0.119;
0.162;
0.331;
0.177;
0.039;
0.089;
0.237;
0.071;
0.434;
0.419;
0.339;
0.505;
0.469;
0.39;
0.315;
0.349;
0.151;
0.43;
0.762;
0.633;
0.781;
0.7;
0.758;
0.625;
0.469;
0.618;
0.44;
0.538;
0.607;
0.53;
0.389;
0.482;
0.579;
0.597;
0.498;
0.374;
0.562;
0.247;
0.383;
0.387;
0.084;
0.586;
0.435;
0.55;
0.53;
0.552;
0.509;
0.369;
0.471;
0.234;
0.346;
0.456;
0.09;
0.038];
ndim = int64(2);
[x, eval, ifail] = g03fa(roots, n, d, ndim)
```
```

x =

0.2408    0.2337
0.1137    0.1168
0.2394    0.0760
0.2129    0.0605
0.2495   -0.0693
0.1487   -0.0778
-0.0514   -0.1623
0.0115   -0.3446
-0.0039    0.0059
0.0386   -0.0089
-0.0421   -0.0566
-0.5158    0.0291
-0.3180    0.1501
-0.3238    0.0475

eval =

0.7871
0.2808
0
0
0
0
0
0
0
0
0
0
0
0

ifail =

0

```