wolffd@0: function sData = som_data_struct(D, varargin)
wolffd@0: 
wolffd@0: %SOM_DATA_STRUCT Create a data struct.
wolffd@0: %
wolffd@0: % sData = som_data_struct(D, [argID, value, ...])
wolffd@0: %
wolffd@0: %  sData  = som_data_struct(D); 
wolffd@0: %  sData  = som_data_struct(D,'name','my_data','labels',labs);
wolffd@0: %
wolffd@0: %  Input and output arguments ([]'s are optional): 
wolffd@0: %   D        (matrix) data matrix, size dlen x dim
wolffd@0: %   [argID,  (string) See below. These are given as argID, value pairs.
wolffd@0: %    value]  (varies) 
wolffd@0: %
wolffd@0: %   sData    (struct) created data struct
wolffd@0: %
wolffd@0: %  Here are the argument IDs and corresponding values: 
wolffd@0: %   'labels'     (string array / cellstr) labels for each data vector,
wolffd@0: %                 length=dlen
wolffd@0: %   'name'       (string) data name
wolffd@0: %   'comp_names' (string array / cellstr) component names, size dim x 1
wolffd@0: %   'comp_norm'  (cell array) normalization operations for each
wolffd@0: %                 component, size dim x 1. Each cell is either empty, 
wolffd@0: %                 or a cell array of normalization structs.
wolffd@0: %
wolffd@0: % For more help, try 'type som_data_struct' or check out online documentation.
wolffd@0: % See also SOM_SET, SOM_INFO, SOM_MAP_STRUCT.
wolffd@0: 
wolffd@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %
wolffd@0: % som_data_struct   
wolffd@0: %
wolffd@0: % PURPOSE
wolffd@0: %
wolffd@0: % Creates a data structure. 
wolffd@0: %
wolffd@0: % SYNTAX
wolffd@0: %
wolffd@0: %  sD = som_data_struct(D);
wolffd@0: %  sD = som_data_struct(...,'argID',value,...);
wolffd@0: %
wolffd@0: % DESCRIPTION
wolffd@0: %
wolffd@0: % Creates a data struct. The struct contains, in addition to the data
wolffd@0: % matrix, component names, normalization operations for the components,
wolffd@0: % labels for each vector, and a name for the whole data set. All of these
wolffd@0: % can be given in the optional arguments of the function. If left
wolffd@0: % unspecified, they are given default values. 
wolffd@0: %
wolffd@0: %  Field         Type         Size / default value    
wolffd@0: %  ------------------------------------------------------------------------
wolffd@0: %   .type        (string)     'som_data'               
wolffd@0: %   .data        (matrix)     size dlen x dim             
wolffd@0: %   .name        (string)     'unnamed'
wolffd@0: %   .labels      (cellstr)    size dlen x m, {''; ''; ... ''}
wolffd@0: %   .comp_names  (cellstr)    size dim x 1, {'Variable1', 'Variable2', ...}
wolffd@0: %   .comp_norm   (cell array) size dim x 1, {[], [], ... []}
wolffd@0: %   .label_names (cellstr)    size m x 1, []
wolffd@0: %                          
wolffd@0: % '.type' field is the struct identifier. Do not change it.
wolffd@0: % '.data' field is the data matrix, each row is one data vector
wolffd@0: % '.name' field is the identifier for the whole data struct
wolffd@0: % '.labels' field contains the labels for each of the vectors. The ith
wolffd@0: %         of '.labels' contains the labels for ith data vector. Note that 
wolffd@0: %         if some vectors have more labels than others, the others are
wolffd@0: %         are given empty labels ('') to pad the '.labels' array up.
wolffd@0: % '.comp_names' field contains the names of the vector components
wolffd@0: % '.comp_norm' field contains normalization information for each
wolffd@0: %         component. Each cell of '.comp_norm' is itself a cell array of
wolffd@0: %         normalization structs. If no normalizations are performed for 
wolffd@0: %         the particular component, the cell is empty ([]).
wolffd@0: % '.label_names' is similar to .comp_names field holding the names for
wolffd@0: %         each data label column
wolffd@0: %
wolffd@0: % REQUIRED INPUT ARGUMENTS
wolffd@0: %
wolffd@0: %  D  (matrix) The data matrix, size dlen x dim. The data matrix may 
wolffd@0: %              contain unknown values, indicated by NaNs. 
wolffd@0: %  
wolffd@0: % OPTIONAL INPUT ARGUMENTS 
wolffd@0: %
wolffd@0: %  argID (string) Argument identifier string (see below).
wolffd@0: %  value (varies) Value for the argument (see below).
wolffd@0: %
wolffd@0: %  The optional arguments can be given as 'argID',value -pairs as
wolffd@0: %  listed below. If an argument is given value multiple times, the
wolffd@0: %  last one is used.
wolffd@0: %
wolffd@0: %   'labels'     (string array / cellstr) labels for each data vector,
wolffd@0: %                 size dlen x m
wolffd@0: %   'name'       (string) data name
wolffd@0: %   'comp_names' (string array / cellstr) component names, size dim x 1
wolffd@0: %   'comp_norm'  (cell array) normalization operations for each
wolffd@0: %                 component, size dim x 1. Each cell is either empty, 
wolffd@0: %                 or a cell array of normalization structs.
wolffd@0: %   'label_names'(string array / cellstr) label names, size m x 1
wolffd@0: %
wolffd@0: % OUTPUT ARGUMENTS
wolffd@0: % 
wolffd@0: %  sD (struct) the data struct
wolffd@0: %
wolffd@0: % EXAMPLES
wolffd@0: %
wolffd@0: % Simplest case:
wolffd@0: %  D  = rand(8, 3); % 8 3-dimensional vectors
wolffd@0: %  sD = som_data_struct(D);
wolffd@0: %  
wolffd@0: % With optional arguments, the other fields can be given values:
wolffd@0: %  labs   = cell(8, 1); labs{1, 1} = 'first_label';
wolffd@0: %  cnames = {'first'; 'second'; 'third'};
wolffd@0: %  
wolffd@0: %  sD = som_data_struct(D,'labels',labs,'name','a data struct');
wolffd@0: %  sD = som_data_struct(D,'comp_names',cnames);
wolffd@0: %
wolffd@0: % SEE ALSO
wolffd@0: % 
wolffd@0: %  som_set          Set values and create SOM Toolbox structs.
wolffd@0: %  som_map_struct   Create a map struct.
wolffd@0: 
wolffd@0: % Copyright (c) 1997-2000 by the SOM toolbox programming team.
wolffd@0: % http://www.cis.hut.fi/projects/somtoolbox/
wolffd@0: 
wolffd@0: % Version 1.0beta ecco 071197
wolffd@0: % Version 2.0beta juuso 101199
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: % data
wolffd@0: [dlen dim] = size(D);
wolffd@0: 
wolffd@0: % default values
wolffd@0: if ~isempty(inputname(1)), name = inputname(1); 
wolffd@0: else name = 'unnamed'; end
wolffd@0: labels = cell(dlen,1);
wolffd@0: labels(1:dlen) = {''};
wolffd@0: %for i=1:dlen, labels{i} = ''; end
wolffd@0: comp_names = cell(dim,1);
wolffd@0: for i = 1:dim, comp_names{i} = sprintf('Variable%d', i); end
wolffd@0: comp_norm = cell(dim,1);
wolffd@0: label_names = []; 
wolffd@0: 
wolffd@0: % varargin
wolffd@0: i=1; 
wolffd@0: while i<=length(varargin), 
wolffd@0:   argok = 1; 
wolffd@0:   if ischar(varargin{i}), 
wolffd@0:     switch varargin{i}, 
wolffd@0:       % argument IDs
wolffd@0:      case 'comp_names', i=i+1; comp_names = varargin{i}; 
wolffd@0:      case 'labels',     i=i+1; labels = varargin{i};
wolffd@0:      case 'name',       i=i+1; name = varargin{i};
wolffd@0:      case 'comp_norm',  i=i+1; comp_norm = varargin{i};
wolffd@0:      case 'label_names',i=i+1; label_names = varargin{i};
wolffd@0:      otherwise argok=0; 
wolffd@0:     end
wolffd@0:   else
wolffd@0:     argok = 0; 
wolffd@0:   end
wolffd@0:   if ~argok, 
wolffd@0:     disp(['(som_data_struct) Ignoring invalid argument #' num2str(i+1)]); 
wolffd@0:   end
wolffd@0:   i = i+1; 
wolffd@0: end
wolffd@0: 
wolffd@0: % create struct
wolffd@0: sData = som_set('som_data','data',D,'labels',labels,...
wolffd@0:                           'name',name,'comp_names',comp_names,...
wolffd@0:                           'comp_norm',comp_norm,'label_names',label_names);
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: 
wolffd@0: