# NAG FL Interfaceg03faf (multidimscal_​metric)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

g03faf performs a principal coordinate analysis also known as classical metric scaling.

## 2Specification

Fortran Interface
 Subroutine g03faf ( n, d, ndim, x, ldx, eval, wk, iwk,
 Integer, Intent (In) :: n, ndim, ldx Integer, Intent (Inout) :: ifail Integer, Intent (Out) :: iwk(5*n) Real (Kind=nag_wp), Intent (In) :: d(n*(n-1)/2) Real (Kind=nag_wp), Intent (Inout) :: x(ldx,ndim) Real (Kind=nag_wp), Intent (Out) :: eval(n), wk(n*(n+17)/2-1) Character (1), Intent (In) :: roots
#include <nag.h>
 void g03faf_ (const char *roots, const Integer *n, const double d[], const Integer *ndim, double x[], const Integer *ldx, double eval[], double wk[], Integer iwk[], Integer *ifail, const Charlen length_roots)
The routine may be called by the names g03faf or nagf_mv_multidimscal_metric.

## 3Description

For a set of $n$ objects a distance matrix $D$ can be calculated such that ${d}_{ij}$ is a measure of how ‘far apart’ are objects $i$ and $j$ (see g03eaf for example). Principal coordinate analysis or metric scaling starts with a distance matrix and finds points $X$ in Euclidean space such that those points have the same distance matrix. The aim is to find a small number of dimensions, $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$ where ${e}_{ij}=-1/2\left({d}_{ij}^{2}-{d}_{i.}^{2}-{d}_{.j}^{2}+{d}_{..}^{2}\right)$ with ${d}_{i.}^{2}$ denoting the average of ${d}_{ij}^{2}$ over the suffix $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, ${\lambda }_{i}$, of the matrix $E$ are all positive, $\sum _{i=1}^{k}{\lambda }_{i}/\sum _{i=1}^{n-1}{\lambda }_{i}$ shows how well the data is represented in $k$ dimensions. The eigenvalues will be non-negative if $E$ is positive semidefinite. This will be true provided ${d}_{ij}$ satisfies the inequality: ${d}_{ij}\le {d}_{ik}+{d}_{jk}$ for all $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. g03faf provides the option for all eigenvalues to be computed so that the smallest eigenvalues can be checked.
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

## 5Arguments

1: $\mathbf{roots}$Character(1) Input
On entry: indicates if all the eigenvalues are to be computed or just the ndim largest.
${\mathbf{roots}}=\text{'A'}$
All the eigenvalues are computed.
${\mathbf{roots}}=\text{'L'}$
Only the largest ndim eigenvalues are computed.
Constraint: ${\mathbf{roots}}=\text{'A'}$ or $\text{'L'}$.
2: $\mathbf{n}$Integer Input
On entry: $n$, the number of objects in the distance matrix.
Constraint: ${\mathbf{n}}>{\mathbf{ndim}}$.
3: $\mathbf{d}\left({\mathbf{n}}×\left({\mathbf{n}}-1\right)/2\right)$Real (Kind=nag_wp) array Input
On entry: the lower triangle of the distance matrix $D$ stored packed by rows. That is ${\mathbf{d}}\left(\left(i-1\right)×\left(i-2\right)/2+j\right)$ must contain ${d}_{ij}$ for $i=2,3,\dots ,n\text{;}j=1,2,\dots ,i-1$.
Constraint: ${\mathbf{d}}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,n\left(n-1\right)/2$.
4: $\mathbf{ndim}$Integer Input
On entry: $k$, the number of dimensions used to represent the data.
Constraint: ${\mathbf{ndim}}\ge 1$.
5: $\mathbf{x}\left({\mathbf{ldx}},{\mathbf{ndim}}\right)$Real (Kind=nag_wp) array Output
On exit: the $i$th row contains $k$ coordinates for the $i$th point, $i=1,2,\dots ,n$.
6: $\mathbf{ldx}$Integer Input
On entry: the first dimension of the array x as declared in the (sub)program from which g03faf is called.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
7: $\mathbf{eval}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Output
On exit: if ${\mathbf{roots}}=\text{'A'}$, eval contains the $n$ scaled eigenvalues of the matrix $E$.
If ${\mathbf{roots}}=\text{'L'}$, eval contains the largest $k$ scaled eigenvalues of the matrix $E$.
In both cases the eigenvalues are divided by the sum of the eigenvalues (that is, the trace of $E$).
8: $\mathbf{wk}\left({\mathbf{n}}×\left({\mathbf{n}}+17\right)/2-1\right)$Real (Kind=nag_wp) array Workspace
9: $\mathbf{iwk}\left(5×{\mathbf{n}}\right)$Integer array Workspace
10: $\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{ldx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ndim}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}>{\mathbf{ndim}}$.
On entry, ${\mathbf{ndim}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ndim}}\ge 1$.
On entry, ${\mathbf{roots}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{roots}}=\text{'A'}$ or $\text{'L'}$.
${\mathbf{ifail}}=2$
On entry, all the elements of ${\mathbf{d}}=0.0$.
On entry, $i=⟨\mathit{\text{value}}⟩$ and ${\mathbf{d}}\left(i\right)<0.0$.
Constraint: ${\mathbf{d}}\left(i\right)\ge 0.0$.
${\mathbf{ifail}}=3$
There are less than ndim eigenvalues greater than zero. Try a smaller number of dimensions or use non-metric scaling.
${\mathbf{ifail}}=4$
The computation of the eigenvalues or eigenvectors has failed. Seek expert help.
${\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

g03faf uses f08jff or f08jjf to compute the eigenvalues and f08jkf to compute the eigenvectors. These routines should be consulted for a discussion of the accuracy of the computations involved.

## 8Parallelism and Performance

g03faf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g03faf 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.

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

## 10Example

The data, given by Krzanowski (1990), are dissimilarities between water vole populations in Europe. The first two principal coordinates are computed.

### 10.1Program Text

Program Text (g03fafe.f90)

### 10.2Program Data

Program Data (g03fafe.d)

### 10.3Program Results

Program Results (g03fafe.r)