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