SNN Graph Based Community Detection — runCluster • rliger

After aligning cell factor loadings, users can additionally run the Leiden or Louvain algorithm for community detection, which is widely used in single-cell analysis and excels at merging small clusters into broad cell classes.

While using aligned factor loadings (result from alignFactors) is recommended, this function looks for unaligned factor loadings (raw result from runIntegration) when the former is not available.

Usage

runCluster(
  object,
  resolution = 1,
  nNeighbors = 20,
  prune = 1/15,
  eps = 0.1,
  nRandomStarts = 10,
  nIterations = 5,
  method = c("leiden", "louvain"),
  useRaw = NULL,
  useDims = NULL,
  groupSingletons = TRUE,
  saveSNN = FALSE,
  clusterName = paste0(method, "_cluster"),
  seed = 1,
  verbose = getOption("ligerVerbose", TRUE)
)

Arguments

object: A liger object. Should have valid factorization result available.
resolution: Numeric, value of the resolution parameter, a larger value results in a larger number of communities with smaller sizes. Default 1.0.
nNeighbors: Integer, the maximum number of nearest neighbors to compute. Default 20.
prune: Numeric. Sets the cutoff for acceptable Jaccard index when computing the neighborhood overlap for the SNN construction. Any edges with values less than or equal to this will be set to 0 and removed from the SNN graph. Essentially sets the stringency of pruning. 0 for no pruning, while 1 prunes everything. Default 1/15.
eps: Numeric, the error bound of the nearest neighbor search. Default 0.1.
nRandomStarts: Integer number of random starts. Will pick the membership with highest quality to return. Default 10.
nIterations: Integer, maximal number of iterations per random start. Default 5.
method: Community detection algorithm to use. Choose from "leiden" or "louvain". Default "leiden".
useRaw: Whether to use un-aligned cell factor loadings ($H$ matrices). Default NULL search for quantile-normalized loadings first and un-aligned loadings then.
useDims: Indices of factors to use for clustering. Default NULL uses all available factors.
groupSingletons: Whether to group single cells that make up their own cluster in with the cluster they are most connected to. Default TRUE, if FALSE, assign all singletons to a "singleton" group.
saveSNN: Logical, whether to store the SNN graph, as a dgCMatrix object, in the object. Default FALSE.
clusterName: Name of the variable that will store the clustering result in cellMeta slot of object. Default "leiden_cluster" and "louvain_cluster".
seed: Seed of the random number generator. Default 1.
verbose: Logical. Whether to show information of the progress. Default getOption("ligerVerbose") or TRUE if users have not set.

Value

object with cluster assignment updated in clusterName

variable in cellMeta slot. Can be fetched with object[[clusterName]]. If saveSNN = TRUE, the SNN graph will be stored at object@uns$snn.

Examples

pbmcPlot <- runCluster(pbmcPlot)
#> ℹ leiden clustering on aligned cell factor loadings
#> ✔ leiden clustering on aligned cell factor loadings ... Found 8 clusters.
#> 
head(pbmcPlot$leiden_cluster)
#> ctrl_AAACATACCTCGCT.1 ctrl_AAACGGCTCTTCGC.1 ctrl_AACACTCTAAGTAG.1 
#>                     0                     0                     0 
#> ctrl_AACCGCCTCAGGAG.1 ctrl_AACGTTCTTCCGTC.1 ctrl_AAGAACGAAACGAA.1 
#>                     3                     1                     0 
#> Levels: 0 1 2 3 4 5 6 7
pbmcPlot <- runCluster(pbmcPlot, method = "louvain")
#> ℹ louvain clustering on aligned cell factor loadings
#> Modularity Optimizer version 1.3.0 by Ludo Waltman and Nees Jan van Eck
#> 
#> Reading input file...
#> 
#> Number of nodes: 600
#> Number of edges: 17528
#> 
#> Running Louvain algorithm...
#> Maximum modularity in 10 random starts: 0.7580
#> Number of communities: 8
#> Elapsed time: 0 seconds
#> ✔ louvain clustering on aligned cell factor loadings ... Found 8 clusters.
#> 
head(pbmcPlot$louvain_cluster)
#> ctrl_AAACATACCTCGCT.1 ctrl_AAACGGCTCTTCGC.1 ctrl_AACACTCTAAGTAG.1 
#>                     0                     0                     0 
#> ctrl_AACCGCCTCAGGAG.1 ctrl_AACGTTCTTCCGTC.1 ctrl_AAGAACGAAACGAA.1 
#>                     3                     1                     0 
#> Levels: 0 1 2 3 4 5 6 7