# NAG CL Interfaceg03fac (multidimscal_​metric)

Settings help

CL Name Style:

## 1Purpose

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

## 2Specification

 #include
 void g03fac (Nag_Eigenvalues roots, Integer n, const double d[], Integer ndim, double x[], Integer tdx, double eval[], NagError *fail)
The function may be called by the names: g03fac, nag_mv_multidimscal_metric or nag_mv_prin_coord_analysis.

## 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’ objects $i$ and $j$ are (see g03eac 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<<\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}=-\frac{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. g03fac 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}$Nag_Eigenvalues Input
On entry: indicates if all the eigenvalues are to be computed or just the ndim largest.
${\mathbf{roots}}=\mathrm{Nag_AllEigVals}$
All the eigenvalues are computed.
${\mathbf{roots}}=\mathrm{Nag_LargeEigVals}$
Only the largest ndim eigenvalues are computed.
Constraint: ${\mathbf{roots}}=\mathrm{Nag_AllEigVals}$ or $\mathrm{Nag_LargeEigVals}$.
2: $\mathbf{n}$Integer Input
On entry: the number of objects in the distance matrix, $n$.
Constraint: ${\mathbf{n}}>{\mathbf{ndim}}$.
3: $\mathbf{d}\left[{\mathbf{n}}×\left({\mathbf{n}}-1\right)/2\right]$const double Input
On entry: the lower triangle of the distance matrix $D$ stored packed by rows. That is, ${\mathbf{d}}\left[\left(\mathit{i}-1\right)×\left(\mathit{i}-2\right)/2+\mathit{j}-1\right]$ must contain ${d}_{\mathit{i}\mathit{j}}$, for $\mathit{i}=2,3,\dots ,n$ and $\mathit{j}=1,2,\dots ,i-1$.
Constraint: ${\mathbf{d}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n\left(n-1\right)/2$.
4: $\mathbf{ndim}$Integer Input
On entry: the number of dimensions used to represent the data, $k$.
Constraint: ${\mathbf{ndim}}\ge 1$.
5: $\mathbf{x}\left[{\mathbf{n}}×{\mathbf{tdx}}\right]$double Output
Note: the $\left(i,j\right)$th element of the matrix $X$ is stored in ${\mathbf{x}}\left[\left(i-1\right)×{\mathbf{tdx}}+j-1\right]$.
On exit: the $i$th row contains $k$ coordinates for the $i$th point, $i=1,2,\dots ,n$.
6: $\mathbf{tdx}$Integer Input
On entry: the stride separating matrix column elements in the array x.
Constraint: ${\mathbf{tdx}}\ge {\mathbf{ndim}}$.
7: $\mathbf{eval}\left[{\mathbf{n}}\right]$double Output
On exit: if ${\mathbf{roots}}=\mathrm{Nag_AllEigVals}$, eval contains the $n$ scaled eigenvalues of the matrix $E$. If ${\mathbf{roots}}=\mathrm{Nag_LargeEigVals}$, 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{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_2_INT_ARG_LE
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$ while ${\mathbf{ndim}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{n}}>{\mathbf{ndim}}$.
NE_2_INT_ARG_LT
On entry, ${\mathbf{tdx}}=⟨\mathit{\text{value}}⟩$ while ${\mathbf{ndim}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{tdx}}\ge {\mathbf{ndim}}$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument roots had an illegal value.
NE_EIGVAL
The computation of eigenvalues or eigenvectors has failed.
NE_INT_ARG_LT
On entry, ${\mathbf{ndim}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ndim}}\ge 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_NEG_ELEMENT
At least one element of the array d < 0.0.
Constraint: ${\mathbf{d}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n×\left(n-1\right)/2$.
NE_NONZERO_EIGVALS
There are fewer than ndim eigenvalues greater than zero. Try a smaller number of dimensions (ndim) or use non-metric scaling (g03fcc).
NE_REALARR
On entry, ${\mathbf{d}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{d}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n×\left(n-1\right)/2$.

## 7Accuracy

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

## 8Parallelism and Performance

g03fac is not threaded in any implementation.

None.

## 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 (g03face.c)

### 10.2Program Data

Program Data (g03face.d)

### 10.3Program Results

Program Results (g03face.r)