05-dimension-reduction.Rmd

```{r, parameters-and-defaults, include = FALSE}
module <- "scRNAseq"
section <- "dimension_reduction"
parameters_and_defaults <- list(
  assay = structure(
    "logcounts",
    type = "character",
    choices = NA,
    several.ok = FALSE
  ),
  subset_het = structure(
    FALSE,
    type = "logical",
    choices = NA,
    several.ok = FALSE
  ),
  include_methods = structure(
    c(),
    type = "character",
    choices = c("pca", "tsne_dist", "som_tsne", "isomds", "rsvd"),
    several.ok = TRUE
  ),
  dims = structure(
    5,
    type = "numeric",
    choices = NA,
    several.ok = FALSE
  ),
  features = structure(
    c("percent_mapped"),
    type = "character",
    choices = NA,
    several.ok = TRUE
  ),
  maxiter = structure(
    3000.,
    type= "numeric",
    choices = NA,
    several.ok = FALSE
  ),
  tsne_perplexity = structure(
    -1,
    type = "numeric",
    choices = NA,
    several.ok = FALSE
  ),
  tsne_dist = structure(
    FALSE,
    type = "logical",
    choices = NA,
    several.ok = FALSE
  ),
  wgcna_cor_method = structure(
    "spearman",
    type = "character",
    choices = c("pearson", "spearman", "kendall"),
    several.ok = FALSE
  ),
  wgcna_cor_denominator = structure(
    1,
    type = "numeric",
    choices = NA,
    several.ok = FALSE
  )
)
```

```{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-load, include=FALSE, eval = !exists("object_filtered")}
assertive.files::is_existing_file(managed_objects$paths$object_filtered$path)

object_filtered <- readRDS(managed_objects$paths$object_filtered$path) %>%
  ReporteR.base::flag_persistent()
```

```{r scRNAseq-dimension-reduction-checks, include = FALSE, echo = FALSE}
assertive.sets::assert_is_subset(local_params$assay, SummarizedExperiment::assayNames(object_filtered))

if (local_params$subset_het) {
  assertive.sets::assert_is_subset("is_het", colnames(SummarizedExperiment::rowData(object_filtered)))
}
```

```{r scRNAseq-dimension-reduction-params, echo = FALSE, include = FALSE, R.options = params}
theme_dimred_scatter <- ggplot2::theme(plot.background = ggplot2::element_blank(),
                                 panel.grid.major = ggplot2::element_line(size=.2, colour = "grey"),
                                 panel.grid.minor = ggplot2::element_line(size=.1, colour = "grey"),
                                 panel.border = ggplot2::element_blank(),
                                 panel.background = ggplot2::element_blank(),
                                 axis.line.x = ggplot2::element_line(size=.3),
                                 axis.line.y = ggplot2::element_line(size=.3),
                                 axis.text = ggplot2::element_text(size = 4),
                                 axis.title.y = ggplot2::element_text(size = 5, margin = ggplot2::margin(0, -2, 0, 0)),
                                 axis.title.x = ggplot2::element_text(size = 5, margin = ggplot2::margin(-2, 0, 0, 0)),
                                 legend.text = ggplot2::element_text(size = 4),
                                 legend.title = ggplot2::element_text(size = 5),
                                 plot.title = ggplot2::element_text(face="bold", color="black", size=5),
                                 legend.key.size =  grid::unit(2, "mm"),
                                 legend.margin = ggplot2::margin(b = 2),#grid::unit(-50, "mm"),
                                 legend.position = c(0,1),
                                 legend.justification = c(0,0),
                                 legend.background = ggplot2::element_rect(fill = "white"),
                                 legend.direction = "horizontal")
```

## Dimensionality reduction

The transformation of high-dimensional data into a lower dimensional space while retaining a meaningful data representation is called *dimensionality reduction*. In an ideal case, a *meaningful* representation corresponds to the *intrinsic* representation, i.e. the transformation that gets along with a minimum number of dimensions to account for observed properties in the data (e.g. local and global structures). Dimensionality reduction enables the use of machine learning techniques that are not effective in a high dimensional space, often caused by the *curse of dimensionality*[^2].

[^2]: The *curse of dimensionality* [@bellman_dimensionality_2016], or *empty space phenomenon* [@anderson_space_1984], describes the phenomenon that an increase in dimensionality exponentially increases the possbile variable space so that the available data becomes sparse. With increased dimensionality, the accurate estimation of a function of several variables requires a sample size that is exponentially larger. 

```{r scRNAseq-dimension-reduction-A-pca, echo=FALSE, include=FALSE, R.options=params, eval = ifelse(exists('local_params'), 'pca' %in% local_params$include_methods, FALSE)}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-A-pca.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path = ReporteR.base::make_md_path(rmd_path)
knitr::knit_child(rmd_path, output = md_path)
```

```{r scRNAseq-dimension-reduction-A-pca-include, echo = FALSE, eval = ifelse(exists('local_params'), 'pca' %in% local_params$include_methods, FALSE), results="asis"}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-A-pca.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path <- ReporteR.base::make_md_path(rmd_path)

assertive.files::assert_all_are_readable_files(md_path)
md_path %>%
  readLines() %>%
  cat(sep = '\n')
```

```{r scRNAseq-dimension-reduction-B-tse-dist, echo=FALSE, include=FALSE, R.options=params, eval = ifelse(exists('local_params'), 'tsne_dist' %in% local_params$include_methods, FALSE)}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-B-tsne-dist.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path = ReporteR.base::make_md_path(rmd_path)
knitr::knit_child(rmd_path, output = md_path)
```

```{r scRNAseq-dimension-reduction-B-tsne-dist-include, echo = FALSE, eval = ifelse(exists('local_params'), 'tsne_dist' %in% local_params$include_methods, FALSE), results="asis"}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-B-tsne-dist.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path <- ReporteR.base::make_md_path(rmd_path)

assertive.files::assert_all_are_readable_files(md_path)
md_path %>%
  readLines() %>%
  cat(sep = '\n')
```

```{r scRNAseq-dimension-reduction-C-som, echo=FALSE, include=FALSE, R.options=params, eval = ifelse(exists('local_params'), 'som_tsne' %in% local_params$include_methods, FALSE)}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-C-som.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path = ReporteR.base::make_md_path(rmd_path)
knitr::knit_child(rmd_path, output = md_path)
```

```{r scRNAseq-dimension-reduction-C-som-include, echo = FALSE, eval = ifelse(exists('local_params'), 'som_tsne' %in% local_params$include_methods, FALSE), results="asis"}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-C-som.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path <- ReporteR.base::make_md_path(rmd_path)

assertive.files::assert_all_are_readable_files(md_path)
md_path %>%
  readLines() %>%
  cat(sep = '\n')
```

```{r scRNAseq-dimension-reduction-D-isomds, echo=FALSE, include=FALSE, R.options=params, eval = ifelse(exists('local_params'), 'isomds' %in% local_params$include_methods, FALSE)}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-D-isomds.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path = ReporteR.base::make_md_path(rmd_path)
knitr::knit_child(rmd_path, output = md_path)
```

```{r scRNAseq-dimension-reduction-D-isomds-include, echo = FALSE, eval = ifelse(exists('local_params'), 'isomds' %in% local_params$include_methods, FALSE), results="asis"}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-D-isomds.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path <- ReporteR.base::make_md_path(rmd_path)

assertive.files::assert_all_are_readable_files(md_path)
md_path %>%
  readLines() %>%
  cat(sep = '\n')
```

```{r scRNAseq-dimension-reduction-E-rsvd, echo=FALSE, include=FALSE, R.options=params, eval = ifelse(exists('local_params'), 'rsvd' %in% local_params$include_methods, FALSE)}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-E-rsvd.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path = ReporteR.base::make_md_path(rmd_path)
knitr::knit_child(rmd_path, output = md_path)
```

```{r scRNAseq-dimension-reduction-E-rsvd-include, echo = FALSE, eval = ifelse(exists('local_params'), 'rsvd' %in% local_params$include_methods, FALSE), results="asis"}
rmd_path <- system.file(file.path('content', '05-dimension-reduction-E-rsvd.Rmd'), package = 'ReporteR.scRNAseq', mustWork = TRUE)
md_path <- ReporteR.base::make_md_path(rmd_path)

assertive.files::assert_all_are_readable_files(md_path)
md_path %>%
  readLines() %>%
  cat(sep = '\n')
```

```{r scRNAseq-dimension-reduction-terminal-cleanup, include = FALSE}
saveRDS(object = object_filtered, file = managed_objects$paths$object_filtered$path)

ReporteR.base::purge_nonpersistent()
```