Multi Resolution Cluster Optimization

Stable Cluster Selection Across Resolutions. Be less dependent on your clustering algorithms resolution parameter!

Visualize your clustering of multiple independently generated resolutions (or sensitivities) in a stacked tree like graph. Check if clusters remain in similar order across resolution change using the same clustering algorithm. Color clusters as pie-charts based on their sample proportions, if sample level metadata is included in the input, to see if cluster splitting is correlating with a split of metadata groups. If samples remain in same cluster grouping across many resolution ‘steps’, we assume a cluster to be stable. An automated cluster selection algorithm is implemented to select the ‘most stable’ clusters relative within the given data. Samples that frequently change between clusters upon change in resolution depict an uncertain state. Therefore, a ‘debris’ cluster is created if samples are not part of any of the selected stable clusters.
The software was tested on single cell RNA-Sequencing data, but can be applied to any type of data (on your own risk). The general concept remains the same: A clustering algorithm can cluster your data similar multiple times, the similarity between multiple reiterations can be used to infer the most stable configuration for your experimental scope.

You can install the development version of MRCO from GitHub with:

# install.packages("devtools")
devtools::install_github("peterwolf4/MRCO")

MRCO comes with some example_data for a quick introduction. The required input is a single dataframe or tibble with: . In single cell RNA-Seq data for example expected input data is cells (rows) and increasing clustering resolution (columns). Metadata variables can be continuous (automatically binned) or discrete.

# Load MRCO
library(MRCO)
# Load example data
data("example_data")
# Check example data
head(example_data)
#>   quality batch  sample expr_A expr_B 0.1 0.2 0.3 0.4
#> 1    high     1  cell_1    951      7   0   1   0   3
#> 2     low     1 cell_10    900      9   0   0   2   3
#> 3  medium     2  cell_2    210      7   0   1   0   0
#> 4  medium     3  cell_3    503      8   0   1   0   0
#> 5     low     1  cell_4    631      6   0   1   0   0
#> 6    high     3  cell_5    700     10   0   0   1   1
# Required: the clustering results saved in columns 6 to 9
# Optional: the sample level metadata saved in columns 1 to 5
# When merging clustering results and metadata manually verify that rows match!

MRCO can run with just the clustering results. In the example data the lowest resolution clustering has one cluster and the highest resolution 4. This example could be the result of 4 k-mers clustering iterations with k = 1,2,3,4. Note that example_data is arbitrary sampled for example purposes only. MRCO needs to know which columns contain the clustering results. clustering_columns uses tidy-select to enable users a well established column selection method. By default, passing a single character is handled as prefix. plot can be used to suppress plotting and only receive stable clustering results.

MRCO(example_data, clustering_columns = starts_with("0."))

# Is the same as
MRCO(example_data, clustering_columns = "0.", plot = FALSE)

Usually MRCO is used to plot metadata variables of interest as piecharts. metadata_column_name can be a character or unquoted name of the column of interest. highlight_selection can disable highlighting of stable nodes, more on selection in topic Stable Cluster Selection. no_labels can be used to remove cluster ids from nodes.

# We can plot metadata variables as piecharts and see how samples cluster.
MRCO(example_data,
  metadata_column_name = "quality",
  clustering_columns = "0."
)

# same as writing quality with the quotes
MRCO(example_data,
  metadata_column_name = quality,
  clustering_columns = "0.", 
  no_labels = TRUE,
  highlight_selection = FALSE
)

Example data is sampled in a way that it resembles frequent real data scenarios. Given examples are of course no final conclusions. They are to demonstrate how the plot can be exploited to quickly draw high level conclusions about your data. Generally, users will want to find some experimental variable from metadata to be linked to a specific sub-cluster in the data.

# MRCO can preview columns of input data when using a pipe to feed the metadata
# Numerical metadata will be binned, set number of bins with nbin
# Example A: graph hints that cluster 3 at resolution step 4 (4_3);
# is split based on expression values of A. (All samples in 4_3 have high values of A)
example_data %>% MRCO("expr_A", "0.", nbins = 5)

# Example B: graph hints that lefthand clusters have rather high-;
# while lefthand have rather low- values of expr_B.
example_data %>% MRCO("expr_B", "0.")

Nodes of the MRCO graph have a unique id that is created by pasting resolution step and clusters id from that resolution step. A node at first resolution step that has the cluster id 0 is therefore refered to as 1_0. Selecting clusters of interest for further downstream analysis was made as dynamic as possible for the user. In the given example, imagine we want to retain all samples of 4_3 as one cluster to investigate which samples have such high expression values of A, but also need all other samples in second step clusters before the separation of B. MRCO enables you to pick any of the clusters manually at wish. Use merge_downwards = TRUE (default) to preserve clusters from lower resolutions. MRCO returns a list with:

# MRCO highlights selected clusters visually.
MRCO_clustering <- MRCO(example_data,
  clustering_columns = "0.",
  nodes_selection = c("4_3", "2_0", "2_1"),
  merge_downwards = FALSE
)

# Each node has a unique cluster number composed of 'resolution'_'cluster'.
# Output is returned in order of input.
head(MRCO_clustering$MRCO_clustering)
#>   cell  id
#> 1    1 2_1
#> 2    2 3_2
#> 3    3 2_1
#> 4    4 2_1
#> 5    5 2_1
#> 6    6 3_1
table(MRCO_clustering$MRCO_clustering$id)
#> 
#> 2_1 3_1 3_2 
#>   4   3   3

By default MRCO runs a stable cluster suggestion. The idea of stable clusters is not represented well in this minimal example. If a cluster does not change its composition across most of the tested resolution steps it is selected as stable. This way the selected clusters should represent the data groups best. By choosing stable clusters independently, rather than from a single resolution, MRCO minimizes the distance its final clustering has to each of the tested input resolutions. Documentation on the details of stable cluster selection is planned. suggest_cut can be set to FALSE to speed up runtime when only plotting.

# Stable clusters are relative to the data and should still be checked
# Note that this example data is too small for the algorithm to be truthfully useful.
MRCO_clustering <- MRCO(example_data, clustering_columns = "0.", suggest_cut = TRUE)

# Check which nodes are stable
MRCO_clustering$selected_nodes
#> [1] "1_0" "2_1" "3_1" "3_2"

Package is currently in development. Planned for release on bioconductor. Feel free to reach out regarding bugs and ideas.