Define a clustering method for clusterGeneSets()

Wraps a community-detection function into the object clusterGeneSets() expects. The function receives the shared-nearest- neighbour (SNN) graph built by clusterGeneSets() and a single resolution, and returns one cluster id per gene set.

Usage

clusterMethod(
  fn,
  name,
  description = NA_character_,
  packages = character(0),
  usesResolution = TRUE
)

Arguments

fn

A function with signature function(snn, resolution, verbose, ...) returning one cluster id per column of snn (vector, factor, or single-column data.frame/matrix). See details.

name

Short name for the method, used in messages and in the algorithm argument of clusterGeneSets().

description

One-line description of what the method does.

packages

Character vector of packages the method needs. They are checked with requireNamespace() before the method runs, so a missing dependency produces a clear error instead of a cryptic one.

usesResolution

Whether the method's output actually depends on resolution. Set to FALSE for algorithms that determine the number of clusters themselves (e.g. affinity propagation); clusterGeneSets() then runs the method once rather than repeating identical work for every requested resolution. Defaults to TRUE.

Value

An object of class gsClusterMethod.

Details

snn is a sparse symmetric matrix (a Seurat Graph) whose rows/columns are gene sets and whose values are SNN similarities in [0, 1]. Returned ids may be 0- or 1-based; clusterGeneSets() renumbers them to start at 0 and orders the factor levels numerically. If the returned ids are named, they are reordered to match colnames(snn).

See also

registerClusterMethod(), listClusterMethods(), clusterGeneSets()

Examples

# A backend built on igraph's fast-greedy modularity optimization
fastGreedy <- clusterMethod(
  fn = function(snn, resolution, verbose = FALSE, ...) {
    g <- snnToIgraph(snn)
    igraph::membership(
      igraph::cluster_fast_greedy(g, weights = igraph::E(g)$weight)
    )
  },
  name = "fast_greedy",
  description = "igraph fast-greedy modularity (ignores resolution)",
  packages = "igraph",
  usesResolution = FALSE
)
fastGreedy
#> <gsClusterMethod> fast_greedy
#>   igraph fast-greedy modularity (ignores resolution)
#>   requires: igraph
#>   picks the number of clusters itself (resolution is ignored)

# Try it on the SNN graph of the example data
ids <- fastGreedy$fn(exampleGsList@cluster@graphs$GSEA_snn, resolution = 1)
table(ids)
#> ids
#>  1  2  3  4 
#> 81 19 27 70 

# Use it in the workflow
geneSetsList <- initializeList(exampleGeneSets, exampleEnrichment,
                               verbose = FALSE)
gsListObject <- clusterGeneSets(geneSetsList, algorithm = fastGreedy,
                                verbose = FALSE)