06-clustering-A-hdbscan.Rmd

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

```{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-A-hdbscan-checks, include = FALSE}
assertive.sets::assert_is_subset(local_params$tabulate, colnames(SummarizedExperiment::colData(object)))
if(length(local_params$tabulate) > 1) {
  warning("Tabulation was requested for more than 1 factors, will use the first given.")
  local_params$tabulate <- local_params$tabulate[1]
}
```

### HDBSCAN

**H**ierarchical **D**ensity-**B**ased **S**patial **C**lustering of **A**pplications with **N**oise (HDBSCAN) [@mcinnes_hdbscan_2017], is a new density-based clustering algorithm that extends DBSCAN [@ester_dbscan_1996] by converting it into a hierarchical clustering algorithm, and then using a technique to extract a flat clustering based in the stability of clusters. This allows HDBSCAN to find clusters of varying densities (unlike DBSCAN), and be more robust to parameters. 

```{r scRNAseq-clustering-A-hdbscan-processing, include = FALSE}
object_filtered <- singlecellutils::add_clustering(object_filtered, flavor = "hdbscan", column = ".hdbscan_clustering", use_dimred = local_params$dimred, min_samples = as.integer(local_params$hdbscan_min_samples), min_cluster_size = as.integer(local_params$hdbscan_min_cluster_size), outlier = NA, seed = as.integer(local_params$seed))

n_clusters <- length(table(SummarizedExperiment::colData(object_filtered)$.hdbscan_clustering))
```

The clustering shown in Figure \@ref(fig:scRNAseq-clustering-A-hdbscan-figure)A consists of **`r ReporteR.base::verbalize_integers(n_clusters)` clusters** `r ifelse(sum(is.na(SummarizedExperiment::colData(object_filtered)$.hdbscan_clustering)) > 0, paste("with", ReporteR.base::verbalize_integers(sum(is.na(SummarizedExperiment::colData(object_filtered)$.hdbscan_clustering)))), "without")` noise `r ifelse(sum(is.na(SummarizedExperiment::colData(object_filtered)$.hdbscan_clustering)) == 1, "point", "points")` and distribute across the experimental factors `r ReporteR.base::itemize(local_params$tabulate)` in the following way:

```{r scRNAseq-clustering-A-hdbscan-table, results = 'asis', echo=FALSE}
if(assertive.properties::is_of_length(local_params$tabulate, n = 0)) {
  tbl <- stats::ftable(SummarizedExperiment::colData(object_filtered)[, ".hdbscan_clustering"])
} else {
  tbl <- stats::ftable(SummarizedExperiment::colData(object_filtered)[, ".hdbscan_clustering"], SummarizedExperiment::colData(object_filtered)[, local_params$tabulate[1]])
}
xftbl <- xtable::xtableFtable(tbl, method = "compact", caption = paste0("Sample clustering across experimental factors: ", ReporteR.base::itemize(local_params$tabulate)))
xtable::print.xtableFtable(xftbl, booktabs = TRUE, comment = FALSE, timestamp = NULL)
```

```{r scRNAseq-clustering-A-hdbscan-figure-params, include = 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("HDBSCAN clustering results. (A) Samples shown in the 2-dimensional space of *{local_params$dimred}*, color-coded by their associated cluster from **HDBSCAN**. (B) Silhouette analysis of the clustering.")
```

```{r scRNAseq-clustering-A-hdbscan-figure, echo = FALSE, message=FALSE, warning=FALSE, fig.height = fig_height$global, fig.cap = caption}
figure_hdbscan <- multipanelfigure::multi_panel_figure(height = fig_height$sub, columns = 2, rows = 1, unit = "in")

tmp_plot_a <- object_filtered %>%
    scater::plotReducedDim(use_dimred = local_params$dimred, colour_by = ".hdbscan_clustering", add_ticks = FALSE) +
    ggplot2::guides(colour = FALSE) +
    theme_clustering_scatter

tmp_plot_b <- object_filtered %>%
  singlecellutils::plotSilhouette(use_dimred = local_params$dimred, clusters = ".hdbscan_clustering") +
  ggplot2::ylab("Silhouette") + ggplot2::xlab("Cell") +
  theme_clustering_silhouette


if(n_clusters <= 10) {
  tmp_plot_a <- tmp_plot_a +
    ggplot2::scale_color_manual(values = scater:::.get_palette("tableau10medium"))
  tmp_plot_b <- tmp_plot_b +
    ggplot2::scale_color_manual(values = scater:::.get_palette("tableau10medium")) +
    ggplot2::scale_fill_manual(values = scater:::.get_palette("tableau10medium"))
} else if (n_clusters <= 20) {
  tmp_plot_a <- tmp_plot_a +
    ggplot2::scale_color_manual(values = scater:::.get_palette("tableau20"))
  tmp_plot_b <- tmp_plot_b +
    ggplot2::scale_color_manual(values = scater:::.get_palette("tableau20")) +
    ggplot2::scale_fill_manual(values = scater:::.get_palette("tableau20"))
}

figure_hdbscan <- multipanelfigure::fill_panel(figure_hdbscan, tmp_plot_a)
figure_hdbscan <- multipanelfigure::fill_panel(figure_hdbscan, tmp_plot_b)
figure_hdbscan
```