---
title: "A basic vignette on grids in SOMbrero"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output:
  html_document:
    theme: journal
    toc: yes
    toc_float:
      collapsed: no
---

<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{A basic vignette on grids in SOMbrero}
%\VignettePackage{SOMbrero}
-->

```{r loading, results='hide', echo=FALSE, warning=FALSE, message=FALSE}
library("SOMbrero")
```

## Definition and purpose of a `myGrid` class object

Objects of class `myGrid` are made to display the SOM grid. 

## Basic functions on a `myGrid` class object

In this section, we will consider only the four basic functions that can be 
applied on a `myGrid` class object:

* `initGrid,`
* `print.myGrid`
* `summary.myGrid`
* `plot.myGrid`

### The `initGrid` function

The `initGrid` function initializes a new `myGrid` object. It has 3 arguments:

* ```dimension```, which is a vector of two integers. The first one is the x
dimension (number of neurons/units on the x axis) and the second one is the y 
dimension. The __default dimensions__ are __x=5__ and  __y=5__,

* ```topo```, which is the chosen topology. The value of this argument must be
one of  ```square``` or `hexagonal`. The__default value__ is __square__.

* ```dist.type```, which is the distance type to compute the distance between
two neurons of the grid. The __default value__ is __euclidean__ and the 
coordinates of the neurons on the grid are chosen so as the minimum Euclidean
distance between two neurons is exactly 1. `hexagonal` topoology is only 
compatible with the Euclidean distance.

The following **R** code initializes a new `myGrid` object of square topology, x 
dimension 5 and y dimension 6, and distance type ```maximum```.

```{r initGird}
first_grid <- initGrid(dimension = c(5,6), topo = "square", dist.type = "maximum")
```

### The `print.myGrid` function

The `myGrid` object `print` function prints the main features of the chosen 
object in the console. The only argument is the object to be printed.

Considering the previously initialized grid, the print command is:

```{r plotFirstGrid}
print(first_grid)
```

### The `summary.myGrid` function

The `myGrid` object `summary` function is quite simple. It only prints the class
of the object and then calls the print function previously described. The only 
argument is the object to be summarized.

```{r summaryMyGrid}
summary(first_grid)
```

### The `plot.myGrid` function

The `myGrid` object `plot` function draws the squared area corresponding to the 
object, in a new graphical window. It has 3 parameters:

* the object to be plotted,

* `show.names`, boolean, indicating if the names of the neurons should be displayed on the graph (default to `TRUE`)

* `names`, a vector, giving the names of the neurons if `show.names = TRUE`, default to the number of the neuron.


```{r plotRainbowGrid}
plot(first_grid)
plot(first_grid) + ggplot2::scale_fill_manual(values = rep("white", 30))
my_palette <- colorRampPalette(c("white", "pink", "purple"))(30)
plot(first_grid, show.names = FALSE) + 
  ggplot2::scale_fill_manual(values = my_palette)
```

Hexagonal grids can be displayed similarly:
```{r plotHexa}
second_grid <- initGrid(dimension = c(4, 5), topo = "hexagonal")
plot(second_grid, names = paste0("N", 1:20)) + 
  ggplot2::ggtitle("Hexagonal SOM grid")
```


### Session information

This vignette has been computed with the following environment:
```{r sessionInfo}
sessionInfo()
```