# 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