NAG Library Routine Document
g03fcf
(multidimscal_ordinal)
1
Purpose
g03fcf performs nonmetric (ordinal) multidimensional scaling.
2
Specification
Fortran Interface
Subroutine g03fcf ( 
typ,
n,
ndim,
d,
x,
ldx,
stress,
dfit,
iter,
iopt,
wk,
iwk,
ifail) 
Integer, Intent (In)  :: 
n,
ndim,
ldx,
iter,
iopt  Integer, Intent (Inout)  :: 
ifail  Integer, Intent (Out)  :: 
iwk(n*(n1)/2+n*ndim+5)  Real (Kind=nag_wp), Intent (In)  :: 
d(n*(n1)/2)  Real (Kind=nag_wp), Intent (Inout)  :: 
x(ldx,ndim)  Real (Kind=nag_wp), Intent (Out)  :: 
stress,
dfit(2*n*(n1)),
wk(15*n*ndim)  Character (1), Intent (In)  :: 
typ 

C Header Interface
#include nagmk26.h
void 
g03fcf_ (
const char *typ,
const Integer *n,
const Integer *ndim,
const double d[],
double x[],
const Integer *ldx,
double *stress,
double dfit[],
const Integer *iter,
const Integer *iopt,
double wk[],
Integer iwk[],
Integer *ifail,
const Charlen length_typ) 

3
Description
For a set of
$n$ objects, a distance or dissimilarity matrix
$D$ can be calculated such that
${d}_{ij}$ is a measure of how ‘far apart’ the objects
$i$ and
$j$ are. If
$p$ variables
${x}_{k}$ have been recorded for each observation this measure may be based on Euclidean distance,
${d}_{ij}={\displaystyle \sum _{k=1}^{p}}{\left({x}_{ki}{x}_{kj}\right)}^{2}$, or some other calculation such as the number of variables for which
${x}_{kj}\ne {x}_{ki}$. Alternatively, the distances may be the result of a subjective assessment. For a given distance matrix, multidimensional scaling produces a configuration of
$n$ points in a chosen number of dimensions,
$m$, such that the distance between the points in some way best matches the distance matrix. For some distance measures, such as Euclidean distance, the size of distance is meaningful, for other measures of distance all that can be said is that one distance is greater or smaller than another. For the former metric scaling can be used, see
g03faf, for the latter, a nonmetric scaling is more appropriate.
For nonmetric multidimensional scaling, the criterion used to measure the closeness of the fitted distance matrix to the observed distance matrix is known as
stress.
stress is given by,
where
${\hat{{d}_{ij}}}^{2}$ is the Euclidean squared distance between points
$i$ and
$j$ and
$\stackrel{~}{{d}_{ij}}$ is the fitted distance obtained when
$\hat{{d}_{ij}}$ is monotonically regressed on
${d}_{ij}$, that is
$\stackrel{~}{{d}_{ij}}$ is monotonic relative to
${d}_{ij}$ and is obtained from
$\hat{{d}_{ij}}$ with the smallest number of changes. So
stress is a measure of by how much the set of points preserve the order of the distances in the original distance matrix. Nonmetric multidimensional scaling seeks to find the set of points that minimize the
stress.
An alternate measure is squared
stress,
$\mathit{sstress}$,
in which the distances in
stress are replaced by squared distances.
In order to perform a nonmetric scaling, an initial configuration of points is required. This can be obtained from principal coordinate analysis, see
g03faf. Given an initial configuration,
g03fcf uses the optimization routine
e04dgf/e04dga to find the configuration of points that minimizes
stress or
$\mathit{sstress}$. The routine
e04dgf/e04dga uses a conjugate gradient algorithm.
g03fcf will find an optimum that may only be a local optimum, to be more sure of finding a global optimum several different initial configurations should be used; these can be obtained by randomly perturbing the original initial configuration using routines from
Chapter G05.
4
References
Chatfield C and Collins A J (1980) Introduction to Multivariate Analysis Chapman and Hall
Krzanowski W J (1990) Principles of Multivariate Analysis Oxford University Press
5
Arguments
 1: $\mathbf{typ}$ – Character(1)Input

On entry: indicates whether
stress or
$\mathit{sstress}$ is to be used as the criterion.
 ${\mathbf{typ}}=\text{'T'}$
 stress is used.
 ${\mathbf{typ}}=\text{'S'}$
 $\mathit{sstress}$ is used.
Constraint:
${\mathbf{typ}}=\text{'S'}$ or $\text{'T'}$.
 2: $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of objects in the distance matrix.
Constraint:
${\mathbf{n}}>{\mathbf{ndim}}$.
 3: $\mathbf{ndim}$ – IntegerInput

On entry: $m$, the number of dimensions used to represent the data.
Constraint:
${\mathbf{ndim}}\ge 1$.
 4: $\mathbf{d}\left({\mathbf{n}}\times \left({\mathbf{n}}1\right)/2\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the lower triangle of the distance matrix
$D$ stored packed by rows. That is
${\mathbf{d}}\left(\left(\mathit{i}1\right)\times \left(\mathit{i}2\right)/2+\mathit{j}\right)$ must contain
${d}_{\mathit{i}\mathit{j}}$, for
$\mathit{i}=2,3,\dots ,n$ and
$\mathit{j}=1,2,\dots ,\mathit{i}1$. If
${d}_{ij}$ is missing then set
${d}_{ij}<0$; for further comments on missing values see
Section 9.
 5: $\mathbf{x}\left({\mathbf{ldx}},{\mathbf{ndim}}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: the
$\mathit{i}$th row must contain an initial estimate of the coordinates for the
$\mathit{i}$th point, for
$\mathit{i}=1,2,\dots ,n$. One method of computing these is to use
g03faf.
On exit: the
$\mathit{i}$th row contains $m$ coordinates for the $\mathit{i}$th point, for $\mathit{i}=1,2,\dots ,n$.
 6: $\mathbf{ldx}$ – IntegerInput

On entry: the first dimension of the array
x as declared in the (sub)program from which
g03fcf is called.
Constraint:
${\mathbf{ldx}}\ge {\mathbf{n}}$.
 7: $\mathbf{stress}$ – Real (Kind=nag_wp)Output

On exit: the value of
stress or
$\mathit{sstress}$ at the final iteration.
 8: $\mathbf{dfit}\left(2\times {\mathbf{n}}\times \left({\mathbf{n}}1\right)\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: auxiliary outputs.
If
${\mathbf{typ}}=\text{'T'}$, the first
$n\left(n1\right)/2$ elements contain the distances,
$\hat{{d}_{ij}}$, for the points returned in
x, the second set of
$n\left(n1\right)/2$ contains the distances
$\hat{{d}_{ij}}$ ordered by the input distances,
${d}_{ij}$, the third set of
$n\left(n1\right)/2$ elements contains the monotonic distances,
$\stackrel{~}{{d}_{ij}}$, ordered by the input distances,
${d}_{ij}$ and the final set of
$n\left(n1\right)/2$ elements contains fitted monotonic distances,
$\stackrel{~}{{d}_{ij}}$, for the points in
x. The
$\stackrel{~}{{d}_{ij}}$ corresponding to distances which are input as missing are set to zero.
If ${\mathbf{typ}}=\text{'S'}$, the results are as above except that the squared distances are returned.
Each distance matrix is stored in lower triangular packed form in the same way as the input matrix $D$.
 9: $\mathbf{iter}$ – IntegerInput

On entry: the maximum number of iterations in the optimization process.
 ${\mathbf{iter}}=0$
 A default value of $50$ is used.
 ${\mathbf{iter}}<0$
 A default value of $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(50,5nm\right)$ (the default for e04dgf/e04dga) is used.
 10: $\mathbf{iopt}$ – IntegerInput

On entry: selects the options, other than the number of iterations, that control the optimization.
 ${\mathbf{iopt}}=0$
 Default values are selected as described in Section 9. In particular if an accuracy requirement of $\epsilon =0.00001$ is selected, see Section 7.
 ${\mathbf{iopt}}>0$
 The default values are used except that the accuracy is given by ${10}^{i}$ where $i={\mathbf{iopt}}$.
 ${\mathbf{iopt}}<0$
 The option setting mechanism of e04dgf/e04dga can be used to set all options except Iteration Limit; this option is only recommended if you are an experienced user of NAG optimization routines. For further details see e04dgf/e04dga.
 11: $\mathbf{wk}\left(15\times {\mathbf{n}}\times {\mathbf{ndim}}\right)$ – Real (Kind=nag_wp) arrayWorkspace

 12: $\mathbf{iwk}\left({\mathbf{n}}\times \left({\mathbf{n}}1\right)/2+{\mathbf{n}}\times {\mathbf{ndim}}+5\right)$ – Integer arrayWorkspace

 13: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{ or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{ 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).
6
Error 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{ndim}}<1$, 
or  ${\mathbf{n}}\le {\mathbf{ndim}}$, 
or  ${\mathbf{typ}}\ne \text{'T'}$ or $\text{'S'}$, 
or  ${\mathbf{ldx}}<{\mathbf{n}}$. 
 ${\mathbf{ifail}}=2$

On entry,  all elements of ${\mathbf{d}}\le 0.0$. 
 ${\mathbf{ifail}}=3$

The optimization has failed to converge in
iter function iterations. Try either increasing the number of iterations using
iter or increasing the value of
$\epsilon $, given by
iopt, used to determine convergence. Alternatively try a different starting configuration.
 ${\mathbf{ifail}}=4$

The conditions for an acceptable solution have not been met but a lower point could not be found. Try using a larger value of
$\epsilon $, given by
iopt.
 ${\mathbf{ifail}}=5$

The optimization cannot begin from the initial configuration. Try a different set of points.
 ${\mathbf{ifail}}=6$

The optimization has failed. This error is only likely if
${\mathbf{iopt}}<0$. It corresponds to
${\mathbf{ifail}}={\mathbf{4}}$,
${\mathbf{7}}$ and
${\mathbf{9}}$ in
e04dgf/e04dga.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
After a successful optimization the relative accuracy of
stress should be approximately
$\epsilon $, as specified by
iopt.
8
Parallelism and Performance
g03fcf 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 implementationspecific information.
The optimization routine
e04dgf/e04dga used by
g03fcf has a number of options to control the process. The options for the maximum number of iterations (
Iteration Limit) and accuracy (
Optimality Tolerance) can be controlled by
iter and
iopt respectively. The printing option (
Print Level) is set to
$1$ to give no printing. The other option set is to stop the checking of derivatives (
${\mathbf{Verify}}=\mathrm{NO}$) for efficiency. All other options are left at their default values. If however
${\mathbf{iopt}}<0$ is used, only the maximum number of iterations is set. All other options can be controlled by the option setting mechanism of
e04dgf/e04dga with the defaults as given by that routine.
Missing values in the input distance matrix can be specified by a negative value and providing there are not more than about two thirds of the values missing the algorithm may still work. However the routine
g03faf does not allow for missing values so an alternative method of obtaining an initial set of coordinates is required. It may be possible to estimate the missing values with some form of average and then use
g03faf to give an initial set of coordinates.
10
Example
The data, given by
Krzanowski (1990), are dissimilarities between water vole populations in Europe. Initial estimates are provided by the first two principal coordinates computed.
10.1
Program Text
Program Text (g03fcfe.f90)
10.2
Program Data
Program Data (g03fcfe.d)
10.3
Program Results
Program Results (g03fcfe.r)