NAG Toolbox: nag_mv_multidimscal_ordinal (g03fc)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{typ}$ – string (length ≥ 1)

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:     $\mathrm{d}\left(\mathbf{n}\times \left(\mathbf{n}-1\right)/2\right)$ – double array

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 Further Comments.

3:     $\mathrm{x}\left(\mathit{ldx},\mathbf{ndim}\right)$ – double array

ldx, the first dimension of the array, must satisfy the constraint $\mathit{ldx}\ge \mathbf{n}$.

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 nag_mv_multidimscal_metric (g03fa).

4:     $\mathrm{iter}$ – int64int32nag_int scalar

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 $\max \left(50,5nm\right)$ (the default for nag_opt_uncon_conjgrd_comp (e04dg)) is used.

5:     $\mathrm{iopt}$ – int64int32nag_int scalar

Selects the options, other than the number of iterations, that control the optimization.

$\mathbf{iopt}=0$

Default values are selected as described in Further Comments. In particular if an accuracy requirement of $\epsilon =0.00001$ is selected, see Accuracy.

$\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 nag_opt_uncon_conjgrd_comp (e04dg) can be used to set all options except Iteration Limit; this option is only recommended if you are an experienced user of NAG optimization functions. For further details see nag_opt_uncon_conjgrd_comp (e04dg).

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the array d and the first dimension of the array x. (An error is raised if these dimensions are not equal.)

$n$, the number of objects in the distance matrix.

Constraint: $\mathbf{n}>\mathbf{ndim}$.

2:     $\mathrm{ndim}$ – int64int32nag_int scalar

Default: the second dimension of the array x.

$m$, the number of dimensions used to represent the data.

Constraint: $\mathbf{ndim}\ge 1$.

Output Parameters

1:     $\mathrm{x}\left(\mathit{ldx},\mathbf{ndim}\right)$ – double array

The $\mathit{i}$th row contains $m$ coordinates for the $\mathit{i}$th point, for $\mathit{i}=1,2,\dots ,n$.

2:     $\mathrm{stress}$ – double scalar

The value of stress or $\mathit{sstress}$ at the final iteration.

3:     $\mathrm{dfit}\left(2\times \mathbf{n}\times \left(\mathbf{n}-1\right)\right)$ – double array

Auxiliary outputs.

If $\mathbf{typ}=\text{'T'}$, the first $n\left(n-1\right)/2$ elements contain the distances, $\widehat{d_{ij}}$, for the points returned in x, the second set of $n\left(n-1\right)/2$ contains the distances $\widehat{d_{ij}}$ ordered by the input distances, $d_{ij}$, the third set of $n\left(n-1\right)/2$ elements contains the monotonic distances, $\widetilde{d_{ij}}$, ordered by the input distances, $d_{ij}$ and the final set of $n\left(n-1\right)/2$ elements contains fitted monotonic distances, $\widetilde{d_{ij}}$, for the points in x. The $\widetilde{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$.

4:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{ifail}=1$

On entry,	$\mathbf{ndim}<1$,
or	$\mathbf{n}\le \mathbf{ndim}$,
or	$\mathbf{typ}\ne \text{'T'}$ or $\text{'S'}$,
or	$\mathit{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.

W  $\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 nag_opt_uncon_conjgrd_comp (e04dg).

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g03fc_example

function g03fc_example


fprintf('g03fc example results\n\n');

% Distance matrix (lower part)
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.240 0.129 0.014 ...
     0.113 0.070 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.390 0.315 0.349 0.151 0.430 ...
     0.762 0.633 0.781 0.700 0.758 0.625 0.469 0.618 0.440 0.538 0.607 ...
     0.530 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.550 0.530 0.552 0.509 0.369 0.471 0.234 0.346 0.456 ...
     0.090 0.038];

% Perform principal co-ordinate analysis
roots = 'l';
ndim = int64(2);

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

% Perform multi-dimensional scaling
typ = 'T';
iter = int64(0);
iopt = int64(0);
[x, stress, dfit, ifail] = g03fc( ...
				  typ, d, x, iter, iopt);

fprintf('Stress = %13.4e\n\n', stress);
mtitle = 'Co-ordinates';
matrix = 'General';
diag = ' ';
[ifail] = x04ca( ...
		 matrix,diag,x,mtitle);

fig1 = figure;
hold on;
xlabel('PC 1');
ylabel('PC 2');
title({'Observation numbers', 'for PC 1 and PC 2'});
axis([-0.6 0.4 -0.4 0.3]);
for j = 1:size(x,1)
  ch = sprintf('%d',j);
  text(x(j,1),x(j,2),ch);
end
plot([-0.6 0.4], [0 0], ':');
plot([0 0], [-0.4 0.3], ':');
hold off;

g03fc example results

Stress =    1.2557e-01

 Co-ordinates
           1       2
  1   0.2060  0.2438
  2   0.1063  0.1418
  3   0.2224  0.0817
  4   0.3032  0.0355
  5   0.2645 -0.0698
  6   0.1554 -0.0435
  7  -0.0070 -0.1612
  8   0.0749 -0.3275
  9   0.0488  0.0289
 10   0.0124 -0.0267
 11  -0.1649 -0.2500
 12  -0.5073  0.1267
 13  -0.3093  0.1590
 14  -0.3498  0.0700