Skip to contents

Run the full CellChat analysis pipeline per group

RunCellChat.Rd

For each level of group.col in the Seurat object, subsets the data, builds a CellChat object, runs the standard pipeline (overexpressed genes → interactions → communication probability → pathway probability → aggregate network → communication patterns), and writes visualizations + the CellChat RDS file to output_dir.

Usage

RunCellChat(
  seurat_object = NULL,
  cell.by,
  group.by,
  groups = NULL,
  identity_column = NULL,
  group.col = NULL,
  species = "human",
  colors = NULL,
  output_dir,
  robj_dir = NULL,
  min.cells = 0L,
  thresh.p = 0.05,
  run.patterns = TRUE,
  pattern_k_range = 3:10,
  vertex.receiver = seq(1, 4),
  save.rds = TRUE,
  resume = FALSE,
  redo_plots = FALSE,
  assay_type = NULL,
  caffeinate = FALSE
)

Arguments

seurat_object

A Seurat object. Ignored when redo_plots = TRUE.

cell.by

Character. Metadata column for cell identities (y-axis of chord/circle diagrams, e.g., "subAssignment"). identity_column is accepted as a deprecated alias.

group.by

Character. Metadata column whose levels each get their own CellChat run (e.g., "Group"). group.col is accepted as a deprecated alias.

groups

Character vector or NULL. Specific levels of group.by to process. NULL uses all levels.

species

Character. Determines which CellChatDB ligand-receptor database and PPI network are loaded. One of:

  • "human" (default) - uses CellChatDB.human and PPI.human

  • "mouse" - uses CellChatDB.mouse and PPI.mouse

colors

Named character vector mapping cell.by levels to colors. NULL uses CellChat's default palette. Tip: use the same color vector as your Seurat DimPlots so all figures are consistent.

output_dir

Character. Root directory for all output. Per-group sub-folders are created automatically.

robj_dir

Character or NULL. Directory for RDS checkpoint files. Defaults to file.path(output_dir, "CellChatObjects").

min.cells

Integer. Minimum number of cells a cell type must have in a given condition for its interactions to be retained by CellChat::filterCommunication(). Increase to reduce noise from rare populations. Default 0 (keep all).

thresh.p

Numeric. P-value threshold used by CellChat::identifyOverExpressedGenes() and CellChat::computeCommunProbPathway(). Lowering this (e.g. 0.01) makes the analysis more conservative; raising it (e.g. 0.1) recovers more interactions. Default 0.05.

Note: this is the pipeline significance threshold. The thresh parameter in CompareCellChat() independently controls which L-R interactions are shown in comparison plots.

run.patterns

Logical. Run communication pattern analysis for outgoing and incoming signals across k values in pattern_k_range? Adds substantially to run time. Default TRUE.

pattern_k_range

Integer vector. Range of latent pattern numbers (k) tested by CellChat::identifyCommunicationPatterns(). Each k×direction combination produces one PDF. Default 3:10. Reduce (e.g. 3:6) if run time is a concern.

vertex.receiver

Integer vector. Indices of receiver cell types for the hierarchy layout in per-pathway plots. Default seq(1, 4) (first four cell types). Adjust to match your biological receiver populations.

save.rds

Logical. Save each CellChat object as an RDS file? Default TRUE.

resume

Logical. Skip groups that have already completed and recover groups interrupted mid-run. Default FALSE. Requires save.rds = TRUE and output_dir to be set. Two checkpoints are used:

  • Pipeline checkpoint ({grp}CellChat_ckpt.rds): written immediately after netAnalysis_computeCentrality (before any plotting). If a run is interrupted during plotting or pattern analysis, this file lets the next run skip the expensive pipeline steps and jump straight to visualizations.

  • Final RDS ({grp}CellChat.rds): written at the end of a successful group run and replaces the checkpoint. If this file exists, that group is considered fully complete and skipped.

redo_plots

Logical. Re-generate all per-group visualization PDFs from existing RDS files without re-running the communication probability pipeline. Default FALSE. When TRUE:

  • For each group, {grp}CellChat.rds is loaded from robj_dir.

  • All plotting code (circle, pathway, bubble, scatter, patterns) is re-executed using the loaded object.

  • The pipeline (computeCommunProb, aggregateNet, etc.) is completely skipped - the seurat_object argument is ignored.

  • Use this after RenameCellTypeInCC() + saveRDS() to regenerate figures with corrected cell-type labels.

assay_type

Character or NULL. Seurat assay to use for ligand-receptor expression. NULL (default) auto-detects: uses "RNA" for Seurat v4 objects and "RNA" / "Spatial" for v5 objects depending on available assays.

caffeinate

Logical. If TRUE, prevents the Mac from sleeping during the run using the caffeinate system command. Default FALSE.

Value

A named list of CellChat objects (one per group level processed).