SOM Toolbox Online documentation http://www.cis.hut.fi/projects/somtoolbox/

# som_unit_dists

### Purpose

``` Returns interunit distances between the units of a Self-Organizing Map
along the map grid.

```

### Syntax

```  Ud = som_unit_dists(sTopol);
Ud = som_unit_dists(sM.topol);
Ud = som_unit_dists(msize);
Ud = som_unit_dists(msize,'hexa');
Ud = som_unit_dists(msize,'rect','toroid');

```

### Description

``` Calculates the distances between the units of a SOM based on the
given topology. The distance are euclidian and they are measured
along the map grid (in the output space).

In case of 'sheet' shape, the distances can be measured directly
from the unit coordinates given by SOM_UNIT_COORDS.

In case of 'cyl' and 'toroid' shapes this is not so. In these cases
the coordinates are calculated as in the case of 'sheet' shape and
the shape is then taken into account by shifting the map grid into
different positions.

Consider, for example, a 4x3 map. The basic position of map units
is shown on the left (with '1' - 'C' each denoting one map unit).
In case of a 'cyl' shape, units on the left and right edges are
neighbors, so for this purpose the map is copied on the left and
right sides of the map, as on right.

basic               left     basic    right
-------             -------  -------  -------
1  5  9             1  5  9  1  5  9  1  5  9
2  6  a             2  6  a  2  6  a  2  6  a
3  7  b             3  7  b  3  7  b  3  7  b
4  8  c             4  8  c  4  8  c  4  8  c

For the 'toroid' shape a similar trick is done, except that the
copies are placed all around the basic position:

1  5  9  1  5  9  1  5  9
2  6  a  2  6  a  2  6  a
3  7  b  3  7  b  3  7  b
4  8  c  4  8  c  4  8  c
1  5  9  1  5  9  1  5  9
2  6  a  2  6  a  2  6  a
3  7  b  3  7  b  3  7  b
4  8  c  4  8  c  4  8  c
1  5  9  1  5  9  1  5  9
2  6  a  2  6  a  2  6  a
3  7  b  3  7  b  3  7  b
4  8  c  4  8  c  4  8  c

From this we can see that the distance from unit '1' is 1 to units
'9','2','4' and '5', and sqrt(2) to units 'C','A','8' and '6'. Notice
that in the case of a 'hexa' lattice and 'toroid' shape, the size
of the map in y-direction should be even. The reason can be clearly
seen from the two figures below. On the left the basic positions for
a 3x3 map. If the map is copied above itself, it can be seen that the
lattice is broken (on the right):

basic positions                 example of broken lattice
---------------                 -------------------------
1  4  7
2  5  8
3  6  9
1  4  7                         1  4  7
2  5  8                         2  5  8
3  6  9                         3  6  9

```

### 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

```  Ud   (matrix) distances from each map unit to each other map unit,
size is [munits munits]

```

### Examples

``` Simplest case:
Ud = som_unit_dists(sTopol);
Ud = som_unit_dists(sMap.topol);
Ud = som_unit_dists(msize);
Ud = som_unit_dists([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:
Ud = som_unit_dists(msize, 'hexa', 'toroid');

The distances can also be calculated for high-dimensional grids:
Ud = som_unit_dists([4 4 4 4 4 4]);

```