som_unit_neighs

Purpose

 Find the adjacent (in 1-neighborhood) units for each map unit of a SOM
 based on given topology.

Syntax

  Ne1 = som_unit_neighs(sMap);
  Ne1 = som_unit_neighs(sM.topol);
  Ne1 = som_unit_neighs(msize);
  Ne1 = som_unit_neighs(msize,'hexa');
  Ne1 = som_unit_neighs(msize,'rect','toroid');

Description

 For each map unit, find the units the distance of which from 
 the map unit is equal to 1. The distances are calculated
 along the map grid. Consider, for example, the case of a 4x3 map. 
 The unit ('1' to 'C') positions for 'rect' and 'hexa' lattice (and
 'sheet' shape) are depicted below: 

   'rect' lattice           'hexa' lattice
   --------------           --------------
      1  5  9                  1  5  9
      2  6  a                   2  6  a
      3  7  b                  3  7  b
      4  8  c                   4  8  c

 The units in 1-neighborhood (adjacent units) for unit '6' are '2','5','7'
 and 'a' in the 'rect' case and '5','2','7','9','a' and 'b' in the 'hexa'
 case. The function returns a sparse matrix having value 1 for these units.  
 Notice that not all units have equal number of neighbors. Unit '1' has only 
 units '2' and '5' in its 1-neighborhood. 

Required input arguments

  topol          Map grid dimensions.
        (struct) topology struct or map struct, the topology 
                 (msize, lattice, shape) of the map is taken from 
                 the appropriate fields (see e.g. SOM_SET)
        (vector) the vector which gives the size of the map grid
                 (msize-field of the topology struct).

Optional input arguments

  lattice (string) The map lattice, either 'rect' or 'hexa'. Default
                   is 'rect'. 'hexa' can only be used with 1- or 
                   2-dimensional map grids.
  shape   (string) The map shape, either 'sheet', 'cyl' or 'toroid'. 
                   Default is 'sheet'. 

Output arguments

  Ne1   (matrix) sparse matrix indicating units in 1-neighborhood
                 by 1, all others have value 0 (including the unit itself!),
                 size is [munits munits]

Examples

 Simplest case:
  Ne1 = som_unit_neighs(sTopol);
  Ne1 = som_unit_neighs(sMap.topol);
  Ne1 = som_unit_neighs(msize);
  Ne1 = som_unit_neighs([10 10]);

 If topology is given as vector, lattice is 'rect' and shape is 'sheet'
 by default. To change these, you can use the optional arguments:
  Ne1 = som_unit_neighs(msize, 'hexa', 'toroid');

 The neighbors can also be calculated for high-dimensional grids:
  Ne1 = som_unit_neighs([4 4 4 4 4 4]);

See also