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 will be of the form
som_xxx.mwhere xxx stands for an arbitrarily long descriptive name. Not too long, though.
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
error('message')function to exit from function.
%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
The files should be well documented. At least the following things should be done:
Additionally you may include:
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