SOM Toolbox Functions and Structures

In this document the SOM Toolbox functions as well as the structures are described shortly. The functions are divided to two types: user functions and utility functions. The former are the ones that the typical end-user will use, and the latter are those that are used by advanced users and by the functions in the first category.

Structures
Basic package
User-level utilities
Visualization
High level functions, GUI and demos
Contributed functions


Structures

The purpose of structures is to group information related to a SOM under one variable, rather than a group of variables. Matlab 4 didn't have structures, so this is one of the primary reasons why the SOM Toolbox does not work with it.

Functions related to the self-organizing map structure
som_create.m, som_trainops.m, som_info.m, som_name.m, som_sub2ind.m, som_ind2sub.m, som_label.m
Functions related to the data structure
som_data_struct.m, som_name.m, som_label.m
Functions related to the training info structure
som_train.m
Functions related to the normalization structure
som_normalize_data.m, som_denormalize_data.m

Self-organizing map structure consists of the following fields:

Field Meaning
codebook the weight vectors of the nodes
labels the labels of each node
msize the dimensions of map grid
lattice neighborhood lattice (local topology)
shape the shape of the map (global topology)
neigh neighborhood function
init_type initialization type
train_type training algorithm (of last training)
train_sequence array of structs containing information of training, see below
mask component mask for distance calculation purposes
name name of the map
data_name name of the latest data set
comp_names names of the vector components
normalization normalization structu, copied from the training data set

Data structure consists of the following fields:

Field Meaning
data the data vectors
labels the labels of each data vector
name of data set
comp_names names of vector components
normalization normalization struct, see below

Training info structure consists of the following fields

Field Meaning
algorithm training algorithm
radius_ini initial neighborhood radius
rad_fin final neighborhood radius
alpha_ini initial learning coefficient
alpha_type alpha function type
trainlen training length
time date and time

Normalization structure consists of the following fields

Field Meaning
name name of the normalization technique
inv_params parameters for the inverse transform


Core functions

These functions are used to create, initialize and train self-organizing maps. Also interaction with the SOM_PAK package (read/write files in SOM_PAK format) and some basic utilities are part of the basic package.

Struct functions
som_create.m, som_data_struct.m, som_info.m, som_name.m, som_label.m
Initialization and training
som_batchtrain.m, som_init.m, som_lininit.m, som_randinit.m, som_seqtrain.m, som_train.m, som_trainops.m
Read / write SOM_PAK
som_read_cod.m, som_read_data.m, som_write_cod.m, som_write_data.m
Low-level utilities
som_nanops.m, som_unit_coords.m, som_unit_distances.m, som_unit_neighborhood.m, som_sub2ind.m, som_ind2sub.m
Function Category Description
som_batchtrain.m utility Use batch algorithm to train the self-organizing map.
som_create.m utility Create self-organizing map structure.
som_data_struct.m utility Create a self-organizing map data struct.
som_ind2sub.m utility Map grid subscripts from linear index.
som_info.m user Displays information of a self-organizing map or data structure.
som_init.m user Create and initialize a self-organizing map.
som_label.m user Give/clear labels to/from map or data struct.
som_lininit.m utility Initialize self-organizing map (linearly).
som_name.m user Name a field of self-organizing map or data struct.
som_nanops.m utility NaN operations needed by somtoolbox.
som_randinit.m utility Initialize self-organizing map (randomly).
som_read_cod.m user Reads a SOM_PAK format codebook file.
som_read_data.m user Reads a data file.
som_seqtrain.m utility Use sequential algorithm to train the self-organizing map.
som_sub2ind.m utility Linear index from map grid subscripts.
som_train.m user Train self-organizing map.
som_trainops.m user Set self-organizing map train options.
som_unit_coords.m utility Returns unit locations on the SOM grid.
som_unit_distances.m utility Calculates distances between unit locations on the SOM grid.
som_unit_neighborhood.m utility Calculates which units belong to the N-neighborhood of each unit.
som_write_cod.m user Writes a map struct into a file in SOM_PAK format.
som_write_data.m user Writes a data struct into a file in SOM_PAK format.


User-level utilities

These are functions used for analysing and postprocessing the map or analysing data with the map.

Data projections (som_bmus.m, som_hits.m): Projecting data on the map means searching for its BMUs from the map. The BMU search (som_bmus.m) looks for the most similar (or closest) weight vector from the map for given data vector. Also the nth-best match can be requested. A more sophisticated form is the calculation of hit histograms (som_hits.m). Different data sets can be compared by projecting them on the map and comparing their distributions.

Local data sets (som_divide.m, som_manualclassify.m): Local data sets are constructed of the data vectors projected to a particular map unit. They can be built using function som_divide.m. Alternatively several map units can contribute to a local data set. The classes can be selected using som_manualclassify.m.

Interpretation (som_autolabel.m): The SOM can be interpreted by identifying key areas from the map and giving them corresponding labels. The simplest way to do this is to select a set of representation samples, give them labels, and forward these labels to the BMUs of the samples. The som_autolabel.m function performs this. It offers three different ways to handle multiple labels in a map unit.

Validation (som_quality.m): Maps are usually validated using two qualifiers: precision and topology preservation. The function som_quality.m can be used to calcute average quantization error (the former property) and the topographic error (the latter property).

Data normalization (som_normalize_data.m, som_denormalize_data.m): These functions offer four invertable normalization functions for the data.

Data projections
som_bmus.m, som_hits.m
Data projections
som_divide.m, som_autolabel.m
Interpretation
som_autolabel.m
Validation
som_quality.m
Data normalization
som_normalize_data.m, som_denormalize_data.m
Function Category Description
som_autolabel.m user Automatically labels the SOM based on labels in given data.
som_bmus.m utility Calculates BMUs for given data vectors.
som_denormalize_data.m utility Invert the normalization to get original values.
som_divide.m user Divides a data set to local data set using a map.
som_hits.m user Calculates the number of hits in each map unit.
som_manualclassify.m user Interactively lets user classify map units.
som_normalize_data.m user Normalize data vectors, four different kinds of methods.
som_quality.m user Quality measures for the map.


Visualization

The toolbox has two basic visualization functions: som_show.m which uses patch objects and is strictly 2D and som_showgrid which uses plot3 and surf commands and can also plot to 3D. The former has many auxiliary functions and is much more advanced than the latter. The graphical user interface uses the same type of visualization as som_show.m.

See the visualization section in the Toolbox properties document to get more insight to how visualization works.

NOTE: Only maps with 1- or 2-dimensional grids can be visualized.

Calculation utilities
som_umat.m, som_projection.m, som_sammon.m, som_pca.m, som_cca.m
Struct-level visualization
som_show.m, som_showgrid.m, som_profile.m
Matrix-level visualization
som_plane.m, som_plane3.m, som_planeH.m, som_planeL.m, som_plane.T, som_planeU.m, som_manualclassify.m
Auxiliary function of som_show
som_addlabels.m, som_addhits.m, som_addtraj.m, som_clear.m, som_recolorbar.m, som_figuredata.m
Function Category Description
som_addlabels.m user Adds labels of map units on a figure using presumed places of the units.
som_addhits.m user As som_addlabels.m, but shows the number of hits for each map unit.
som_addtraj.m user As som_addlabels.m, but adds the given trajectory.
som_cca.m utility Calculates the CCA (Curvilinear Component Analysis) projection for given data set.
som_clear.m user Clears hit marks, labels or trajectories from the current figure.
som_figuredata.m utility Gets graphical handles from a som_show figure.
som_manualclassify.m user The SOM can be classified manually.
som_pca.m utility Calculates the PCA (Principal Component Analysis) projection for given data set.
som_plane.m utility Draws a 2D-component plane.
som_plane3.m utility Draws a 3D-component plane.
som_planeH.m utility Writes a hit matrix or any matrix on the current axes.
som_planeL.m utility Writes label(s) on current axes.
som_planeT.m utility Draws a trajectory on the map.
som_planeU.m utility Draws a 2D unified distance matrix.
som_profile.m user Shows the model vectors of a given map.
som_projection.m user Calculates a projection to lower dimension for the given map / data set.
som_recolorbar.m user Reconfigures the colorbars of som_show figure.
som_sammon.m user Calculates the Sammon's projection for given data set.
som_show.m user Shows given component planes and/or u-matrix of self-organizing map.
som_showgrid.m user Shows the grid of given map / matrix. Used to visualize Sammon's projection.
som_umat.m utility Compute the unified distance matrix of self-organizing map.


General

High level tools (som_doit.m, som_gui.m): These functions are very high level functions. The function som_doit.m performs a default SOM analysis of a data: normalizes the map, initializes, trains, validates and finally visualizes the map. Function som_gui.m starts the graphical user interface tool.

Demos (som_demo{,1,2,3,4}.m, som_toolbox.m): The demos (som_demo1.m, som_demo2.m, som_demo3.m and som_demo4.m) form a brief introduction to SOM and the toolbox. Function som_demo.m is graphical user interface to the demos.

GUI: The graphical user interface contains several functions, most of which the user should never call directly. There are however two functions that the user might want to use: somui_it.m which is the initialization and training tool and somui_vis.m which is the visualization tool.

High level tools
som_doit.m, som_gui.m
Helps and demos
som_demo.m, som_demo1.m, som_demo2.m, som_demo3.m, som_demo4.m
GUI high level
somui_it.m, somui_vis.m
GUI low level
somui_fig.m, somui_info.m, somui_load.m, somui_loaddata.m, somui_loadfile.m, somui_loadmap.m, somui_mlg.m, somui_next.m, somui_save.m, somui_savemap.m, somui_sel_file.m, somui_sel_var.m, somui_show.m, somui_text.m, somui_vis.m
Function Category Description
som_demo.m user GUI for the SOM Toolbox demos.
som_demo1.m user Demo #1: basic usage of the SOM Toolbox, part I.
som_demo2.m user Demo #2: basic usage of the SOM Toolbox, part II.
som_demo3.m user Demo #3: SOM visualization.
som_demo4.m user Demo #4: Data analysis using the SOM.
som_doit.m user Performs a default analysis for the given data set.
som_gui.m user Starts the GUI of the toolbox.
somui_it.m user GUI for initialization and training of SOM .
somui_vis.m user GUI for visualization of SOM.


Contributed functions

The contributed functions are not part of the SOM Toolbox, but rely on or support it.

Other quantization methods
neural_gas.m
Function Contributed by Description
neural_gas.m Juha Vesanto Implements the Neural Gas algorithm: a quantization method related to the SOM.


somtlbx@mail.cis.hut.fi
Last modified: Fri Dec 19 11:36:51 EET 1997