function result = agnes(x,method,vtype,stdize,metric,banner)
%AGNES is a agglomerative clustering algorithm. It returns a hierarchy of clusters.
%
%The algorithm is fully described in:
% Kaufman, L. and Rousseeuw, P.J. (1990),
% "Finding groups in data: An introduction to cluster analysis",
% Wiley-Interscience: New York (Series in Applied Probability and
% Statistics), ISBN 0-471-87876-6.
%
% Required input arguments:
% x : Data matrix (rows = observations, columns = variables)
% or Dissimilarity matrix (if number of rows equals 1)
% method : method used
% Possible values are 1 : Group Average
% 2 : Single Linkage
% 3 : Complete Linkage
% 4 : Ward
% 5 : Weighted Average
% vtype : Variable type vector (length equals number of variables)
% Possible values are 1 Asymmetric binary variable (0/1)
% 2 Nominal variable (includes symmetric binary)
% 3 Ordinal variable
% 4 Interval variable
% (if x is a dissimilarity matrix vtype is not required.)
%
% Optional input arguments:
% stdize : standardise the variables given by the x-matrix
% Possible values are 0 : no standardisation (default)
% 1 : standardisation by the mean
% 2 : standardisation by the median
% (if x is a dissimilarity matrix, stdize is ignored)
% metric : Metric to be used
% Possible values are 'eucli' Euclidian (all interval variables, default)
% 'manha' Manhattan
% 'mixed' Mixed (not all interval variables, default)
% (if x is a dissimilarity matrix, metric is ignored)
% banner : draws picture
% Possible values are 0 : do not create a banner (default)
% 1 : create a banner
% I/O:
% result=agnes(x,method,vtype,stdize,metric,banner)
%
% Example (subtracted from the referenced book)
% load agricul.mat
% result=agnes(agricul,1,[4 4],0,0,1);
%
% The output of AGNES is a structure containing:
% result.x : input matrix x
% result.diss : whether the inputmatrix x is a dissimilarity matrix
% or not
% result.dys : calculated dissimilarities (read row by row from the
% lower dissimilarity matrix, without the elements of
% the diagonal)
% result.metric : metric used
% result.stdize : standardisation used
% result.number : number of observations
% result.method : method used
% result.objectorder : order of objects
% result.heights : dissimilarity between the 2 relative clusters
% (=length of banner)
% result.ac : agglomerative coefficient
% result.merge : a (n-1) by 2 matrix related to the merge
%
% And AGNES will create the plot banner if banner equals 1.
%
% This function is part of LIBRA: the Matlab Library for Robust Analysis,
% available at:
% http://wis.kuleuven.be/stat/robust.html
%
% Written by Wai Yan Kong
% Created on 05/2006
% Last Revision: 19/09/2006
%Checking and filling out the inputs
if (nargin<2)
error('Two input arguments required (data or dissimilarity vector and method)')
elseif ((nargin<3) & (size(x,1)~=1))
error('Three input arguments required (data matrix x, method and vtype)')
% so, only datamatrix x and method as input
elseif (nargin<3)
metri ='unknown';
metr='unknown';
stdize = 0;
banner = 0;
% so, only dissim matrix x and method as input
elseif (nargin<4)
stdize = 0;
banner = 0;
if (sum(vtype)~=4*size(x,2))
metr ='mixed';
metri='mixed';
else
metr ='eucli';
metri='euclidean';
end
% so, only datamatrix or dissimilarity matrix x , method and vtype as
% input
elseif (nargin<5)
banner = 0;
if (sum(vtype)~=4*size(x,2))
metr ='mixed';
metri='mixed';
else
metr ='eucli';
metri='euclidean';
end
% so, only datamatrix or dissimilarity matrix x, method, vtype and
% stdize as input
elseif (nargin<6)
banner=0;
elseif (nargin>6)
error('Too many input arguments')
end
% defining metric (for 4 input arguments) and diss
if (nargin>=5)
if (metric==0)
metr='eucli';
metri='euclidean';
elseif (metric==1)
metr='manha';
metri='manhattan';
elseif (metric==2)
metr='mixed';
metri='mixed';
else
error('metric must be 0,1 or 2')
end
end
if ((size(x,1)~=1))
diss=0;
dissi='x is no dissimilarity matrix';
else
diss=1;
dissi='x is a dissimilarity matrix';
end
%Standardization
if ((stdize==1) & (strcmp(metr,'eucli')| strcmp(metr,'manha')) & (diss==0))
x = ((x - repmat(mean(x),size(x,1),1))./(repmat(std(x),size(x,1),1)));
standardisation='standardisation by mean';
elseif ((stdize==2) & (strcmp(metr,'eucli')| strcmp(metr,'manha')) & (diss==0))
x = ((x - repmat(median(x),size(x,1),1))./(repmat(mad(x),size(x,1),1)));
standardisation='standardisation by median';
elseif(stdize==0)
standardisation='no standardisation';
elseif (stdize==1 | stdize==2)
standardisation='no standardisation(not enough num var or x is a diss matrix)';
elseif (nargin<=3)
standardisation='no standardisation';
else
error('stdize must be 0,1 or 2');
end
% defining dissimilarity matrix, number and method
if (diss==1)
disv=x;
number=(1+sqrt(1+8*size(x,2)))/2; %number of observations
% checking for missing values in the dissimilarity matrix
if any(isnan(disv))
error('There are missing value(s) in the dissimilarity matrix!')
end
% checking the dimensions of the dissimilarity matrix
if mod(number,fix(number))~=0
error(['The dimension of the dissimilarity matrix is not correct!'])
end
else
resl=daisy(x,vtype,metr);
disv=resl.disv;
number=size(x,1);
end
if (method==1)
namemethod='Group Average';
elseif (method==2)
namemethod='Single Linkage';
elseif (method==3)
namemethod='Complete Linkage';
elseif (method==4)
namemethod='Ward';
elseif (method==5)
namemethod='Weighted Average';
else
error('method must be 1,2,3,4, or 5')
end
%Actual calculations
[ner,ban,coef,merge,dys]=twinsc(number,[0 disv]',method,1);
% We want ban to be a vector of length n-1
ban2=zeros(1,(number-1));
for i = 1:(number-1)
ban2(i) = ban(i+1);
end
% We want merge to be a (n-1) by 2 matrix
merge2=ones(number-1,2);
for i = 1:(number-1)
merge2(i,:) = merge(2*i-1:2*i);
end
% Create a banner
if (banner==1)
Y=ban2;
Y1=fliplr(Y);
whitebg([0.4 0.5 0.75]);
barh(Y1,1,'w');
title('Banner of Agnes')
xlabel('Height')
YT=0.5:number;
set(gca,'YTick',YT)
set(gca,'YTickLabel',fliplr(ner))
set(gca,'YAxisLocation','right')
axis([min([ban2 0]),max([ban2 0]),0.5,number-0.5])
set(gcf,'Color',[0.855388 0.855388 0.855388]);
elseif ((banner~=0) & (banner~=1) & (nargin==6))
error('banner must equals 0 or 1')
end
%Putting things together
result = struct('x',x,'diss',dissi,'dys',dys,'metric',metri,...
'stdize',standardisation,'number',number,...
'method',namemethod,'objectorder',ner,'heights',ban2,...
'ac',coef,'merge',merge2);
if diss
result=rmfield(result, 'x');
end