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
Not yet ready
See also