som_unit_coords

Purpose

 Returns map grid coordinates for the units of a Self-Organizing Map.

Syntax

  Co = som_unit_coords(sTopol);
  Co = som_unit_coords(sM.topol);
  Co = som_unit_coords(msize);
  Co = som_unit_coords(msize,'hexa');
  Co = som_unit_coords(msize,'rect','toroid');

Description

 Calculates the map grid coordinates of the units of a SOM based on 
 the given topology. The coordinates are such that they can be used to
 position map units in space. In case of 'sheet' shape they can be 
 (and are) used to measure interunit distances. 

 NOTE: for 'hexa' lattice, the x-coordinates of every other row are shifted 
 by +0.5, and the y-coordinates are multiplied by sqrt(0.75). This is done 
 to make distances of a unit to all its six neighbors equal. It is not 
 possible to use 'hexa' lattice with higher than 2-dimensional map grids.

 'cyl' and 'toroid' shapes: the coordinates are initially determined as 
 in case of 'sheet' shape, but are then bended around the x- or the 
 x- and then y-axes to get the desired shape. 

Possible bugs

 I don't know if the bending operation works ok for high-dimensional
 map grids. Anyway, if anyone wants to make a 4-dimensional
 toroid map, (s)he deserves it.

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

  Co   (matrix) coordinates for each map units, size is [munits k] 
                where k is 2, or more if the map grid is higher
                dimensional or the shape is 'cyl' or 'toroid'

Examples

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

 The coordinates can also be calculated for high-dimensional grids:
  Co = som_unit_coords([4 4 4 4 4 4]);

See also