function h=som_show_add(mode,D,varargin)%SOM_SHOW_ADD Shows hits, labels and trajectories on SOM_SHOW visualization%% h = som_show_add(mode, D, ['argID',value,...])%%  som_show_add('label',sMap)%  som_show_add('hit',som_hits(sMap,sD))%  som_show_add('traj',som_bmus(sMap,sD))%  som_show_add('comet',som_bmus(sMap,sD))%  som_show_add('comet',inds, 'markersize', [1 0.2])% %  Input and output arguments ([]'s are optional): %   mode    (string) operation mode 'label', 'hit', 'traj', 'comet'%   D       (varies) depending on operation mode%      In 'label' mode gives the labels  %           (struct) map struct, the .labels field of which is used%           (cell array of strings) size munits x number_of_labels%      In 'hit' mode gives the hit histogram(s)%           (matrix) size munits x k, if k>1, D gives hit histograms %                    for k different sets of data (e.g. k classes).     %      In 'traj' and 'comet' modes gives the trace of the trajectory%           (vector) size N x 1, D(1) is the current and D(end) %                    is oldest item of the trajectory%   [argID, (string) Additional arguments are given as argID, value%    value] (varies) pairs. Depend on the operation mode (see below).                   %%   h    (vector)    handles to the created objects%% Here are the valid argument IDs and corresponding values. Most of % them depend on the operation mode: %% all modes%   'SubPlot'   (vector) which subplots are affected (default: current)%               (string) 'all': all subplots are affected % mode = 'label'%   'TextSize'  (scalar) text size in points%   'TextColor' (string) ColorSpec, 'xor' or 'none': label color %% mode = 'hit'%   'EdgeColor'  (string) ColorSpec, 'none' %   'MarkerSize' (scalar) maximum marker size%  if k == 1, %   'Marker'     (string) 'lattice', Matlab's built-in markerstyles, 'none'%   'MarkerColor'(string) Colorspec, 'none': fill color for markers%   'Text'       (string) 'on', 'off':  whether to write the number of hits%   'TextColor'  (string) ColorSpec, 'xor': text color if Text is 'on'%   'TextSize'   (scalar) text font size in points if Text is 'on'%  if k > 1, %   'SizeFactor' (string) 'common', 'separate': size scaling%   'Marker'     (string) 'lattice', Matlab's built-in markerstyles, 'pie', 'none' %                (cell array) size k x 1, marker style for each histogram%   'MarkerColor'(string) Colorspec, 'none': fill color for markers%                (matrix) size k x 3, color for each histogram%% mode = 'traj'%   'TrajWidth'  (scalar) basic trajectory line width in points%   'WidthFactor'(string) 'hit' or 'equal': effect of hits on line width %   'TrajColor'  (string) ColorSpec, 'xor': color for trajectory line%   'Marker'     (string) 'lattice', Matlab's built-in markerstyles, 'none'%   'MarkerSize' (scalar) basic marker size (in points)%   'SizeFactor' (string) 'equal', 'hit' (equal size/size depends on freq.) %   'MarkerColor'(string) Colorspec, 'none': color of markers%   'EdgeColor'  (string) ColorSpec, 'none': edgecolor of markers %% mode = 'comet'%   'Marker'     (string) 'lattice', Matlab's built-in markerstyles%   'MarkerColor'(string) ColorSpec, 'none': color for the markers%                (matrix) size N x 3, RGB color for each step %   'EdgeColor'  (string) ColorSpec, 'none': edgecolor for markers%   'MarkerSize' (vector) size 1 x 2, size of comet core and tail% % For more help, try 'type som_show_add' or check out online documentation.% See also SOM_SHOW.%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% som_show_add %% PURPOSE %%  Shows hits, labels and trajectories on SOM_SHOW visualization%% SYNTAX%%  h = som_show_add(mode, D); %  h = som_show_add(..., 'argID', value);%% DESCRIPTION %% The SOM_SHOW function makes the basic visualization of the SOM.% With SOM_SHOW_ADD one can set labels, hit histogarms or different % trajectories on this visualization.%%  labels (mode = 'label')%% Labels are strings describing the units. They may be, e.g., a result% of SOM_AUTOLABEL function. Labels are centered on the unit so that% multiple labels are in a column.%%  hit histograms (mode = 'hit')%% Hit histograms indicate how the best matching units of a data% set/some data sets are distribited on a SOM. The hit histogram can% be calculated using function SOM_HITS.%%  trajectories (mode = 'traj' or mode = 'comet')%% Trajectories show the best matching units for a data set that is% time (or any ordered) series. It may be either a line connecting the% consecutive best matching units ('traj' mode) or a "comet"% trajectory where the current (first sample in D) best matching unit% has biggest marker and the oldest (last sample) has smallest% marker ('comet' mode).%% NOTE: that the SOM_SHOW_ADD function can only be applied to% figures that have been drawn by SOM_SHOW.% % KNOWN BUGS%% for 'hit' mode, if the given hit matrix is all zeros, a series of % error messages is generated% % REQUIRED INPUT ARGUMENTS%% mode     (string) Visuzalization mode %                   'label'  map labeling%                   'hit'    hit histograms%                   'traj'   line style trajectory%                   'comet'  comet style trajectory %% D (vector, map struct, cell array of strings) Data%% The valid value of D depends on the visualization mode:%%  Mode       Valid D%  'label'    map struct or Mxl cell array of strings, where%              M is number of map units and l maximum numer of%              labels in unit.%%  'hit'      Mx1 vector or MxK matrix, where M is number of map%             units and K is number of hit histograms (of K%             different classes of data) to be shown%%  'comet'    Lx1 vector of best matchig unit indices that have to%  'traj'     be in range of the map that is in the figure. L is %             the length of trajectory%             % OPTIONAL INPUT ARGUMENTS%% Optional arguments must be given as 'argument identifier', value% -pairs. This section is divided in four parts because each mode% functions in a different way, though they may have same identifier% names.%% If user specifies an identifier that is not operational in the% specified mode, the functions gives a warning message. If the% identifier does not exist in any mode the execution is terminated% and an error message is returned.%% GENERAL OPTIONAL INPUT ARGUMENTS (in all modes)%% 'SubPlot'     Target subplots in the figure    %      (vector) Subplots' ordinal numbers in a vector. By default%               the target is the current subplot (see GCA).%      (string) String 'all' means all subplots. %% 'Marker'      Data marker (not in use in 'label' mode)%      (string) 'none': sets the markers off%               'lattice': sets the marker shape according to the%                lattice of the underlying map, i.e. it gives%                rectangles if underlying map lattice is 'rect' and%                hexagons for 'hexa', respectively%               any of the Matlab's built-in marker styles: 'o', 's',%               'd', 'v', '^', '<' ,'> ', 'p', 'h', 'x', '.', '*', '+'%      %               NOTE that '.','x','+' or '*' are not recommended since%               they have only edgecolor and many visualizations are %               based on _face_ color. %%               NOTE there is an important difference between built-in%               markers. If figure size is changed the 'lattice'%               markers are rescaled but the built-in markers stay at%               fixed size, and consequently, the size unit for%               'lattice' markers is normalized but for built-in%               markers the size is given in points. For 'lattice'%               markers size 1 means the size of the map unit.%%               NOTE that in 'hit' mode there are some additional features.%% 'EdgeColor'   Sets edgecolor for the markers (not in use in 'label' mode)%      (string) ColorSpec, e.g. 'r',  gives each edge the specified color%               'none': sets markers edges invisible %               Default is 'none' - except if MarkerColor is set to 'none' the%               defaults is 'black'.%% OPTIONAL INPUT ARGUMENTS mode 'label'%% Labels are centered on the unit so that multiple labels are in% a single column.%% 'SubPlot'     see General Optional Input Arguments %% 'TextSize'    Text size for labels%      (scalar) Text size in points. Default is 10.%% 'TextColor'   Text color%      (string) ColorSpec specifies the text color for all labels %               'xor': gives Matlab's "xor" text color mode where the %                label color depends on background color     %               'none': sets labels invisble (but creates the objects)%% OPTIONAL INPUT ARGUMENTS mode 'hit'%% The function in mode 'hit' depends on the input argument size. If% only one hit histogram is drawn (K==1), it is possible to show the% hits using numbers. This is not possible for multiple hit% histograms (K>1).%% 'SubPlot'     see General Optional Input Arguments %        % 'Marker'      Marker style(s)%      (string) As in General Optional Input Arguments. In addition %               'pie': sets pie charts for markers. The size of the%                pie in each unit describes the number of total hits in the%                unit and the share of each sector is the relative amount of%                hits in each class (requires multiple histograms). Color for%                each class is set by MarkerColor. Default coloring %                is hsv(K), where K is the number of hit histograms (classes).%      (cell array) size K x 1, of built-in marker style characters. K is%               number of histograms (classes), i.e., same as size(D,2)%               where D is the second input argument. Cell value is%               valid only if multiple histograms are specified (K>1). % %               NOTE if multiple histograms (classes) are specified%               and Marker is one of the built-in marker styles or%               'lattice', the markers are drawn in size order from%               largest to smallest. This insures that all markers are%               visible (or at least their edges are). But if two%               markers for different classes in the same node were of%               same size, the other would be totally hidden. In order%               to prevent this, the markers for different classes are%               shifted different amounts from the exact centre of the%               unit. (Evidently, if Marker is 'pie' this problem does%               not exist.)%%               Default marker is 'lattice' for one histogram and%               'pie' for multiple histograms.%% 'MarkerColor' Marker color(s) %      (string) ColorSpec gives all markers the same color%               'none': leaves the markes transparent (only edges are visible)%      (matrix) size K x 3, RGB triples for each histogram class%               giving each hit histogram an own color%%               NOTE that markers '*','+','x', or '.' cannot use %               MarkerColor since these objects have no face (fill)%               color. For them only EdgeColor matters.% % 'MarkerSize'  Maximum size for marker%      (scalar) set the _maximum_ marker size that corresponds to%               maximum hit count. If Marker is 'pie' or 'lattice' the %               MarkerSize is in normalized scale: 1 correspons to unit size.%               If Marker is one of the built-in styles, MarkerSize is given%               in points.  %               %               Marker        Default MarkerSize  %               'lattice'      1 (normalized units)%               'pie'          1 (normalized units) %               'o','s', etc.  6 (points)%% 'SizeFactor'  Defines the scaling of the marker sizes in multiple%               histogram case (when Marker is one of the built-in marker %               styles or 'lattice').%      (string) 'separate' (the default) means that marker size shows %                the share of the data which hits the unit compared to %                amount of data in that class. That is, the size of%                markers show the relative distribution of data on the map %                in each class separately. The maximum size is SizeFactor.       %               'common' means that marker size shows the distribution of%                the data in the different classes compared to %                _the total amount of data_. %% 'EdgeColor'   Sets edgecolor for the markers, see General%               Optional Input Arguments. Default is 'none' -%               except if MarkerColor is 'none' or Marker is%               'x','*,'x', or '.'. In these cases default EdgeColor is 'black'. %% 'Text'        Write/don't write the number of hits on the%               units. This option is not in use for multiple histograms.%      (string) 'on' or 'off' (the default)%% 'TextColor'   Text color %      (string) ColorSpec gives each letter the same color%               'xor' gives a "xor" coloring for the text%% 'TextSize'    Text size (in points)    %      (scalar) text size in points, default is 10%% OPTIONAL INPUT ARGUMENTS mode 'traj'%% Input D is a Nx1 vector of N BMU indices that describe the trace of the % comet. First element D(1) is "newest" and D(end) "oldest". Note% that at least two indeces are expected: size of D must be at% least 2x1.%% 'SubPlot'     see General Optional Input Arguments%% 'TrajColor'   Color for trajectory line%      (string) ColorSpec gives each marker the same color, 'w' by default%               'none' sets the marker fill invisible: only edges are shown%% 'TrajWidth'   Maximum width of trajectory line%      (scalar) width in points. Default is 3.%% 'WidthFactor' Shows how often edge between two units has been traversed.%      (string) 'hit': the size of the marker shows how frequent the%                trajectory visits the unit (TrajWidth sets the%                maximum size). This is the default.%               'equal': all lines have the same width (=TrajWidth)%% 'Marker'      Marker style, see General Optional Input%               Arguments. Default is 'o'.%    %               NOTE Marker style 'lattice' is not valid in mode 'traj'.%               NOTE Markers can be turned off by setting MarkerSize to zero.%% 'MarkerSize'  Maximum size of markers%      (scalar) Default is 12 (points).%% 'SizeFactor'  Sets the frequency based marker size or constant marker size.                  %      (string) 'hit': the size of the marker shows how frequent the%                trajectory visits the unit (MarkerSize sets the%                maximum size). This is the default.%               'equal': all markers have th esame size (=MarkerSize)%% 'MarkerColor' The fill color(s) for hit markers%      (string) ColorSpec gives each marker the same color, default is 'w'%               'none' sets the marker fill invisible: only edges are shown%%               NOTE markers '*','+','x', or '.' can't use MarkerColor since%               these objects have no face (fill) color: only EdgeColor%               matters for these markers.% % 'EdgeColor'   see General Optional Input Arguments. Default is%               'none' - except if MarkerColor is 'none' or Marker%               is 'x','*','x', or '.'. In these cases default%               EdgeColor is 'white'. %% OPTIONAL INPUT ARGUMENTS mode 'comet'%% Input D is a Nx1 vector of N BMU indices that describe the trace of% the comet. First element D(1) is "newest" and D(end) "oldest". Note% that at least two indeces are expected: size of D must be at least% 2x1.%% 'SubPlot'     see General Optional Input Arguments %% 'Marker'      Marker style, see General Optional Input%               Arguments. Default is 'lattice'.%% 'MarkerColor' The fill color(s) for comet markers%      (string) ColorSpec gives each marker the same color, default is 'w'%               'none' sets the marker fill invisible: only edges are shown %      (matrix) size N x 3, consisting of RGB triples as rows %               sets different color for each marker. This may be%               used to code the time series using color/grayscale.%%               NOTE Markers '*','+','x', or '.' can't use MarkerColor%               since these objects have no face (fill) color: only %               EdgeColor matters for these markers.% % 'EdgeColor'   see General Optional Input Arguments. Default is%               'none' - except if MarkerColor is 'none' or Marker%               is 'x','*,'x', or '.'. In these cases default %               EdgeColor is 'white'. %% 'MarkerSize'  The size of "comet core" and tail %      (vector) size 1 x 2: first element sets the size for the marker%               representing D(1) and the second set size for D(end)%               the size (area) of the markes between these changes linearly.%               Note that size units for 'lattice' marker style are%               normalized so that 1 means map unit size but for built-in%               marker styles the size is given points.%%               Marker          default value%               'lattice'        [0.8 0.1]%               'o','v', etc.    [20 4]%% OUTPUT ARGUMENTS%% h (vector) handles to all objects created by the function% % OBJECT TAGS%%  Field Tag in every object is set to%%   'Lab'  for objects created in mode 'label'%   'Hit'                -"-           'hit'%   'Traj'               -"-           'traj'%   'Comet'              -"-           'comet'%% EXAMPLES