## Function to overlay additional data onto the trained map for viewing the distribution of that additional data

### Description

`sMapOverlay` is supposed to overlay additional data onto the trained map for viewing the distribution of that additional data. It returns an object of class "sMap". It is realised by first estimating the hit histogram weighted by the neighborhood kernel, and then calculating the distribution of the additional data over the map (similarly weighted by the neighborhood kernel). The final overlaid distribution of additional data is normalised by the hit histogram.

### Usage

`sMapOverlay(sMap, data, additional)`

### Arguments

sMap
an object of class "sMap"
data
a data frame or matrix of input data
a numeric vector or numeric matrix used to overlay onto the trained map. It must have the length (if being vector) or row number (if matrix) being equal to the number of rows in input data

### Value

an object of class "sMap", a list with following components:

• `nHex`: the total number of hexagons/rectanges in the grid
• `xdim`: x-dimension of the grid
• `ydim`: y-dimension of the grid
• `r`: the hypothetical radius of the grid
• `lattice`: the grid lattice
• `shape`: the grid shape
• `coord`: a matrix of nHex x 2, with rows corresponding to the coordinates of all hexagons/rectangles in the 2D map grid
• `init`: an initialisation method
• `neighKernel`: the training neighborhood kernel
• `codebook`: a codebook matrix of nHex x ncol(additional), with rows corresponding to overlaid vectors
• `hits`: a vector of nHex, each element meaning that a hexagon/rectangle contains the number of input data vectors being hit wherein
• `mqe`: the mean quantization error for the "best" BMH
• `call`: the call that produced this result

### Note

Weighting by neighbor kernel is to avoid rigid overlaying by only focusing on the best-matching map nodes as there may exist several closest best-matching nodes for an input data vector.

### Examples

```# 1) generate an iid normal random matrix of 100x10
data <- matrix( rnorm(100*10,mean=0,sd=1), nrow=100, ncol=10)
colnames(data) <- paste(rep('S',10), seq(1:10), sep="")

# 2) get trained using by default setup
sMap <- sPipeline(data=data)

Start at 2018-01-18 16:56:08

First, define topology of a map grid (2018-01-18 16:56:08)...
Second, initialise the codebook matrix (61 X 10) using 'linear' initialisation, given a topology and input data (2018-01-18 16:56:08)...
Third, get training at the rough stage (2018-01-18 16:56:08)...
1 out of 7 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
2 out of 7 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
3 out of 7 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
4 out of 7 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
5 out of 7 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
6 out of 7 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
7 out of 7 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
Fourth, get training at the finetune stage (2018-01-18 16:56:08)...
1 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
2 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
3 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
4 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
5 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
6 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
7 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
8 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
9 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
10 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
11 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
12 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
13 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
14 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
15 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
16 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
17 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
18 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
19 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
20 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
21 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
22 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
23 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
24 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
25 out of 25 (2018-01-18 16:56:08)
updated (2018-01-18 16:56:08)
Next, identify the best-matching hexagon/rectangle for the input data (2018-01-18 16:56:08)...
Finally, append the response data (hits and mqe) into the sMap object (2018-01-18 16:56:08)...

Below are the summaries of the training results:
dimension of input data: 100x10
xy-dimension of map grid: xdim=9, ydim=9, r=5
grid lattice: hexa
grid shape: suprahex
dimension of grid coord: 61x2
initialisation method: linear
dimension of codebook matrix: 61x10
mean quantization error: 4.92761300512866

Below are the details of trainology:
training algorithm: batch
alpha type: invert
training neighborhood kernel: gaussian
trainlength (x input data length): 7 at rough stage; 25 at finetune stage
radius (at rough stage): from 3 to 1
radius (at finetune stage): from 1 to 1

End at 2018-01-18 16:56:08
Runtime in total is: 0 secs

# 3) overlay additional data onto the trained map
# here using the first two columns of the input "data" as "additional"
# codebook in "sOverlay" is the same as the first two columns of codebook in "sMap"

# 4) viewing the distribution of that additional data
visHexMulComp(sOverlay)
```

## Source code

`sMapOverlay.r`

## Source man

`sMapOverlay.Rd` `sMapOverlay.pdf`

`sPipeline`, `sBMH`, `sHexDist`, `visHexMulComp`