FindConnectedComponents

Inspects an SNN (or any named) graph from a Seurat object, or a raw adjacency/transition matrix, and labels each cell by its connected component. When run on a Seurat object, the result is written to a new column in seurat_obj@meta.data. This is a useful diagnostic before running PerturbationTransitions, because cells that belong to different connected components cannot exchange transition probability mass through the graph. It is also used internally by PredictAttractors to check the post-masking transition matrix for disconnected components, which can otherwise make the dominant eigenvalue non-unique and cause the stationary-distribution eigensolver to fail to converge.

Usage

FindConnectedComponents(
  seurat_obj = NULL,
  graph = NULL,
  matrix = NULL,
  meta_data_name = "connected_component",
  verbose = TRUE
)

Arguments

seurat_obj

A Seurat object containing at least one graph in seurat_obj@graphs. Ignored if matrix is provided.

graph

Character. Name of the graph in Graphs(seurat_obj) to analyse. If NULL (default), the function auto-detects a graph whose name ends in "_snn". When multiple SNN graphs exist the first one is used and a message is emitted. If no SNN graph is present the first available graph is used instead (with a warning). Ignored if matrix is provided.

matrix

A square adjacency or transition matrix (sparse or dense) to analyse directly, bypassing the Seurat object entirely. Row/column names, if present, are used as cell identifiers. When supplied, the function returns a plain list of component info (see Value) instead of a Seurat object, and seurat_obj/graph/meta_data_name are ignored.

meta_data_name

Character. Name of the new column written to seurat_obj@meta.data. Default "connected_component". Ignored if matrix is provided.

verbose

Logical. Print a summary of the component structure. Default TRUE.

Value

If matrix is NULL (default), the Seurat object with a new integer-factor column in seurat_obj@meta.data. Levels are ordered by component size (largest component = level 1) so the dominant component always has the lowest label. If matrix is supplied instead, a list with elements membership (a named integer vector, one entry per row/column of matrix, ranked the same way), n_components, and component_sizes (sizes in decreasing order).

Details

The graph/matrix is treated as undirected for component finding — any non-zero edge weight in either direction is interpreted as a connection, and the diagonal is ignored. The underlying computation uses igraph::components(), which implements a fast depth-first-search.