SOM Toolbox Online documentation http://www.cis.hut.fi/projects/somtoolbox/

# som_bmus

### Purpose

``` Finds Best-Matching Units (BMUs) for given data vector from a given map.

```

### Syntax

```  Bmus = som_bmus(sMap, sData)
Bmus = som_bmus(..., which)
[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
third-best 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:

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
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]);
% 3-dimensional 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

```