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
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.
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 |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
The contributed functions are not part of the SOM Toolbox, but rely on or support it.
Function | Contributed by | Description |
---|---|---|
neural_gas.m | Juha Vesanto | Implements the Neural Gas algorithm: a quantization method related to the SOM. |