M-file format specifications

In this document the convention for naming the files, structuring, writing and commenting the code and naming variables and constants is given for the SOM Toolbox project. It is offered both as a help for those who read and want to understand the function files, and as a guideline for those who wish to add something to the project.

File names
File structure
Errors
Helps
Comments
Variable names


File names

File names will be of the form

  som_xxx.m
where xxx stands for an arbitrarily long descriptive name. Not too long, though.


File structure

In principle each file should be structured as follows. In practice you can add/combine/leave out necessary parts. Notice the checking for the number of input and output arguments.

function [ret1] = som_fu(arg1,arg2)

% Help
%
% 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Check arguments

error(nargchk(n, m, nargin));
error(nargchk(k, l, nargout));

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Initialization                           

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Action

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Build / clean up the return arguments


Errors

When encountering an error in a function, use
  error('message')
function to exit from function.


Helps

Each file will have a short help notice at the beginning of the file. The format of the help is as follows:
%FUNCTION_NAME  One-line description of the purpose/function of the file.
%
% [ret1, ret2] = function(arg1, [arg2])
%
% ARGUMENTS ([]'s are optional) 
%
%  arg1      (type) size and description 
%  [arg2]    (type) size, description and default value
%
% RETURNS
%
%  ret1      (type) size and description 
%  ret2      (type) size and description 
%
% A longer multiline description of the function, if necessary. 
% In any case put here a couple of examples with possible tagline 
% of EXAMPLES
%
% See also FUNCTION1, FUNCTION2, FUNCTION3.

% Copyright (c) 1997 by the SOM toolbox programming team.
% http://www.cis.hut.fi/projects/somtoolbox/

% ecco 160797

In the help use the following variable names:

  n1, n2, ..., nk        the sizes of the SOM along each dimension
  dim                    the input dimension
  k                      the output dimension (dimension of the grid)
  p                      the length of training


Comments

The files should be well documented. At least the following things should be done:

Additionally you may include:


Standard variable names

To make the development and understanding of the package easier, the following standard variable names should be used:

  dim          =   dimension of the input space
  sData        =   data struct
  D            =   data matrix
  dlen         =   number of data vectors
  dlabels      =   labels of data
  data_id      =   data set name

  sMap         =   map struct
  M            =   map matrix (codebook)
  msize        =   map grid sizes
  mdim         =   map output dimension (dimension of the grid)
  munits       =   total number of map units
  mlabels      =   labels of map
  lattice      =   map lattice
  shape        =   map shape
  neigh        =   neighborhood function  

  cnames       =   names of components
  cweights     =   weights of components
  
  rad          =   neighborhood radius
  rad_ini      =   initial neighborhood radius
  rad_fin      =   final neighborhood radius
  sTrseq       =   train sequence
  alpha        =   training coefficient
  alpha_ini    =   initial training coefficient
  alpha_fin    =   final training coefficient
  alphaf       =   training coefficient function
  epochs       =   train cycles
  train_len    =   training length

 Name strings:
  'hexa'       =   hexagonal
  'rect'       =   rectangular
  'toroid'     =   toroid shape
  'cyl'        =   cylinder shape
  'bubble'     =   bubble neighborhood function
  'gaussian'   =   gaussian neighborhood function
  'ep'         =   ep neighborhood function
  'random'     =   random initialization
  'linear'     =   linear initialization and linear train coeff. function
  'inv'        =   inverse train coefficient function  
  'seq'        =   sequential training
  'batch'      =   batch training 
  


somtlbx@mail.cis.hut.fi
Last modified: Wed Sep 10 13:30:24 EET DST 1997