wolffd@0: function C=som_connection(S)
wolffd@0: 
wolffd@0: %SOM_CONNECTION Connection matrix for 'hexa' and 'rect' lattices
wolffd@0: %
wolffd@0: % C=som_connection(S)
wolffd@0: %
wolffd@0: %  C=som_connection(sMap);
wolffd@0: %  C=som_connection(sTopol);
wolffd@0: %  C=som_connection({'hexa', [6 5], 'sheet'});
wolffd@0: %
wolffd@0: % Input and output arguments:
wolffd@0: %  S    (struct) map or topol struct
wolffd@0: %       (cell array) a cell array of form {lattice, msize, shape}, where
wolffd@0: %                lattice: 'hexa' or 'rect'
wolffd@0: %                msize  : 1x2 vector
wolffd@0: %                shape  : 'sheet', 'cyl or 'toroid' 
wolffd@0: %
wolffd@0: %  C    (sparse) An NxN connection matrix, N=prod(msize)
wolffd@0: %
wolffd@0: % The function returns a connection matrix, e.g., for drawing
wolffd@0: % connections between map units in the function som_grid. Note that
wolffd@0: % the connections are defined only in the upper triangular part to
wolffd@0: % save some memory!! Function SOM_UNIT_NEIGHS does the same thing, 
wolffd@0: % but also has values in the lower triangular. It is also slower.
wolffd@0: %
wolffd@0: % For more help, try 'type som_connection' or check out online documentation.
wolffd@0: % See also SOM_GRID, SOM_UNIT_NEIGHS.
wolffd@0: 
wolffd@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %
wolffd@0: % som_connection
wolffd@0: %
wolffd@0: % PURPOSE
wolffd@0: % 
wolffd@0: %  To create a connection matrix of SOM 'hexa' and 'rect' negihborhoods
wolffd@0: %
wolffd@0: % SYNTAX
wolffd@0: %
wolffd@0: %  C = som_connection(S)
wolffd@0: %
wolffd@0: % DESCRIPTION
wolffd@0: %
wolffd@0: %  Creates a connection matrix of SOM 'hexa' and 'rect'
wolffd@0: %  neighborhoods. The connections are defined only in the upper
wolffd@0: %  triangular part to save some memory.
wolffd@0: %  
wolffd@0: %  Function SOM_UNIT_NEIGHS does the same thing, but also has values
wolffd@0: %  in the lower triangular. It is also slower, except for 
wolffd@0: %  'toroid' shape because in that case this function calls 
wolffd@0: %  SOM_UNIT_NEIGHS...
wolffd@0: %
wolffd@0: % REQUIRED INPUT ARGUMENTS
wolffd@0: %  
wolffd@0: %  S                 map topology 
wolffd@0: %    (map struct)    S.topol is used to build the matrix
wolffd@0: %    (topol struct)  topology information is used to build the matrix
wolffd@0: %    (cell array)    of form {lattice, msize, shape}, where
wolffd@0: %                     lattice: 'hexa' or 'rect'
wolffd@0: %                     msize  : 1x2 vector
wolffd@0: %                     shape  : 'sheet', 'cyl or 'toroid' 
wolffd@0: %
wolffd@0: % OUTPUT ARGUMENTS
wolffd@0: %
wolffd@0: %  C (sparse)        munits x munits sparse matrix which describes 
wolffd@0: %                    nearest neighbor connections between units
wolffd@0: %
wolffd@0: % EXAMPLE 
wolffd@0: %
wolffd@0: % C = som_connection('hexa',[3 4],'sheet');
wolffd@0: % full(C)
wolffd@0: % ans =
wolffd@0: %
wolffd@0: %      0     1     0     1     0     0     0     0     0     0     0     0
wolffd@0: %      0     0     1     1     1     1     0     0     0     0     0     0
wolffd@0: %      0     0     0     0     0     1     0     0     0     0     0     0
wolffd@0: %      0     0     0     0     1     0     1     0     0     0     0     0
wolffd@0: %      0     0     0     0     0     1     1     1     1     0     0     0
wolffd@0: %      0     0     0     0     0     0     0     0     1     0     0     0
wolffd@0: %      0     0     0     0     0     0     0     1     0     1     0     0
wolffd@0: %      0     0     0     0     0     0     0     0     1     1     1     1
wolffd@0: %      0     0     0     0     0     0     0     0     0     0     0     1
wolffd@0: %      0     0     0     0     0     0     0     0     0     0     1     0
wolffd@0: %      0     0     0     0     0     0     0     0     0     0     0     1
wolffd@0: %      0     0     0     0     0     0     0     0     0     0     0     0
wolffd@0: %
wolffd@0: % SEE ALSO
wolffd@0: % 
wolffd@0: % som_grid         Visualization of a SOM grid
wolffd@0: % som_unit_neighs  Units in 1-neighborhood for all map units.
wolffd@0: 
wolffd@0: % Copyright (c) 1999-2000 by the SOM toolbox programming team.
wolffd@0: % http://www.cis.hut.fi/projects/somtoolbox/             
wolffd@0: 
wolffd@0: % Version 2.0alpha Johan 061099 juuso 151199 170400
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: % Check arguments
wolffd@0: 
wolffd@0: error(nargchk(1, 1, nargin));   % check number of input arguments
wolffd@0: 
wolffd@0: [tmp,ok,tmp]=som_set(S);
wolffd@0: if isstruct(S) & all(ok),       % check m type
wolffd@0:   switch S.type
wolffd@0:   case 'som_topol' 
wolffd@0:     msize=S.msize;
wolffd@0:     lattice=S.lattice;
wolffd@0:     shape=S.shape;
wolffd@0:   case 'som_map'  
wolffd@0:     msize=S.topol.msize;
wolffd@0:     lattice=S.topol.lattice;
wolffd@0:     shape=S.topol.shape;
wolffd@0:   otherwise
wolffd@0:     error('Invalid map or topol struct.');
wolffd@0:   end
wolffd@0: elseif iscell(S),
wolffd@0:   if vis_valuetype(S,{'topol_cell'}),
wolffd@0:     lattice=S{1};
wolffd@0:     msize=S{2}; 
wolffd@0:     shape=S{3}; 
wolffd@0:   else
wolffd@0:     error('{lattice, msize, shape} expected for cell input.')
wolffd@0:   end
wolffd@0: else
wolffd@0:   error('{lattice, msize, shape}, or map or topol struct expected.')
wolffd@0: end
wolffd@0: 
wolffd@0: if ~vis_valuetype(msize,{'1x2'})
wolffd@0:   error('Invalid map size: only 2D maps allowed.')
wolffd@0: end  
wolffd@0: 
wolffd@0: %% Init %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: N=msize(1)*msize(2);
wolffd@0: 
wolffd@0: %% Action & Build output arguments %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: switch lattice
wolffd@0: case 'hexa'
wolffd@0:   l1=ones(N,1); l1((msize(1)+1):msize(1):end)=0;
wolffd@0:   l2=zeros(msize(1),1); l3=l2;
wolffd@0:   l2(1:2:end-1)=1; l3(3:2:end)=1;
wolffd@0:   l2=repmat(l2,msize(2),1); 
wolffd@0:   l3=repmat(l3,msize(2),1);
wolffd@0:   C= ...
wolffd@0:     spdiags([l1 l2 ones(N,1) l3], [1 msize(1)-1:msize(1)+1],N,N);
wolffd@0: case 'rect'
wolffd@0:   l1=ones(N,1);l1((msize(1)+1):msize(1):end)=0;
wolffd@0:   C=spdiags([l1 ones(N,1)],[1 msize(1)],N,N);
wolffd@0: otherwise
wolffd@0:   error('Unknown lattice.')
wolffd@0: end
wolffd@0: 
wolffd@0: switch shape
wolffd@0: case 'sheet'
wolffd@0:   ;
wolffd@0: case 'cyl'
wolffd@0:   C=spdiags(ones(N,1),msize(1)*(msize(2)-1),C);
wolffd@0: case 'toroid'
wolffd@0:   %warning('Toroid not yet implemented: using ''cyl''.');
wolffd@0:   %C=spdiags(ones(N,1),msize(1)*(msize(2)-1),C);
wolffd@0:   %l=zeros(N,1); l(1:msize(2):end)=1;
wolffd@0:   %C=spdiags(l,msize(1),C);
wolffd@0: 
wolffd@0:   % use som_unit_neighs to calculate these
wolffd@0:   C = som_unit_neighs(msize,lattice,'toroid');
wolffd@0:   % to be consistent, set the lower triangular values to zero
wolffd@0:   munits = prod(msize);
wolffd@0:   for i=1:(munits-1), C((i+1):munits,i) = 0; end
wolffd@0: otherwise
wolffd@0:   error('Unknown shape.');
wolffd@0: end
wolffd@0: 
wolffd@0: