som_bmus
Purpose
Finds BestMatching Units (BMUs) for given data vector from a given map.
Syntax
Bmus = som_bmus(sMap, sData)
Bmus = som_bmus(..., which)
Bmus = som_bmus(..., which, mask)
[Bmus, Qerrs] = som_bmus(...)
Description
Returns the indexes and corresponding quantization errors of the
vectors in sMap that best matched the vectors in sData.
By default only the index of the best matching unit (/vector) is
returned, but the 'which' argument can be used to get others as
well. For example it might be desirable to get also second and
thirdbest matching units as well (which = [1:3]).
A mask can be used to weight the search process. The mask is used to
weight the influence of components in the distance calculation, as
follows:
distance(x,y) = (xy)' diag(mask) (xy)
where x and y are two vectors, and diag(mask) is a diagonal matrix with
the elements of mask vector on the diagonal.
The vectors in the data set (sData) can contain unknown components
(NaNs), but the map (sMap) cannot. If there are completely empty
vectors (all NaNs), the returned BMUs and quantization errors for those
vectors are NaNs.
Required input arguments
sMap The vectors from among which the BMUs are searched
for. These must not have any unknown components (NaNs).
(struct) map struct
(matrix) codebook matrix, size munits x dim
sData The data vector(s) for which the BMUs are searched.
(struct) data struct
(matrix) data matrix, size dlen x dim
Optional input arguments
which (vector) which BMUs are returned,
by default only the best (ie. which = [1])
(string) 'all', 'best' or 'worst' meaning [1:munits],
[1] and [munits] respectively
mask (vector) mask vector to be used in BMU search,
by default sMap.mask, or ones(dim,1) in case
a matrix was given
Output arguments
Bmus (matrix) the requested BMUs for each data vector,
size dlen x length(which)
Qerrors (matrix) the corresponding quantization errors,
size equal to that of Bmus
Examples
Simplest case:
bmu = som_bmus(sM, [0.3 0.4 1.0]);
% 3dimensional data, returns BMU for vector [0.3 0.4 1]
bmu = som_bmus(sM, [0.3 0.4 1.0], [3 5]);
% as above, except returns the 3rd and 5th BMUs
bmu = som_bmus(sM, [0.3 0.4 1.0], [], [1 0 1]);
% as above, except ignores second component in searching
[bmus qerrs] = som_bmus(sM, D);
% returns BMUs and corresponding quantization errors
% for each vector in D
bmus = som_bmus(sM, sD);
% returns BMUs for each vector in sD using the mask in sM
See also
som_quality
 Measure the quantization and topographic error of a SOM.
