NAG Toolbox: nag_mv_cluster_hier_dendrogram (g03eh)

Purpose

Syntax

Description

Figure 1

References

Parameters

Compulsory Input Parameters

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

Indicates which orientation the dendrogram is to take.

$\mathbf{orient}=\text{'N'}$

The end points of the dendrogram are to the north.

$\mathbf{orient}=\text{'S'}$

The end points of the dendrogram are to the south.

$\mathbf{orient}=\text{'E'}$

The end points of the dendrogram are to the east.

$\mathbf{orient}=\text{'W'}$

The end points of the dendrogram are to the west.

Constraint: $\mathbf{orient}=\text{'N'}$, $\text{'S'}$, $\text{'E'}$ or $\text{'W'}$.

2:     $\mathrm{dord}\left(\mathbf{n}\right)$ – double array

The array dord as output by nag_mv_cluster_hier (g03ec). dord contains the distances, in dendrogram order, at which clustering takes place.

Constraint: $\mathbf{dord}\left(\mathbf{n}\right)\ge \mathbf{dord}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{n}-1$.

3:     $\mathrm{dmin}$ – double scalar

The clustering distance at which the dendrogram begins.

Constraint: $\mathbf{dmin}\ge 0.0$.

4:     $\mathrm{dstep}$ – double scalar

The distance represented by one symbol of the dendrogram.

Constraint: $\mathbf{dstep}>0.0$.

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

The number of character positions used in the dendrogram. Hence the clustering distance at which the dendrogram terminates is given by $\mathbf{dmin}+\mathbf{nsym}\times \mathbf{dstep}$.

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

6:     $\mathrm{lenc}$ – int64int32nag_int scalar

The dimension of the array c.

Constraints:

• if $\mathbf{orient}=\text{'N'}$ or $\text{'S'}$, $\mathbf{lenc}\ge \mathbf{nsym}$;
• if $\mathbf{orient}=\text{'E'}$ or $\text{'W'}$, $\mathbf{lenc}\ge \mathbf{n}$.

Optional Input Parameters

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

Default: the dimension of the array dord.

The number of objects in the cluster analysis.

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

Output Parameters

1:     $\mathrm{c}\left(\mathbf{lenc}\right)$ – cell array of strings

The elements of c contain consecutive lines of the dendrogram.

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

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

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry,	$\mathbf{n}\le 2$,
or	$\mathbf{nsym}<1$,
or	$\mathbf{dmin}<0.0$,
or	$\mathbf{dstep}\le 0.0$,
or	$\mathbf{orient}\ne \text{'N'},\text{'S'},\text{'E'}$, or 'W',
or	$\mathbf{orient}=\text{'N'}$ or $\text{'S'}$, $\mathbf{lenc}<\mathbf{nsym}$,
or	$\mathbf{orient}=\text{'E'}$ or $\text{'W'}$, $\mathbf{lenc}<\mathbf{n}$,
or	the number of characters that can be stored in each element of array c is insufficient for the requested orientation.

   $\mathbf{ifail}=2$

On entry,

$\mathbf{dord}\left(\mathbf{n}\right)<\mathbf{dord}\left(i\right)$, for some $i=1,2,\dots ,\mathbf{n}-1$.

   $\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: g03eh_example

function g03eh_example


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

x = [1, 1, 1;
     2, 1, 2;
     3, 6, 3;
     4, 8, 2;
     5, 8, 0];
[n,m]  = size(x);

isx    = ones(m,1,'int64');
isx(1) = int64(0);
s      = ones(m,1);
ld     = (n*(n-1))/2;
d      = zeros(ld,1);

% Compute the distance matrix
update = 'I';
dist = 'S';
scal = 'U';
[s, d, ifail] = g03ea( ...
		       update, dist, scal, x, isx, s, d);

% Clustering method
method = int64(5);

% Perform clustering
n      = int64(n);
[d, ilc, iuc, cd, iord, dord, ifail] = ...
  g03ec(method, n, d);

% Produce dendograms
orient = 'East';
fprintf('Dendrogram, Orientation %s\n', orient);
dmin  = 0;
dstep = 1.1;
nsym  = int64(40);
lenc  = int64(n);

% Generate character array holding the dendogram
[c, ifail] = g03eh( ...
		    orient, dord, dmin, dstep, nsym, lenc);

for i = 1:lenc
  fprintf('%s\n',c{i});
end

orient = 'South';
fprintf('\nDendrogram, Orientation %s\n', orient);
dstep = 1.0;
lenc  = int64(nsym);

% Generate character array holding the dendogram
[c, ifail] = g03eh( ...
		    orient, dord, dmin, dstep, nsym, lenc);

for i = 1:lenc
  fprintf('%s\n',c{i});
end

g03eh example results

Dendrogram, Orientation East
                                        
        ...............................(
       (                         .......
       (                        (    ...
       (........................(...(...

Dendrogram, Orientation South
               
               
               
   ----------  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I        I  
   I  ------*  
   I  I     I  
   I  I     I  
   I  I     I  
   I  I  ---*  
   I  I  I  I  
   I  I  I  I  
---*  I  I  I  
I  I  I  I  I