06-clustering.Rmd

```{r, parameters-and-defaults, include = FALSE}
module <- "scRNAseq"
section <- "clustering"
parameters_and_defaults <- list(
  dimred = structure(
    "",
    type = "character",
    choices = NA,
    several.ok = FALSE
  ),
  include_methods = structure(
    "hdbscan",
    type = "character",
    choices = c("hdbscan", "kmeans", "pam"),
    several.ok = TRUE
  ),
  tabulate = structure(
    c(),
    type = "character",
    choices = NA,
    several.ok = TRUE
  ),
  seed = structure(
    1579,
    type = "numeric",
    choices = NA,
    several.ok = FALSE
  ),
  hdbscan_min_samples = structure(
    7,
    type = "numeric",
    choices = NA,
    several.ok = FALSE
  ),
  hdbscan_min_cluster_size = structure(
    13,
    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-clustering-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-clustering-checks, include = FALSE, echo = FALSE}
if (assertive.properties::is_non_empty(local_params$assay)) {
  assertive.sets::assert_is_subset(local_params$assay, SummarizedExperiment::assayNames(object_filtered))
}

if (assertive.properties::is_non_empty(local_params$dimred)) {
  assertive.sets::assert_is_subset(local_params$dimred, SingleCellExperiment::reducedDimNames(object_filtered))
}
```

```{r scRNAseq-clustering-params, echo = FALSE, include = FALSE, R.options = params}
theme_clustering_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")

theme_clustering_silhouette <- ggplot2::theme(plot.background = ggplot2::element_blank(),
                                 panel.grid.major = ggplot2::element_blank(),
                                 panel.grid.minor = ggplot2::element_blank(),
                                 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.x = ggplot2::element_text(size = 4),
                                 axis.text.y = ggplot2::element_blank(),
                                 axis.ticks.y = ggplot2::element_blank(),
                                 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")
```

## Sample cluster analysis

**Cluster analysis** or **clustering** is the task of grouping a set of objects in such a way that objects in the same group (called a *cluster*) are more similar (in some sense) to each other than to those in other clusters. Cluster analysis itself is not one specific algorithm, but the general task to be solved. It can be achieved by various algorithms that differ significantly in their understanding of what constitutes a cluster and how to efficiently find them. Popular notions of clusters include groups with small distances between cluster members, dense areas of the data space, intervals or particular statistical distributions. The appropriate clustering algorithm and parameter settings (including parameters such as the distance function to use, a density threshold or the number of expected clusters) depend on the individual data set and intended use of the results. Typically, we explore results from multiple algorithms that perform cluster analysis and choose the clustering with the highest stability. 

Interpretation and validation of cluster stability and consistency can be judged using the *Silhouette* method: The technique provides a succinct graphical representation of how well each object lies within its cluster. The *silhouette value* is a measure of how similar an object is to its own cluster (*cohesion*) compared to other clusters (*separation*). The silhouette ranges from $-1$ to $+1$, where a high value indicates that the object is well matched to its own cluster and poorly matched to neighboring clusters. If most objects have a high value, then the clustering configuration is appropriate. If many points have a low or negative value, then the clustering configuration may have too many or too few clusters. 

```{r scRNAseq-clustering-A-hdbscan, echo=FALSE, include=FALSE, R.options=params, eval = ifelse(exists('local_params'), 'hdbscan' %in% local_params$include_methods, FALSE)}
rmd_path <- system.file(file.path('content', '06-clustering-A-hdbscan.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-clustering-A-hdbscan-include, echo = FALSE, eval = ifelse(exists('local_params'), 'hdbscan' %in% local_params$include_methods, FALSE), results="asis"}
rmd_path <- system.file(file.path('content', '06-clustering-A-hdbscan.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-clustering-terminal-cleanup, include = FALSE}
saveRDS(object = object_filtered, file = managed_objects$paths$object_filtered$path)

ReporteR.base::purge_nonpersistent()
```