05-dimension-reduction-C-som.Rmd

```{r parameters-and-defaults, include = FALSE}
module <- "scRNAseq"
section <- "dimension_reduction"
```

```{r parameter-merge, include = FALSE}
local_params <- module %>%
  options() %>%
  magrittr::extract2(module) %>%
  magrittr::extract2(section) %>%
  ReporteR.base::validate_params(parameters_and_defaults)
```

```{r scRNAseq-dimension-reduction-C-som-checks, include = FALSE}
assertive.sets::assert_is_subset(local_params$features, colnames(SummarizedExperiment::colData(object_filtered)))
```

### Self-organizing feature maps

A **s**elf-**o**rganizing feature **m**ap (SOM) [@kohonen_som_2001] is a type of artificial neuronal network that is trained using *unsupervised learning* to produce a low-dimensional representation of its input. SOMs aim to reproduce the high-dimensional datas topology, i.e. if two objects are similar, their position of a two-dimensional plane should be similar as well. Instead of mapping to a continous space, SOMs use regular grids of *units* onto which objects are mapped [@wehrens_som_2007]. Objects in the same or neighbouring units are generally similar. In terms of data obtained from single cells, *units* correspond to so-called meta-features, i.e. clusters of similar and hence potentially co-regulated single features. Although the whole set of single feature profiles remains virtually *hidden* in a corresponding meta-feature [@wirth_som_2012], this reduction efficiently mitigates the effect of *feature dropouts* by aggregating signal from many similar features. The reduction of dimension is attained by the re-weighting of primary information and does not entail a loss of primary information in contrast to simple filtering approaches [@wirth_som_2012]. 

```{r scRNAseq-dimension-reduction-C-som-processing, echo=FALSE, include=FALSE}
features <- NULL
if (local_params$subset_het) {
  features <- SummarizedExperiment::rowData(object_filtered)$is_het
}

object_filtered <- singlecellutils::reduce_dimension(object_filtered, flavor = "som_tsne", som.dots = list(exprs_values = local_params$assay, num_epochs = local_params$maxiter, features = features), tsne.dots = list(dims = local_params$dims, max_iter = local_params$maxiter))
```

```{r scRNAseq-dimension-reduction-C-som-figure-params, include = FALSE, echo = FALSE}
fig_height <- ReporteR.base::estimate_figure_height(
  height_in_panels = 1,
  panel_height_in_in = params$formatting_defaults$figures$panel_height_in,
  axis_space_in_in = params$formatting_defaults$figures$axis_space_in,
  mpf_row_space = as.numeric(grid::convertUnit(grid::unit(5, 'mm'), 'in')),
  max_height_in_in = params$formatting_defaults$figures$max_height_in)

caption <- glue::glue("Dimensionality reduction using **SOMs** [@kohonen_som_2001;@wehrens_som_2007], followed by a further reduction into two dimensions using **t-SNE** [@maaten_tsne_2008] for visualization.")
```

```{r scRNAseq-dimension-reduction-C-som-figure, echo = FALSE, message=FALSE, warning=FALSE, fig.height = fig_height$global, fig.cap = caption}
figure_dimred_som_tsne <- multipanelfigure::multi_panel_figure(height = fig_height$sub, columns = min(3, length(local_params$features)), rows = 1, unit = "in")

for(i in 1:min(3, length(local_params$features))) {
  tmp_plot <- object_filtered %>%
    scater::plotReducedDim(use_dimred = "som_tsne", colour_by = local_params$features[i], add_ticks = FALSE) +
    ggplot2::guides(colour = FALSE) +
    theme_dimred_scatter
  figure_dimred_som_tsne <- multipanelfigure::fill_panel(figure_dimred_som_tsne, tmp_plot)
}

figure_dimred_som_tsne
```