clusterModularity {scran}R Documentation

Compute the cluster-wise modularity

Description

Calculate the modularity of each cluster from a graph, based on a null model of random connections between nodes.

Usage

clusterModularity(graph, clusters, get.values=FALSE) 

Arguments

graph

A graph object from igraph, like that produced by buildSNNGraph.

clusters

A factor specifying the cluster identity for each node.

get.values

A logical scalar indicating whether the observed and expected edge weights should be returned.

Details

This function computes a modularity score in the same manner as that from modularity. The modularity is defined as the difference between the observed and expected number of edges between nodes in the same cluster. The expected number of edges is defined by a null model where edges are randomly distributed among nodes. The same logic applies for weighted graphs, replacing the number of edges with the summed weight of edges.

Whereas modularity returns a modularity score for the entire graph, clusterModularity provides scores for the individual clusters. This allows users to determine which clusters are enriched for intra-cluster edges based on their high modularity scores. For comparison, clusterModularity also reports the modularity scores between pairs of clusters. The sum of the diagonal elements of the output matrix should be equal to the output of modularity (after supplying weights to the latter, if necessary).

Value

If get.values=FALSE, a symmetric numeric matrix of order equal to the number of clusters is returned. Each entry corresponds to a pair of clusters and is proportional to the difference between the observed and expected edge weights between those clusters.

If get.values=TRUE, a list is returned containing two symmetric numeric matrices. The observed matrix contains the observed sum of edge weights between and within clusters, while the expected matrix contains the expected sum of edge weights under the random model.

Author(s)

Aaron Lun

See Also

buildSNNGraph, modularity

Examples

example(buildSNNGraph) # using the mocked-up graph in this example.

# Examining the modularity values directly.
out <- clusterModularity(g, clusters)
image(out)

# Alternatively, compare the ratio of observed:expected.
out <- clusterModularity(g, clusters, get.values=TRUE)
log.ratio <- log2(out$observed/out$expected + 1)
image(log.ratio)

[Package scran version 1.12.0 Index]